Reuse an approved sponsor or create and fund your own: Agents.

These playbooks start with a named droplit and an existing wallet signer selected with --wallet-url <URL>. Writes go to https://api.droplit.dev with BRC-103/104 AuthFetch. https://droplit.dev is discovery only. Sigma OAuth (bap_id / bearer) is not AuthFetch.

The CLI (npx @droplit.dev/cli) registers, creates, lists, statuses, requests a deposit address, and operates: action --kind tap|push|mint|fund, api-keys list|add|rm, withdraw, activity. Signed commands use --wallet-url (recommended) or mutually exclusive explicit --wif. The CLI does not read a WIF from the environment. --drop-sats sends JSON fixed_drop_sats.

The faucet owner is unlimited. Allowlisted keys get N per kind per period (rate limit, not a credits ledger). Exhausted quota is HTTP 429 with resets_at. Authenticated GET /faucet/{name}/access includes per-kind quotas with remaining and resets_at.

Reuse one AuthFetch client. The backend does not implement idempotency-key replay. Do not automatically repeat a write after an ambiguous response: inspect activity and transaction status first to avoid a duplicate payment.

Playbook 1: Payout

Pay sats from a hosted droplit to a BSV address.

Setup (CLI)

npx @droplit.dev/cli create --name payouts --drop-sats 1000 --wallet-url <URL>
npx @droplit.dev/cli deposit-address --name payouts --wallet-url <URL>
# send BSV to payouts@droplit.dev
npx @droplit.dev/cli status --name payouts

--drop-sats sends JSON fixed_drop_sats. status is public. Do not invent a no-auth write to credit a balance.

Tap

npx @droplit.dev/cli action --kind tap --name payouts --recipient-address 1ExampleAddressForDocsOnly --amount-sat 1000 --wallet-url <URL>

POST https://api.droplit.dev/faucet/payouts/actions

{
	"kind": "tap",
	"recipientAddress": "1ExampleAddressForDocsOnly",
	"amountSat": 1000
}

Validate the recipient before you send. Cap amountSat in your runtime. Use a wallet identity with appropriate payout permissions. Quota'd keys must send amountSat; they cannot omit it and spend the whole wallet.

On 429, read resets_at and wait. Do not treat remaining as a spendable credits balance.

Legacy POST /faucet/{name}/tap uses { "recipient_address", "satoshis" } and expects satoshis to match the droplit drop_sats. Prefer /actions.

Fund (optional)

Sponsor a pre-built transaction instead of tapping:

npx @droplit.dev/cli action --kind fund --name payouts --rawtx 0100000000... --broadcast true --wallet-url <URL>

{
	"kind": "fund",
	"rawtx": "0100000000...",
	"broadcast": true
}

Persist txid and the recipient. Optional audit: playbook 2.

Playbook 2: On-chain data

Write a deterministic OP_RETURN from an agent event.

Push

npx @droplit.dev/cli action --kind push --name payouts --data '["event:order-filled","order:12345","v1"]' --encoding utf8 --wallet-url <URL>

POST https://api.droplit.dev/faucet/{name}/actions

{
	"kind": "push",
	"data": ["event:order-filled", "order:12345", "v1"],
	"encoding": "utf8"
}

Keep a stable schema. Put IDs in the data array so you can reconcile later. Keep secrets off-chain.

Legacy POST /faucet/{name}/push still accepts { "data", "encoding" }. Prefer /actions.

Mint (optional)

npx @droplit.dev/cli action --kind mint --name payouts --content-type text/plain --inscription hello --wallet-url <URL>

{ "kind": "mint", ... } on the same /actions path. See OpenAPI ActionRequest for contentType, inscription, and bsv21.

Playbook 3: Monitor

Read balance and UTXO counts. Then, if you need a live stream, attach Peer.

Status (do this first)

npx @droplit.dev/cli status --name payouts

GET https://api.droplit.dev/faucet/{name}/status is public. No --wif. Balances and faucet-level action_quotas are public. Use authenticated GET /faucet/{name}/access for is_owner, authorized, quotas and unrestricted_kinds; public status is not the caller policy.

Use this for "does the faucet exist" and "is it funded" before writes.

Activity stream (advanced)

GET /faucet/{name}/activity-stream upgrades to a WebSocket. Peer from @bsv/sdk then does BRC-103/104 over that connection. For a JSON page of history: npx @droplit.dev/cli activity --name payouts --wallet-url <URL> (POST /faucet/{name}/activity). The CLI does not open the live stream.

See WebSocket Activity Stream.

If you do subscribe: treat handlers as idempotent, reconnect on drop, and do not invent event types.

Allowlist (optional)

Delegate N taps/day (or another kind/period) to a worker key. Owner stays unlimited.

npx @droplit.dev/cli api-keys add --name payouts --public-key <compressed-hex> --quotas '[{"kind":"tap","n_per_period":10,"period":"day"}]' --wallet-url <URL>
npx @droplit.dev/cli api-keys list --name payouts --wallet-url <URL>

Faucet-level policy: GET/PUT https://api.droplit.dev/faucet/{name}/action-quotas. CLI: npx @droplit.dev/cli quotas list|set --name <slug> --wallet-url <URL>. quotas[].remaining and quotas[].resets_at are the current window.

Don't

POST wallet writes to https://droplit.dev
Pass a Sigma bearer as API auth
Expect the CLI to read DROPLIT_SIGNER_WIF or any other env name
Treat remaining as a credits ledger or merge it with monthly owner metering
Treat Droplit as an exchange, fiat on-ramp, or Ethereum paymaster

Agent Playbooks