# Xverse Developer Documentation Build with the world's leading Bitcoin self-custodial platform ## Build on Bitcoin with Xverse [Xverse](https://www.xverse.app/) is the Bitcoin super-app trusted by nearly 2 million users β€” built for payments, trading, earning, and borrowing across Bitcoin, Lightning, [Spark](https://www.spark.money/), [Starknet](https://www.starknet.io/), and [Stacks](https://www.stacks.co/). The infrastructure behind it is now open to developers. Whether you're building a Bitcoin app, a data service, or an AI agent, Xverse gives you the tools to ship on Bitcoin and Bitcoin layers without running your own nodes, indexers, or infrastructure. ## What are you building? ### **Xverse API** - The Data Layer for Bitcoin Apps {% columns %} {% column %} REST APIs for real-time and historical Bitcoin data β€” no node, no indexer, no custom infrastructure required. * Bitcoin RPC, mempool, UTXOs, and balances. * Portfolio indexing, analytics, and market data for Bitcoin, Spark, Starknet, Stacks. * Ordinals, Runes, BRC-20, and inscription services. * Swap aggregation across Bitcoin AMMs and Bitcoin L2s. Get started MCP server {% endcolumn %} {% column %} {% code title="" overflow="wrap" %} ```http GET /v2/bitcoin/address/{address}/utxo HTTP/1.1 Host: api.secretkeylabs.io x-api-key: YOUR_API_KEY Accept: */* ``` {% endcode %} {% endcolumn %} {% endcolumns %} *** ### **Sats Connect -** The Wallet SDK for Bitcoin Apps {% columns %} {% column %} Build apps that connect to users' Bitcoin wallets. Send transactions, request signatures, and interact with the full Bitcoin asset stack β€” BTC, Ordinals, Runes, BRC-20, Spark, Stacks, and Starknet. * Bitcoin PSBTs, transfers, and message signing. * Ordinals, Runes, and BRC-20 operations. * Spark, Stacks, and Starknet support. * \~2 million downloads. Used by leading BitcoinFi apps. Get started AI Agent integration {% endcolumn %} {% column %} {% code title="index.js" overflow="wrap" %} ```javascript import { request, BitcoinNetworkType, RpcErrorCode, } from "sats-connect"; try { const response = await request('signPsbt', { psbt: psbtBase64, signInputs: { "1ef9...Jn1r": [0], "bc1p...ra4w": [1,2], }, }); ``` {% endcode %} {% endcolumn %} {% endcolumns %} *** ### **Xverse Agent Wallet -** The Agent Economy on Bitcoin Rails {% columns %} {% column width="50%" %} Give your AI agent a Bitcoin-native wallet that can pay, receive, and trade programmatically across Lightning, Spark, and Starknet. No custodian, no permissions to ask for, and no infrastructure to run. * ⚑ **Pay and get paid on Lightning** request invoices, settle instantly, sub-cent fees. The natural primitive for any agent that needs to charge for or consume a service on Bitcoin rails. * πŸ”² **Trade Runes & Ordinals** directly from the agent, no intermediary. * 🌐 **Trade on Starknet** β€” Bitcoin assets, stables, RWAs with high throughput & low fees. * ⚑ **Trade on Flashnet** via Spark β€” the cheapest way to move Bitcoin assets. Get started Agent Mode {% endcolumn %} {% column width="50%" %} {% code title="johndoe\@john-mbp \~ %" overflow="wrap" %} ```bash xverse [my-agent.com] mainnet:0> --agent my-agent.com bitcoin balance BTC Balance: +------------------+-----------+-------------+ | Address Type | Confirmed | Unconfirmed | +------------------+-----------+-------------+ | Native Segwit | 0.1823 | 0.0000 | | Taproot | 0.0412 | 0.0050 | +------------------+-----------+-------------+ | Total | 0.2235 | 0.0050 | +------------------+-----------+-------------+ ``` {% endcode %} {% endcolumn %} {% endcolumns %} ## Not sure where to start? | I want to… | Use this | | -------------------------------------------------- | ------------------------------------------------------------------------------------------ | | Let users connect their wallet to my app | [Sats Connect](/sats-connect) | | Request transaction signatures from my users | [Sats Connect](/sats-connect) | | Query balances, UTXOs, or mempool data server-side | [Xverse API](/api) | | Fetch Ordinals, Runes, or BRC-20 data | [Xverse API](/api) | | Get market data or floor prices | [Xverse API](/api) | | Give my AI agent a Bitcoin wallet to pay and trade | [Agent Wallet](/xverse-agentic-wallet#the-first-bitcoin-native-wallet-built-for-ai-agents) | | Use Bitcoin data inside Claude or Cursor | [MCP Server](/api/mcp-server) | | Build a full-stack Bitcoin app | Both [Xverse API](/api) + [Sats Connect](/sats-connect) | ## Developer resources

:discord:

Discord communityPost questions, feature requests, get help, and share resources with other developers.Join Discord

:github:

GitHubCheck out our GitHub repository and submit your first PR.Go to Github
# Xverse API ## ✨ Welcome to the Xverse API Build powerful Bitcoin applications with production-grade APIs used by [Xverse wallet ](https://www.xverse.app/)β€” 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:
ModuleDescription
🟠 BitcoinBitcoin RPC, real-time and comprehensive Bitcoin mempool & transaction data, advanced indexing of UTXOs & balances, optimised for apps and dashboards.
πŸ’Ή Portfolio API &
πŸ‘€ Watch Addresses		Monitor Bitcoin asset balances and activity across multiple addresses, with automatic daily tracking and historical portfolio insights.
πŸ–ΌοΈ OrdinalsFetch 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.
πŸ”² RunesQuery Rune balances and detailed information.
Integrate Runes into your apps without building infra.
Mint and etch Runes, with cost estimates, order management and execution.
πŸͺ™ BRC-20Query BRC-20 balances and detailed information. Integrate BRC-20 into your apps without building infra.

Mint and deploy BRC-20, with cost estimates, order management and execution.
:sparkle: Spark

Query Spark balances, transactions & activity for Bitcoin & BTKN tokens. Access Flashnet market & trading data.

Integrate Spark & Flashnet into your apps without building infra.

πŸ”„ Swap Aggregator Seamlessly integrate Bitcoin-asset swaps into your application. Aggregate quotes from multiple AMMs across Bitcoin and L2s, generate and execute swap orders, and facilitate cross-chain swapsβ€”all through a unified interface.
*** ### βš™οΈ 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](/api/get-started) section. Need autonomous, machine-payable access without an API key? See [MPP Lightning Payments](/api/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](/api/get-started) guide or [get your API key](https://api-dashboard.xverse.app/login) 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. # Get Started ## :electric\_plug: Endpoints
NetworkEndpoint URL
Mainnethttps://api.secretkeylabs.io
Signethttps://api-signet.secretkeylabs.io
## :key: Get your API keys [Start your free trial to get API keys](https://api-dashboard.xverse.app/login). 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)**](/api/mpp-lightning-payments) β€” 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. ## :speech\_balloon: Developer Support & Feedback Have feedback, feature requests, or want to partner? [Contact us](https://discord.com/invite/tN84HhSDrz) β€” we’d love to hear from you.
# ⚑ MPP Lightning Payments 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](https://docs.xverse.app/xverse-agentic-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](https://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: ```http GET /v1/bitcoin/price HTTP/1.1 Host: api.secretkeylabs.io ``` ```http HTTP/1.1 402 Payment Required WWW-Authenticate: Payment 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: ```http GET /v1/bitcoin/price HTTP/1.1 Host: api.secretkeylabs.io Authorization: Payment ``` 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 HTTP/1.1 200 OK Payment-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: | Method | Header | Description | | --------------- | ------------------------------------- | ----------------------------------------------- | | **API Key** | `x-api-key: ` | Traditional API key with rate limiting | | **MPP Payment** | `Authorization: Payment ` | Pay-per-request via Lightning, no rate limiting | 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**: ```json { "type": "https://paymentauth.org/problems/invalid-credential", "title": "Forbidden", "status": 403, "detail": "Credential was issued for /v1/bitcoin/price, not /v1/runes" } ``` ### ⚠️ Error responses | Status Code | Meaning | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | **402 Payment Required** | No payment credential provided. Response includes a Lightning invoice challenge in the `WWW-Authenticate` header. | | **403 Forbidden** | Payment credential is valid but was issued for a different route. | | **500 Payment service unavailable** | The payment service encountered an error. Retry the request. | ### πŸ€– 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**](https://docs.xverse.app/xverse-agentic-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: ```bash # 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 [Machine Payments page in the Agent Wallet docs](/xverse-agentic-wallet/guides/agentic-lightning-commerce#step-4-call-paid-apis-automatically-mpp) for the full agent workflow. #### Other integrations You can also integrate MPP using any Lightning-compatible wallet or SDK. Libraries like [`mppx`](https://www.npmjs.com/package/mppx) provide client SDKs that handle the 402 challenge-response flow automatically, and any [Spark](https://www.spark.money/)-compatible wallet can be used for Lightning payments. ### πŸ“š Example: full flow A complete example using `curl`: **1. Request without credentials (get the 402 challenge):** ```bash 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:** ```bash curl -H "Authorization: Payment " \ 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: ```bash xverse-wallet pay api --json ``` Or see the full module reference: * [Bitcoin API](/api/bitcoin) * [Ordinals API](/api/ordinals) * [Runes API](/api/runes) * [BRC-20 API](/api/brc-20) * [Spark API](/api/spark) * [Portfolio API](/api/portfolio) * [Swap Aggregator](/api/swaps) # MCP Server 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](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#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 ` You can get an API key from the Get Started page. *** ### Claude Code ```bash claude mcp add --transport http xverse https://mcp.secretkeylabs.io/mcp \ --header "Authorization: Bearer " ``` Then run `/mcp` once you've opened a Claude Code session to verify the connection. *** ### Cursor `CTRL/CMD` + `,` to open Cursor settings. Navigate to the MCP tools page and add a new server with the following configuration: ```json { "mcpServers": { "xverse": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.secretkeylabs.io/mcp", "--header", "Authorization: Bearer " ] } } } ``` *** ### Visual Studio Code `CTRL/CMD` + `P` and search for **MCP: Add Server**. Select **Command (stdio)** and enter: ``` npx mcp-remote https://mcp.secretkeylabs.io/mcp --header "Authorization: Bearer " ``` 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: ```json { "mcpServers": { "xverse": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.secretkeylabs.io/mcp", "--header", "Authorization: Bearer " ] } } } ``` *** ### Codex Run the following command in Terminal: ```bash codex mcp add xverse --url https://mcp.secretkeylabs.io/mcp ``` If this is your first MCP in Codex, enable the `rmcp` feature first: ```toml # ~/.codex/config.toml [features] experimental_use_rmcp_client = true ``` *** ### Windsurf `CTRL/CMD` + `,` to open Windsurf settings. Scroll to **Cascade β†’ MCP servers**, select **Add Server β†’ Add custom server**, and add: ```json { "mcpServers": { "xverse": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.secretkeylabs.io/mcp", "--header", "Authorization: Bearer " ] } } } ``` *** ### Zed `CMD` + `,` to open Zed settings. Add the following: ```json { "context_servers": { "xverse": { "source": "custom", "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.secretkeylabs.io/mcp", "--header", "Authorization: Bearer " ], "env": {} } } } ``` *** ### Others Many tools now support MCP servers. Configure them with the following settings: | Setting | Value | | --------------- | ------------------------------------------------------------------------------------------------ | | **Command** | `npx` | | **Arguments** | `-y mcp-remote https://mcp.secretkeylabs.io/mcp --header "Authorization: Bearer "` | | **Environment** | None | *** ## Available Tools The MCP server exposes 54 read-only tools organized by domain. All tools correspond to endpoints in the Xverse API. ### 🟠 Bitcoin | Tool | Description | | ------------------------------------- | ---------------------------------------------------------------- | | `bitcoin_get_fee_estimates` | Current mempool fee estimates for next blocks | | `bitcoin_get_mempool_stats` | Projected mempool block statistics | | `bitcoin_get_transaction` | Transaction details including inputs, outputs, and confirmations | | `bitcoin_get_transaction_hex` | Raw transaction hex | | `bitcoin_get_address_balance` | Confirmed and unconfirmed balance for an address | | `bitcoin_get_address_utxos` | Mempool-aware UTXOs with inscription filtering | | `bitcoin_get_address_summary` | Address summary with recent transaction IDs | | `bitcoin_get_address_unconfirmed_txs` | Pending mempool transactions for an address | | `bitcoin_get_price` | Current BTC price | ### πŸ–ΌοΈ Ordinals & Collections | Tool | Description | | -------------------------------------- | ------------------------------------------ | | `ordinals_get_address_utxos` | UTXOs containing inscriptions or rare sats | | `ordinals_get_address_inscriptions` | Inscriptions owned by an address | | `ordinals_get_address_collections` | Collections held by an address | | `ordinals_get_inscription` | Single inscription details | | `ordinals_get_inscription_activity` | Inscription transfer history | | `ordinals_batch_get_inscriptions` | Batch inscription lookup (max 25) | | `ordinals_get_transaction` | Inscription-enriched transaction details | | `ordinals_get_transaction_inputs` | Inscription-enriched transaction inputs | | `ordinals_get_transaction_outputs` | Inscription-enriched transaction outputs | | `ordinals_batch_get_outputs` | Batch output details (max 20) | | `ordinals_list_collections` | Browse ordinal collections | | `ordinals_get_collection` | Collection metadata and market info | | `ordinals_get_collection_holders` | Collection holder list | | `ordinals_get_collection_inscriptions` | Inscriptions in a collection | | `ordinals_get_collection_floor_prices` | Historical floor price data | | `ordinals_top_collections_by_volume` | Top collections ranked by trading volume | ### πŸ”² Runes | Tool | Description | | ---------------------------- | -------------------------------------------------------- | | `runes_get_address_balances` | All Runes balances for an address | | `runes_get_address_activity` | Rune activity for a specific address and rune | | `runes_get_address_utxos` | Mempool-aware Rune UTXOs | | `runes_get_info` | Rune details β€” supply, symbol, divisibility, market data | | `runes_get_holders` | Top holders for a rune | | `runes_get_activity` | Recent transfer and mint activity | | `runes_batch_get_info` | Batch rune info (max 10) | | `runes_top_by_volume` | Top runes ranked by trading volume | | `runes_top_gainers_losers` | Top gainers and losers by price change | | `runes_get_floor_prices` | Historical floor price data | | `runes_decode_runestone` | Decode runestone data from raw transaction hex | ### πŸͺ™ BRC-20 | Tool | Description | | ------------------------------------- | -------------------------------------------- | | `brc20_get_address_balances` | All BRC-20 balances for an address | | `brc20_get_address_ticker_balance` | Balance for a specific BRC-20 token | | `brc20_get_address_unspent_transfers` | Unspent BRC-20 transfer inscriptions | | `brc20_get_ticker_info` | Token details β€” supply, holders, deploy info | | `brc20_batch_get_tickers` | Batch BRC-20 token info | ### ⚑ Spark | Tool | Description | | -------------------------------- | ----------------------------------------- | | `spark_get_token_info` | Token info with pool metadata and pricing | | `spark_get_token_holders` | Token holder list | | `spark_get_token_transactions` | Token transaction history | | `spark_get_token_details` | Token details or search by name/ticker | | `spark_get_address_balances` | All BTKN token balances for an address | | `spark_get_address_transactions` | Address transaction history | | `spark_get_address_summary` | Address summary | | `spark_get_transaction` | Transaction details | | `spark_get_latest_transactions` | Latest network transactions | | `spark_get_token_rankings` | Top tokens by volume and TVL | | `spark_batch_get_token_metadata` | Batch token metadata (max 100) | ### πŸ”„ Swaps | Tool | Description | | ------------------------------ | ----------------------------------------------------- | | `swaps_get_destination_tokens` | Available destination tokens for a swap | | `swaps_get_quotes` | Aggregated swap quotes from multiple AMMs (read-only) | *** ## FAQ #### What authentication does the MCP server use? 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. #### Does the MCP support Streamable HTTP? Yes, at the `https://mcp.secretkeylabs.io/mcp` endpoint. #### Can the MCP server execute transactions? 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. #### What rate limits apply? 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. #### I'm getting connection errors β€” what should I do? 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` and reconnect. #### Which AI clients are supported? Any client that supports the [Model Context Protocol](https://modelcontextprotocol.io) 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. # Bitcoin Bitcoin RPC, real-time and comprehensive **Bitcoin mempool & transaction data**, advanced indexing of **UTXOs & balances**, optimised for apps and dashboards. # Address # Balance ## GET /v1/bitcoin/address/{address}/balance > Get both confirmed and unconfirmed BTC balances. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Bitcoin"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/bitcoin/address/{address}/balance":{"get":{"tags":["Bitcoin"],"description":"Get both confirmed and unconfirmed BTC balances. ","parameters":[{"schema":{"minLength":10,"default":"bc1q0egjvlcfq77cxd9kvpgppyuxckzvws46e3sxch","format":"BitcoinAddress","type":"string"},"in":"path","name":"address","required":true}],"responses":{"200":{"description":"Bitcoin balance for an address","content":{"application/json":{"schema":{"description":"Bitcoin balance for an address","type":"object","properties":{"address":{"type":"string"},"confirmed":{"type":"object","properties":{"fundedTxoCount":{"type":"number"},"fundedTxoSum":{"type":"number"},"spentTxoCount":{"type":"number"},"spentTxoSum":{"type":"number"},"txCount":{"type":"number"}},"required":["fundedTxoCount","fundedTxoSum","spentTxoCount","spentTxoSum","txCount"]},"unconfirmed":{"type":"object","properties":{"fundedTxoCount":{"type":"number"},"fundedTxoSum":{"type":"number"},"spentTxoCount":{"type":"number"},"spentTxoSum":{"type":"number"},"txCount":{"type":"number"}},"required":["fundedTxoCount","fundedTxoSum","spentTxoCount","spentTxoSum","txCount"]}},"required":["address","confirmed","unconfirmed"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Bitcoin Address Summary Returns the balance and a paginated list of transaction IDs for a given Bitcoin address. Fully mempool-aware. ## GET /v1/bitcoin/address/{address}/summary > Get address summary including paginated transaction IDs and balance information.\ > This endpoint is mempool-aware and includes both confirmed and unconfirmed data.\ > \
\
\ > \Response fields:\\ > \
    \ > \
  • \txids\ - Paginated list of transaction IDs for this address, ordered by block height\ > descending.\ > When there is mempool activity, unconfirmed transactions appear first.\
    • \ > \
  • \confirmedBalance\ - Current confirmed balance in satoshis, ignoring mempool activity.\
    • \ > \
  • \unconfirmedBalance\ - Net unconfirmed balance change (received - sent) in satoshis.\ > It can be negative as it only considers mempool, eg. when spending more than receiving.\
    • \ > \
  • \offset\ - Current pagination offset.\
    • \ > \
  • \limit\ - Current pagination limit.\
    • \ > \
