---
name: droplit-api-operations
description: Operate Droplit sponsored BSV wallets using the current HTTP API and BRC-103/104 AuthFetch.
version: 0.2.0
---

# Droplit API operations

## Existing signer and sponsor approval

Use the same existing wallet identity across tools. If your wallet exposes the
SDK BRC100 HTTP signer, pass its URL explicitly:

```sh
droplit access --name <known-sponsor> --wallet-url http://127.0.0.1:3321 --json
droplit action --name <known-sponsor> --kind push --data '["hello"]' --wallet-url http://127.0.0.1:3321 --json
```

`--originator` optionally identifies the caller to the signer; default
`droplit-cli.local`. `--wallet-url` uses SDK `HTTPWalletJSON` and never loads a
WIF or generates another identity. It requires HTTPS or HTTP loopback, without
credentials, queries or fragments. Signer calls time out after 10 seconds;
redirects are rejected and signer errors never fall back to local keys.
`--wif` remains a mutually exclusive compatibility option; no environment WIF
is read. **`1sat serve wallet` is storage RPC, not signer RPC.** This CLI does
not launch a signer daemon. Sigma OAuth tokens do not replace wallet signing.

`access --name` makes an authenticated `GET /faucet/{slug}/access` using
`AuthFetch`. The result describes this exact caller: `slug`, `public_key`,
`authorized`, `is_owner`, `quotas`, `unrestricted_kinds`, and `approval_path`.
The CLI adds `approval_url`, constructed from the trusted `DROPLIT_SITE_URL`
(default `https://droplit.dev`), the requested slug and the signer public key.
It does not trust a server-provided cross-origin approval URL or open a browser.
`DROPLIT_API_URL` selects the API (default `https://api.droplit.dev`); signed
requests require HTTPS or HTTP loopback with no URL credentials.

Copy the approval URL to the sponsor's owner. The owner selects **Review access**,
edits limits, then explicitly selects **Approve access**. The default policy is
10 pushes per day with `max_bytes: 1024`; tap, fund and mint each have an explicit
zero daily limit. Missing action kinds are unlimited, so all four rows matter.
Transaction fees are not included in current satoshi quotas; this is not an
expiry or total spending ceiling. Existing allowlisted keys show their current
policy and are not overwritten by opening the link.

Run `access` again with the same signer after owner approval. Access checks are
read-only and do not authorize automatic payment of HTTP 402 challenges. The
link is a convenience handoff, not a stored pending/denied request. No approval
is implied by copying it. Unknown sponsor names remain errors; no sponsor is
invented. Public `/status` reports balances, while authenticated `/access` is
authoritative for the caller's policy and remaining quotas.


Docs: https://droplit.dev/docs/agents
Contract: https://droplit.dev/openapi.json
Backend: https://api.droplit.dev

Use an existing WalletInterface with @bsv/sdk AuthFetch. Reuse one client; let the SDK own signing, handshake and sessions. Sigma OAuth identity tokens alone do not provide wallet signing. Never send private keys to the service or put them in source or logs.

## Workflow

1. Register the identity with POST /auth/register and JSON {"publicKey":"<compressed public key>"}.
2. Create a wallet using authenticated POST /faucets with {"name":"<slug>","fixed_drop_sats":1000}.
3. Deposit BSV to <slug>@droplit.dev or an address from authenticated POST /faucet/<slug>/deposit-address.
4. Read public GET /faucet/<slug>/status.
5. Send authorized operations to POST /faucet/<slug>/actions.

## Action fields

- tap: {"kind":"tap","recipientAddress":"<BSV address>","amountSat":1000}
- push: {"kind":"push","data":["hello"],"encoding":"utf8"}
- mint: {"kind":"mint","contentType":"text/plain","inscription":"hello"}
- fund: {"kind":"fund","rawtx":"<complete transaction hex>"}
- Optional broadcast: false signs without broadcasting.

Always set amountSat for a specific payout. An owner tap without an amount or configured fixed amount can send the entire spendable balance.

## Reads and access control

- GET /admin/faucets lists wallets owned by the signer.
- POST /faucet/<slug>/activity accepts {"limit":20,"offset":0}.
- GET/POST /faucet/<slug>/api-keys lists/adds allowlisted public keys; DELETE /faucet/<slug>/api-keys/<publicKey> removes one.
- GET/PUT /faucet/<slug>/action-quotas reads/replaces {"quotas":[{"kind":"tap","n_per_period":10,"period":"day"}]}.
- Owners are unlimited. Allowlisted keys use per-action quotas. There are no named actions:* scopes in the current backend.
- GET /faucet/<slug>/activity-stream upgrades to WebSocket. Authenticate with SDK Peer and send a general subscription message; owner verification precedes JSON activity events. It is not SSE or bearer-token authentication.

## Failed writes

Idempotency-Key replay is not implemented. Do not automatically repeat payments after timeouts or ambiguous responses. Check activity and transaction status first. 400 indicates validation/funding failures, 401/403 access failures, 409 a conflict, and 429 exhausted quota (inspect resets_at). Preserve the returned txid when a write succeeds.