psbt

PSBT Skill

Provides PSBT (Partially Signed Bitcoin Transaction) construction and signing operations on the Bitcoin L1. PSBTs enable multi-party signing workflows such as ordinals marketplace purchases where both buyer and seller must sign before broadcast.

• estimate-fee — Read-only fee estimation for a PSBT given its structure.
• sign — Sign one or more PSBT inputs with the active unlocked wallet (P2WPKH or Taproot keys).
• broadcast — Finalize a fully signed PSBT and broadcast it to the Bitcoin network via mempool.space.

Usage

bun run psbt/psbt.ts <subcommand> [options]

Subcommands

estimate-fee

Estimate the network fee in satoshis for a given PSBT. Parses the transaction structure and computes vsize-based fee estimate for fast, medium, and slow fee tiers.

bun run psbt/psbt.ts estimate-fee --psbt <base64>

Options:

• --psbt <base64> (required) — PSBT in base64 format

Output:

{
  "network": "mainnet",
  "vsize": 253,
  "inputsLength": 2,
  "outputsLength": 3,
  "feeEstimates": {
    "fast": { "satPerVb": 12, "totalSats": 3036 },
    "medium": { "satPerVb": 6, "totalSats": 1518 },
    "slow": { "satPerVb": 2, "totalSats": 506 }
  },
  "currentFeeSats": "1200"
}

sign

Sign PSBT inputs with the active wallet's BTC private keys (P2WPKH and/or Taproot). The wallet must be unlocked before calling this subcommand.

bun run psbt/psbt.ts sign --psbt <base64>

Options:

• --psbt <base64> (required) — PSBT in base64 format to sign
• --inputs <indexes> (optional) — Comma-separated input indexes to sign (signs all signable inputs if omitted)
• --finalize (optional) — Finalize signed inputs immediately (default: false)

Output:

{
  "success": true,
  "network": "mainnet",
  "signedInputs": [1, 2],
  "finalizedInputs": [],
  "skippedInputs": [{ "index": 0, "reason": "no matching key for this input" }],
  "psbtBase64": "<updated-base64>"
}

broadcast

Finalize a fully signed PSBT and broadcast it to the Bitcoin network via mempool.space.

bun run psbt/psbt.ts broadcast --psbt <base64>

Options:

• --psbt <base64> (required) — Fully signed PSBT in base64 format

Output:

{
  "success": true,
  "network": "mainnet",
  "txid": "abc123...",
  "explorerUrl": "https://mempool.space/tx/abc123...",
  "txHex": "0200..."
}

Notes

• Wallet must be unlocked with bun run wallet/wallet.ts unlock before calling sign.
• For ordinals purchase PSBTs (built by the MCP tool psbt_create_ordinal_buy): input index 0 is the seller's inscription UTXO; buyer inputs start at index 1. Sign only buyer inputs (index 1+) unless you are the seller.
• broadcast calls tx.finalize() — all inputs must be fully signed or it will throw.
• Fee estimates in estimate-fee are based on the PSBT's current vsize; they reflect the signed transaction size, not the unsigned size.