\ > \
\ > ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Bitcoin"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/bitcoin/address/{address}/summary":{"get":{"tags":["Bitcoin"],"description":"Get address summary including paginated transaction IDs and balance information.\n This endpoint is mempool-aware and includes both confirmed and unconfirmed data.\n

\n Response fields:\n
    \n
  • txids - Paginated list of transaction IDs for this address, ordered by block height\n descending.\n When there is mempool activity, unconfirmed transactions appear first.
    • \n
  • confirmedBalance - Current confirmed balance in satoshis, ignoring mempool activity.
    • \n
  • unconfirmedBalance - Net unconfirmed balance change (received - sent) in satoshis.\n It can be negative as it only considers mempool, eg. when spending more than receiving.
    • \n
  • offset - Current pagination offset.
    • \n
  • limit - Current pagination limit.
    • \n
\n
\n ","parameters":[{"schema":{"default":0,"minimum":0,"multipleOf":25,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":25,"minimum":25,"maximum":25,"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"minLength":10,"default":"bc1q0egjvlcfq77cxd9kvpgppyuxckzvws46e3sxch","format":"BitcoinAddress","type":"string"},"in":"path","name":"address","required":true}],"responses":{"200":{"description":"Address summary with txids and balance","content":{"application/json":{"schema":{"description":"Address summary with txids and balance","type":"object","properties":{"txids":{"type":"array","items":{"type":"string"}},"confirmedBalance":{"type":"string"},"unconfirmedBalance":{"type":"string"},"offset":{"type":"number"},"limit":{"type":"number"}},"required":["txids","confirmedBalance","unconfirmedBalance","offset","limit"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # \[v1] Get Bitcoin UTXOs {% hint style="info" %} We recommend switching to [\[v2\] UTXOs](/api/bitcoin/address/v2-get-bitcoin-utxos-mempool-aware) for real-time mempool support {% endhint %} ## GET /v1/bitcoin/address/{address}/utxo > Retrieve confirmed UTXOs ignoring mempool completely. This can be useful for applications that\ > need to rely on confirmed UTXOs only, eg constructing RBF txs as well.\ > To query mempool aware endpoint use \ /v2/bitcoin/address/:address/utxo\.\ > \
\ > Iterate using offset if hasMore is true. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Bitcoin"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/bitcoin/address/{address}/utxo":{"get":{"tags":["Bitcoin"],"description":"Retrieve confirmed UTXOs ignoring mempool completely. This can be useful for applications that\n need to rely on confirmed UTXOs only, eg constructing RBF txs as well.\n To query mempool aware endpoint use /v2/bitcoin/address/:address/utxo.\n
\n Iterate using offset if hasMore is true.","parameters":[{"schema":{"default":0,"minimum":0,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":60,"minimum":25,"maximum":5000,"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"minLength":10,"default":"bc1q0egjvlcfq77cxd9kvpgppyuxckzvws46e3sxch","format":"BitcoinAddress","type":"string"},"in":"path","name":"address","required":true}],"responses":{"200":{"description":"Paginated Utxo list","content":{"application/json":{"schema":{"description":"Paginated Utxo list","type":"object","properties":{"hasMore":{"type":"boolean"},"items":{"type":"array","items":{"type":"object","properties":{"txid":{"type":"string"},"vout":{"type":"number"},"value":{"type":"number"},"status":{"type":"object","properties":{"confirmed":{"type":"boolean"},"blockHeight":{"type":"number"},"blockHash":{"type":"string"},"blockTime":{"type":"number"}},"required":["confirmed","blockHeight","blockHash","blockTime"]}},"required":["txid","vout","value","status"]}}},"required":["hasMore","items"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # \[v2] Get Bitcoin UTXOs (Mempool-Aware) ## GET /v2/bitcoin/address/{address}/utxo > Mempool-aware: Retrieve UTXOs. This endpoint considers both confirmed and unconfirmed\ > utxos. When a confirmed UTXO is spent in the mempool, it will not be returned here as its no longer a utxo.\ > To query confirmed-only endpoint use \ /v1/bitcoin/address/:address/utxo\.\ > \
\ > Iterate using offset if hasMore is true.\ > \
\
\ > \UTXO filtering:\\
\ > \excludeNonVoidProtocolInscriptionUtxos\ - When true, excludes UTXOs that hold valuable\ > inscriptions, but can include void protocol inscriptions (e.g. BRC-20, TAP spent inscriptions).\
\ > \excludeAllInscriptionUtxos\ - When true, excludes all inscription-bearing UTXOs,\ > including both valuable inscriptions(non-void protocol inscriptions) and void protocol inscriptions.\ > Implies \excludeNonVoidProtocolInscriptionUtxos=true\. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Bitcoin"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/bitcoin/address/{address}/utxo":{"get":{"tags":["Bitcoin"],"description":"Mempool-aware: Retrieve UTXOs. This endpoint considers both confirmed and unconfirmed\n utxos. When a confirmed UTXO is spent in the mempool, it will not be returned here as its no longer a utxo.\n To query confirmed-only endpoint use /v1/bitcoin/address/:address/utxo.\n
\n Iterate using offset if hasMore is true.\n

\n UTXO filtering:
\n excludeNonVoidProtocolInscriptionUtxos - When true, excludes UTXOs that hold valuable\n inscriptions, but can include void protocol inscriptions (e.g. BRC-20, TAP spent inscriptions).
\n excludeAllInscriptionUtxos - When true, excludes all inscription-bearing UTXOs,\n including both valuable inscriptions(non-void protocol inscriptions) and void protocol inscriptions.\n Implies excludeNonVoidProtocolInscriptionUtxos=true.","parameters":[{"schema":{"default":0,"minimum":0,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":60,"minimum":25,"maximum":5000,"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"default":false,"type":"boolean"},"in":"query","name":"excludeNonVoidProtocolInscriptionUtxos","required":false},{"schema":{"default":false,"type":"boolean"},"in":"query","name":"excludeAllInscriptionUtxos","required":false},{"schema":{"minLength":10,"default":"bc1q0egjvlcfq77cxd9kvpgppyuxckzvws46e3sxch","format":"BitcoinAddress","type":"string"},"in":"path","name":"address","required":true}],"responses":{"200":{"description":"Paginated Utxo list","content":{"application/json":{"schema":{"description":"Paginated Utxo list","type":"object","properties":{"hasMore":{"type":"boolean"},"items":{"type":"array","items":{"type":"object","properties":{"txid":{"type":"string"},"vout":{"type":"number"},"value":{"type":"number"},"status":{"type":"object","properties":{"confirmed":{"type":"boolean"},"blockHeight":{"type":"number"},"blockHash":{"type":"string"},"blockTime":{"type":"number"}},"required":["confirmed"]}},"required":["txid","vout","value","status"]}}},"required":["hasMore","items"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Activity # Historical Activity (Confirmed) This endpoint returns the combined historical activity across BTC, inscriptions, and runes for a set of addresses, including all incoming/outgoing transfers. ## GET /v1/global/ordinals/multi-address/activity > Retrieve efficient aggregated confirmed history (Bitcoin, Runes, Inscriptions) for multiple\ > addresses. \
\ > Up to 3 addresses(comma separated) can be queried via \addresses\ query param. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Bitcoin"},{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/global/ordinals/multi-address/activity":{"get":{"tags":["Ordinals","Bitcoin","Runes"],"description":"Retrieve efficient aggregated confirmed history (Bitcoin, Runes, Inscriptions) for multiple\n addresses.
\n Up to 3 addresses(comma separated) can be queried via addresses query param. ","parameters":[{"schema":{"minLength":10,"default":"bc1q0egjvlcfq77cxd9kvpgppyuxckzvws46e3sxch,bc1px3kttdtg479vqfu0s2lhxvyuz2snhl8jct3f84k5heerl750n28scr9qt6","format":"BitcoinAddressList","type":"string"},"in":"query","name":"addresses","required":true},{"schema":{"default":0,"minimum":0,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":60,"minimum":25,"maximum":60,"type":"number"},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"transactions":{"type":"array","items":{"type":"object","properties":{"txid":{"type":"string"},"blockHeight":{"type":"number"},"blockTime":{"type":"number"},"ownActivity":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"sent":{"type":"number"},"received":{"type":"number"},"outgoing":{"type":"number"},"incoming":{"type":"number"}},"required":["address","sent","received","outgoing","incoming"]}},"totalOut":{"type":"number"},"totalIn":{"type":"number"},"addressList":{"type":"object","properties":{"hasMore":{"type":"boolean"},"items":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"type":{"type":"string"},"isInput":{"type":"boolean"},"isOutput":{"type":"boolean"}},"required":["type","isInput","isOutput"]}}},"required":["hasMore","items"]},"runes":{"type":"object","properties":{"ownActivity":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"runeId":{"type":"string"},"runeName":{"type":"string"},"divisibility":{"type":"number"},"symbol":{"type":"string"},"address":{"type":"string"},"sent":{"type":"string"},"received":{"type":"string"},"outgoing":{"type":"string"},"incoming":{"type":"string"}},"required":["runeId","runeName","divisibility","symbol","address","sent","received","outgoing","incoming"]}},"hasMore":{"type":"boolean"}},"required":["items","hasMore"]},"allActivity":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"runeId":{"type":"string"},"runeName":{"type":"string"},"divisibility":{"type":"number"},"symbol":{"type":"string"},"outgoing":{"type":"string"},"incoming":{"type":"string"},"isMint":{"type":"boolean"},"isEtch":{"type":"boolean"},"isBurn":{"type":"boolean"}},"required":["runeId","runeName","divisibility","symbol","outgoing","incoming","isMint","isEtch","isBurn"]}},"hasMore":{"type":"boolean"}},"required":["items","hasMore"]}},"required":["ownActivity","allActivity"]},"inscriptions":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"inscriptionId":{"type":"string"},"contentType":{"type":"string"},"address":{"type":"string"},"sent":{"type":"boolean"},"received":{"type":"boolean"},"inscribed":{"type":"boolean"},"burned":{"type":"boolean"}},"required":["inscriptionId","address","sent","received","inscribed","burned"]}},"hasMore":{"type":"boolean"}},"required":["items","hasMore"]}},"required":["txid","blockHeight","blockTime","ownActivity","totalOut","totalIn","addressList","runes","inscriptions"]}},"offset":{"type":"number"},"limit":{"type":"number"}},"required":["transactions","offset","limit"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Real-Time Mempool Activity (Unconfirmed) This endpoint returns the real-time mempool activity across BTC, inscriptions, and runes for a set of addresses, including all incoming/outgoing transfers. ## GET /v1/global/ordinals/multi-address/activity/mempool > Retrieve efficient aggregated unconfirmed activity (Bitcoin, Runes, Inscriptions) for\ > multiple addresses. \
\ > Up to 3 addresses(comma separated) can be queried via \addresses\ query param. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Bitcoin"},{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/global/ordinals/multi-address/activity/mempool":{"get":{"tags":["Ordinals","Bitcoin","Runes"],"description":"Retrieve efficient aggregated unconfirmed activity (Bitcoin, Runes, Inscriptions) for\n multiple addresses.
\n Up to 3 addresses(comma separated) can be queried via addresses query param. ","parameters":[{"schema":{"minLength":10,"default":"bc1q0egjvlcfq77cxd9kvpgppyuxckzvws46e3sxch,bc1px3kttdtg479vqfu0s2lhxvyuz2snhl8jct3f84k5heerl750n28scr9qt6","format":"BitcoinAddressList","type":"string"},"in":"query","name":"addresses","required":true},{"schema":{"default":0,"minimum":0,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":60,"minimum":25,"maximum":60,"type":"number"},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"transactions":{"type":"array","items":{"type":"object","properties":{"txid":{"type":"string"},"ownActivity":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"sent":{"type":"number"},"received":{"type":"number"},"outgoing":{"type":"number"},"incoming":{"type":"number"}},"required":["address","sent","received","outgoing","incoming"]}},"totalOut":{"type":"number"},"totalIn":{"type":"number"},"addressList":{"type":"object","properties":{"hasMore":{"type":"boolean"},"items":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"type":{"type":"string"},"isInput":{"type":"boolean"},"isOutput":{"type":"boolean"}},"required":["type","isInput","isOutput"]}}},"required":["hasMore","items"]},"runes":{"type":"object","properties":{"ownActivity":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"runeId":{"type":"string"},"runeName":{"type":"string"},"divisibility":{"type":"number"},"symbol":{"type":"string"},"address":{"type":"string"},"sent":{"type":"string"},"received":{"type":"string"},"outgoing":{"type":"string"},"incoming":{"type":"string"}},"required":["runeId","runeName","divisibility","symbol","address","sent","received","outgoing","incoming"]}},"hasMore":{"type":"boolean"}},"required":["items","hasMore"]},"allActivity":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"runeId":{"type":"string"},"runeName":{"type":"string"},"divisibility":{"type":"number"},"symbol":{"type":"string"},"outgoing":{"type":"string"},"incoming":{"type":"string"},"isMint":{"type":"boolean"},"isEtch":{"type":"boolean"},"isBurn":{"type":"boolean"}},"required":["runeId","runeName","divisibility","symbol","outgoing","incoming","isMint","isEtch","isBurn"]}},"hasMore":{"type":"boolean"}},"required":["items","hasMore"]}},"required":["ownActivity","allActivity"]},"inscriptions":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"inscriptionId":{"type":"string"},"contentType":{"type":"string"},"address":{"type":"string"},"sent":{"type":"boolean"},"received":{"type":"boolean"},"inscribed":{"type":"boolean"},"burned":{"type":"boolean"}},"required":["inscriptionId","address","sent","received","inscribed","burned"]}},"hasMore":{"type":"boolean"}},"required":["items","hasMore"]}},"required":["txid","ownActivity","totalOut","totalIn","addressList","runes","inscriptions"]}},"offset":{"type":"number"},"limit":{"type":"number"}},"required":["transactions","offset","limit"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Unconfirmed Transactions ## GET /v1/bitcoin/address/{address}/txs/unconfirmed > Fetch unconfirmed transactions for a given address. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Bitcoin"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/bitcoin/address/{address}/txs/unconfirmed":{"get":{"tags":["Bitcoin"],"description":"Fetch unconfirmed transactions for a given address. ","parameters":[{"schema":{"default":25,"minimum":1,"maximum":10000,"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"minLength":10,"default":"bc1q0egjvlcfq77cxd9kvpgppyuxckzvws46e3sxch","format":"BitcoinAddress","type":"string"},"in":"path","name":"address","required":true}],"responses":{"200":{"description":"List of unconfirmed txs","content":{"application/json":{"schema":{"description":"List of unconfirmed txs","type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"txid":{"type":"string"},"version":{"type":"number"},"locktime":{"type":"number"},"vin":{"type":"array","items":{"type":"object","properties":{"txid":{"type":"string"},"vout":{"type":"number"},"prevout":{"type":"object","properties":{"scriptpubkey":{"type":"string"},"scriptpubkeyAsm":{"type":"string"},"scriptpubkeyType":{"type":"string"},"scriptpubkeyAddress":{"type":"string"},"value":{"type":"number"}},"required":["value"]},"scriptsig":{"type":"string"},"scriptsigAsm":{"type":"string"},"witness":{"type":"array","items":{"type":"string"}},"isCoinbase":{"type":"boolean"},"sequence":{"type":"number"}},"required":["txid","vout","prevout","witness","isCoinbase"]}},"vout":{"type":"array","items":{"type":"object","properties":{"scriptpubkey":{"type":"string"},"scriptpubkeyAsm":{"type":"string"},"scriptpubkeyType":{"type":"string"},"scriptpubkeyAddress":{"type":"string"},"value":{"type":"number"}},"required":["value"]}},"size":{"type":"number"},"weight":{"type":"number"},"sigops":{"type":"number"},"fee":{"type":"number"},"status":{"type":"object","properties":{"confirmed":{"type":"boolean"}},"required":["confirmed"]}},"required":["txid","version","locktime","vin","vout","size","weight","sigops","fee","status"]}}},"required":["items"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Transactions # Get Bitcoin Transaction This endpoint returns confirmation status, block height, and timestamp for a given Bitcoin transaction. Mempool-aware. ## GET /v1/bitcoin/tx/{txid} > Retrieve stats for the transaction. Works for confirmed and unconfirmed transactions. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Bitcoin"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/bitcoin/tx/{txid}":{"get":{"tags":["Bitcoin"],"description":"Retrieve stats for the transaction. Works for confirmed and unconfirmed transactions.","parameters":[{"schema":{"minimum":0,"multipleOf":25,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"minimum":25,"maximum":25,"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"format":"regex","pattern":"^[a-fA-F0-9]{64}$","type":"string"},"in":"path","name":"txid","required":true,"description":"Transaction id"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"height":{"type":"number"},"confirmations":{"type":"number"},"inputs":{"type":"array","items":{"type":"object","properties":{"vin":{"type":"number"},"prevTxid":{"type":"string"},"prevVout":{"type":"number"},"value":{"type":"number"},"address":{"type":"string"},"script":{"type":"string"},"isCoinbase":{"type":"boolean"}},"required":["vin","value","address"]}},"outputs":{"type":"array","items":{"type":"object","properties":{"vout":{"type":"number"},"value":{"type":"number"},"address":{"type":"string"},"script":{"type":"string"}},"required":["vout","value","address"]}}},"required":["confirmations","inputs","outputs"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Get Raw Bitcoin Transaction Hex This endpoint returns the raw hex for a given Bitcoin transaction. It supports confirmed and unconfirmed transactions. ## GET /v1/bitcoin/tx/{txid}/hex > Retrieve transaction hex. Supports confirmed and unconfirmed transactions. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Bitcoin"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/bitcoin/tx/{txid}/hex":{"get":{"tags":["Bitcoin"],"description":"Retrieve transaction hex. Supports confirmed and unconfirmed transactions.","parameters":[{"schema":{"format":"regex","pattern":"^[a-fA-F0-9]{64}$","type":"string"},"in":"path","name":"txid","required":true,"description":"Transaction id"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Decode Raw Bitcoin Transaction 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. ## POST /v1/rpc/bitcoin/rawtx > Retrieve raw transaction details by txid. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/rpc/bitcoin/rawtx":{"post":{"tags":["Bitcoin RPC"],"description":"Retrieve raw transaction details by txid.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"txid":{"description":"Transaction id","format":"regex","pattern":"^[a-fA-F0-9]{64}$","type":"string"}},"required":["txid"]}}},"required":true},"responses":{"200":{"description":"Default Response"}}}}}} ``` # Ordinal Transaction 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 ## GET /v1/ordinals/tx/{txid} > Retrieve historic ordinal info (inputs and outputs) for a specific tx. It is mempool aware. \isOrdinalsIndexed\ determines if ordinals data is available ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/ordinals/tx/{txid}":{"get":{"tags":["Ordinals"],"description":"Retrieve historic ordinal info (inputs and outputs) for a specific tx. It is mempool aware. isOrdinalsIndexed determines if ordinals data is available","parameters":[{"schema":{"format":"regex","pattern":"^[a-fA-F0-9]{64}$","type":"string"},"in":"path","name":"txid","required":true,"description":"Transaction id"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"confirmations":{"type":"number"},"blockHeight":{"type":"number"},"isOrdinalsIndexed":{"type":"boolean"},"inputs":{"type":"array","items":{"type":"object","properties":{"vin":{"type":"number"},"prevTxid":{"type":"string"},"prevVout":{"type":"number"},"value":{"type":"number"},"address":{"type":"string"},"isCoinbase":{"type":"boolean"},"runes":{"type":"array","items":{"type":"object","properties":{"runeId":{"type":"string"},"amount":{"type":"string"},"divisibility":{"type":"number"}},"required":["runeId","amount","divisibility"]}},"inscriptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"contentType":{"type":"string"},"offset":{"type":"number"}},"required":["id","contentType","offset"]}}},"required":["vin","value","runes","inscriptions"]}},"outputs":{"type":"array","items":{"type":"object","properties":{"vout":{"type":"number"},"value":{"type":"number"},"address":{"type":"string"},"script":{"type":"string"},"runes":{"type":"array","items":{"type":"object","properties":{"runeId":{"type":"string"},"runeName":{"type":"string"},"amount":{"type":"string"},"divisibility":{"type":"number"}},"required":["runeId","runeName","amount","divisibility"]}},"inscriptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"contentType":{"type":"string"},"offset":{"type":"number"}},"required":["id","contentType","offset"]}}},"required":["vout","value","script","runes","inscriptions"]}},"runeEvents":{"type":"object","properties":{"etch":{"type":"object","properties":{"runeId":{"type":"string"},"runeName":{"type":"string"},"divisibility":{"type":"number"},"symbol":{"type":"string"},"premine":{"type":"string"},"turbo":{"type":"boolean"},"terms":{"type":"object","properties":{"amount":{"type":"string"},"cap":{"type":"string"},"heightLow":{"type":"string"},"heightHigh":{"type":"string"},"offsetLow":{"type":"string"},"offsetHigh":{"type":"string"}},"required":["amount","cap"]},"inscriptionId":{"type":"string"}},"required":["runeName","divisibility","symbol","premine","turbo"]},"mint":{"type":"object","properties":{"runeId":{"type":"string"},"runeName":{"type":"string"},"amount":{"type":"string"}},"required":["runeName","amount"]}}}},"required":["confirmations","isOrdinalsIndexed","inputs","outputs"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Ordinal Transaction Outputs 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 ## GET /v1/ordinals/tx/{txid}/outputs > Retrieve historic ordinal output info for a specific tx. It is mempool aware. \isOrdinalsIndexed\ determines if ordinals data is available ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/ordinals/tx/{txid}/outputs":{"get":{"tags":["Ordinals"],"description":"Retrieve historic ordinal output info for a specific tx. It is mempool aware. isOrdinalsIndexed determines if ordinals data is available","parameters":[{"schema":{"minimum":0,"multipleOf":25,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"minimum":25,"maximum":25,"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"format":"regex","pattern":"^[a-fA-F0-9]{64}$","type":"string"},"in":"path","name":"txid","required":true,"description":"Transaction id"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number"},"offset":{"type":"number"},"limit":{"type":"number"},"confirmations":{"type":"number"},"blockHeight":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"vout":{"type":"number"},"value":{"type":"number"},"address":{"type":"string"},"script":{"type":"string"},"runes":{"type":"array","items":{"type":"object","properties":{"runeId":{"type":"string"},"runeName":{"type":"string"},"amount":{"type":"string"},"divisibility":{"type":"number"}},"required":["runeId","runeName","amount","divisibility"]}},"inscriptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"contentType":{"type":"string"},"offset":{"type":"number"}},"required":["id","contentType","offset"]}}},"required":["vout","value","script","runes","inscriptions"]}},"isOrdinalsIndexed":{"type":"boolean"}},"required":["total","offset","limit","confirmations","items","isOrdinalsIndexed"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Ordinal Transaction Inputs 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 ## GET /v1/ordinals/tx/{txid}/inputs > Retrieve historic input output info for a specific tx. It is mempool aware. \isOrdinalsIndexed\ determines if ordinals data is available ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/ordinals/tx/{txid}/inputs":{"get":{"tags":["Ordinals"],"description":"Retrieve historic input output info for a specific tx. It is mempool aware. isOrdinalsIndexed determines if ordinals data is available","parameters":[{"schema":{"minimum":0,"multipleOf":25,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"minimum":25,"maximum":25,"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"format":"regex","pattern":"^[a-fA-F0-9]{64}$","type":"string"},"in":"path","name":"txid","required":true,"description":"Transaction id"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number"},"offset":{"type":"number"},"limit":{"type":"number"},"confirmations":{"type":"number"},"blockHeight":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"vin":{"type":"number"},"prevTxid":{"type":"string"},"prevVout":{"type":"number"},"value":{"type":"number"},"address":{"type":"string"},"isCoinbase":{"type":"boolean"},"runes":{"type":"array","items":{"type":"object","properties":{"runeId":{"type":"string"},"amount":{"type":"string"},"divisibility":{"type":"number"}},"required":["runeId","amount","divisibility"]}},"inscriptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"contentType":{"type":"string"},"offset":{"type":"number"}},"required":["id","contentType","offset"]}}},"required":["vin","value","runes","inscriptions"]}},"isOrdinalsIndexed":{"type":"boolean"}},"required":["total","offset","limit","confirmations","items","isOrdinalsIndexed"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Outputs ## POST /v1/outputs > Retrieve Ordinal details for a specific list of outputs (txid:vout). ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/outputs":{"post":{"tags":["Ordinals"],"description":"Retrieve Ordinal details for a specific list of outputs (txid:vout).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"outputs":{"minItems":1,"maxItems":20,"type":"array","items":{"format":"regex","pattern":"^[0-9a-fA-F]{64}:[0-9]*$","type":"string"}}},"required":["outputs"]}}},"required":true},"responses":{"200":{"description":"List of ordinal detail outputs","content":{"application/json":{"schema":{"description":"List of ordinal detail outputs","type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"xVersion":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"txid":{"type":"string"},"address":{"type":"string"},"isSpent":{"type":"boolean"},"vout":{"type":"number"},"result":{"type":"object","properties":{"blockHeight":{"type":"number"},"value":{"type":"number"},"satRanges":{"type":"array","items":{"type":"object","properties":{"range":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]},"offset":{"type":"number"},"sattributes":{"type":"array","items":{"type":"string"}},"yearMined":{"type":"number"},"block":{"type":"number"},"inscriptions":{"type":"array","items":{"type":"object","properties":{"contentType":{"type":"string"},"id":{"type":"string"}},"required":["contentType","id"]}}},"required":["range","offset","sattributes","yearMined","block","inscriptions"]}},"runes":{"type":"array","items":{"type":"object","properties":{"runeId":{"type":"string"},"runeName":{"type":"string"},"amount":{"type":"string"},"divisibility":{"type":"number"},"symbol":{"type":"string"}},"required":["runeName","amount","divisibility","symbol"]}}},"required":["satRanges","runes"]}},"required":["txid","isSpent","vout"]}}},"required":["total","limit","offset","items"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Node & Mempool # Estimate Transaction Fee Estimate the approximate fee per kilobyte required for a transaction to confirm in the next blocks, based on the current state of the mempool. ## GET /v1/bitcoin/mempool/fee-estimates > Retrieve estimated fee rates to use for transactions to be confirmed within a specific range of blocks. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Bitcoin"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/bitcoin/mempool/fee-estimates":{"get":{"tags":["Bitcoin"],"description":"Retrieve estimated fee rates to use for transactions to be confirmed within a specific range of blocks.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"currentBlockHeight":{"type":"number"},"estimates":{"type":"object","properties":{"nextBlock":{"type":"number"},"in2Blocks":{"type":"number"},"in3Blocks":{"type":"number"}},"required":["nextBlock","in2Blocks","in3Blocks"]}},"required":["currentBlockHeight","estimates"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Mempool Fees Retrieve statistics regarding the fee rates of transactions within estimated mempool blocks. ## GET /v1/bitcoin/mempool/stats > Retrieve stats for the projected blocks from the transactions in the mempool. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Bitcoin"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/bitcoin/mempool/stats":{"get":{"tags":["Bitcoin"],"description":"Retrieve stats for the projected blocks from the transactions in the mempool.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"currentBlockHeight":{"type":"number"},"projectedBlocks":{"type":"array","items":{"type":"object","properties":{"height":{"type":"number"},"weight":{"type":"number"},"vbytes":{"type":"number"},"txnCount":{"type":"number"},"totalFeesSats":{"type":"number"},"feeRates":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"avg":{"type":"number"},"median":{"type":"number"},"p75":{"type":"number"},"p95":{"type":"number"}},"required":["min","max","avg","median","p75","p95"]}},"required":["height","weight","vbytes","txnCount","totalFeesSats","feeRates"]}}},"required":["currentBlockHeight","projectedBlocks"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Send Transaction This endpoint can be used to post a signed raw transaction to the Bitcoin network ## POST /v1/rpc/bitcoin/tx > Post transaction. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/rpc/bitcoin/tx":{"post":{"tags":["Bitcoin RPC"],"description":"Post transaction.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tx":{"description":"Raw transaction hex to be posted to the Bitcoin network.","type":"string"}},"required":["tx"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"description":"The transaction ID of the posted transaction.","type":"string"}},"required":["result"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"}},"required":["message","code"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Mempool Acceptance Test This endpoint lets you run a mempool acceptance test to check if the mempool will accept the serialized hex-encoded raw transaction ## POST /v1/rpc/bitcoin/testmempoolaccept > Forward to RPC using testmempoolaccept method. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/rpc/bitcoin/testmempoolaccept":{"post":{"tags":["Bitcoin RPC"],"description":"Forward to RPC using testmempoolaccept method.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"txList":{"type":"array","items":{"description":"Raw transaction hex to be checked with testmempoolaccept method.","type":"string"}},"maxFeeRate":{"default":0.1,"type":"number"}},"required":["txList"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"array","items":{"type":"object","properties":{"txid":{"type":"string"},"wtxid":{"type":"string"},"allowed":{"type":"boolean"},"vsize":{"type":"number"},"fees":{"type":"object","properties":{"base":{"type":"number"}},"required":["base"]},"rejectReason":{"type":"string"},"packageError":{"type":"string"}},"required":["txid","wtxid"]}}},"required":["result"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"}},"required":["message","code"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Blocks # Get Current Block Returns the latest Bitcoin block with height, hash, timestamp, and more. ## GET /v1/block/current > Get information about the current block ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Bitcoin"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/block/current":{"get":{"tags":["Bitcoin"],"description":"Get information about the current block","responses":{"200":{"description":"Block information","content":{"application/json":{"schema":{"description":"Block information","type":"object","properties":{"block":{"type":"object","properties":{"height":{"type":"number"},"hash":{"type":"string"},"previousHash":{"type":"string"},"timestamp":{"type":"string"}},"required":["height","hash"]}},"required":["block"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Get Block by Height Returns block metadata (hash, timestamp, tx count, etc.) for a specific height. ## GET /v1/block/height/{height} > Get information about a specific block by height ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Bitcoin"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/block/height/{height}":{"get":{"tags":["Bitcoin"],"description":"Get information about a specific block by height","parameters":[{"schema":{"minimum":0,"type":"number"},"in":"path","name":"height","required":true}],"responses":{"200":{"description":"Block information","content":{"application/json":{"schema":{"description":"Block information","type":"object","properties":{"block":{"type":"object","properties":{"height":{"type":"number"},"hash":{"type":"string"},"previousHash":{"type":"string"},"timestamp":{"type":"string"}},"required":["height","hash"]}},"required":["block"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Bitcoin JSON-RPC 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` ## POST /v2/rpc/bitcoin > JSON RPC ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"enum":["getbestblockhash","getblock","getblockchaininfo","getblockcount","getblockfilter","getblockhash","getblockheader","getblockstats","getchaintips","getchaintxstats","getdifficulty","getmempoolancestors","getmempooldescendants","getmempoolentry","getmempoolinfo","getrawmempool","gettxout","gettxoutproof","createrawtransaction","decoderawtransaction","decodescript","getrawtransaction","sendrawtransaction","testmempoolaccept","createmultisig","estimatesmartfee","validateaddress","verifymessage"],"type":"string"},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # getblockhash This RPC Method returns the hash of the tip block in the most-work fully-validated chain. ## POST /v2/rpc/bitcoin/getblockhash > JSON RPC - getblockhash ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/getblockhash":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - getblockhash","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["getblockhash"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # getblock This RPC Method returns information about the block. ## POST /v2/rpc/bitcoin/getblock > JSON RPC - getblock ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/getblock":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - getblock","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["getblock"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # getblockchaininfo This RPC Method returns an object that contains the information regarding blockchain processing in different states. ## POST /v2/rpc/bitcoin/getblockchaininfo > JSON RPC - getblockchaininfo ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/getblockchaininfo":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - getblockchaininfo","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["getblockchaininfo"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # getblockcount This RPC Method returns the height of the fully-validated chain. The genesis block has a height of 0. ## POST /v2/rpc/bitcoin/getblockcount > JSON RPC - getblockcount ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/getblockcount":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - getblockcount","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["getblockcount"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # getblockfilter This RPC Method returns the BIP-157 compact block filter and filter header for a given block. ## POST /v2/rpc/bitcoin/getblockfilter > JSON RPC - getblockfilter ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/getblockfilter":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - getblockfilter","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["getblockfilter"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # getblockhash This RPC Method returns the hash of the block provided its height. ## POST /v2/rpc/bitcoin/getblockhash > JSON RPC - getblockhash ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/getblockhash":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - getblockhash","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["getblockhash"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # getblockheader This RPC Method returns the header of the block given it's hash. ## POST /v2/rpc/bitcoin/getblockheader > JSON RPC - getblockheader ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/getblockheader":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - getblockheader","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["getblockheader"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # getblockstats This RPC Method calculates per block statistics for a given window. ## POST /v2/rpc/bitcoin/getblockstats > JSON RPC - getblockstats ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/getblockstats":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - getblockstats","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["getblockstats"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # getchaintips This RPC Method returns information about all known chaintips in the block tree, including the main chain as well as orphaned branches. ## POST /v2/rpc/bitcoin/getchaintips > JSON RPC - getchaintips ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/getchaintips":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - getchaintips","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["getchaintips"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # getchaintxstats This RPC Method calculates data about the total number and rate of transactions in the chain. ## POST /v2/rpc/bitcoin/getchaintxstats > JSON RPC - getchaintxstats ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/getchaintxstats":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - getchaintxstats","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["getchaintxstats"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # getdifficulty This RPC Method returns the proof-of-work difficulty as a multiple of the minimum difficulty. ## POST /v2/rpc/bitcoin/getdifficulty > JSON RPC - getdifficulty ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/getdifficulty":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - getdifficulty","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["getdifficulty"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # getmempoolancestors This RPC Method returns all in-mempool ancestors for a transaction in the mempool. ## POST /v2/rpc/bitcoin/getmempoolancestors > JSON RPC - getmempoolancestors ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/getmempoolancestors":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - getmempoolancestors","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["getmempoolancestors"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # getmempooldescendants This RPC Method returns all in-mempool descendants for a transaction in the mempool. ## POST /v2/rpc/bitcoin/getmempooldescendants > JSON RPC - getmempooldescendants ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/getmempooldescendants":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - getmempooldescendants","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["getmempooldescendants"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # getmempoolentry This RPC Method returns detailed mempool entry data for a specific transaction. ## POST /v2/rpc/bitcoin/getmempoolentry > JSON RPC - getmempoolentry ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/getmempoolentry":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - getmempoolentry","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["getmempoolentry"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # getmempoolinfo This RPC Method returns mempool statistics such as size, bytes, usage, and limits. ## POST /v2/rpc/bitcoin/getmempoolinfo > JSON RPC - getmempoolinfo ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/getmempoolinfo":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - getmempoolinfo","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["getmempoolinfo"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # getrawmempool This RPC Method returns all transaction IDs currently in the mempool. ## POST /v2/rpc/bitcoin/getrawmempool > JSON RPC - getrawmempool ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/getrawmempool":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - getrawmempool","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["getrawmempool"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # gettxout This RPC Method returns details about an unspent transaction output (UTXO). ## POST /v2/rpc/bitcoin/gettxout > JSON RPC - gettxout ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/gettxout":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - gettxout","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["gettxout"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # gettxoutproof This RPC Method returns a proof that specific transactions are included in a block. ## POST /v2/rpc/bitcoin/gettxoutproof > JSON RPC - gettxoutproof ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/gettxoutproof":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - gettxoutproof","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["gettxoutproof"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # createrawtransaction This RPC Method creates an unsigned raw transaction from inputs and outputs. ## POST /v2/rpc/bitcoin/createrawtransaction > JSON RPC - createrawtransaction ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/createrawtransaction":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - createrawtransaction","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["createrawtransaction"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # decoderawtransaction This RPC Method decodes a serialized raw transaction hex into a JSON object. ## POST /v2/rpc/bitcoin/decoderawtransaction > JSON RPC - decoderawtransaction ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/decoderawtransaction":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - decoderawtransaction","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["decoderawtransaction"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # decodescript This RPC Method decodes a hex-encoded script into a JSON object. ## POST /v2/rpc/bitcoin/decodescript > JSON RPC - decodescript ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/decodescript":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - decodescript","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["decodescript"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # getrawtransaction This RPC Method returns detailed information about a raw transaction by txid. ## POST /v2/rpc/bitcoin/getrawtransaction > JSON RPC - getrawtransaction ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/getrawtransaction":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - getrawtransaction","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["getrawtransaction"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # sendrawtransaction This RPC Method submits a raw signed transaction to the network. ## POST /v2/rpc/bitcoin/getrawtransaction > JSON RPC - getrawtransaction ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/getrawtransaction":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - getrawtransaction","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["getrawtransaction"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # testmempoolaccept This RPC Method tests whether a raw transaction would be accepted by the mempool. ## POST /v2/rpc/bitcoin/getrawtransaction > JSON RPC - getrawtransaction ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/getrawtransaction":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - getrawtransaction","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["getrawtransaction"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # createmultisig This RPC Method creates a multisig address and redeem script from a set of public keys. ## POST /v2/rpc/bitcoin/createmultisig > JSON RPC - createmultisig ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/createmultisig":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - createmultisig","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["createmultisig"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # estimatesmartfee This RPC Method estimates the transaction fee per kilobyte needed for confirmation within a target number of blocks. ## POST /v2/rpc/bitcoin/createmultisig > JSON RPC - createmultisig ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/createmultisig":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - createmultisig","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["createmultisig"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # validateaddress This RPC Method verifies whether a Bitcoin address is valid and provides related info. ## POST /v2/rpc/bitcoin/createmultisig > JSON RPC - createmultisig ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/createmultisig":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - createmultisig","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["createmultisig"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # verifymessage This RPC Method verifies that a signed message was created with the private key corresponding to a given address. ## POST /v2/rpc/bitcoin/createmultisig > JSON RPC - createmultisig ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/rpc/bitcoin/createmultisig":{"post":{"tags":["Bitcoin RPC"],"description":"JSON RPC - createmultisig","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["createmultisig"]},"params":{"type":"array","items":{}}},"required":["method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{},"error":{},"id":{}}}}}}}}}}} ``` # Bitcoin Price This endpoint can be used to get the latest Bitcoin price ## GET /v1/bitcoin/price > Fetch latest bitcoin price. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Bitcoin"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/bitcoin/price":{"get":{"tags":["Bitcoin"],"description":"Fetch latest bitcoin price.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"rate":{"type":"number"}},"required":["currency","rate"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Portfolio Monitor Bitcoin asset balances and activity across multiple addresses, with automatic daily tracking and historical portfolio insights. # Register Portfolio Address Use this endpoint to register a portfolio address for continuous balance tracking. Xverse API will automatically keep its daily balance and activity updated. {% hint style="info" %} Once a portfolio address is registered, use [Get Portfolio Address History](/api/portfolio/get-portfolio-address-history)to query its balances {% endhint %} ## POST /v1/portfolio/register > Register an address to the portfolio for balance tracking. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/portfolio/register":{"post":{"tags":["Portfolio"],"description":"Register an address to the portfolio for balance tracking.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assetType":{"type":"string"},"addresses":{"type":"array","items":{"type":"string"}}},"required":["assetType","addresses"]}}},"required":true},"responses":{"200":{"description":"Default Response"}}}}}} ``` # List Registered Portfolio Addresses This endpoint returns all the registered portfolio addresses for the current API key. {% hint style="info" %} You can use [Register Portfolio Address](/api/portfolio/register-portfolio-address)to register a portfolio address. {% endhint %} ## GET /v1/portfolio > Get list of addresses from a portfolio. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/portfolio":{"get":{"tags":["Portfolio"],"description":"Get list of addresses from a portfolio.","parameters":[{"schema":{"type":"string"},"in":"query","name":"assetType","required":true},{"schema":{"default":0,"minimum":0,"multipleOf":25,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":25,"minimum":25,"maximum":25,"type":"number"},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"total":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"assetType":{"enum":["bitcoin"],"type":"string"},"address":{"type":"string"}},"required":["assetType","address"]}}},"required":["limit","offset","total","items"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Get Portfolio Address History Use this endpoint to retrieve the daily balance history for a registered portfolio address over a specific time period. {% hint style="info" %} You need to first register a portfolio address with [Register Portfolio Address](/api/portfolio/register-portfolio-address) {% endhint %} {% hint style="success" %} Only BTC balances are supported at the moment. More Bitcoin asset balances will follow soon. {% endhint %} ## GET /v1/portfolio/history > Get the daily balance history for an address from the portfolio. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/portfolio/history":{"get":{"tags":["Portfolio"],"description":"Get the daily balance history for an address from the portfolio.","parameters":[{"schema":{"type":"string"},"in":"query","name":"address","required":true},{"schema":{"default":0,"minimum":0,"multipleOf":25,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":25,"minimum":25,"maximum":25,"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"startDate","required":true,"description":"from date, inclusive - (e.g. 2024-08-29)"},{"schema":{"type":"string"},"in":"query","name":"endDate","required":true,"description":"to date, exclusive - (e.g. 2024-09-01)"},{"schema":{"enum":["bitcoin"],"type":"string"},"in":"query","name":"assetType","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"lastBlockHeight":{"nullable":true,"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"assetType":{"type":"string"},"assetId":{"type":"string"},"address":{"type":"string"},"balance":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}},"date":{"type":"string"}},"required":["assetType","assetId","address","balance","date"]}}},"required":["limit","offset","lastBlockHeight","items"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Watch Addresses 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. *** ## πŸ”” Transaction Webhooks Webhooks are how Xverse delivers **address activity events** to your application. Once a webhook subscription is registered for a set of addresses: * Xverse monitors the addresses * Transaction events are pushed to your backend via HTTP POST * No custom indexing or node infrastructure is required #### Supported networks | Network | Status | | -------------------------- | ------------- | | Bitcoin | βœ… Live | | Runes, Ordinals and BRC-20 | βœ… Live | | Spark | ⏳ Coming soon | | Starknet | ⏳ Coming soon | | Stacks | ⏳ Coming soon | You can subscribe to: * Incoming transactions * Outgoing transactions *** ## :eyes: Register a Webhook Subscription Start watching a set of addresses. * Registers the address for transaction monitoring * Enables webhook notifications for relevant transactions involving the addresses {% hint style="info" %} Currently supports Bitcoin addresses only.\ Spark & Starknet will be added soon and follow the same model. {% endhint %} ## POST /v1/subscription > Register a subscription for events. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/subscription":{"post":{"tags":["Subscription"],"description":"Register a subscription for events.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"webhookEndpoint":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"]},"subscriptionAddressPredicate":{"type":"object","properties":{"addresses":{"type":"array","items":{"type":"string"}}},"required":["addresses"]}},"required":["webhookEndpoint","subscriptionAddressPredicate"]}}},"required":true},"responses":{"200":{"description":"Default Response"}}}}}} ``` *** ### πŸ“¬ Webhook Payload (Bitcoin) When a transaction involving any of the watched addresses is confirmed, Xverse sends a POST request to your webhook URL: ```json [ { "status": "confirmed", "address": "bc1qjpnsvwgsxtf005x2qd28l3zlmexa3095fa6g4e", "totalSatsIn": "0", "totalSatsOut": "1421459", "txid": "cc46ce35c459cd91585ec3848e0ec58b10a24770da5cdd264da41da7b3f07649", "blockHeight": 928800, "blockTime": "2025-12-21T07:42:08.000+02:00" } ] ``` Payloads for Spark and Starknet will follow a similar structure. *** ### πŸ“„ List Webhook Subscriptions Returns all active address-watching webhook subscriptions for your API key. **Use this to** * Inspect active address watchers * Debug webhook behavior * Manage multiple monitored sets of addresses ## GET /v1/subscription > Get registered subscriptions. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/subscription":{"get":{"tags":["Subscription"],"description":"Get registered subscriptions.","parameters":[{"schema":{"default":0,"minimum":0,"multipleOf":25,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":25,"minimum":25,"maximum":25,"type":"number"},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"total":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"webhookEndpoint":{"type":"object","properties":{"url":{"type":"string"},"updatedAt":{"type":"string"}},"required":["url","updatedAt"]},"subscriptionAddressPredicate":{"type":"object","properties":{"addresses":{"type":"array","items":{"type":"string"}},"updatedAt":{"type":"string"}},"required":["addresses","updatedAt"]}},"required":["id","webhookEndpoint","subscriptionAddressPredicate"]}}},"required":["limit","offset","total","items"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` *** ### ❌ Delete a Subscription Stop watching a set of addresses by deleting the webhook subscription. **Use this to** * Stop receiving notifications for an address * Clean up unused subscriptions ## DELETE /v1/subscription/{subscriptionId} > Delete subscriptions. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/subscription/{subscriptionId}":{"delete":{"tags":["Subscription"],"description":"Delete subscriptions.","parameters":[{"schema":{"type":"number"},"in":"path","name":"subscriptionId","required":true}],"responses":{"200":{"description":"Default Response"}}}}}} ``` # Ordinals 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. # Ordinals by Address # UTXOs ## GET /v1/ordinals/address/{address}/utxo > Get detailed Ordinals info (inscriptions, rare sats, Runes) for all confirmed UTXOs. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/ordinals/address/{address}/utxo":{"get":{"tags":["Ordinals"],"description":"Get detailed Ordinals info (inscriptions, rare sats, Runes) for all confirmed UTXOs.","parameters":[{"schema":{"default":0,"minimum":0,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":60,"minimum":25,"maximum":60,"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"minLength":10,"default":"bc1q0egjvlcfq77cxd9kvpgppyuxckzvws46e3sxch","format":"BitcoinAddress","type":"string"},"in":"path","name":"address","required":true}],"responses":{"200":{"description":"Ordinal information for all utxos belonging to the address","content":{"application/json":{"schema":{"description":"Ordinal information for all utxos belonging to the address","type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"total":{"type":"number"},"rareSatsVersion":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"txid":{"type":"string"},"vout":{"type":"number"},"value":{"type":"number"},"blockHeight":{"type":"number"},"satRanges":{"type":"array","items":{"type":"object","properties":{"range":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]},"offset":{"type":"number"},"sattributes":{"type":"array","items":{"type":"string"}},"yearMined":{"type":"number"},"block":{"type":"number"},"inscriptions":{"type":"array","items":{"type":"object","properties":{"contentType":{"type":"string"},"id":{"type":"string"}},"required":["contentType","id"]}}},"required":["range","offset","sattributes","yearMined","block","inscriptions"]}},"runes":{"type":"array","items":{"type":"object","properties":{"runeId":{"type":"string"},"runeName":{"type":"string"},"amount":{"type":"string"},"divisibility":{"type":"number"},"symbol":{"type":"string"}},"required":["runeName","amount","divisibility","symbol"]}}},"required":["txid","vout","value","satRanges","runes"]}}},"required":["limit","offset","total","rareSatsVersion","items"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Collections This endpoint returns all Ordinal collections held by a given wallet address, along with the list of inscriptions owned within each collection. ## GET /v1/ordinals/address/{address}/collections > Fetch inscriptions by collection for assets in a specific address. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/ordinals/address/{address}/collections":{"get":{"tags":["Ordinals"],"description":"Fetch inscriptions by collection for assets in a specific address.","parameters":[{"schema":{"default":0,"minimum":0,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":60,"minimum":25,"maximum":60,"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"minLength":10,"default":"bc1q0egjvlcfq77cxd9kvpgppyuxckzvws46e3sxch","format":"BitcoinAddress","type":"string"},"in":"path","name":"address","required":true}],"responses":{"200":{"description":"Collection info for inscriptions owned by the address","content":{"application/json":{"schema":{"description":"Collection info for inscriptions owned by the address","type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"totalCollections":{"type":"number"},"totalInscriptions":{"type":"number"},"items":{"type":"array","items":{"type":"object","allOf":[{"type":"object","properties":{"id":{"type":"string"},"symbol":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"supply":{"type":"string"},"holderCount":{"type":"string"},"floorPrice":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"},"percentageChange24h":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}}},"required":["percentageChange24h"]},"marketCap":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}},"volume24h":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"},"percentageChange":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}}},"required":["percentageChange"]},"links":{"type":"object","properties":{"coinMarketCap":{"type":"string"},"telegram":{"type":"string"},"twitter":{"type":"string"},"discord":{"type":"string"},"website":{"type":"string"}}}},"required":["id","symbol","floorPrice","marketCap","links"]},{"type":"object","properties":{"total":{"type":"number"},"inscriptionSubset":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"number"},"contentType":{"type":"string"}},"required":["id","number"]}}},"required":["total","inscriptionSubset"]}]}}},"required":["limit","offset","totalCollections","totalInscriptions","items"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Inscriptions ## GET /v1/ordinals/address/{address}/inscriptions > List all confirmed inscriptions an address owns.\
\
\Note:\ The Api response includes limit & offset for future pagination extension, but\ > at the moment query parameters are ignored and the response is always the full list.\ > So, limit equals the total items number, be sure to handle pagination as the limit can change once pagination\ > is implemented. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/ordinals/address/{address}/inscriptions":{"get":{"tags":["Ordinals"],"description":"List all confirmed inscriptions an address owns.

Note: The Api response includes limit & offset for future pagination extension, but\n at the moment query parameters are ignored and the response is always the full list.\nSo, limit equals the total items number, be sure to handle pagination as the limit can change once pagination\nis implemented.","parameters":[{"schema":{"default":0,"minimum":0,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":60,"minimum":25,"maximum":60,"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"minLength":10,"default":"bc1q0egjvlcfq77cxd9kvpgppyuxckzvws46e3sxch","format":"BitcoinAddress","type":"string"},"in":"path","name":"address","required":true}],"responses":{"200":{"description":"Inscriptions owned by the address","content":{"application/json":{"schema":{"description":"Inscriptions owned by the address","type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"offset":{"type":"number"},"parentIds":{"type":"array","items":{"type":"string"}},"delegateId":{"type":"string"},"blockHeight":{"type":"number"},"contentType":{"type":"string"},"contentLength":{"type":"number"},"effectiveContentType":{"type":"string"},"number":{"type":"number"},"sat":{"type":"number"},"charms":{"type":"array","items":{"type":"string"}},"currentOutput":{"type":"string"},"currentAddress":{"type":"string"},"lastTransferHeight":{"type":"number"},"lastTransferTimestamp":{"type":"number"},"value":{"type":"number"},"contentUrl":{"type":"string"},"renderUrl":{"type":"string"},"collectionId":{"type":"string"},"collectionName":{"type":"string"},"collectionFloorPrice":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}},"lastInscriptionSalePrice":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}},"name":{"type":"string"},"indexerHeight":{"type":"number"}},"required":["id","parentIds","blockHeight","contentLength","number","charms","currentOutput","currentAddress","lastTransferHeight","lastTransferTimestamp","value","contentUrl","renderUrl","collectionFloorPrice","lastInscriptionSalePrice"]}}},"required":["limit","offset","items"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Unconfirmed Inscriptions (Mempool) ## GET /v1/mempool/ordinals/address/{address}/inscriptions > List all unconfirmed inscriptions an address owns. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/mempool/ordinals/address/{address}/inscriptions":{"get":{"tags":["Ordinals"],"description":"List all unconfirmed inscriptions an address owns.","parameters":[{"schema":{"default":0,"minimum":0,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":60,"minimum":25,"maximum":60,"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"minLength":10,"default":"bc1q0egjvlcfq77cxd9kvpgppyuxckzvws46e3sxch","format":"BitcoinAddress","type":"string"},"in":"path","name":"address","required":true}],"responses":{"200":{"description":"Inscriptions owned by the address","content":{"application/json":{"schema":{"description":"Inscriptions owned by the address","type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"offset":{"type":"number"},"parentIds":{"type":"array","items":{"type":"string"}},"delegateId":{"type":"string"},"contentType":{"type":"string"},"contentLength":{"type":"number"},"effectiveContentType":{"type":"string"},"number":{"type":"number"},"sat":{"type":"number"},"charms":{"type":"array","items":{"type":"string"}},"currentOutput":{"type":"string"},"currentAddress":{"type":"string"},"value":{"type":"number"},"contentUrl":{"type":"string"},"renderUrl":{"type":"string"},"collectionId":{"nullable":true,"type":"string"},"collectionName":{"nullable":true,"type":"string"},"collectionFloorPrice":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}},"lastInscriptionSalePrice":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}}},"required":["id","currentOutput","currentAddress","value","collectionFloorPrice","lastInscriptionSalePrice"]}}},"required":["limit","offset","items"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Inscriptions of a Collection ## GET /v1/ordinals/address/{address}/inscriptions/collection/{collectionId} > Get inscriptions owned by an address in a specific collection. It includes current inscription location ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/ordinals/address/{address}/inscriptions/collection/{collectionId}":{"get":{"tags":["Ordinals"],"description":"Get inscriptions owned by an address in a specific collection. It includes current inscription location","parameters":[{"schema":{"default":0,"minimum":0,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":25,"minimum":25,"maximum":25,"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"minLength":10,"default":"bc1q0egjvlcfq77cxd9kvpgppyuxckzvws46e3sxch","format":"BitcoinAddress","type":"string"},"in":"path","name":"address","required":true},{"schema":{"type":"string"},"in":"path","name":"collectionId","required":true}],"responses":{"200":{"description":"Inscriptions for a specific collection owned by an address","content":{"application/json":{"schema":{"description":"Inscriptions for a specific collection owned by an address","type":"object","properties":{"collectionId":{"type":"string"},"collectionName":{"type":"string"},"total":{"type":"number"},"offset":{"type":"number"},"limit":{"type":"number"},"inscriptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"number"},"sat":{"type":"number"},"contentType":{"type":"string"},"blockHeight":{"type":"number"},"charms":{"type":"array","items":{"type":"string"}},"currentLocation":{"type":"string"}},"required":["id","number","blockHeight","charms"]}}},"required":["collectionId","collectionName","total","offset","limit","inscriptions"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Void inscriptions ## GET /v1/ordinals/address/{address}/void-protocol-inscriptions/collection/{collectionId} > Get BRC20 & TAP void inscriptions(already spent/used) owned by an address\ > in a specific collection. A void inscription is a BRC-20 or TAP inscription that is no longer protocol\ > valid (transfer inscriptions become invalid after first transfer, other inscriptions like\ > mint become invalid right after inscribe). ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/ordinals/address/{address}/void-protocol-inscriptions/collection/{collectionId}":{"get":{"tags":["Ordinals"],"description":"Get BRC20 & TAP void inscriptions(already spent/used) owned by an address\n in a specific collection. A void inscription is a BRC-20 or TAP inscription that is no longer protocol\n valid (transfer inscriptions become invalid after first transfer, other inscriptions like\n mint become invalid right after inscribe).","parameters":[{"schema":{"default":0,"minimum":0,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":25,"minimum":25,"maximum":25,"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"minLength":10,"default":"bc1q0egjvlcfq77cxd9kvpgppyuxckzvws46e3sxch","format":"BitcoinAddress","type":"string"},"in":"path","name":"address","required":true},{"schema":{"type":"string"},"in":"path","name":"collectionId","required":true}],"responses":{"200":{"description":"Inscriptions for a specific collection owned by an address","content":{"application/json":{"schema":{"description":"Inscriptions for a specific collection owned by an address","type":"object","properties":{"collectionId":{"type":"string"},"collectionName":{"type":"string"},"total":{"type":"number"},"offset":{"type":"number"},"limit":{"type":"number"},"inscriptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"number"},"sat":{"type":"number"},"contentType":{"type":"string"},"blockHeight":{"type":"number"},"charms":{"type":"array","items":{"type":"string"}},"currentLocation":{"type":"string"}},"required":["id","number","blockHeight","charms"]}}},"required":["collectionId","collectionName","total","offset","limit","inscriptions"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Collections # Collection by ID This endpoint is used to retrieve the metadata & market data associated with an ordinal collection, based on the ordinal collection ID. ## GET /v1/ordinals/collections/{collectionId} > Get metadata and market info for an Ordinals collection. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/ordinals/collections/{collectionId}":{"get":{"tags":["Ordinals"],"description":"Get metadata and market info for an Ordinals collection.","parameters":[{"schema":{"type":"string"},"in":"path","name":"collectionId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"symbol":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"supply":{"type":"string"},"holderCount":{"type":"string"},"floorPrice":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"},"percentageChange24h":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}}},"required":["percentageChange24h"]},"marketCap":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}},"volume24h":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"},"percentageChange":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}}},"required":["percentageChange"]},"links":{"type":"object","properties":{"coinMarketCap":{"type":"string"},"telegram":{"type":"string"},"twitter":{"type":"string"},"discord":{"type":"string"},"website":{"type":"string"}}}},"required":["id","symbol","floorPrice","marketCap","links"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Top Collections by Volume This endpoint provides the top collections by sales volume for different time periods, along with collections' metadata & market data. ## GET /v1/ordinals/stats/collections/top-by-volume > Get top collections by volume. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/ordinals/stats/collections/top-by-volume":{"get":{"tags":["Ordinals"],"description":"Get top collections by volume.","parameters":[{"schema":{"enum":["24h","trailing7d","trailing30d","1d","7d","30d"],"default":"24h","type":"string"},"in":"query","name":"timePeriod","required":false,"description":"* `24h` - trailing 24 hours' volume, ending at the start of the prior hour (default)\n* `trailing7d` - trailing 7 days' volume, ending at the start of the prior hour\n* `trailing30d` - trailing 30 days' volume, ending at the start of the prior hour\n* `1d` - prior day's volume, ending at midnight GMT\n* `7d` - prior seven days' volume, ending at midnight GMT\n* `30d` - prior 30 days' volume, ending at midnight GMT"},{"schema":{"default":0,"minimum":0,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":10,"minimum":0,"maximum":100,"type":"number"},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number"},"offset":{"type":"number"},"limit":{"type":"number"},"timePeriod":{"type":"string"},"collections":{"type":"array","items":{"type":"object","properties":{"collectionId":{"type":"string"},"tradingVolumeSats":{"type":"string"},"name":{"type":"string"},"logo":{"type":"string"},"floorPrice":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"},"percentageChange24h":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}}},"required":["percentageChange24h"]}},"required":["collectionId","tradingVolumeSats","name","floorPrice"]}}},"required":["total","offset","limit","timePeriod","collections"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Collections This endpoint returns the full list of indexed Ordinals collections with their basic information and metadata ## GET /v1/ordinals/collections > Get list of ordinals collections. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/ordinals/collections":{"get":{"tags":["Ordinals"],"description":"Get list of ordinals collections.","parameters":[{"schema":{"default":0,"minimum":0,"multipleOf":25,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":25,"minimum":25,"maximum":25,"type":"number"},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"total":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"links":{"type":"object","properties":{"coinMarketCap":{"type":"string"},"telegram":{"type":"string"},"twitter":{"type":"string"},"discord":{"type":"string"},"website":{"type":"string"}}}},"required":["id","links"]}}},"required":["limit","offset","total","items"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Holders by Collection 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. ## GET /v1/ordinals/collections/{collectionId}/holders > Get unique holders of an Ordinals collection. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/ordinals/collections/{collectionId}/holders":{"get":{"tags":["Ordinals"],"description":"Get unique holders of an Ordinals collection.","parameters":[{"schema":{"default":0,"minimum":0,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":10,"minimum":0,"maximum":25,"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"collectionId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number"},"offset":{"type":"number"},"limit":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"inscriptionCount":{"type":"number"},"address":{"type":"string"}},"required":["inscriptionCount","address"]}}},"required":["total","offset","limit","items"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Inscriptions by Collection This endpoint is commonly used to retrieve the list of inscriptions associated with an ordinal collection, together with their info and metadata. ## GET /v1/ordinals/collections/{collectionId}/inscriptions > Get inscriptions for an Ordinals collection. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/ordinals/collections/{collectionId}/inscriptions":{"get":{"tags":["Ordinals"],"description":"Get inscriptions for an Ordinals collection.","parameters":[{"schema":{"default":0,"minimum":0,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":10,"minimum":0,"maximum":25,"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"collectionId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"collectionId":{"type":"string"},"collectionName":{"type":"string"},"total":{"type":"number"},"offset":{"type":"number"},"limit":{"type":"number"},"inscriptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"number"},"sat":{"type":"number"},"contentType":{"type":"string"},"blockHeight":{"type":"number"},"charms":{"type":"array","items":{"type":"string"}}},"required":["id","number","blockHeight","charms"]}}},"required":["collectionId","collectionName","total","offset","limit","inscriptions"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # \[v1] Collection Historical Floor Prices {% hint style="info" %} We recommend switching to [\[v2\] Collection Historical Floor Prices](/api/ordinals/collections/v2-collection-historical-floor-prices) to access data from more marketplaces {% endhint %} This endpoint provides the historical floor price for a specific collection and a given time period. ## GET /v1/ordinals/collections/{collectionId}/historical-floor-prices > Get historical floor prices for an Ordinals collection. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/ordinals/collections/{collectionId}/historical-floor-prices":{"get":{"tags":["Ordinals"],"description":"Get historical floor prices for an Ordinals collection.","parameters":[{"schema":{"type":"string"},"in":"query","name":"fromTimestamp","required":true,"description":"ISO timestamp - no older than 1 year ago (e.g. 2024-08-29T03:09:35.236Z)"},{"schema":{"type":"string"},"in":"query","name":"toTimestamp","required":false,"description":"ISO timestamp - up until now / not in the future"},{"schema":{"type":"string"},"in":"path","name":"collectionId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string"},"floorPrice":{"type":"object","properties":{"valueInSats":{"type":"number"},"valueInUsd":{"type":"string"}}}},"required":["timestamp","floorPrice"]}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # \[v2] Collection Historical Floor Prices This endpoint provides the historical floor price for a specific collection and a given time period. Collection prices are sourced from multiple ordinals marketplaces. ## GET /v2/ordinals/collections/{collectionId}/historical-floor-prices > Get historical floor prices for an Ordinals collection. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/ordinals/collections/{collectionId}/historical-floor-prices":{"get":{"tags":["Ordinals"],"description":"Get historical floor prices for an Ordinals collection.","parameters":[{"schema":{"type":"string"},"in":"query","name":"fromTimestamp","required":true,"description":"ISO timestamp - no older than 1 year ago (e.g. 2024-08-29T03:09:35.236Z)"},{"schema":{"type":"string"},"in":"query","name":"toTimestamp","required":false,"description":"ISO timestamp - up until now / not in the future"},{"schema":{"type":"string"},"in":"path","name":"collectionId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string"},"floorPrices":{"type":"array","items":{"type":"object","properties":{"marketplace":{"type":"string"},"valueInSats":{"type":"number"},"valueInUsd":{"type":"string"}}}}},"required":["timestamp","floorPrices"]}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Inscriptions # Inscription by ID This endpoint returns the information & metadata of a specific inscription ID. ## GET /v1/inscriptions/{inscriptionId} > Get inscription info with collection & pricing. Collection and price fields will be undefined if not available. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/inscriptions/{inscriptionId}":{"get":{"tags":["Ordinals"],"description":"Get inscription info with collection & pricing. Collection and price fields will be undefined if not available.","parameters":[{"schema":{"type":"string"},"in":"path","name":"inscriptionId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"offset":{"type":"number"},"parentIds":{"type":"array","items":{"type":"string"}},"delegateId":{"type":"string"},"blockHeight":{"type":"number"},"contentType":{"type":"string"},"contentLength":{"type":"number"},"effectiveContentType":{"type":"string"},"number":{"type":"number"},"sat":{"type":"number"},"charms":{"type":"array","items":{"type":"string"}},"currentOutput":{"type":"string"},"currentAddress":{"type":"string"},"lastTransferHeight":{"type":"number"},"lastTransferTimestamp":{"type":"number"},"value":{"type":"number"},"contentUrl":{"type":"string"},"renderUrl":{"type":"string"},"collectionId":{"type":"string"},"collectionSymbol":{"type":"string"},"collectionName":{"type":"string"},"collectionFloorPrice":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}},"lastInscriptionSalePrice":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}},"name":{"type":"string"},"indexerHeight":{"type":"number"}},"required":["id","parentIds","blockHeight","contentLength","number","charms","currentOutput","currentAddress","lastTransferHeight","lastTransferTimestamp","value","contentUrl","renderUrl","collectionFloorPrice","lastInscriptionSalePrice"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Inscription Thumbnail Returns a generated thumbnail image for the specified inscription ID ## GET /v1/inscriptions/{inscriptionId}/thumbnail > Get inscription rendered thumbnail. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/inscriptions/{inscriptionId}/thumbnail":{"get":{"tags":["Ordinals"],"description":"Get inscription rendered thumbnail.","parameters":[{"schema":{"type":"string"},"in":"path","name":"inscriptionId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Inscriptions by IDs This endpoint returns the information & metadata for multiple inscription IDs in a single request. ## GET /v1/inscriptions/batch > Get inscription info with collection & pricing for a batch of Inscriptions by IDs. Collection and price fields will be undefined if not available. The \`inscriptionIds\` query parameter should be a comma-separated list of Inscription IDs. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/inscriptions/batch":{"get":{"tags":["Ordinals"],"description":"Get inscription info with collection & pricing for a batch of Inscriptions by IDs. Collection and price fields will be undefined if not available. The `inscriptionIds` query parameter should be a comma-separated list of Inscription IDs.","parameters":[{"schema":{"minLength":1,"type":"string"},"in":"query","name":"inscriptionIds","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"offset":{"type":"number"},"parentIds":{"type":"array","items":{"type":"string"}},"delegateId":{"type":"string"},"blockHeight":{"type":"number"},"contentType":{"type":"string"},"contentLength":{"type":"number"},"effectiveContentType":{"type":"string"},"number":{"type":"number"},"sat":{"type":"number"},"charms":{"type":"array","items":{"type":"string"}},"currentOutput":{"type":"string"},"currentAddress":{"type":"string"},"lastTransferHeight":{"type":"number"},"lastTransferTimestamp":{"type":"number"},"value":{"type":"number"},"contentUrl":{"type":"string"},"renderUrl":{"type":"string"},"collectionId":{"type":"string"},"collectionSymbol":{"type":"string"},"collectionName":{"type":"string"},"collectionFloorPrice":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}},"lastInscriptionSalePrice":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}},"name":{"type":"string"},"indexerHeight":{"type":"number"}},"required":["id","parentIds","blockHeight","contentLength","number","charms","currentOutput","currentAddress","lastTransferHeight","lastTransferTimestamp","value","contentUrl","renderUrl","collectionFloorPrice","lastInscriptionSalePrice"]}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Inscription Activity This endpoint returns the full activity history (transfers, listings, sales) for a specific inscription. ## GET /v1/inscriptions/{inscriptionId}/activity > Get activity information for an inscription. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/inscriptions/{inscriptionId}/activity":{"get":{"tags":["Ordinals"],"description":"Get activity information for an inscription.","parameters":[{"schema":{"minimum":0,"multipleOf":25,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"minimum":25,"maximum":25,"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"inscriptionId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"offset":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"blockHeight":{"type":"number"},"blockTime":{"type":"string"},"inscriptionId":{"type":"string"},"toAddress":{"type":"string"},"txid":{"type":"string"},"vout":{"type":"number"}},"required":["blockHeight","blockTime","inscriptionId","toAddress","txid","vout"]}}},"required":["offset","limit","total","items"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Inscription Service **Automate Ordinal inscriptions** with advanced features. Estimate costs, create orders, and track inscription statuses seamlessly. # Estimate ## POST /v1/inscriptions/estimate > \

Coming soon...\

\
Estimate total cost for a new inscription order. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/inscriptions/estimate":{"post":{"tags":["Inscriptions"],"description":"

Coming soon...


Estimate total cost for a new inscription order.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{}}}}}}}}}} ``` # Order ## POST /v1/inscriptions/order > \

Coming soon...\

\
Create an inscription order (returns a funding address to pay). ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/inscriptions/order":{"post":{"tags":["Inscriptions"],"description":"

Coming soon...


Create an inscription order (returns a funding address to pay).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{}}}}}}}}}} ``` ## GET /v1/inscriptions/order/{orderId} > \

