🔌 Endpoints

🔑 Get your API keys

Start your free trial to get API keys. Happy building!

⚡ Alternative: pay-per-request via Lightning

Don't want to manage an API key? Every Xverse API endpoint also accepts payment over the Machine Payments Protocol (MPP) — pay 1 satoshi per request via Lightning, no key required. This is the recommended path for AI agents and autonomous clients.

See MPP Lightning Payments for the full flow.

💬 Developer Support & Feedback

Have feedback, feature requests, or want to partner? Contact us — we’d love to hear from you.

Bitcoin RPC, real-time and comprehensive Bitcoin mempool & transaction data, advanced indexing of UTXOs & balances, optimised for apps and dashboards.

Monitor Bitcoin asset balances and activity across multiple addresses, with automatic daily tracking and historical portfolio insights.

Fetch detailed information on all inscriptions, UTXOs, rare sats — everything you need to power an Ordinals experience.

Automate Ordinal inscriptions with advanced features. Estimate costs, create orders, and track inscription statuses seamlessly.

Automate Ordinal inscriptions with advanced features. Estimate costs, create orders, and track inscription statuses seamlessly.

Query Rune balances, metadata & trading data.

Integrate Runes into your apps without building infra.

Mint and etch Runes, with cost estimates, order management and execution.

✨ Welcome to the Xverse API

Build powerful Bitcoin applications with production-grade APIs used by Xverse wallet — now available to developers.

Our suite of APIs provides everything you need to interact with the modern Bitcoin ecosystem: from Ordinals and Runes, to Bitcoin-native swaps, inscriptions, and Bitcoin L2 integrations. Whether you're building wallets, DeFi platforms, NFT marketplaces, or cross-chain bridges, our infrastructure gives you access to reliable, real-time blockchain data and ready-to-use transaction workflows.

🚀 Why use the Xverse API?

We built these APIs to solve the real infrastructure problems we faced while building the Xverse wallet. Now we’re opening them up so Bitcoin developers can skip the heavy lifting and focus on building.

Your Bitcoin RPC, indexer, and data layer — all in one API.

With the Xverse API, you get:

• ⚡ Ultra-fast Bitcoin RPC and real-time mempool data — without running your own node

• 🧩 Advanced indexing for transaction history, UTXO data, and Bitcoin asset protocols

• 🔲 Comprehensive Ordinals, Runes & BRC-20 support — balances, parsing, and transaction data with zero custom indexing

• 💹 Live & historical market data for Bitcoin assets: Ordinals, Runes, BRC-20, and Bitcoin L2 tokens

• 💱 Swap aggregation across Bitcoin AMMs & L2s (Spark, Stacks, Starknet, BOB, Runes AMMs, BRC-20, etc.)

• 📊 Portfolio analytics with real-time activity and daily balance history

• ✍️ Automated minting, etching & inscription at scale — simple endpoints that handle high volumes without custom scripts

• 🌉 Cross-chain swaps & bridging with aggregated liquidity — one interface to move assets seamlessly across Bitcoin and L2s

• 🤖 ⚡ Pay-per-request API access via Lightning — every endpoint accepts payment over the Machine Payments Protocol (MPP) at 1 sat per call. Built for AI agents that don't want to manage API keys.

🧰 What’s Inside

Our API suite is organized into powerful modules that serve different needs across the Bitcoin ecosystem:

⚙️ How It Works

All endpoints are RESTful and return JSON responses. You can use them with your preferred stack — whether you're writing in JavaScript, Python, Rust, or anything else.

Authentication, rate limits, and response formats will be covered in the Getting Started section.

Need autonomous, machine-payable access without an API key? See MPP Lightning Payments.

🧑‍💻 Built for Builders

This API suite powers real products — including the Xverse wallet and app — and is optimized for scale, speed, and uptime.

✅ >99% Uptime ⚡ Low-latency responses 🔒 Secure & production-tested 📈 Scalable for any app size

💡 Start Building

If you're ready to dive in, check out our Getting Started guide or get your API key to start exploring endpoints.

Looking to integrate specific functionality like portfolio monitoring, swaps or Ordinals support? Each section is fully documented with example requests, response formats, and real-world use cases.

The Xverse API supports the Machine Payments Protocol (MPP) — a pay-per-request authentication method over the Lightning Network. Instead of provisioning an API key, your client can pay a small Lightning invoice for each request.

This is built for AI agents and autonomous clients that need to access the API without human-managed credentials. Agents using the Xverse Agent Wallet handle MPP payments transparently — the agent calls an endpoint, the wallet pays the Lightning invoice in the background, and the response comes back. No checkout, no human approval, no API key.

MPP is an open standard defined at mpp.dev. Any Lightning-compatible wallet or SDK can use it.

