{"openapi":"3.1.0","info":{"title":"Hiro (BYOK) API","version":"0.1.0","description":"Hiro (BYOK) lets an AI assistant read your own Hiro data through the Hiro API with a key you supply (Hiro API key (free in the Hiro Platform: 500 requests per minute)). Read-only: 11 tools (get_api_status, get_stx_supply, get_mempool_summary, list_blocks, get_block, get_transaction, get_principal_stx_balance, list_principal_ft_balances, list_principal_nft_balances, list_principal_transactions,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-hiro.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-hiro/docs"},"termsOfService":"https://connectorbay.com/byok-hiro/terms"},"servers":[{"url":"https://byok-hiro.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-hiro/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_api_status":{"post":{"operationId":"get_api_status","summary":"Get the running status of the Stacks Blockchain API: server version and the chain tip with block height and hashes. Use ","description":"Get the running status of the Stacks Blockchain API: server version and the chain tip with block height and hashes. Use for \"What is the current Stacks block height\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_api_statusArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_stx_supply":{"post":{"operationId":"get_stx_supply","summary":"Get the total liquid STX supply in micro-STX and the projected supply in 2050. Use for \"What is the current STX supply\".","description":"Get the total liquid STX supply in micro-STX and the projected supply in 2050. Use for \"What is the current STX supply\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_stx_supplyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_mempool_summary":{"post":{"operationId":"get_mempool_summary","summary":"Get a summary of pending Stacks transactions: counts and fee, size and wait percentiles, overall and by transaction type","description":"Get a summary of pending Stacks transactions: counts and fee, size and wait percentiles, overall and by transaction type. Use for \"How busy is the Stacks mempool and what fees are pending\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_mempool_summaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_blocks":{"post":{"operationId":"list_blocks","summary":"List recently mined Stacks blocks with height, hash, time, tenure height, Bitcoin anchor and transaction count. Use for ","description":"List recently mined Stacks blocks with height, hash, time, tenure height, Bitcoin anchor and transaction count. Use for \"What are the latest Stacks blocks\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Results per page.","title":"Limit"},"offset":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Result offset.","title":"Offset"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor taken from the previous page's cursor.next.","title":"Cursor"}},"title":"list_blocksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_block":{"post":{"operationId":"get_block","summary":"Get one Stacks block by height or hash. Use for \"What is in Stacks block 144000\".","description":"Get one Stacks block by height or hash. Use for \"What is in Stacks block 144000\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"height_or_hash":{"description":"Block height or block hash.","maxLength":80,"title":"Height Or Hash","type":"string"}},"required":["height_or_hash"],"title":"get_blockArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_transaction":{"post":{"operationId":"get_transaction","summary":"Get a Stacks transaction by id: sender, sponsor, fee, status, type, block, execution cost and result. Use for \"What are ","description":"Get a Stacks transaction by id: sender, sponsor, fee, status, type, block, execution cost and result. Use for \"What are the details of this Stacks transaction\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tx_id":{"description":"Transaction id, 0x-prefixed.","maxLength":70,"title":"Tx Id","type":"string"}},"required":["tx_id"],"title":"get_transactionArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_principal_stx_balance":{"post":{"operationId":"get_principal_stx_balance","summary":"Get the STX balance of a Stacks address: total, spendable, locked amount and the projected balance from pending transact","description":"Get the STX balance of a Stacks address: total, spendable, locked amount and the projected balance from pending transactions. Use for \"What is the STX balance of this Stacks address\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"principal":{"description":"Stacks address (principal), for example an SP... address or a contract id.","maxLength":160,"title":"Principal","type":"string"}},"required":["principal"],"title":"get_principal_stx_balanceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_principal_ft_balances":{"post":{"operationId":"list_principal_ft_balances","summary":"List the fungible token balances of a Stacks address, sorted by balance descending. Use for \"Which fungible tokens does ","description":"List the fungible token balances of a Stacks address, sorted by balance descending. Use for \"Which fungible tokens does this Stacks address hold\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"principal":{"description":"Stacks address (principal), for example an SP... address or a contract id.","maxLength":160,"title":"Principal","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Results per page.","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor taken from the previous page's cursor.next.","title":"Cursor"}},"required":["principal"],"title":"list_principal_ft_balancesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_principal_nft_balances":{"post":{"operationId":"list_principal_nft_balances","summary":"List the NFTs owned by a Stacks address, optionally limited to one NFT asset class. Use for \"Which NFTs does this Stacks","description":"List the NFTs owned by a Stacks address, optionally limited to one NFT asset class. Use for \"Which NFTs does this Stacks address own\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"principal":{"description":"Stacks address (principal), for example an SP... address or a contract id.","maxLength":160,"title":"Principal","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Results per page.","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor taken from the previous page's cursor.next.","title":"Cursor"},"asset_identifier":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only instances of this NFT asset class, for example SP000000000000000000002Q6VF78.bns::names.","title":"Asset Identifier"}},"required":["principal"],"title":"list_principal_nft_balancesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_principal_transactions":{"post":{"operationId":"list_principal_transactions","summary":"List confirmed transactions sent or received by a Stacks address, with type, status, block, and the balances affected. U","description":"List confirmed transactions sent or received by a Stacks address, with type, status, block, and the balances affected. Use for \"What are the latest transactions of this Stacks address\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"principal":{"description":"Stacks address (principal), for example an SP... address or a contract id.","maxLength":160,"title":"Principal","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Results per page.","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor taken from the previous page's cursor.next.","title":"Cursor"}},"required":["principal"],"title":"list_principal_transactionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_ft_holders":{"post":{"operationId":"list_ft_holders","summary":"List the holders of a fungible token on Stacks, sorted by balance descending, in the token's base units. Use for \"Who ho","description":"List the holders of a fungible token on Stacks, sorted by balance descending, in the token's base units. Use for \"Who holds the sBTC token on Stacks\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"asset_identifier":{"description":"Fungible token asset identifier, contract id followed by :: and the token name.","maxLength":200,"title":"Asset Identifier","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Results per page.","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor taken from the previous page's cursor.next.","title":"Cursor"}},"required":["asset_identifier"],"title":"list_ft_holdersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}