{"openapi":"3.1.0","info":{"title":"Subscan (BYOK) API","version":"0.1.0","description":"Subscan (BYOK) lets an AI assistant read your own Subscan data through the Subscan API with a key you supply (Subscan direct API key (paid plan; free access now goes through the PubFi gateway)). Read-only: 11 tools (get_network_metadata, get_account, list_account_tokens, list_transfers, list_blocks, get_block, list_extrinsics, get_extrinsic, list_events, list_validators,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-subscan.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-subscan/docs"},"termsOfService":"https://connectorbay.com/byok-subscan/terms"},"servers":[{"url":"https://byok-subscan.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-subscan/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_network_metadata":{"post":{"operationId":"get_network_metadata","summary":"Show the current network's metadata: node name, SS58 address type, current runtime and other chain settings. Use for \"Wh","description":"Show the current network's metadata: node name, SS58 address type, current runtime and other chain settings. Use for \"What is the SS58 prefix of the Polkadot network on Subscan\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"network":{"description":"Network name as in its Subscan address: polkadot for polkadot.subscan.io, kusama, astar, moonbeam and so on.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Network","type":"string"}},"required":["network"],"title":"get_network_metadataArguments","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":{"post":{"operationId":"get_account","summary":"Look up one account by Substrate address, EVM address or SS58 index: balance, locks, reserved and bonded amounts, nonce,","description":"Look up one account by Substrate address, EVM address or SS58 index: balance, locks, reserved and bonded amounts, nonce, roles and extrinsic count. Use for \"What is the balance of account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY on Polkadot\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"network":{"description":"Network name as in its Subscan address: polkadot for polkadot.subscan.io, kusama, astar, moonbeam and so on.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Network","type":"string"},"key":{"description":"Account address (Substrate or EVM) or SS58 account index.","maxLength":100,"title":"Key","type":"string"}},"required":["network","key"],"title":"get_accountArguments","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_account_tokens":{"post":{"operationId":"list_account_tokens","summary":"List the token holdings of one account (native token, assets, ERC-20 and ERC-721 where available) with balance, price, s","description":"List the token holdings of one account (native token, assets, ERC-20 and ERC-721 where available) with balance, price, symbol, decimals and category. Use for \"Which tokens does this Polkadot account hold\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"network":{"description":"Network name as in its Subscan address: polkadot for polkadot.subscan.io, kusama, astar, moonbeam and so on.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Network","type":"string"},"address":{"description":"Account address.","maxLength":100,"title":"Address","type":"string"},"order_field":{"anyOf":[{"enum":["token","balance","price","supply"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by token, balance, price or supply.","title":"Order Field"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: desc or asc.","title":"Order"},"page":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting from 0.","title":"Page"},"row":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Rows per page (1 to 100).","title":"Row"}},"required":["network","address"],"title":"list_account_tokensArguments","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_transfers":{"post":{"operationId":"list_transfers","summary":"List transfers on the network filtered by account, direction, token, amount, success or block range, with amounts, sende","description":"List transfers on the network filtered by account, direction, token, amount, success or block range, with amounts, sender, receiver, block and timestamp. Use for \"What are the latest transfers for this Polkadot account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"network":{"description":"Network name as in its Subscan address: polkadot for polkadot.subscan.io, kusama, astar, moonbeam and so on.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Network","type":"string"},"address":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only transfers involving this account.","title":"Address"},"direction":{"anyOf":[{"enum":["all","sent","received"],"type":"string"},{"type":"null"}],"default":null,"description":"all, sent or received (relative to address).","title":"Direction"},"asset_symbol":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only transfers of this token symbol, for example DOT.","title":"Asset Symbol"},"sender":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only transfers sent by this account.","title":"Sender"},"receiver":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only transfers received by this account.","title":"Receiver"},"success":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for successful transfers only.","title":"Success"},"block_range":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only items in this block range, for example '1000-2000'.","title":"Block Range"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: desc or asc.","title":"Order"},"page":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting from 0.","title":"Page"},"row":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Rows per page (1 to 100).","title":"Row"}},"required":["network"],"title":"list_transfersArguments","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 recent blocks with number, hash, timestamp, extrinsic and event counts, finalized flag and block author. Use for \"W","description":"List recent blocks with number, hash, timestamp, extrinsic and event counts, finalized flag and block author. Use for \"What are the latest blocks on Polkadot\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"network":{"description":"Network name as in its Subscan address: polkadot for polkadot.subscan.io, kusama, astar, moonbeam and so on.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Network","type":"string"},"author":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only blocks authored by this validator address.","title":"Author"},"block_range":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only items in this block range, for example '1000-2000'.","title":"Block Range"},"page":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting from 0.","title":"Page"},"row":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Rows per page (1 to 100).","title":"Row"}},"required":["network"],"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 block by number, hash or nearest timestamp: hash, parent hash, roots, extrinsic and event counts, finalized flag","description":"Get one block by number, hash or nearest timestamp: hash, parent hash, roots, extrinsic and event counts, finalized flag, validator and spec version. Use for \"Show Polkadot block 1000000\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"network":{"description":"Network name as in its Subscan address: polkadot for polkadot.subscan.io, kusama, astar, moonbeam and so on.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Network","type":"string"},"block_num":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Block number.","title":"Block Num"},"block_hash":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Block hash (0x...).","title":"Block Hash"},"block_timestamp":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Unix timestamp in seconds; returns the nearest block.","title":"Block Timestamp"}},"required":["network"],"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/list_extrinsics":{"post":{"operationId":"list_extrinsics","summary":"List extrinsics (transactions) filtered by signer, module, call, success or block range, with hash, index, fee, tip and ","description":"List extrinsics (transactions) filtered by signer, module, call, success or block range, with hash, index, fee, tip and block time. Use for \"Which extrinsics did this account sign recently on Polkadot\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"network":{"description":"Network name as in its Subscan address: polkadot for polkadot.subscan.io, kusama, astar, moonbeam and so on.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Network","type":"string"},"address":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only extrinsics signed by this account.","title":"Address"},"module":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only extrinsics of this pallet, for example balances.","title":"Module"},"call":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only extrinsics of this call, for example transfer_keep_alive (use with module).","title":"Call"},"success":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for successful extrinsics only.","title":"Success"},"block_range":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only items in this block range, for example '1000-2000'.","title":"Block Range"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: desc or asc.","title":"Order"},"page":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting from 0.","title":"Page"},"row":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Rows per page (1 to 100).","title":"Row"}},"required":["network"],"title":"list_extrinsicsArguments","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_extrinsic":{"post":{"operationId":"get_extrinsic","summary":"Get one extrinsic by index (block-position) or hash: call, signer, success, fee, nonce, events count, error and transfer","description":"Get one extrinsic by index (block-position) or hash: call, signer, success, fee, nonce, events count, error and transfer summary. Use for \"What happened in extrinsic 100-2 on Polkadot\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"network":{"description":"Network name as in its Subscan address: polkadot for polkadot.subscan.io, kusama, astar, moonbeam and so on.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Network","type":"string"},"extrinsic_index":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Extrinsic index such as 12345-2.","title":"Extrinsic Index"},"hash":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Extrinsic hash (0x...).","title":"Hash"},"hide_events":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to leave events out of the answer.","title":"Hide Events"}},"required":["network"],"title":"get_extrinsicArguments","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_events":{"post":{"operationId":"list_events","summary":"List on-chain events filtered by pallet, event, extrinsic or block range with event ID, extrinsic index, phase and times","description":"List on-chain events filtered by pallet, event, extrinsic or block range with event ID, extrinsic index, phase and timestamp. Use for \"Which Balances events happened in Polkadot block 1000000\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"network":{"description":"Network name as in its Subscan address: polkadot for polkadot.subscan.io, kusama, astar, moonbeam and so on.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Network","type":"string"},"module":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only events of this pallet, for example balances.","title":"Module"},"event_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only events with this event ID, for example Transfer.","title":"Event Id"},"block_num":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only events of this block number.","title":"Block Num"},"extrinsic_index":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only events of this extrinsic index.","title":"Extrinsic Index"},"address":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only events related to this account.","title":"Address"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: desc or asc.","title":"Order"},"page":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting from 0.","title":"Page"},"row":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Rows per page (1 to 100).","title":"Row"}},"required":["network"],"title":"list_eventsArguments","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_validators":{"post":{"operationId":"list_validators","summary":"List staking validators (networks with the staking pallet) with status, bonded totals, nominator count, commission value","description":"List staking validators (networks with the staking pallet) with status, bonded totals, nominator count, commission value and reward points. Use for \"Which Polkadot validators have the lowest commission\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"network":{"description":"Network name as in its Subscan address: polkadot for polkadot.subscan.io, kusama, astar, moonbeam and so on.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Network","type":"string"},"order_field":{"anyOf":[{"enum":["rank_validator","bonded_nominators","bonded_owner","count_nominators","validator_prefs_value","bonded_total"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by rank_validator, bonded_nominators, bonded_owner, count_nominators, validator_prefs_value or bonded_total.","title":"Order Field"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: desc or asc.","title":"Order"},"blocked":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to list only validators that block nominations.","title":"Blocked"},"page":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting from 0.","title":"Page"},"row":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Rows per page (1 to 100).","title":"Row"}},"required":["network"],"title":"list_validatorsArguments","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_democracy_referendums":{"post":{"operationId":"list_democracy_referendums","summary":"List democracy referendums (networks with the democracy pallet) with index, title, status, call and vote threshold. Use ","description":"List democracy referendums (networks with the democracy pallet) with index, title, status, call and vote threshold. Use for \"Which referendums are active on Kusama\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"network":{"description":"Network name as in its Subscan address: polkadot for polkadot.subscan.io, kusama, astar, moonbeam and so on.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Network","type":"string"},"status":{"anyOf":[{"enum":["active","completed"],"type":"string"},{"type":"null"}],"default":null,"description":"active or completed.","title":"Status"},"page":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting from 0.","title":"Page"},"row":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Rows per page (1 to 100).","title":"Row"}},"required":["network"],"title":"list_democracy_referendumsArguments","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}}}}