🔁 How it works

MPP uses an HTTP 402 challenge-response flow:

Step 1 — Request without credentials

Send a request to any endpoint without an x-api-key or Authorization header. The server responds with HTTP 402 Payment Required and a Lightning invoice challenge in the WWW-Authenticate header:

GET /v1/bitcoin/price HTTP/1.1
Host: api.secretkeylabs.io

HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment id="<challenge-id>", realm="https://api.secretkeylabs.io", method="lightning", amount="1", ...
Cache-Control: no-store
Content-Type: application/problem+json

{
  "type": "https://paymentauth.org/problems/payment-required",
  "title": "Payment Required",
  "status": 402
}

The WWW-Authenticate header contains everything needed to pay the invoice, including the Lightning payment details and the amount in satoshis.

Step 2 — Pay the Lightning invoice

Extract the Lightning invoice from the 402 challenge and pay it using any Lightning-compatible wallet or SDK. Upon successful payment, you receive a preimage — the cryptographic proof of payment.

Step 3 — Retry with the payment credential

Retry the same request with the payment credential in the Authorization header:

GET /v1/bitcoin/price HTTP/1.1
Host: api.secretkeylabs.io
Authorization: Payment <base64url-encoded-credential>

The credential contains the preimage and is bound to the route it was issued for. On success, the server returns the API response along with a Payment-Receipt header:

HTTP/1.1 200 OK
Payment-Receipt: <base64url-encoded-receipt>
Content-Type: application/json

{ ... }

💰 Pricing

All API endpoints are priced at 1 satoshi per request.

🔐 Authentication methods

Every endpoint supports two authentication methods. You can use either one:

If both headers are present, MPP is checked first. If MPP verification fails but an API key is present, the request falls back to API key authentication.

MPP-authenticated requests bypass rate limiting — you pay per request instead.

🛣️ Route binding

Payment credentials are bound to the specific endpoint they were issued for. A credential obtained for /v1/bitcoin/price cannot be reused on /v1/runes. Attempting to use a credential on a different route returns HTTP 403 Forbidden:

{
  "type": "https://paymentauth.org/problems/invalid-credential",
  "title": "Forbidden",
  "status": 403,
  "detail": "Credential was issued for /v1/bitcoin/price, not /v1/runes"
}

⚠️ Error responses

🤖 Built for AI agents

MPP is designed for autonomous AI agent workflows. Agents can detect 402 challenges, pay Lightning invoices, and retry with credentials — enabling fully autonomous access to Bitcoin data and services.

Xverse Agent Wallet

The Xverse Agent Wallet is purpose-built for AI agents that need to interact with Bitcoin. An AI agent equipped with Xverse Agent Wallet can autonomously call any MPP-enabled endpoint and handle the Lightning payment without human intervention.

The agent wallet manages:

• Lightning payments for MPP 402 challenges

• Key management and credential handling

• Automatic retry with payment credentials

This is the simplest way to give your AI agent full access to the Xverse API via MPP. From the agent's CLI:

# Preview cost (dry run)
xverse-wallet pay request https://api.secretkeylabs.io/v1/bitcoin/price --json

# Execute the paid request
xverse-wallet pay request https://api.secretkeylabs.io/v1/bitcoin/price --yes --json

# Discover MPP-enabled endpoints
xverse-wallet pay api --json

See the for the full agent workflow.

Other integrations

You can also integrate MPP using any Lightning-compatible wallet or SDK. Libraries like mppx provide client SDKs that handle the 402 challenge-response flow automatically, and any Spark-compatible wallet can be used for Lightning payments.

📚 Example: full flow

A complete example using curl:

1. Request without credentials (get the 402 challenge):

curl -i https://api.secretkeylabs.io/v1/bitcoin/price

2. Parse the WWW-Authenticate header, extract the Lightning invoice, and pay it using your wallet.

3. Retry with the payment credential:

curl -H "Authorization: Payment <base64url-credential>" \
  https://api.secretkeylabs.io/v1/bitcoin/price

The response includes a Payment-Receipt header confirming the payment was processed.

🟢 Available endpoints

Every endpoint in the Xverse API supports MPP Lightning payments — Bitcoin, Blocks, BRC-20, Inscriptions, Ordinals, Runes, Spark, Swaps, Subscriptions, Portfolio, and Bitcoin RPC (v1 and v2).

Browse the live catalog from the Agent Wallet CLI:

xverse-wallet pay api --json

Or see the full module reference:

• Bitcoin API

• Ordinals API

• Runes API

Returns the balance and a paginated list of transaction IDs for a given Bitcoin address. Fully mempool-aware.

