Fund Transaction Endpoint
Fund pre-signed transactions using Droplit as a paymaster.
Fund Transaction Endpoint
The fund endpoint takes a pre-built transaction template (with outputs but no funding inputs), adds inputs from the droplit's UTXO pool, signs, and broadcasts. This is the paymaster pattern — your app or agent builds and signs the transaction logic, Droplit pays for it.
- Endpoint:
POST /faucet/{droplitName}/fund- Replace
{droplitName}with the name of your Droplit.
- Replace
- Authentication: Required (see Authentication)
When to use Fund vs Push
| Use case | Endpoint | Why |
|---|---|---|
| Publish arbitrary data (OP_RETURN) | /push | Droplit builds the entire transaction |
| Fund a transaction your app already built | /fund | Your app controls the outputs, Droplit just pays |
| Identity operations (BAP publish, profile update) | /fund | App signs the BAP protocol, Droplit funds it |
| Complex multi-output transactions | /fund | Full control over transaction structure |
Request Body
{
"rawtx": "0100000000...",
"broadcast": true
}rawtx: Hex-encoded transaction with outputs defined but no funding inputs. The transaction should contain your desired outputs (OP_RETURN data, token operations, etc.) — Droplit adds inputs to cover the outputs and fee.broadcast: Optional boolean (default:true). Set tofalseto receive the funded transaction without broadcasting.
How It Works
- Your app builds a transaction with the desired outputs (e.g., signed BAP OP_RETURN)
- POST the raw transaction hex to
/fund - Droplit selects UTXOs from the droplit's pool to cover outputs + mining fee
- Droplit signs the funding inputs
- Transaction is broadcast to the network (unless
broadcast: false) - Returns the txid and optionally the complete raw transaction
Example: Fund a BAP Identity Transaction
import { Transaction, LockingScript } from "@bsv/sdk";
// 1. Build the transaction with your signed outputs
const tx = new Transaction();
tx.addOutput({
lockingScript: LockingScript.fromHex(signedBapScript),
satoshis: 0,
});
// 2. Send to Droplit for funding
const response = await fetch(`${DROPLIT_API_URL}/faucet/${droplitName}/fund`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Auth-Token": authToken,
},
body: JSON.stringify({
rawtx: tx.toHex(),
broadcast: true,
}),
});
const result = await response.json();
console.log("Funded txid:", result.txid);Example: FundingProvider for @1sat/actions
Droplit implements the FundingProvider interface from @1sat/actions, so any action that supports external funding works with Droplit out of the box:
import { createContext, publishIdentity, updateProfile } from "@1sat/actions";
import type { FundingProvider } from "@1sat/actions";
class DroplitFundingProvider implements FundingProvider {
async fund(args) {
const tx = new Transaction();
for (const output of args.outputs ?? []) {
tx.addOutput({
lockingScript: LockingScript.fromHex(output.lockingScript),
satoshis: output.satoshis ?? 0,
});
}
const res = await fetch(`${apiUrl}/faucet/${name}/fund`, {
method: "POST",
headers: { "Content-Type": "application/json", "X-Auth-Token": token },
body: JSON.stringify({ rawtx: tx.toHex(), broadcast: true }),
});
const result = await res.json();
return { txid: result.txid, tx: toArray(result.rawtx, "hex") };
}
}
// Use it with any @1sat/actions operation
const ctx = createContext(wallet, { services, chain: "main" });
const provider = new DroplitFundingProvider();
await publishIdentity.execute(ctx, { fundingProvider: provider });
await updateProfile.execute(ctx, {
profile: { "@type": "Person", name: "Alice" },
fundingProvider: provider,
});Success Response
{
"txid": "abcdef123456...",
"message": "Transaction funded and broadcast"
}With broadcast: false:
{
"txid": "abcdef123456...",
"rawtx": "0100000001...",
"message": "Transaction funded (not broadcast)"
}Error Responses
400 Bad Request: Invalid transaction hex or malformed outputs.401 Unauthorized: Missing or invalidX-Auth-Token.402 Payment Required: Droplit has insufficient balance to fund the transaction.500 Internal Server Error: Server-side issue.