{"openapi":"3.1.0","info":{"title":"Blockscout (BYOK) API","version":"0.1.0","description":"Blockscout (BYOK) lets an AI assistant read your own Blockscout data through the Blockscout API with a key you supply (Blockscout PRO API key (starts with proapi_)). Read-only: 12 tools (get_network_stats, get_address, list_address_transactions, list_address_token_balances, list_address_token_transfers, get_transaction, list_blocks, get_block, list_tokens, get_token, get_smart_contract, search)....\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-blockscout.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-blockscout/docs"},"termsOfService":"https://connectorbay.com/byok-blockscout/terms"},"servers":[{"url":"https://byok-blockscout.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-blockscout/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_stats":{"post":{"operationId":"get_network_stats","summary":"Get a network's headline statistics: total addresses, blocks and transactions, transactions today, average block time, n","description":"Get a network's headline statistics: total addresses, blocks and transactions, transactions today, average block time, native coin price and market cap, gas prices and network utilization. Use for \"How busy is the Ethereum network right now and what are gas prices\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain_id":{"description":"Numeric chain id of the network: 1 Ethereum, 10 Optimism, 137 Polygon, 8453 Base, 42161 Arbitrum One. Any chain the Blockscout PRO API supports.","maxLength":20,"title":"Chain Id","type":"string"}},"required":["chain_id"],"title":"get_network_statsArguments","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":{"post":{"operationId":"get_address","summary":"Get an address or contract: native coin balance, name, ENS name, whether it is a contract and verified, creator, creatio","description":"Get an address or contract: native coin balance, name, ENS name, whether it is a contract and verified, creator, creation transaction, scam reputation and its token details if it is a token. Use for \"What is the balance of vitalik.eth's address on Ethereum\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain_id":{"description":"Numeric chain id of the network: 1 Ethereum, 10 Optimism, 137 Polygon, 8453 Base, 42161 Arbitrum One. Any chain the Blockscout PRO API supports.","maxLength":20,"title":"Chain Id","type":"string"},"address_hash":{"description":"Address hash, a 0x-prefixed hex string.","maxLength":66,"title":"Address Hash","type":"string"}},"required":["chain_id","address_hash"],"title":"get_addressArguments","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_address_transactions":{"post":{"operationId":"list_address_transactions","summary":"List the newest transactions of an address (first page, up to 50), optionally only incoming or outgoing, with status, va","description":"List the newest transactions of an address (first page, up to 50), optionally only incoming or outgoing, with status, value, fee, method and time. Use for \"What are the latest transactions sent from this Ethereum address\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain_id":{"description":"Numeric chain id of the network: 1 Ethereum, 10 Optimism, 137 Polygon, 8453 Base, 42161 Arbitrum One. Any chain the Blockscout PRO API supports.","maxLength":20,"title":"Chain Id","type":"string"},"address_hash":{"description":"Address hash, a 0x-prefixed hex string.","maxLength":66,"title":"Address Hash","type":"string"},"filter":{"anyOf":[{"enum":["to","from"],"type":"string"},{"type":"null"}],"default":null,"description":"Only transactions sent to the address ('to') or from it ('from'). Omit for both.","title":"Filter"},"sort":{"anyOf":[{"enum":["block_number","value","fee"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by block_number, value or fee.","title":"Sort"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort order: asc or desc.","title":"Order"}},"required":["chain_id","address_hash"],"title":"list_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/list_address_token_balances":{"post":{"operationId":"list_address_token_balances","summary":"List the token balances held by an address (ERC-20, ERC-721, ERC-1155) with token name, symbol and decimals; values are ","description":"List the token balances held by an address (ERC-20, ERC-721, ERC-1155) with token name, symbol and decimals; values are raw integer amounts. Use for \"Which tokens does this Ethereum address hold\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain_id":{"description":"Numeric chain id of the network: 1 Ethereum, 10 Optimism, 137 Polygon, 8453 Base, 42161 Arbitrum One. Any chain the Blockscout PRO API supports.","maxLength":20,"title":"Chain Id","type":"string"},"address_hash":{"description":"Address hash, a 0x-prefixed hex string.","maxLength":66,"title":"Address Hash","type":"string"}},"required":["chain_id","address_hash"],"title":"list_address_token_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_address_token_transfers":{"post":{"operationId":"list_address_token_transfers","summary":"List the newest token transfers involving an address (first page, up to 50), optionally by direction, token type or toke","description":"List the newest token transfers involving an address (first page, up to 50), optionally by direction, token type or token contract. Use for \"What USDC transfers did this address receive recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain_id":{"description":"Numeric chain id of the network: 1 Ethereum, 10 Optimism, 137 Polygon, 8453 Base, 42161 Arbitrum One. Any chain the Blockscout PRO API supports.","maxLength":20,"title":"Chain Id","type":"string"},"address_hash":{"description":"Address hash, a 0x-prefixed hex string.","maxLength":66,"title":"Address Hash","type":"string"},"filter":{"anyOf":[{"enum":["to","from"],"type":"string"},{"type":"null"}],"default":null,"description":"Only transfers to the address ('to') or from it ('from').","title":"Filter"},"type":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Token types to include, comma-separated, for example 'ERC-20,ERC-721'.","title":"Type"},"token":{"anyOf":[{"maxLength":66,"type":"string"},{"type":"null"}],"default":null,"description":"Only transfers of the token with this contract address.","title":"Token"}},"required":["chain_id","address_hash"],"title":"list_address_token_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/get_transaction":{"post":{"operationId":"get_transaction","summary":"Get one transaction by hash: status, block, time, sender, recipient, value, fee, gas, method, confirmations, result or r","description":"Get one transaction by hash: status, block, time, sender, recipient, value, fee, gas, method, confirmations, result or revert reason and decoded call. Use for \"Did transaction 0x5c50... succeed and what did it cost\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain_id":{"description":"Numeric chain id of the network: 1 Ethereum, 10 Optimism, 137 Polygon, 8453 Base, 42161 Arbitrum One. Any chain the Blockscout PRO API supports.","maxLength":20,"title":"Chain Id","type":"string"},"transaction_hash":{"description":"Transaction hash, a 0x-prefixed hex string.","maxLength":66,"title":"Transaction Hash","type":"string"}},"required":["chain_id","transaction_hash"],"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/list_blocks":{"post":{"operationId":"list_blocks","summary":"List the newest blocks of a network (first page, up to 50) with height, time, miner, transaction count and gas use. Use ","description":"List the newest blocks of a network (first page, up to 50) with height, time, miner, transaction count and gas use. Use for \"What are the latest blocks on Ethereum\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain_id":{"description":"Numeric chain id of the network: 1 Ethereum, 10 Optimism, 137 Polygon, 8453 Base, 42161 Arbitrum One. Any chain the Blockscout PRO API supports.","maxLength":20,"title":"Chain Id","type":"string"},"type":{"anyOf":[{"enum":["block","uncle","reorg"],"type":"string"},{"type":"null"}],"default":null,"description":"block for main-chain blocks, uncle for uncles, reorg for reorganized blocks.","title":"Type"}},"required":["chain_id"],"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 or hash: time, miner, transaction count, gas used and limit, base fee, size, fees and parent has","description":"Get one block by number or hash: time, miner, transaction count, gas used and limit, base fee, size, fees and parent hash. Use for \"Show Ethereum block 21000000\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain_id":{"description":"Numeric chain id of the network: 1 Ethereum, 10 Optimism, 137 Polygon, 8453 Base, 42161 Arbitrum One. Any chain the Blockscout PRO API supports.","maxLength":20,"title":"Chain Id","type":"string"},"block_id":{"description":"Block number or block hash.","maxLength":66,"title":"Block Id","type":"string"}},"required":["chain_id","block_id"],"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_tokens":{"post":{"operationId":"list_tokens","summary":"List tokens on a network ranked by market cap, holders or fiat value, optionally filtered by name or symbol and token ty","description":"List tokens on a network ranked by market cap, holders or fiat value, optionally filtered by name or symbol and token type (first page). Use for \"What are the biggest ERC-20 tokens on Ethereum by market cap\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain_id":{"description":"Numeric chain id of the network: 1 Ethereum, 10 Optimism, 137 Polygon, 8453 Base, 42161 Arbitrum One. Any chain the Blockscout PRO API supports.","maxLength":20,"title":"Chain Id","type":"string"},"q":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by token name or symbol.","title":"Q"},"type":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Token types, comma-separated: ERC-20, ERC-721, ERC-1155, ERC-404.","title":"Type"},"sort":{"anyOf":[{"enum":["fiat_value","holders_count","circulating_market_cap"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by fiat_value, holders_count or circulating_market_cap.","title":"Sort"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort order: asc or desc.","title":"Order"}},"required":["chain_id"],"title":"list_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/get_token":{"post":{"operationId":"get_token","summary":"Get one token by contract address: name, symbol, decimals, type, holder count, price, market cap, supply and 24-hour vol","description":"Get one token by contract address: name, symbol, decimals, type, holder count, price, market cap, supply and 24-hour volume. Use for \"How many holders does the USDC token have on Ethereum\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain_id":{"description":"Numeric chain id of the network: 1 Ethereum, 10 Optimism, 137 Polygon, 8453 Base, 42161 Arbitrum One. Any chain the Blockscout PRO API supports.","maxLength":20,"title":"Chain Id","type":"string"},"token_address":{"description":"Token contract address, 0x-prefixed.","maxLength":66,"title":"Token Address","type":"string"}},"required":["chain_id","token_address"],"title":"get_tokenArguments","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_smart_contract":{"post":{"operationId":"get_smart_contract","summary":"Get a verified smart contract's metadata: name, language, compiler version, optimization settings, license, verification","description":"Get a verified smart contract's metadata: name, language, compiler version, optimization settings, license, verification status and proxy type. Source code and bytecode are not returned. Use for \"Is the contract at this address verified and which compiler was used\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain_id":{"description":"Numeric chain id of the network: 1 Ethereum, 10 Optimism, 137 Polygon, 8453 Base, 42161 Arbitrum One. Any chain the Blockscout PRO API supports.","maxLength":20,"title":"Chain Id","type":"string"},"address_hash":{"description":"Address hash, a 0x-prefixed hex string.","maxLength":66,"title":"Address Hash","type":"string"}},"required":["chain_id","address_hash"],"title":"get_smart_contractArguments","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/search":{"post":{"operationId":"search","summary":"Search a network for tokens, addresses, contracts, blocks or transactions by name, symbol, address, hash or block number","description":"Search a network for tokens, addresses, contracts, blocks or transactions by name, symbol, address, hash or block number (first page, up to 10 results). Use for \"Search Ethereum for the token called Tether\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain_id":{"description":"Numeric chain id of the network: 1 Ethereum, 10 Optimism, 137 Polygon, 8453 Base, 42161 Arbitrum One. Any chain the Blockscout PRO API supports.","maxLength":20,"title":"Chain Id","type":"string"},"q":{"description":"Text, address, hash or block number to look for.","maxLength":200,"title":"Q","type":"string"}},"required":["chain_id","q"],"title":"searchArguments","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}}}}