This is the signup, create, and deposit playbook for software agents. Humans can follow the same HTTP steps from a backend. Wallet writes stay on https://api.droplit.dev with BRC-103/104 AuthFetch. This documentation host does not proxy create, deposit, tap, push, fund, or mint.

When to use

Use Droplit when an agent or app needs a hosted BSV wallet it can operate over HTTP:

Sponsor user transactions so the user never buys coin
Pay out sats to addresses from a dedicated faucet wallet
Write OP_RETURN / push-data attestations
Receive deposits at {name}@droplit.dev
Run a faucet or mint pipeline with allowlisted keys

Do not use Droplit as an exchange, a custodial fiat on-ramp, or an Ethereum paymaster. There is no unauthenticated create or deposit endpoint.

Which host to call

Host	Role
`https://droplit.dev`	Docs, OpenAPI, `llms.txt`, trust pages. Discovery only.
`https://api.droplit.dev`	Register, create faucets, deposit addresses, actions.
`https://auth.sigmaidentity.com`	OAuth and RFC 8628 device authorization for Sigma identity.

Protected API routes use @bsv/sdk AuthFetch, not a bearer token you mint on droplit.dev.

Identity options

Autonomous service key

Build a ProtoWallet from a WIF held in the agent environment. Never put a real WIF in source, issues, or chat logs.

import { AuthFetch, PrivateKey, ProtoWallet } from "@bsv/sdk";

const wif = process.env.DROPLIT_SIGNER_WIF;
if (!wif) {
	throw new Error("DROPLIT_SIGNER_WIF environment variable is required");
}

const wallet = new ProtoWallet(PrivateKey.fromWif(wif));
const client = new AuthFetch(wallet);

Human-approved Sigma device auth

If a person must approve the agent, use Sigma device authorization (RFC 8628) at the auth server, then wrap the resulting identity/wallet in the same AuthFetch:

POST https://auth.sigmaidentity.com/api/auth/device/code
Show the user code / verification URI and wait
POST https://auth.sigmaidentity.com/api/auth/device/token
Use the issued identity with AuthFetch against https://api.droplit.dev

Keys for Sigma-hosted identity stay in the Sigma domain. Do not reimplement the BRC-103/104 handshake.

Register

Register the signer with the API before creating wallets. POST /auth/register requires JSON { "publicKey": "<compressed hex>" } (EnsureKeyRegisteredRequest). A bodyless POST is 400.

{
	"publicKey": "<compressed-public-key-hex>"
}

const register = await client.fetch("https://api.droplit.dev/auth/register", {
	method: "POST",
	headers: { "Content-Type": "application/json" },
	body: JSON.stringify({
		publicKey: "<compressed-public-key-hex>",
	}),
});

Reuse one AuthFetch instance so the authenticated session can be reused.

Create

POST https://api.droplit.dev/faucets

name is required. The other fields are optional faucet configuration.

{
	"name": "agent-payouts",
	"drop_sats": 1000,
	"target_buckets": 4,
	"current_bucket_idx": 0,
	"max_consolidation_inputs": 100
}

const create = await client.fetch("https://api.droplit.dev/faucets", {
	method: "POST",
	headers: { "Content-Type": "application/json" },
	body: JSON.stringify({
		name: "agent-payouts",
		drop_sats: 1000,
	}),
});

A typical response includes faucet_name, instance_pub_key, owner_pub_key, and message. The owner is the identity that signed the create request.

Deposit

Two supported paths:

Paymail — send BSV to {name}@droplit.dev (example: agent-payouts@droplit.dev).
Deposit address — POST https://api.droplit.dev/faucet/{name}/deposit-address with AuthFetch, then pay the returned address.

Status is public at GET https://api.droplit.dev/faucet/{name}/status. Do not invent a no-auth write to credit a balance.

Operate

Canonical write endpoint:

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

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

Send Idempotency-Key on retryable writes. Same key plus same body replays the prior result. Same key plus a different body is a conflict.

Legacy wrappers still exist for compatibility: /tap, /push, /fund, /mint. Prefer /actions. Delegated keys are scoped (actions:tap, actions:push, actions:mint, actions:fund, or actions:*).

Errors

Status	Meaning
`401`	BRC-103/104 authentication or ownership failure. Check the signer, `AuthFetch`, and that you called `api.droplit.dev`.
`403`	The key is known to the faucet but not allowed for this action scope.
`409`	Idempotency key reused with a different body, or another conflict such as a name that already exists.

This documentation host returns problem+json 401 if you POST wallet writes to /api/v1/*. Those writes belong on the API with AuthFetch.

Agents