Coming soon...\

\
Retrieve status for a given inscription order. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/inscriptions/order/{orderId}":{"get":{"tags":["Inscriptions"],"description":"

Coming soon...


Retrieve status for a given inscription order.","parameters":[{"schema":{"type":"string"},"in":"path","name":"orderId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{}}}}}}}}}} ``` # Execute ## POST /v1/inscriptions/order/{orderId}/execute > \

Coming soon...\

\
Once funded, finalize (execute) the inscription order. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/inscriptions/order/{orderId}/execute":{"post":{"tags":["Inscriptions"],"description":"

Coming soon...


Once funded, finalize (execute) the inscription order.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"orderId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{}}}}}}}}}} ``` # Runes 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. # Runes by Address # \[v1] Rune Balances {% hint style="info" %} We recommend switching to [\[v2\] Rune balances](/api/runes/runes-by-address/v2-rune-balances-mempool-aware) for real-time mempool support {% endhint %} ## GET /v1/ordinals/address/{address}/runes > Retrieve confirmed Runes balances held by a specific address.\
\
\Note:\ The Api response includes limit & offset for future pagination extension, but\ > at the moment query parameters are ignored and the response is always the full list.\ > So, limit equals the total items number, be sure to handle pagination as the limit can change once pagination\ > is implemented. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/ordinals/address/{address}/runes":{"get":{"tags":["Ordinals","Runes"],"description":"Retrieve confirmed Runes balances held by a specific address.

