Documentation

1. Add the server

Install Bun, then run the command for your client in a terminal. These examples start without a wallet and disable broadcasting. You only need one command.

# Codexcodex mcp add bsv-mcp --env DISABLE_WALLET_TOOLS=true --env DISABLE_BROADCASTING=true -- bunx bsv-mcp@latest --stdio
# Claude Codeclaude mcp add --env DISABLE_WALLET_TOOLS=true --env DISABLE_BROADCASTING=true --transport stdio bsv-mcp -- bunx bsv-mcp@latest --stdio

2. Connect a wallet

When you need funds, choose a wallet option below, remove DISABLE_WALLET_TOOLS and DISABLE_BROADCASTING from the server configuration, and restart your client. The tools available to you depend on that choice and the tool groups enabled on your server.

3. Check the connection

Ask your assistant: "Run bsv_status and explain whether my wallet and 1Sat service are available."

This check reports the server configuration and contacts the 1Sat capabilities endpoint, which lists enabled API services. It does not sign transactions, spend funds, or import deposits. A successful check does not verify every wallet operation.

Connect an existing wallet

Your wallet must expose the BSV SDK HTTPWalletJSON interface, an API for wallet requests. Set BRC100_WALLET_URL to that API address. The wallet controls permissions and keeps its keys; BSV MCP does not create local or remote wallet storage in this mode.

Add the following variables to your MCP server environment, replace the wallet URL with your own, then restart the server. BSV_CHAIN must match the wallet network: main for mainnet or test for testnet.

BRC100_WALLET_URL=http://127.0.0.1:3321BRC100_WALLET_ORIGINATOR=bsv-mcp.localBSV_CHAIN=main

Set up an encrypted account

Run bsv-mcp init in a local terminal. Choose a network, create or import a key, and enter an encryption password twice. The command shows only a public address. Back up the encrypted files before funding the wallet. Never paste private keys or passwords into chat.

Each account lives in ~/.bsv-mcp/accounts/<name>/ and has config.json, encrypted keys.bep, and wallet-main.db or wallet-test.db. BSV_MCP_ACCOUNT selects an account; the default name is default. Supply BSV_MCP_PASSWORD in the server process environment to unlock it. PRIVATE_KEY_WIF and IDENTITY_KEY_WIF are legacy environment overrides that trigger a persistent Vault migration warning; move them into Vault and remove them. A missing key, invalid key or bad password stops startup without generating a replacement.

Wallet storage is local by default. The account configuration can set activeRemote and backups; REMOTE_STORAGE_URL overrides the active remote. Wallet storage must be compatible with the 1Sat wallet SDK. These settings are separate from blockchain lookup services.

bunx bsv-mcp@latest init --account defaultbunx bsv-mcp@latest wallet_list# Configure BSV_MCP_PASSWORD locally, then start:BSV_MCP_ACCOUNT=default bunx bsv-mcp@latest --stdio

Manage and migrate accounts

wallet_list reports public addresses without unlocking accounts. wallet_generate and wallet_import create encrypted named accounts after human approval. WIF import is terminal-only; the MCP import tool accepts an encrypted backup. wallet_use returns the account environment setting: restart the MCP server to apply it. wallet_remove requires force, a verified backup and human confirmation because funds may exist on other derived addresses.

Existing plaintext keys are migration inputs only. Stop the old wallet process, then run wallet_migrate in a terminal. Migration verifies the encrypted copy and preserves the lab storage identity and database. It leaves the source in place unless you explicitly request --erase-source after verification and backup. Overwriting a file cannot guarantee erasure from SSD snapshots or backups.

bunx bsv-mcp@latest wallet_migrate --source legacy --account defaultbunx bsv-mcp@latest wallet_migrate --source sigma-lab --account sigma-lab

Run the bundled external signer

signer-serve unlocks one named account and starts an MCP child with a private loopback signer connection. The child receives no private-key or password variables. The signer checks the secret request path, Origin and SDK method before handling a request. It requires terminal approval for createAction and signAction; those calls fail closed when a headless client has no terminal. An existing signer with its own approval UI is the better fit for payments from a headless MCP host.

bunx bsv-mcp@latest signer-serve --account sigma-lab

Existing-wallet connection rules

Use the wallet signing API address. The /1sat/wallet endpoint and the storage endpoint exposed by 1sat serve wallet store wallet data; they cannot act as BRC100_WALLET_URL.

The wallet URL must use HTTPS, or HTTP on the local computer. Credentials, query strings, fragments, and redirects are rejected. Startup requests the wallet identity public key once and stops if the request fails or takes more than 10 seconds. Wallet calls are not automatically retried.

