Documentation

1. Add the server

Install Bun and Node.js, then run the command for your client:

# Codexcodex mcp add bsv-mcp -- npx -y bsv-mcp@latest --stdio
# Claude Codeclaude mcp add --transport stdio bsv-mcp -- npx -y bsv-mcp@latest --stdio
# Grok Buildgrok plugin install b-open-io/bsv-mcp --trust

2. Connect a wallet

Ask your assistant to open wallet setup. Create, import or unlock an account in the browser. To connect another wallet, open the wallet guide below.

3. Check the connection

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

This checks your server and its 1Sat connection without spending funds.

Check your balance or a transaction

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

Use wallet_getBalance for BSV, wallet_getOrdinals for inscriptions, wallet_getBsv21Balances for token balances, and wallet_getLockData for 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. 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.

Connect an existing wallet

Use a wallet that supports the BSV SDK HTTPWalletJSON signing API. It keeps your keys and asks you to approve wallet operations.

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

Start BSV MCP in your MCP client and open wallet setup. The browser wizard can create a wallet, import a detected account, or upload an encrypted or plaintext backup. Choose an account and network, then enter the Vault password in the local browser. Back up your Vault before funding the wallet. Never paste private keys or passwords into chat.

Accounts keep configuration and wallet databases locally; the Vault holds encrypted keys. Browser setup unlocks the current server and refreshes its tools. Unlock again after a restart. Existing account files and environment keys can be migrated without replacing their keys.

Import or link wallets in the Vault picker, then choose the payment, identity and ordinals roles. Project settings can override those choices. An explicitly disabled role cannot borrow another key. Ordinal fees come from the ordinals wallet. SIGMA-signed inscriptions also need a published BAP identity in the identity role.

New mainnet accounts use remote wallet storage with local SQLite as backup. Testnet starts with local storage. Account configuration can select an active remote and backups independently of blockchain lookup services.

BSV_MCP_ACCOUNT=default bunx bsv-mcp@latest --stdio# Open wallet setup from your MCP client.# Or prepare an account in your browser before connecting:bunx bsv-mcp@latest vault-setup

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 one-sat --source-directory /path/to/wallet --storage-identity existing-id --account imported

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 imported

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.

Choose a stable app origin so the signer can reuse its permission grants. Remove legacy private-key settings and the integrated Droplit wallet mode before connecting an external signer. A separately configured sponsor can be paired with that 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, transaction proof, ordinal content and wallet storage services can be configured independently. Each tool uses its configured provider and reports a failure rather than silently switching providers.

Explorer URLs exclude the final network segment. BSV MCP appends main or test; BananaBlocks uses /api/v1/bsv and WhatsOnChain uses /v1/bsv. Testnet uses WhatsOnChain by default.

Content previews follow the 1Sat base unless overridden. Legacy social integrations and sponsorship have separate settings. MNEE uses its own SDK service configuration.

# 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.

Read posts and conversations

Choose query.type: posts, post, replies, search, likes, friends, channels, messages, videos, or records. Use records with types follow and unfollow for relationship history; targetBapId filters incoming records and authorBapId filters outgoing records. Results are indexer data, not independently verified authorship or universally agreed current state.

{"query":{"type":"search","q":"bitcoin","limit":10}}

Publish and reply

Choose action.type: post, repost, like, unlike, follow, unfollow, friend, unfriend, message, or video. A reply is a post with replyTo set to the parent transaction ID. General context and subcontext each take a key and value. unfriend and video are indexer extensions to the core social vocabulary.

Use preview to inspect unsigned output scripts without signing, funding, or broadcasting. Publishing requires the selected identity wallet; its transaction and signing permissions apply. Legacy mode requires an explicit identity key plus a funding key, and never signs as the payment key by default.

{"action":{"type":"post","content":"Hello Bitcoin","contentType":"text/markdown","tags":["bitcoin"]},"preview":true}

Media and messages

Posts and messages accept a content type, utf8 or base64 input encoding, and up to eight attachments with the same fields. Base64 is decoded to binary B content. Total unsigned output size is limited to 300 KB. Tags and attachments are separate outputs signed by the same current identity key.

All published content is public and permanent. A message with context key bapID names a recipient but does not encrypt the content. Publish already-encrypted content when using an established secure messaging workflow. A friend record needs your communication publicKey from that workflow; it does not prove a reciprocal friendship or establish encryption by itself.

{"action":{"type":"message","content":"Hello channel","context":{"key":"channel","value":"bitcoin"}},"preview":true}

Migration and indexer setup

bsocial_read replaces bsocial_readPosts and bmap_readPosts (query.type posts or post), bmap_readLikes (likes), and bmap_readFollows (records with follow/unfollow types). bsocial_publish replaces bsocial_createPost and bap_friend. Old names are removed; refresh the client tool list. The publish input schema is the same across wallet modes.

PUBLIC_BMAP_URL must point to a BMAP server root exposing /social and /q. The adapter uses the routes in b-open-io/bmap-api. An unavailable indexer returns an error rather than an empty feed. Publication broadcasts through the wallet; it does not guarantee immediate indexing. Never retry a publication solely because it has not appeared in a feed.

Enable or disable tool groups

Disable a tool group when an assistant should not have it in its catalog. Broadcasting controls block guarded transaction submissions; they do not replace the connected wallet’s permissions.

External signer mode supports context wallet and BRC-100 tools. Legacy collection minting/gathering, raw-key BAP and MNEE tools are unavailable in that mode. Public social reads are available; social publishing is currently unavailable with an external signer. 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 the wallet URL points to its signing API, the app origin is correct and the network matches. Approve any request shown in the wallet. After a transaction timeout, inspect 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.