{"openapi":"3.1.0","info":{"title":"Koios (BYOK) API","version":"0.1.0","description":"Koios (BYOK) lets an AI assistant read your own Koios data through the Koios API with a key you supply (Koios API token (JWT from your Koios profile)). Read-only: 12 tools (get_chain_tip, get_epoch_info, get_tokenomics_totals, list_recent_blocks, list_stake_pools, get_pool_info, get_address_info, get_address_assets, get_address_transactions, get_account_info, get_transaction_info,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-koios.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-koios/docs"},"termsOfService":"https://connectorbay.com/byok-koios/terms"},"servers":[{"url":"https://byok-koios.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-koios/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_chain_tip":{"post":{"operationId":"get_chain_tip","summary":"Get the latest Cardano block: hash, era, epoch, slot, block height and block time. Use for \"What is the latest Cardano b","description":"Get the latest Cardano block: hash, era, epoch, slot, block height and block time. Use for \"What is the latest Cardano block and epoch\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_chain_tipArguments","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_epoch_info":{"post":{"operationId":"get_epoch_info","summary":"Get statistics for one Cardano epoch (or the current one if none is given): transactions, blocks, fees, active stake and","description":"Get statistics for one Cardano epoch (or the current one if none is given): transactions, blocks, fees, active stake and rewards. Use for \"How many transactions and how much active stake did Cardano epoch 500 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"epoch_no":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Epoch number; leave empty for the current epoch.","title":"Epoch No"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Maximum rows to return (1 to 1000).","title":"Limit"}},"title":"get_epoch_infoArguments","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_tokenomics_totals":{"post":{"operationId":"get_tokenomics_totals","summary":"Get Cardano supply figures per epoch: circulation, treasury, reserves, rewards, fees and deposits, in lovelace. Use for ","description":"Get Cardano supply figures per epoch: circulation, treasury, reserves, rewards, fees and deposits, in lovelace. Use for \"How big is the Cardano treasury in the latest epoch\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"epoch_no":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Epoch number; leave empty for all epochs (use limit to cut the list).","title":"Epoch No"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Maximum rows to return (1 to 1000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Rows to skip, for paging; the next page of 25 starts at offset 25.","title":"Offset"}},"title":"get_tokenomics_totalsArguments","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_recent_blocks":{"post":{"operationId":"list_recent_blocks","summary":"List the most recent Cardano blocks with height, epoch, size, transaction count, producing pool and time. Use for \"Show ","description":"List the most recent Cardano blocks with height, epoch, size, transaction count, producing pool and time. Use for \"Show the last 10 Cardano blocks and who minted them\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Maximum rows to return (1 to 1000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Rows to skip, for paging; the next page of 25 starts at offset 25.","title":"Offset"}},"title":"list_recent_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/list_stake_pools":{"post":{"operationId":"list_stake_pools","summary":"List Cardano stake pools with ticker, margin, fixed cost, pledge, active stake and status. Use for \"Which Cardano stake ","description":"List Cardano stake pools with ticker, margin, fixed cost, pledge, active stake and status. Use for \"Which Cardano stake pools have the most active stake\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Maximum rows to return (1 to 1000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Rows to skip, for paging; the next page of 25 starts at offset 25.","title":"Offset"}},"title":"list_stake_poolsArguments","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_pool_info":{"post":{"operationId":"get_pool_info","summary":"Get detail of one Cardano stake pool: live stake, delegators, saturation, blocks minted, margin, pledge and metadata. Us","description":"Get detail of one Cardano stake pool: live stake, delegators, saturation, blocks minted, margin, pledge and metadata. Use for \"How saturated is the pool pool100wj94uzf54vup2hdzk0afng4dhjaqggt7j434mtgm8v2gfvfgp\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"pool_id":{"description":"Stake pool ID in bech32 form, starting with pool1.","maxLength":80,"title":"Pool Id","type":"string"}},"required":["pool_id"],"title":"get_pool_infoArguments","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_address_info":{"post":{"operationId":"get_address_info","summary":"Get the ADA balance (lovelace), stake address and script flag of one Cardano payment address. Use for \"What is the ADA b","description":"Get the ADA balance (lovelace), stake address and script flag of one Cardano payment address. Use for \"What is the ADA balance of this Cardano address\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"address":{"description":"Cardano payment address in bech32 form, starting with addr1.","maxLength":200,"title":"Address","type":"string"}},"required":["address"],"title":"get_address_infoArguments","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_address_assets":{"post":{"operationId":"get_address_assets","summary":"List the native tokens and NFTs held by one Cardano payment address, with policy ID, asset name, fingerprint and quantit","description":"List the native tokens and NFTs held by one Cardano payment address, with policy ID, asset name, fingerprint and quantity. Use for \"Which tokens does this Cardano address hold\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"address":{"description":"Cardano payment address in bech32 form, starting with addr1.","maxLength":200,"title":"Address","type":"string"}},"required":["address"],"title":"get_address_assetsArguments","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_address_transactions":{"post":{"operationId":"get_address_transactions","summary":"List transaction hashes that touched one Cardano payment address, with epoch, block height and time, optionally after a ","description":"List transaction hashes that touched one Cardano payment address, with epoch, block height and time, optionally after a block height. Use for \"What are the recent transactions of this Cardano address\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"address":{"description":"Cardano payment address in bech32 form, starting with addr1.","maxLength":200,"title":"Address","type":"string"},"after_block_height":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only transactions after this block height.","title":"After Block Height"}},"required":["address"],"title":"get_address_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/get_account_info":{"post":{"operationId":"get_account_info","summary":"Get a Cardano stake account: delegation status, delegated pool and DRep, total balance, rewards and withdrawals, in love","description":"Get a Cardano stake account: delegation status, delegated pool and DRep, total balance, rewards and withdrawals, in lovelace. Use for \"Which pool is this Cardano stake address delegated to and what rewards does it have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"stake_address":{"description":"Stake (reward) address in bech32 form, starting with stake1.","maxLength":80,"title":"Stake Address","type":"string"}},"required":["stake_address"],"title":"get_account_infoArguments","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_info":{"post":{"operationId":"get_transaction_info","summary":"Get one Cardano transaction: block, time, fee, total output and size. Inputs and outputs are not requested. Use for \"How","description":"Get one Cardano transaction: block, time, fee, total output and size. Inputs and outputs are not requested. Use for \"How much was the fee of this Cardano transaction\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tx_hash":{"description":"Transaction hash, 64 hexadecimal characters.","maxLength":64,"title":"Tx Hash","type":"string"}},"required":["tx_hash"],"title":"get_transaction_infoArguments","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_policy_assets":{"post":{"operationId":"list_policy_assets","summary":"List the native assets minted under one Cardano policy ID, with asset name, fingerprint, total supply and decimals. Use ","description":"List the native assets minted under one Cardano policy ID, with asset name, fingerprint, total supply and decimals. Use for \"Which assets exist under this Cardano policy ID\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"asset_policy":{"description":"Native asset policy ID as hexadecimal text (56 characters).","maxLength":64,"title":"Asset Policy","type":"string"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Maximum rows to return (1 to 1000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Rows to skip, for paging; the next page of 25 starts at offset 25.","title":"Offset"}},"required":["asset_policy"],"title":"list_policy_assetsArguments","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}}}}