BRC100_WALLET_ORIGINATOR defaults to bsv-mcp.local. Use a domain or HTTP(S) origin without credentials, paths, queries or fragments. Empty, malformed, and admin.bsv-mcp.internal origins are rejected. Remove PRIVATE_KEY_WIF and IDENTITY_KEY_WIF and leave USE_DROPLIT_API unset when using an external signer. The explicit sponsor pair described below can be used alongside the signer.

Change the 1Sat service

ONESAT_API_URL controls blockchain lookups and local-wallet services, including transaction submission. It defaults to https://api.1sat.app on mainnet and https://testnet.api.1sat.app on testnet. An existing wallet continues to use its own storage and transaction submission services.

Set the base URL without /1sat. The SDK adds that path. If PUBLIC_ORDFS_URL is unset, its default follows this base URL. Wallet remote storage is configured separately.

# Example: a 1Sat stack running locallyONESAT_API_URL=http://127.0.0.1:8080

Configure services separately

EXPLORER_API_URL selects the explorer API used for blockchain lookups and prices. BananaBlocks is the mainnet default. JUNGLEBUS_API_URL supplies transaction decoding and legacy raw/BEEF reads. ORDINALS_API_URL remains for legacy sweep and token-listing data; marketplace browsing now uses 1Sat. Each tool uses its configured service; it does not automatically switch to another provider if that service fails.

Set EXPLORER_API_URL to a compatible API base without the final /main or /test; BSV MCP appends the selected network. BananaBlocks uses /api/v1/bsv. WhatsOnChain uses /v1/bsv. Testnet still defaults to WhatsOnChain because the public BananaBlocks API documents a mainnet mirror. The older WOC_API_URL setting still works when EXPLORER_API_URL is unset.

PUBLIC_ORDFS_URL overrides the content base used in generated links and dashboard previews. PUBLIC_BMAP_URL, BSOCIAL_API_URL and V5_API_URL configure optional legacy social integrations. MNEE uses its SDK's own service configuration. DROPLIT_API_URL and OAUTH_ISSUER configure sponsorship and authentication separately.

# Defaults for mainnetONESAT_API_URL=https://api.1sat.appEXPLORER_API_URL=https://bananablocks.com/api/v1/bsvJUNGLEBUS_API_URL=https://junglebus.gorillapool.io/v1ORDINALS_API_URL=https://ordinals.gorillapool.io/apiPUBLIC_ORDFS_URL=https://api.1sat.app/content

Check which 1Sat services are enabled

The /1sat/capabilities endpoint lists the services enabled on a deployment. These can include marketplace data, token balances, identity records, file content, and transaction submission. Self-hosted deployments may enable fewer services.

A service appearing in this list does not automatically enable a corresponding MCP tool. The admin entry also does not grant permission to administer the server.

Route requests through a proxy

Most API routes begin with /1sat. File content uses /content/{outpoint}; file metadata uses /1sat/ordfs/metadata/{outpoint}. An outpoint identifies one transaction output, written as a transaction ID followed by its output number.

Owner output and synchronization routes use server-sent events (SSE), a stream of responses. Raw transaction endpoints and BEEF endpoints return binary data. BEEF packages transactions with their supporting proof data. Preserve these response formats in your proxy. The SDK submits transactions through /1sat/tx.

Check your balance or a transaction

Ask: "Show my BSV balance and the ordinals in my wallet."

wallet_getBalance reports funds. wallet_getOrdinals lists ordinals, wallet_getBsv21Balances reports token balances, and wallet_getLockData reports locked funds.

To inspect the blockchain, use bsv_explore for addresses, blocks, and transactions. bsv_decodeTransaction reads a transaction ID or transaction data encoded as hex or base64.

Receive a payment

Ask: "Give me a deposit address, then check for incoming funds."

wallet_getAddress returns the deposit address. After the payment arrives, wallet_refreshUtxos imports deposits found by the blockchain indexer into the wallet. The indexer is the service that tracks blockchain activity. Your wallet balance may lag behind the on-chain balance until indexing and import finish.

Browse listings and recent sales

Ask: "Find 20 active listings whose names start with cat."

ordinals_marketListings searches active listings; ordinals_marketSales searches completed sales. The q argument matches the beginning of a name. Use type to filter by content type, such as image/png.

The limit is 1–100 results. To get another page, pass the response's nextFrom value as from. A null nextFrom means there are no more pages. Results can change between requests.

// Arguments for ordinals_marketListings{"q":"cat","limit":20}

Find assets belonging to an address