Note: The Api response includes limit & offset for future pagination extension, but\n at the moment query parameters are ignored and the response is always the full list.\nSo, limit equals the total items number, be sure to handle pagination as the limit can change once pagination\nis implemented.","parameters":[{"schema":{"default":0,"minimum":0,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":60,"minimum":25,"maximum":60,"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"runeId","required":false},{"schema":{"minLength":10,"default":"bc1q0egjvlcfq77cxd9kvpgppyuxckzvws46e3sxch","format":"BitcoinAddress","type":"string"},"in":"path","name":"address","required":true}],"responses":{"200":{"description":"Rune balances for all utxos belonging to the address","content":{"application/json":{"schema":{"description":"Rune balances for all utxos belonging to the address","type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"total":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"runeName":{"type":"string"},"amount":{"type":"string"},"divisibility":{"type":"number"},"symbol":{"type":"string"},"inscriptionId":{"type":"string"},"id":{"type":"string"}},"required":["runeName","amount","id"]}},"indexerHeight":{"type":"number"}},"required":["limit","offset","total","items","indexerHeight"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # \[v2] Rune Balances (Mempool-Aware) ## GET /v2/runes/address/{address}/balance > Get confirmed and unconfirmed runes balance.\ > \balance\ fields explained:\ > \
    \ > \
  • \confirmedBalance\ is the rune balance ignoring unconfirmed transactions in mempool.\
    • \ > \
  • \availableBalance\ is the confirmed balance minus amounts used by any\ > outgoing unconfirmed transaction in mempool.\
    • \ > \
  • \projectedBalance\ is the final balance if all unconfirmed mempool\ > transactions are confirmed.\
    • \ > \
  • \pendingBalance\ is a breakdown of the unconfirmed transactions amounts.\ > They represent aggregate amounts for the whole mempool activity, so as more\ > transactions are chained together the amounts will increase.\ > \
      \ > \
    • \incomingAmount\ is the sum of all incoming unconfirmed amounts.\
      • \ > \
    • \outgoingAmount\ is the sum of all outgoing unconfirmed amounts.\
      • \ > \
    • \netAmount\ is \incoming\ - \outgoing\.\ > The \netAmount\ can be negative,\ > when sending more than receiving. It should always match what is expected to be added to\ > the confirmed balance when all unconfirmed transactions are confirmed, which is computed\ > as \projectedBalance\ for convenience.\
      • \ > \
    \ > \
    • \ > \
\ > ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v2/runes/address/{address}/balance":{"get":{"tags":["Runes"],"description":"Get confirmed and unconfirmed runes balance.\n balance fields explained:\n
    \n
  • confirmedBalance is the rune balance ignoring unconfirmed transactions in mempool.
    • \n
  • availableBalance is the confirmed balance minus amounts used by any\n outgoing unconfirmed transaction in mempool.
    • \n
  • projectedBalance is the final balance if all unconfirmed mempool\n transactions are confirmed.
    • \n
  • pendingBalance is a breakdown of the unconfirmed transactions amounts.\n They represent aggregate amounts for the whole mempool activity, so as more\n transactions are chained together the amounts will increase.\n
      \n
    • incomingAmount is the sum of all incoming unconfirmed amounts.
      • \n
    • outgoingAmount is the sum of all outgoing unconfirmed amounts.
      • \n
    • netAmount is incoming - outgoing.\n The netAmount can be negative,\n when sending more than receiving. It should always match what is expected to be added to\n the confirmed balance when all unconfirmed transactions are confirmed, which is computed\n as projectedBalance for convenience.
      • \n
    \n
    • \n
\n ","parameters":[{"schema":{"type":"string"},"in":"query","name":"runeId","required":false},{"schema":{"type":"boolean"},"in":"query","name":"includePricing","required":false},{"schema":{"minLength":10,"default":"bc1q0egjvlcfq77cxd9kvpgppyuxckzvws46e3sxch","format":"BitcoinAddress","type":"string"},"in":"path","name":"address","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"balances":{"type":"array","items":{"type":"object","properties":{"runeId":{"type":"string"},"divisibility":{"type":"number"},"symbol":{"type":"string"},"runeName":{"type":"string"},"confirmedBalance":{"description":"Confirmed balance, ignoring mempool","type":"string"},"availableBalance":{"description":"Confirmed balance minus spent in mempool amounts","type":"string"},"projectedBalance":{"description":"Confirmed balance plus unconfirmed amounts. Final balance if all get confirmed.","type":"string"},"pendingBalance":{"description":"Breakdown of unconfirmed/mempool amounts","type":"object","properties":{"incomingAmount":{"description":"Sum of all incoming unconfirmed amounts","type":"string"},"outgoingAmount":{"description":"Sum of all outgoing unconfirmed amounts","type":"string"},"netAmount":{"description":"Incoming - Outgoing","type":"string"}},"required":["incomingAmount","outgoingAmount","netAmount"]},"prices":{"type":"object","properties":{"floorPrice":{"type":"object","allOf":[{"type":"object","properties":{"marketplace":{"type":"string"},"percentageChange24h":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}}},"required":["percentageChange24h"]},{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}}]},"lastSalePrice":{"type":"object","allOf":[{"type":"object","properties":{"marketplace":{"type":"string"}}},{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}}]}},"required":["floorPrice","lastSalePrice"]},"volume24h":{"type":"object","allOf":[{"type":"object","properties":{"percentageChange":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}}},"required":["percentageChange"]},{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}}]}},"required":["runeId","confirmedBalance","availableBalance","projectedBalance","pendingBalance"]}},"indexerHeight":{"description":"Last height indexed by the runes indexer","type":"number"}},"required":["balances","indexerHeight"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Rune Activity Returns historical activity (transfers, mints, etc.) for a specific Rune held by a given address. ## GET /v1/ordinals/address/{address}/runes/{identifier}/activity > Get rune activity for a specific address and rune ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/ordinals/address/{address}/runes/{identifier}/activity":{"get":{"tags":["Ordinals","Runes"],"description":"Get rune activity for a specific address and rune","parameters":[{"schema":{"default":0,"minimum":0,"multipleOf":25,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":25,"minimum":25,"maximum":25,"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"minimum":0,"type":"number"},"in":"query","name":"fromBlockHeight","required":false},{"schema":{"minimum":0,"type":"number"},"in":"query","name":"toBlockHeight","required":false},{"schema":{"type":"string"},"in":"path","name":"address","required":true},{"schema":{"type":"string"},"in":"path","name":"identifier","required":true}],"responses":{"200":{"description":"Rune activity for a specific rune or address","content":{"application/json":{"schema":{"description":"Rune activity for a specific rune or address","type":"object","properties":{"offset":{"type":"number"},"limit":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"blockHeight":{"type":"number"},"blockTime":{"type":"string"},"txid":{"type":"string"},"index":{"nullable":true,"type":"number"},"type":{"type":"string"},"amount":{"type":"string"},"address":{"nullable":true,"type":"string"}},"required":["blockHeight","blockTime","txid","index","type","amount","address"]}}},"required":["offset","limit","items"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # UTXOs ## GET /v1/runes/address/{address}/utxo > Get Rune UTXOs for a specific address with pagination support. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/runes/address/{address}/utxo":{"get":{"tags":["Runes"],"description":"Get Rune UTXOs for a specific address with pagination support.","parameters":[{"schema":{"default":0,"minimum":0,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":60,"minimum":25,"maximum":60,"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"runeId","required":false},{"schema":{"default":false,"type":"boolean"},"in":"query","name":"includeUnconfirmed","required":false},{"schema":{"minLength":10,"default":"bc1q0egjvlcfq77cxd9kvpgppyuxckzvws46e3sxch","format":"BitcoinAddress","type":"string"},"in":"path","name":"address","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"total":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"txid":{"type":"string"},"vout":{"type":"number"},"amount":{"type":"number"},"blockHeight":{"nullable":true,"type":"number"},"runes":{"type":"array","items":{"type":"object","properties":{"runeName":{"type":"string"},"runeId":{"type":"string"},"amount":{"type":"string"},"divisibility":{"type":"number"},"symbol":{"type":"string"}},"required":["runeName","runeId","amount","divisibility","symbol"]}}},"required":["txid","vout","amount","blockHeight","runes"]}}},"required":["limit","offset","total","items"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Rune by ID This endpoint is used to retrieve the metadata & market data associated with a rune, based on the rune ID. ## GET /v1/runes/{identifier} > Get price info for a specific Rune by ID. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/runes/{identifier}":{"get":{"tags":["Ordinals","Runes"],"description":"Get price info for a specific Rune by ID.","parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"chain":{"type":"string"},"runeName":{"type":"string"},"symbol":{"type":"string"},"runeId":{"type":"string"},"spacedRuneName":{"type":"string"},"amount":{"type":"string"},"cap":{"type":"string"},"divisibility":{"nullable":true,"type":"string"},"premine":{"type":"string"},"turbo":{"type":"boolean"},"genesisBlock":{"type":"number"},"mint":{"type":"object","properties":{"offset":{"type":"object","properties":{"low":{"nullable":true,"type":"string"},"high":{"nullable":true,"type":"string"}}},"height":{"type":"object","properties":{"low":{"nullable":true,"type":"string"},"high":{"nullable":true,"type":"string"}}}},"required":["offset","height"]},"holders":{"type":"string"},"supply":{"type":"string"},"marketCap":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}},"prices":{"type":"object","properties":{"floorPrice":{"type":"object","properties":{"marketplace":{"type":"string"},"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"},"percentageChange24h":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}}},"required":["percentageChange24h"]},"lastSalePrice":{"type":"object","properties":{"marketplace":{"type":"string"},"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}}},"required":["floorPrice","lastSalePrice"]},"volume24h":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"},"percentageChange":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}}},"required":["percentageChange"]},"inscriptionId":{"type":"string"},"inscriptionRenderUrl":{"type":"string"}},"required":["chain","runeName","runeId","spacedRuneName","divisibility","turbo","genesisBlock","mint","marketCap","prices","volume24h"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Runes by IDs 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. ## GET /v1/runes/batch-info > Get price info for a list of runes. The \`runeIds\`\ > query parameter should be a comma-separated list of Rune IDs. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/runes/batch-info":{"get":{"tags":["Ordinals","Runes"],"description":"Get price info for a list of runes. The `runeIds`\n query parameter should be a comma-separated list of Rune IDs.","parameters":[{"schema":{"minLength":1,"type":"string"},"in":"query","name":"runeIds","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"chain":{"type":"string"},"runeName":{"type":"string"},"symbol":{"type":"string"},"runeId":{"type":"string"},"spacedRuneName":{"type":"string"},"amount":{"type":"string"},"cap":{"type":"string"},"divisibility":{"nullable":true,"type":"string"},"premine":{"type":"string"},"turbo":{"type":"boolean"},"genesisBlock":{"type":"number"},"mint":{"type":"object","properties":{"offset":{"type":"object","properties":{"low":{"nullable":true,"type":"string"},"high":{"nullable":true,"type":"string"}}},"height":{"type":"object","properties":{"low":{"nullable":true,"type":"string"},"high":{"nullable":true,"type":"string"}}}},"required":["offset","height"]},"holders":{"type":"string"},"supply":{"type":"string"},"marketCap":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}},"prices":{"type":"object","properties":{"floorPrice":{"type":"object","properties":{"marketplace":{"type":"string"},"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"},"percentageChange24h":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}}},"required":["percentageChange24h"]},"lastSalePrice":{"type":"object","properties":{"marketplace":{"type":"string"},"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}}},"required":["floorPrice","lastSalePrice"]},"volume24h":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"},"percentageChange":{"type":"object","properties":{"valueInSats":{"type":"string"},"valueInUsd":{"type":"string"}}}},"required":["percentageChange"]},"inscriptionId":{"type":"string"},"inscriptionRenderUrl":{"type":"string"}},"required":["chain","runeName","runeId","spacedRuneName","divisibility","turbo","genesisBlock","mint","marketCap","prices","volume24h"]}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` # Search Runes Search existing Runes by name, order results by name or by etching block + index. ## GET /v1/runes > Search for runes by name. ```json {"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[{"name":"Ordinals"}],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/runes":{"get":{"tags":["Ordinals","Runes"],"description":"Search for runes by name.","parameters":[{"schema":{"minLength":1,"type":"string"},"in":"query","name":"startingWith","required":true,"description":"Search for runes starting with this string"},{"schema":{"enum":["runeName","etch"],"default":"runeName","type":"string"},"in":"query","name":"sortBy","required":false,"description":"* `runeName` - sort by rune name ascending\n* `etch` - sort by etching order block_height, rune_etch_index ascending"},{"schema":{"minimum":0,"default":0,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":5,"minimum":1,"maximum":10,"type":"number"},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Search results for runes","content":{"application/json":{"schema":{"description":"Search results for runes","type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"runeId":{"type":"string"},"runeName":{"type":"string"},"symbol":{"type":"string"},"divisibility":{"type":"number"}},"required":["runeId","runeName","symbol"]}},"offset":{"type":"number"},"limit":{"type":"number"}},"required":["items","offset","limit"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}} ``` --- [Next Page](/llms-full.txt/1)