{"openapi":"3.1.0","info":{"title":"beaconcha.in (BYOK) API","version":"0.1.0","description":"beaconcha.in (BYOK) lets an AI assistant read your own beaconcha.in data through the beaconcha.in API with a key you supply (beaconcha.in API key (30-day free trial, then paid plans)). Read-only: 11 tools (get_chain_state, get_epoch, get_block, get_staking_queues, get_network_performance, list_eth_store, get_validator, get_validator_balances, get_validator_rewards, get_validator_apy,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-beaconchain.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-beaconchain/docs"},"termsOfService":"https://connectorbay.com/byok-beaconchain/terms"},"servers":[{"url":"https://byok-beaconchain.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-beaconchain/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_state":{"post":{"operationId":"get_chain_state","summary":"Get the explorer's current view of the Ethereum chain: finalization health, head, justified and finalized checkpoints an","description":"Get the explorer's current view of the Ethereum chain: finalization health, head, justified and finalized checkpoints and data freshness. Use for \"Is Ethereum finalizing and what is the head slot\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain":{"anyOf":[{"enum":["mainnet","hoodi"],"type":"string"},{"type":"null"}],"default":"mainnet","description":"Ethereum network to query.","title":"Chain"}},"title":"get_chain_stateArguments","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":{"post":{"operationId":"get_epoch","summary":"Get a rolled-up overview of one consensus epoch: slot range, validator count, balances, participation rate, proposals, a","description":"Get a rolled-up overview of one consensus epoch: slot range, validator count, balances, participation rate, proposals, attestations and finality. Use for \"How did the latest Ethereum epoch go\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain":{"anyOf":[{"enum":["mainnet","hoodi"],"type":"string"},{"type":"null"}],"default":"mainnet","description":"Ethereum network to query.","title":"Chain"},"view":{"anyOf":[{"enum":["latest","finalized"],"type":"string"},{"type":"null"}],"default":"latest","description":"Which chain view to read: latest (may still reorganise) or finalized.","title":"View"}},"title":"get_epochArguments","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 an execution-layer block: number, hash, time, gas used and limit, base fee, transaction counts, miner and finality. ","description":"Get an execution-layer block: number, hash, time, gas used and limit, base fee, transaction counts, miner and finality. Use for \"What is the latest Ethereum execution block\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain":{"anyOf":[{"enum":["mainnet","hoodi"],"type":"string"},{"type":"null"}],"default":"mainnet","description":"Ethereum network to query.","title":"Chain"},"view":{"anyOf":[{"enum":["latest","finalized"],"type":"string"},{"type":"null"}],"default":"latest","description":"Which chain view to read: latest (may still reorganise) or finalized.","title":"View"}},"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_staking_queues":{"post":{"operationId":"get_staking_queues","summary":"Get the Ethereum staking queues: deposit queue, exit queue, withdrawal sweep delay, with counts, balances and estimated ","description":"Get the Ethereum staking queues: deposit queue, exit queue, withdrawal sweep delay, with counts, balances and estimated processing times. Use for \"How long is the Ethereum validator entry and exit queue\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain":{"anyOf":[{"enum":["mainnet","hoodi"],"type":"string"},{"type":"null"}],"default":"mainnet","description":"Ethereum network to query.","title":"Chain"}},"title":"get_staking_queuesArguments","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_network_performance":{"post":{"operationId":"get_network_performance","summary":"Get network-wide validator performance over a rolling window: BeaconScore and attestation, sync committee and proposal d","description":"Get network-wide validator performance over a rolling window: BeaconScore and attestation, sync committee and proposal duty counts. Use for \"How well are Ethereum validators performing this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain":{"anyOf":[{"enum":["mainnet","hoodi"],"type":"string"},{"type":"null"}],"default":"mainnet","description":"Ethereum network to query.","title":"Chain"},"evaluation_window":{"anyOf":[{"enum":["24h","7d","30d","90d","all_time"],"type":"string"},{"type":"null"}],"default":"24h","description":"Rolling window ending now: 24h, 7d, 30d, 90d or all_time.","title":"Evaluation Window"}},"title":"get_network_performanceArguments","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_eth_store":{"post":{"operationId":"list_eth_store","summary":"List ETH.STORE daily staking returns: effective balance, rewards (consensus and execution layer) and APR with 7 and 31 d","description":"List ETH.STORE daily staking returns: effective balance, rewards (consensus and execution layer) and APR with 7 and 31 day moving averages. Use for \"What was the Ethereum staking APR over the last 7 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain":{"anyOf":[{"enum":["mainnet","hoodi"],"type":"string"},{"type":"null"}],"default":"mainnet","description":"Ethereum network to query.","title":"Chain"},"evaluation_window":{"anyOf":[{"enum":["24h","7d","30d","90d","all_time"],"type":"string"},{"type":"null"}],"default":"24h","description":"Rolling window ending now: 24h, 7d, 30d, 90d or all_time.","title":"Evaluation Window"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor from the previous page.","title":"Cursor"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page.","title":"Page Size"}},"title":"list_eth_storeArguments","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_validator":{"post":{"operationId":"get_validator","summary":"Get Ethereum validators by index and/or public key: status, slashed and online flags, withdrawal credentials, lifecycle ","description":"Get Ethereum validators by index and/or public key: status, slashed and online flags, withdrawal credentials, lifecycle epochs and balances. Use for \"What is the status and balance of validator 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain":{"anyOf":[{"enum":["mainnet","hoodi"],"type":"string"},{"type":"null"}],"default":"mainnet","description":"Ethereum network to query.","title":"Chain"},"validator_index":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Validator index (a number).","title":"Validator Index"},"validator_pubkey":{"anyOf":[{"maxLength":120,"type":"string"},{"type":"null"}],"default":null,"description":"Validator public key, 0x-prefixed hex (use instead of or with the index).","title":"Validator Pubkey"}},"title":"get_validatorArguments","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_validator_balances":{"post":{"operationId":"get_validator_balances","summary":"Get the current and effective balance of Ethereum validators by index and/or public key. Use for \"What is the balance of","description":"Get the current and effective balance of Ethereum validators by index and/or public key. Use for \"What is the balance of validator 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain":{"anyOf":[{"enum":["mainnet","hoodi"],"type":"string"},{"type":"null"}],"default":"mainnet","description":"Ethereum network to query.","title":"Chain"},"validator_index":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Validator index (a number).","title":"Validator Index"},"validator_pubkey":{"anyOf":[{"maxLength":120,"type":"string"},{"type":"null"}],"default":null,"description":"Validator public key, 0x-prefixed hex (use instead of or with the index).","title":"Validator Pubkey"}},"title":"get_validator_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/get_validator_rewards":{"post":{"operationId":"get_validator_rewards","summary":"Get aggregated consensus and execution rewards, penalties and missed rewards of Ethereum validators over a rolling windo","description":"Get aggregated consensus and execution rewards, penalties and missed rewards of Ethereum validators over a rolling window. Use for \"How much did validator 1 earn in the last 30 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain":{"anyOf":[{"enum":["mainnet","hoodi"],"type":"string"},{"type":"null"}],"default":"mainnet","description":"Ethereum network to query.","title":"Chain"},"validator_index":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Validator index (a number).","title":"Validator Index"},"validator_pubkey":{"anyOf":[{"maxLength":120,"type":"string"},{"type":"null"}],"default":null,"description":"Validator public key, 0x-prefixed hex (use instead of or with the index).","title":"Validator Pubkey"},"evaluation_window":{"anyOf":[{"enum":["24h","7d","30d","90d","all_time"],"type":"string"},{"type":"null"}],"default":"24h","description":"Rolling window ending now: 24h, 7d, 30d, 90d or all_time.","title":"Evaluation Window"}},"title":"get_validator_rewardsArguments","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_validator_apy":{"post":{"operationId":"get_validator_apy","summary":"Get ROI and APY of Ethereum validators over a rolling window, split into execution layer, consensus layer and combined. ","description":"Get ROI and APY of Ethereum validators over a rolling window, split into execution layer, consensus layer and combined. Use for \"What is the APY of validator 1 over 30 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain":{"anyOf":[{"enum":["mainnet","hoodi"],"type":"string"},{"type":"null"}],"default":"mainnet","description":"Ethereum network to query.","title":"Chain"},"validator_index":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Validator index (a number).","title":"Validator Index"},"validator_pubkey":{"anyOf":[{"maxLength":120,"type":"string"},{"type":"null"}],"default":null,"description":"Validator public key, 0x-prefixed hex (use instead of or with the index).","title":"Validator Pubkey"},"evaluation_window":{"anyOf":[{"enum":["24h","7d","30d","90d","all_time"],"type":"string"},{"type":"null"}],"default":"24h","description":"Rolling window ending now: 24h, 7d, 30d, 90d or all_time.","title":"Evaluation Window"}},"title":"get_validator_apyArguments","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_validator_performance":{"post":{"operationId":"get_validator_performance","summary":"Get aggregated performance of Ethereum validators over a rolling window: BeaconScore and attestation, sync committee and","description":"Get aggregated performance of Ethereum validators over a rolling window: BeaconScore and attestation, sync committee and proposal duty results. Use for \"How well has validator 1 performed this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chain":{"anyOf":[{"enum":["mainnet","hoodi"],"type":"string"},{"type":"null"}],"default":"mainnet","description":"Ethereum network to query.","title":"Chain"},"validator_index":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Validator index (a number).","title":"Validator Index"},"validator_pubkey":{"anyOf":[{"maxLength":120,"type":"string"},{"type":"null"}],"default":null,"description":"Validator public key, 0x-prefixed hex (use instead of or with the index).","title":"Validator Pubkey"},"evaluation_window":{"anyOf":[{"enum":["24h","7d","30d","90d","all_time"],"type":"string"},{"type":"null"}],"default":"24h","description":"Rolling window ending now: 24h, 7d, 30d, 90d or all_time.","title":"Evaluation Window"}},"title":"get_validator_performanceArguments","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}}}}