ordinals_searchInscriptions accepts an index key. For an address, use own: followed by the address. Other supported keys include ev:EVENT and tp:TOPIC. This tool searches indexed unspent transaction outputs; results can include available inscription, origin, and MAP metadata. It does not support full-text search or guarantee that every result is an NFT.

Use ordinals_getInscription to read an inscription's metadata. Lookup tools accept outpoints written as txid.vout or txid_vout. The historically named ordinals_getTokenByIdOrTicker currently accepts token IDs only.

// Arguments for ordinals_searchInscriptions// Replace YOUR_ADDRESS with the address to look up.{"key":"own:YOUR_ADDRESS","limit":20}

Send funds or create an ordinal

wallet_sendBsv sends to addresses or paymail recipients and accepts BSV or USD amounts. wallet_createOrdinals records content on-chain; it takes the content encoded as base64 and a MIME type, such as image/png.

wallet_transferOrdToken transfers an ordinal using its wallet tracking ID, or BSV21 tokens using a token ID and integer amount. Transfers, listings, purchases, cancellations, and locking or unlocking funds create transactions and may incur fees.

Enable or disable tool groups

Tool groups can be disabled with DISABLE_BSV_TOOLS, DISABLE_ORDINALS_TOOLS, DISABLE_WALLET_TOOLS, DISABLE_BAP_TOOLS, DISABLE_BSOCIAL_TOOLS, DISABLE_MNEE_TOOLS and DISABLE_UTILS_TOOLS=true. DISABLE_BROADCASTING=true blocks guarded transaction operations. This does not replace the signer's permissions.

External signer mode supports context wallet and BRC-100 tools. Legacy collection minting/gathering, BAP/raw-key, BSocial and MNEE tools are unavailable in that mode. An advertised backend module does not automatically enable a tool group.

Build custom transactions

wallet_createAction, wallet_signAction, and wallet_abortAction let you create, sign, and cancel a pending wallet action. Custom inputs require BEEF data containing the supporting transactions and proofs. These tools do not provide a universal quote or dry-run feature.

If a request times out after submission, inspect wallet_listActions and the transaction status before sending it again. The first request may already have succeeded.

1. Send the request without paying

Call x402_request with the URL, HTTP method, and any body or headers required by the service. It returns either the service response or a payment quote with a quoteId, price in satoshis, and expiry. It never automatically pays.

This sends a real request. If the service allows it without payment, the operation can execute immediately. Use the method intended for the task: GET for a lookup, for example, or POST to create something.

For a service using BSV mutual authentication, set auth to brc31. The wallet proves its identity and derives payment details, but does not sign a payment until you authorize it. These services use BRC-31 authentication and BRC-105 payments.

{  "url": "https://service.example/generate",  "method": "POST",  "headers": {    "content-type": "application/json"  },  "body": "{\"prompt\":\"an image of a cat\"}",  "auth": "brc31"}

2. Review and pay the quote

Review the service URL, requested operation, price, and any terms returned by the service. Once you approve, call x402_payQuote with the quoteId and maxTotalSats: the most you will spend, including the mining fee.

The client uses the stored request so the URL, method, body, and credentials cannot be changed by the payment call. The connected BRC-100 wallet funds and signs the transaction under its permissions. The client checks the price and fee before submitting the payment proof.

The result includes the payment transaction ID and the service response. A successful HTTP response does not independently prove blockchain confirmation. DISABLE_BROADCASTING blocks payments; DISABLE_WALLET_TOOLS prevents the client from using the wallet.

Example: upgrade BananaBlocks

BananaBlocks sells higher API rate limits through a paid POST request. Its API key identifies the account being upgraded; it is a BananaBlocks requirement, not an x402 requirement. Configure that credential as shown below, then send this request and review the returned price.

After payment, use x402_request with GET https://bananablocks.com/api/v1/key/usage to check the tier. If you also use bsv_explore, set EXPLORER_API_KEY to the same key so explorer calls use the purchased allowance.

{  "url": "https://bananablocks.com/api/v1/key/upgrade",  "method": "POST",  "headers": {    "content-type": "application/json"  },  "body": "{\"tier\":\"pro\"}"}

Optional credentials for a service

If a service needs an API key or bearer token, set X402_SERVICE_HEADERS in the MCP server environment. It maps exact HTTPS origins to their required headers. A credential for one origin is never sent to another origin. Keep secrets out of tool arguments, chat, and source control.

The example below is only needed for BananaBlocks. A service that accepts payment without an account needs no credential configuration.

X402_SERVICE_HEADERS='{"https://bananablocks.com":{"X-API-Key":"YOUR_KEY"}}'

Supported payment formats