This endpoint returns the combined historical activity across BTC, inscriptions, and runes for a set of addresses, including all incoming/outgoing transfers.

This endpoint returns the real-time mempool activity across BTC, inscriptions, and runes for a set of addresses, including all incoming/outgoing transfers.

This endpoint returns confirmation status, block height, and timestamp for a given Bitcoin transaction. Mempool-aware.

This endpoint returns the raw hex for a given Bitcoin transaction. It supports confirmed and unconfirmed transactions.

This endpoint decodes a raw Bitcoin transaction. Optimized to use the RPC node only for parsing, while transaction hex and I/O data are retrieved from our indexer.

This endpoint returns detailed info on Ordinal assets (BTC, inscriptions, runes) for each input and output of a transaction.

It is mempool-aware and includes unconfirmed BTC, inscriptions & runes data for mempool transactions

This endpoint returns detailed info on Ordinal assets (BTC, inscriptions, runes) for each output of a transaction.

It is mempool-aware and includes unconfirmed BTC, inscriptions & runes data for mempool transactions

This endpoint returns detailed info on Ordinal assets (BTC, inscriptions, runes) for each input of a transaction.

It is mempool-aware and includes unconfirmed BTC, inscriptions & runes data for mempool transactions

Estimate the approximate fee per kilobyte required for a transaction to confirm in the next blocks, based on the current state of the mempool.

This endpoint can be used to post a signed raw transaction to the Bitcoin network

This endpoint lets you run a mempool acceptance test to check if the mempool will accept the serialized hex-encoded raw transaction

Returns the latest Bitcoin block with height, hash, timestamp, and more.

Returns block metadata (hash, timestamp, tx count, etc.) for a specific height.

This endpoint offers a unified RPC interface for Bitcoin Core node functionality:

• Blockchain data: getbestblockhash, getblock, getblockchaininfo, getblockcount, getblockfilter, getblockhash, getblockheader, getblockstats, getchaintips, getchaintxstats, getdifficulty

• Mempool data: getmempoolancestors, getmempooldescendants, getmempoolentry, getmempoolinfo, getrawmempool, testmempoolaccept

• Transactions: getrawtransaction, sendrawtransaction, gettxout, gettxoutproof

• Raw tx/script utils: createrawtransaction, decoderawtransaction, decodescript

• Wallet & addresses: createmultisig, validateaddress, verifymessage

• Fees: estimatesmartfee

This RPC Method returns the hash of the tip block in the most-work fully-validated chain.

This RPC Method returns information about the block.

This RPC Method returns an object that contains the information regarding blockchain processing in different states.

This RPC Method returns the height of the fully-validated chain. The genesis block has a height of 0.

This RPC Method returns the BIP-157 compact block filter and filter header for a given block.

This RPC Method returns the hash of the block provided its height.

This RPC Method returns the header of the block given it's hash.

This RPC Method calculates per block statistics for a given window.

This RPC Method returns information about all known chaintips in the block tree, including the main chain as well as orphaned branches.

This RPC Method calculates data about the total number and rate of transactions in the chain.

This RPC Method returns the proof-of-work difficulty as a multiple of the minimum difficulty.

This RPC Method returns all in-mempool ancestors for a transaction in the mempool.

This RPC Method returns all in-mempool descendants for a transaction in the mempool.

This RPC Method returns detailed mempool entry data for a specific transaction.

This RPC Method returns mempool statistics such as size, bytes, usage, and limits.

This RPC Method returns all transaction IDs currently in the mempool.

This RPC Method returns details about an unspent transaction output (UTXO).

This RPC Method returns a proof that specific transactions are included in a block.

This RPC Method creates an unsigned raw transaction from inputs and outputs.

This RPC Method decodes a serialized raw transaction hex into a JSON object.

This RPC Method decodes a hex-encoded script into a JSON object.

This RPC Method returns detailed information about a raw transaction by txid.

This RPC Method submits a raw signed transaction to the network.

This RPC Method tests whether a raw transaction would be accepted by the mempool.

This RPC Method creates a multisig address and redeem script from a set of public keys.

This RPC Method estimates the transaction fee per kilobyte needed for confirmation within a target number of blocks.

This RPC Method verifies whether a Bitcoin address is valid and provides related info.

This RPC Method verifies that a signed message was created with the private key corresponding to a given address.

This endpoint can be used to get the latest Bitcoin price

Use this endpoint to register a portfolio address for continuous balance tracking.

Xverse API will automatically keep its daily balance and activity updated.

This endpoint returns all the registered portfolio addresses for the current API key.

Use this endpoint to retrieve the daily balance history for a registered portfolio address over a specific time period.

The Xverse API lets you watch blockchain addresses and receive transaction events as they happen.

