@droplit.dev/cli

Find a public sponsor

droplit discover --limit 20 --json
# Fetch another page using the returned next_cursor:
droplit discover --limit 20 --after <next_cursor> --json

This unsigned command calls GET /sponsors on DROPLIT_API_URL; no wallet, private key or signature is needed. limit defaults to 20 (maximum 50). The response is { sponsors: [{ name, slug, approval_required: true }], next_cursor: null | string }, ordered by slug. An empty list is valid. Listing does not promise free funds or grant access: run access --name <slug> with your signer, then request separate owner approval.

Owners opt in with List publicly in the droplit's API tab. Existing droplits stay unlisted. Turning the setting off removes the name from discovery; it does not revoke previously approved wallets or make public status endpoints private.

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:

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.

Official Droplit CLI for agents. Discover the public catalog, and operate droplits with BRC-103/104 AuthFetch over a WalletInterface.

Auth is AuthFetch + WalletInterface. --wallet-url is the recommended signer; --wif remains supported. Sigma device OAuth is identity-only until a WalletInterface exists — it does not complete Droplit AuthFetch.

Keys never go to droplit.dev. Prefer --wallet-url so keys stay in the wallet; --wif <WIF> signs locally. It does not read a WIF from the environment. @1sat/vault / ClawNet SE wrapping is future at-rest protection, not this release.

Node.js >= 20. ESM. Runtime dependency: @bsv/sdk.

Install

npx @droplit.dev/cli help
npx @droplit.dev/cli list --wif <WIF>
npx @droplit.dev/cli status --name agent-demo

npm install -g @droplit.dev/cli
droplit list --wif <WIF> --json

The unscoped npm name droplit is a different, unrelated package (file uploads). Never npm i droplit for this product. Use @droplit.dev/cli.

Signer

| Flag | Required | What it is | | --- | --- | --- | | --wif <WIF> | all signed commands (register, list, create, deposit-address, action, withdraw, activity, api-keys, quotas) | WalletInterface signer. Compatibility option when no --wallet-url is supplied. No environment key names. |

Do not set DROPLIT_SIGNER_WIF, SIGMA_ACCOUNT_PRIVATE_KEY, or CLAWNET_* and expect this CLI to read them. It will not. There is no DROPLIT_SIGNER_WIF fallback.

Environment

| Variable | Required | What it is | | --- | --- | --- | | DROPLIT_API_URL | No | API base used as-is when set. If unset, https://api.droplit.dev. No other names. Not trimmed. |

Hosts

| Role | URL | | --- | --- | | docs / discovery | https://droplit.dev | | wallet API | DROPLIT_API_URL or https://api.droplit.dev (AuthFetch, no bearer token) | | identity (OAuth + device) | https://auth.sigmaidentity.com (identity only until a WalletInterface exists) |

Commands

| Command | What it does | | --- | --- | | help | Hosts, AuthFetch/WalletInterface, usage | | when | When to use / not use Droplit (jobs and non-jobs) | | signup | Identity → register → POST /faucets → paymail or deposit-address → actions | | catalog | GET https://droplit.dev/api/v1 | | llms | GET https://droplit.dev/llms.txt | | openapi | GET https://droplit.dev/openapi.json | | skill | Pointers to the agent skill and docs | | register --wif <WIF> | POST {API}/auth/register with { "publicKey" } from the WalletInterface identity key | | list --wif <WIF> | GET {API}/admin/faucets | | create --name <slug> [--drop-sats N] --wif <WIF> | POST {API}/faucets with { name, fixed_drop_sats } | | status --name <slug> | GET {API}/faucet/{name}/status (public, no --wif) | | deposit-address --name <slug> --wif <WIF> | POST {API}/faucet/{name}/deposit-address | | action --kind tap\|push\|mint\|fund --name <slug> --wif <WIF> | POST {API}/faucet/{name}/actions with ActionRequest JSON fields | | withdraw --name <slug> --address <addr> [--amount-sat N] --wif <WIF> | POST /actions with { kind: "tap", recipientAddress } | | activity --name <slug> [--limit N] [--offset N] --wif <WIF> | POST {API}/faucet/{name}/activity | | api-keys list --name <slug> --wif <WIF> | GET {API}/faucet/{name}/api-keys | | api-keys add --name <slug> --public-key <hex> [--label] [--quotas json] --wif <WIF> | POST {API}/faucet/{name}/api-keys | | api-keys rm --name <slug> --public-key <hex> --wif <WIF> | DELETE {API}/faucet/{name}/api-keys/{publicKey} | | quotas list --name <slug> --wif <WIF> | GET {API}/faucet/{name}/action-quotas | | quotas set --name <slug> --quotas '<json array>' --wif <WIF> | PUT {API}/faucet/{name}/action-quotas with { quotas } |

action maps flags onto /actions JSON fields: --kind, --recipient-address, --amount-sat, --data, --encoding, --content-type, --inscription, --bsv21, --rawtx, --broadcast. --data is one or more strings, or a JSON string array.

withdraw is a tap to --address. It does not call legacy /tap.

activity POSTs { limit, offset } when those flags are set. The live API has no GET /activity.

Owner of a faucet is unlimited. Allowlisted keys get N (optional --quotas JSON: n_per_period, period, max_bytes, max_sats_per_action, max_sats_per_period). Faucet-level policy is quotas list|set against /action-quotas. quotas set --quotas '[]' clears faucet-level policy (no rows = unlimited allowlist). Rate limit is not a credits ledger and is not monthly Sigma owner metering. Exhausted quota is HTTP 429 with resets_at. Authenticated GET /access quotas and api-keys list include remaining and resets_at.

Add --json or -j for machine-readable output.

Signed commands require --wallet-url or --wif and reuse one AuthFetch per process. status is unauthenticated.

On non-OK HTTP, the CLI prints the status and a body clipped to 400 characters, then exits 1. It does not retry another URL.

catalog, llms, and openapi are discovery GETs. They may 404 until droplit.dev ships those routes.

Agent signup (short)

1. Identity: pass --wif <WIF> and use AuthFetch + WalletInterface. Sigma RFC 8628 device flow yields identity (bap_id / pubkey / bearer) only — not Droplit AuthFetch — until a WalletInterface exists. Use verification_uri / verification_uri_complete from the device-code JSON; do not invent a verification URL.
2. droplit register --wif <WIF> → POST /auth/register with { "publicKey": "<compressed-public-key-hex>" }. A bodyless POST is 400.
3. droplit create --name agent-demo --wif <WIF> → POST /faucets with { "name": "agent-demo" }.
4. Deposit to {name}@droplit.dev or droplit deposit-address --name agent-demo --wif <WIF>.
5. Operate: droplit action --kind tap --name agent-demo --recipient-address <addr> --wif <WIF>, or droplit withdraw --name agent-demo --address <addr> --wif <WIF>. Canonical write is POST /faucet/{name}/actions.

Full playbook: https://droplit.dev/docs/agents

When to use

• Sponsor user transactions
• Agent payouts
• Faucet wallets
• On-chain OP_RETURN
• Paymail deposits

Not an exchange. Not a custodial fiat on-ramp. Not Ethereum/EVM.