The client supports BRC-105 x-bsv-payment requests, request-bound BRC-120 challenges with OP_TRUE server nonces, and compact bsv-tx-v1 challenges such as those used by BananaBlocks. It selects the proof format from the service response; an unsupported format is rejected before payment.

An OP_TRUE nonce is a small server-provided transaction output that anyone can spend. Including it ties a BRC-120 payment to one challenge. Other nonce scripts need an additional unlocking implementation. The client obtains nonce transaction proofs through the configured 1Sat service.

For BRC-120, the URL, method, body, and selected headers must match the challenge. If the service binds only some headers, provide their names in boundHeaders according to that service’s documentation. By default, the client checks all supplied request headers.

Requests must use public HTTPS addresses. Redirects are refused. Request and response bodies are limited to 1 MiB; use bodyEncoding: base64 to send binary content. Binary responses include their encoding. The x402 Foundation’s EVM and Solana payment formats are not supported by this BSV wallet client.

If payment does not complete

Do not pay again after a timeout or an unexpected response. Check wallet_listActions and the service first: it may have accepted the payment even if its reply was lost. The client does not create a second payment automatically.

A not_submitted result means the transaction was withheld; wallet funds may still be reserved. An outcome_unknown result requires checking whether the service received it before releasing inputs or trying again. Further payments are blocked in that MCP session after such a failure.

Quotes are kept for the current MCP session, and wallet history records attempted challenge IDs. Restarting the server does not establish that an earlier payment failed. Refund handling is not yet automated.

Find a sponsor

Set DROPLIT_API_URL to the sponsor API, including its base path. Call droplit_discover to list sponsors; this public lookup requires no wallet or selected sponsor. An empty list is a valid response.

DROPLIT_API_URL=https://api.droplit.dev/droplitDROPLIT_FAUCET_NAME=your-sponsor-slug# Optional if the approval UI is hosted elsewhereDROPLIT_SITE_URL=https://droplit.dev

Check access before requesting funds

Set DROPLIT_FAUCET_NAME to a sponsor slug (its short identifier) returned by the catalog, then call droplit_getAccess to check authorization and quotas. If approval is required, follow the returned link for the owner to review your request. Wallet identity and Sigma delegation do not grant sponsor approval. Creating your own faucet requires funding.

Leave USE_DROPLIT_API unset when pairing sponsorship with an existing wallet or locally managed BRC-100 wallet. The older USE_DROPLIT_API=true wallet mode is separate. DROPLIT_SITE_URL defaults to https://droplit.dev and must be an HTTPS origin, or HTTP loopback, without a path, query, fragment or credentials.

Submit a sponsored operation

droplit_push publishes data and droplit_fund requests funding and broadcast. They honor broadcast-disable settings and do not automatically pay 402 responses, follow redirects or retry ambiguous writes. For an authorized user, an omitted quota category has no limit; a category set to zero allows no operations. Permission to transfer funds or perform a certain number of operations does not guarantee enough funding for transaction fees. If the outcome is unknown, check whether the operation succeeded before submitting it again.

Submit the owner handoff

Once the owner has issued the certificate, call wallet_revealDelegation. Put the complete handoff JSON in handoffJSON and the address of the Sigma service that will verify it in sigmaOrigin. Keep all four handoff fields: certificate, subjectKeyring, revealTo, and revelationPath.

The tool acquires the certificate, proves its restrictions and sends only the verifier keyring to the specified Sigma verifier. The subject keyring stays with the wallet. It activates an existing delegation; it does not issue one, pay, broadcast or grant sponsor approval. An Ed25519 agent token cannot replace the bound wallet for this step.

Handle an uncertain result

The Sigma origin must be HTTPS (HTTP loopback is allowed for local testing). Redirects and ambiguous POST retries are disabled. If the result is outcome_unknown, refresh the delegation status before trying again; certificate acquisition may already have succeeded.

The 1Sat service is unavailable

Start with bsv_status. A capabilities error identifies the configured 1Sat service; check the base URL and enabled modules. A 404 from a self-hosted market or ORDFS route may mean that module is disabled. Do not append /1sat twice.

The wallet cannot connect

Check that BRC100_WALLET_URL points to the wallet signing API, not its storage endpoint. Confirm that BRC100_WALLET_ORIGINATOR identifies this app, that BSV_CHAIN matches the wallet network, and that any request shown in the wallet has been approved. If a transaction request timed out, check wallet history before retrying; it may already have succeeded.

A payment is missing

Ask the assistant to run wallet_refreshUtxos, then check the balance again. If it is still missing, inspect the transaction with bsv_explore. Indexing and wallet import must finish before a received payment appears in the wallet balance.