This is built for apps that need to react to on-chain activity — without polling — such as wallets, payment flows, portfolio trackers, and backend reconciliation systems.

Address watching is currently available for Bitcoin. Support for Spark and Starknet webhooks is coming soon.

Webhooks are how Xverse delivers address activity events to your application.

Once a webhook subscription is registered for a set of addresses:

This endpoint returns all Ordinal collections held by a given wallet address, along with the list of inscriptions owned within each collection.

This endpoint is used to retrieve the metadata & market data associated with an ordinal collection, based on the ordinal collection ID.

This endpoint provides the top collections by sales volume for different time periods, along with collections' metadata & market data.

This endpoint returns the full list of indexed Ordinals collections with their basic information and metadata

This endpoint is commonly used to pass an ordinal collection ID, and get the full list of wallets holding inscriptions in that collection, and the number of items of the collection they hold.

This endpoint is commonly used to retrieve the list of inscriptions associated with an ordinal collection, together with their info and metadata.

This endpoint provides the historical floor price for a specific collection and a given time period.

This endpoint provides the historical floor price for a specific collection and a given time period.

Collection prices are sourced from multiple ordinals marketplaces.

This endpoint returns the information & metadata of a specific inscription ID.

Returns a generated thumbnail image for the specified inscription ID

This endpoint returns the information & metadata for multiple inscription IDs in a single request.

This endpoint returns the full activity history (transfers, listings, sales) for a specific inscription.

Returns historical activity (transfers, mints, etc.) for a specific Rune held by a given address.

This endpoint is used to retrieve the metadata & market data associated with a rune, based on the rune ID.

This endpoint is used to retrieve the metadata & market data associated with a batch of up to 10 runes, based on the runes' IDs, in a single request.

Search existing Runes by name, order results by name or by etching block + index.

This endpoint is commonly used to pass a rune ID, and get the full list of wallets holding the rune, and the amount they hold.

The Xverse MCP server provides a standardized interface that allows any compatible AI model or agent to access Bitcoin blockchain data through the Xverse API — including Bitcoin transactions, Ordinals, Runes, BRC-20, Spark, and swap quotes.

Connect to the MCP server natively in Claude, Cursor, and other clients, or use the mcp-remote module for backwards compatibility with clients that do not support remote MCP.

The Xverse MCP server is centrally hosted, uses Streamable HTTP transport, and authenticates with your existing Xverse API key. It exposes 54 read-only tools across Bitcoin, Ordinals, Runes, BRC-20, Spark, and Swaps — with more functionality on the way.

Setup Instructions

General

The MCP server supports Streamable HTTP transport and authenticates via your Xverse API key passed as a Bearer token:

https://mcp.secretkeylabs.io/mcp

Authentication: Authorization: Bearer <your-api-key>

You can get an API key from the Get Started page.

Then run /mcp once you've opened a Claude Code session to verify the connection.

CTRL/CMD + , to open Cursor settings. Navigate to the MCP tools page and add a new server with the following configuration:

CTRL/CMD + P and search for MCP: Add Server. Select Command (stdio) and enter:

Enter the name Xverse and hit enter. Activate the server using MCP: List Servers, selecting Xverse, and selecting Start Server.

Alternatively, add to your VS Code MCP settings file:

Run the following command in Terminal:

If this is your first MCP in Codex, enable the rmcp feature first:

CTRL/CMD + , to open Windsurf settings. Scroll to Cascade → MCP servers, select Add Server → Add custom server, and add:

CMD + , to open Zed settings. Add the following:

Many tools now support MCP servers. Configure them with the following settings:

The MCP server exposes 54 read-only tools organized by domain. All tools correspond to endpoints in the Xverse API.

The MCP server uses your Xverse API key as a Bearer token. Pass it in the Authorization header on connection. The same API key you use for REST API calls works with the MCP server — no separate credentials needed.

Yes, at the https://mcp.secretkeylabs.io/mcp endpoint.

No. The MCP server is currently read-only. It provides data access and swap quotes but does not execute transactions, mint tokens, or modify any on-chain state. Write operations may be added in the future.

The same rate limits from your Xverse API plan apply. If you hit a rate limit, the MCP server will return an error with Retry-After guidance so the AI agent can wait and retry automatically.

1. Verify your API key is valid and correctly formatted (UUID format: 8-4-4-4-12 hex characters).

2. If using mcp-remote, make sure you have a recent version of Node.js installed.

3. Try clearing cached auth info: rm -rf ~/.mcp-auth

Any client that supports the can connect. This includes Claude (Code, Desktop, and claude.ai), Cursor, VS Code, Codex, Windsurf, Zed, and many others. Clients that support Streamable HTTP can connect directly; older clients can use the mcp-remote bridge.