> ## Documentation Index > Fetch the complete documentation index at: https://docs.beaconcha.in/llms.txt > Use this file to discover all available pages before exploring further. # Withdrawals > Returns comprehensive details about all validator withdrawals processed in the specified slot. The validator filter is optional; if omitted, results include all withdrawals processed in the slot. Results may include *system withdrawals* — protocol-generated withdrawals that are not initiated by a user, such as the withdrawal created when a validator switches to compounding. See [System deposits and withdrawals](/faqs/system-deposits-and-withdrawals) for details. Use this endpoint to quickly identify all relevant withdrawals for a slot. You can combine this endpoint with: - Find withdrawals associated with your validators: [v2/ethereum/validators/withdrawal-slots](/api-reference/ethereum/validators/withdrawal-slots) ## OpenAPI ````yaml /v3/bundled.yaml post /api/v2/ethereum/slot/withdrawals openapi: 3.0.4 info: title: External Service API version: 1.0.3 servers: - url: https://beaconcha.in description: Production API security: - ApiKeyAuth: [] paths: /api/v2/ethereum/slot/withdrawals: post: tags: - Slot summary: Withdrawals description: > Returns comprehensive details about all validator withdrawals processed in the specified slot. The validator filter is optional; if omitted, results include all withdrawals processed in the slot. Results may include *system withdrawals* — protocol-generated withdrawals that are not initiated by a user, such as the withdrawal created when a validator switches to compounding. See [System deposits and withdrawals](/faqs/system-deposits-and-withdrawals) for details. Use this endpoint to quickly identify all relevant withdrawals for a slot. You can combine this endpoint with: - Find withdrawals associated with your validators: [v2/ethereum/validators/withdrawal-slots](/api-reference/ethereum/validators/withdrawal-slots) operationId: GetSlotWithdrawals requestBody: $ref: '#/components/requestBodies/slotWithdrawalsRequest' responses: '200': $ref: '#/components/responses/SlotWithdrawal' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/DefaultError' components: requestBodies: slotWithdrawalsRequest: description: '`validator` and `type_filter` are optional in this request body' content: application/json: schema: allOf: - $ref: '#/components/schemas/NamedSlotSelector' - type: object properties: chain: $ref: '#/components/schemas/Chain' cursor: $ref: '#/components/schemas/Cursor' page_size: $ref: '#/components/schemas/PageSize' validator: $ref: '#/components/schemas/nullableValidatorSelector' type_filter: description: >- Filter results by withdrawal type. Pass one or more types as an array to include withdrawals of any of the selected types; omit the field (or pass an empty array) to return all types. type: array nullable: true items: $ref: '#/components/schemas/ValidatorWithdrawals.Type' required: - slot - chain example: slot: view: latest chain: mainnet type_filter: - manual responses: SlotWithdrawal: description: Successful response. content: application/json: schema: allOf: - $ref: '#/components/schemas/SlotWithdrawal.ContainerList' - $ref: '#/components/schemas/PagingTemplate' description: >- Response containing detailed information about past or future withdrawal duties. BadRequest: description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Bad request. Please check your input and try again. Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Unauthorized. Please provide a valid API key. Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' example: error: >- endpoint not allowed for your subscription tier. upgrade your subscription at https://beaconcha.in/pricing. NotFound: description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: The requested resource was not found. MethodNotAllowed: description: Method Not Allowed content: application/json: schema: $ref: '#/components/schemas/Error' example: error: 'method not allowed: GET. all public API endpoints use POST.' RateLimitExceeded: description: Rate Limit Exceeded content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Rate limit exceeded. Please try again later. InternalServerError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: internal server error. please try again later. DefaultError: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: An unexpected error occurred. schemas: NamedSlotSelector: type: object properties: slot: $ref: '#/components/schemas/SlotSelector' required: - slot Chain: type: string enum: - mainnet - hoodi default: mainnet description: The Ethereum chain to query. Cursor: type: string description: >- Cursor value for pagination. See our [pagination guide](/api/pagination) for more details. default: '' PageSize: type: integer description: The number of items to return per page. minimum: 1 maximum: 10 default: 10 nullableValidatorSelector: description: >- `validator` is optional in this request body. If not provided, results will be unfiltered. nullable: true default: null allOf: - $ref: '#/components/schemas/validatorsSelector' ValidatorWithdrawals.Type: type: string description: > The type of withdrawal: - `manual`: A voluntary withdrawal request submitted by the validator operator on the execution layer. - `partial_sweep`: An automatic partial withdrawal sweep performed by the protocol, withdrawing the balance above 32 ETH (or 2048 ETH for compounding validators) to the withdrawal address. - `full_exit_sweep`: An automatic full withdrawal sweep performed by the protocol after the validator has fully exited, withdrawing the entire balance to the withdrawal address. - `system`: A protocol-internal balance movement that is re-queued as a pending deposit rather than paid out to a withdrawal address. Occurs when a validator switches to compounding withdrawal credentials (balance above 32 ETH is removed and re-queued), and as a one-time event at the Electra fork, when validators still awaiting activation had their pending balance re-queued through the new activation queue. enum: - manual - partial_sweep - full_exit_sweep - system SlotWithdrawal.ContainerList: type: object properties: data: type: array items: $ref: '#/components/schemas/SlotWithdrawal.Data' required: - data PagingTemplate: type: object properties: paging: $ref: '#/components/schemas/Paging' Error: type: object properties: error: type: string SlotSelector: description: | Specify a slot using one of the following methods. - Slot number - Consensus layer block root - View: "latest", "finalized" oneOf: - $ref: '#/components/schemas/SlotByNumber' - $ref: '#/components/schemas/SlotByConsensusLayerBlockRoot' - $ref: '#/components/schemas/SlotByChainView' default: latest validatorsSelector: description: >- Free selectors available to all users: - validator_identifiers: One or more validator indices or public keys to filter by. - dashboard_id: Your beaconcha.in dashboard ID (requires a free account). **Premium selectors** for Scale & Enterprise plans (https://beaconcha.in/pricing): - withdrawal: The validator's withdrawal credential or the Ethereum wallet address used for withdrawals. - deposit_address: The Ethereum wallet address used for the validator's deposit. - entity: The name of the assigned entity (e.g., "Lido", "Coinbase"). Optionally include `sub_entity` for more specific filtering. Matching is case-sensitive. Note: The set of validators matched by `deposit_address` and `withdrawal` selectors is updated once per epoch (~6.4 minutes). Newly deposited validators may take up to one epoch to appear in query results. Note: The set of validators matched by `entity` selector is updated once per day. oneOf: - $ref: '#/components/schemas/ValidatorsByIdentifiers' - $ref: '#/components/schemas/ValidatorsByDashboard' - $ref: '#/components/schemas/ValidatorsByDeposit' - $ref: '#/components/schemas/ValidatorsByWithdrawal' - $ref: '#/components/schemas/ValidatorsByEntity' SlotWithdrawal.Data: type: object properties: validator: $ref: '#/components/schemas/validator' amount: $ref: '#/components/schemas/wei' reject_reason: allOf: - $ref: '#/components/schemas/ValidatorWithdrawals.RejectReason' nullable: true status: allOf: - $ref: '#/components/schemas/ConsensusLayerEventStatus' nullable: true type: allOf: - $ref: '#/components/schemas/ValidatorWithdrawals.Type' nullable: true stage_history: $ref: '#/components/schemas/clQueues' withdrawal_credentials: allOf: - $ref: '#/components/schemas/withdrawalCredential' nullable: true recipient: allOf: - $ref: '#/components/schemas/ExecutionLayerAddress' nullable: true request: $ref: '#/components/schemas/SlotWithdrawal.Request' finality: $ref: '#/components/schemas/FinalityParams' required: - validator - amount - finality Paging: type: object properties: next_cursor: description: >- Cursor to the next page of results. See our [pagination guide](/api/pagination) for more details. If empty, there are no more pages to fetch. type: string SlotByNumber: title: Number type: object properties: number: $ref: '#/components/schemas/Slot' required: - number SlotByConsensusLayerBlockRoot: title: Root type: object properties: root: $ref: '#/components/schemas/ConsensusLayerBlockRoot' required: - root SlotByChainView: title: View type: object properties: view: allOf: - $ref: '#/components/schemas/ChainView' description: > - "latest": Refers to the most recent slot, which may be subject to reorganization. - "finalized": Refers to the latest slot that has been finalized and is not subject to change. required: - view ValidatorsByIdentifiers: type: object title: Indices/Pubkeys properties: validator_identifiers: $ref: '#/components/schemas/validatorIndexPublicKeys' required: - validator_identifiers ValidatorsByDashboard: type: object title: Dashboard properties: dashboard_id: $ref: '#/components/schemas/dashboardID' group_id: $ref: '#/components/schemas/dashboardGroupID' required: - dashboard_id ValidatorsByDeposit: type: object title: 💎 Deposit properties: deposit_address: $ref: '#/components/schemas/ExecutionLayerAddress' required: - deposit_address ValidatorsByWithdrawal: type: object title: 💎 Withdrawal properties: withdrawal: $ref: '#/components/schemas/AddressOrCredential' required: - withdrawal ValidatorsByEntity: type: object title: 💎 Entity description: > Select validators by their assigned entity (e.g., staking provider) and optionally a sub-entity. Entity and sub-entity names are matched exactly and are case-sensitive. properties: entity: type: string description: > The name of the entity to filter validators by (e.g., "Lido", "Coinbase"). Matching is case-sensitive; use the exact name as returned by the entities overview endpoint. sub_entity: type: string description: > Optional sub-entity name to further filter validators within the entity. Matching is case-sensitive; use the exact name as returned by the sub-entities overview endpoint. required: - entity validator: type: object properties: index: allOf: - $ref: '#/components/schemas/validatorIndex' nullable: true public_key: $ref: '#/components/schemas/validatorPublicKey' wei: type: string description: Amount in wei (1 ETH = 10^18 wei) pattern: ^(0|-?[1-9][0-9]*)$ ValidatorWithdrawals.RejectReason: type: string enum: - full_queue - unknown_public_key - no_execution_withdrawal_credentials - address_mismatch - inactive - exiting - too_young - pending_withdrawals - not_compounding - insufficient_effective_balance - excess_balance ConsensusLayerEventStatus: type: string enum: - queued - completed - rejected nullable: true clQueues: type: object description: > Displays the complete queue stage history for an item. For example, a deposit that has been processed on the consensus layer will include the slot numbers for when it was queued on the execution layer and consensus layer, providing full traceability of its progression through each stage. properties: execution_layer_queued: allOf: - $ref: '#/components/schemas/ExecutionLayerReference' nullable: true execution_layer_processed: allOf: - $ref: '#/components/schemas/ExecutionLayerReference' nullable: true consensus_layer_queued: $ref: '#/components/schemas/ConsensusLayerReference' nullable: true x-sortable: true consensus_layer_processed: $ref: '#/components/schemas/ConsensusLayerReference' nullable: true x-sortable: true withdrawalCredential: type: object properties: type: $ref: '#/components/schemas/withdrawalCredentialType' prefix: $ref: '#/components/schemas/withdrawalCredentialPrefix' credential: $ref: '#/components/schemas/withdrawalCredentialPrimitive' address: $ref: '#/components/schemas/ExecutionLayerAddress' nullable: true description: Present only if type is execution_address required: - type - prefix - credential ExecutionLayerAddress: type: string pattern: ^0x[a-fA-F0-9]{40}$ description: A standard Ethereum address (20-byte hex string with 0x prefix). SlotWithdrawal.Request: type: object nullable: true properties: tx_hash: $ref: '#/components/schemas/transactionHash' tx_from: $ref: '#/components/schemas/ExecutionLayerAddressDetails' description: > The address that originally initiated the transaction (`tx.origin`). This is always the externally owned account (EOA) that signed the transaction — typically the user's wallet. When the user sends the transaction directly, `tx_from` and `tx_msg_sender` are the same. When the user interacts through a contract (e.g. a multisig, smart wallet, or staking service), `tx_from` is the user's wallet while `tx_msg_sender` is the contract. tx_msg_sender: $ref: '#/components/schemas/ExecutionLayerAddressDetails' description: > The address that directly called the contract (`msg.sender`). This is the immediate caller — either the user's wallet (EOA) or an intermediary contract. When the user sends the transaction directly, this equals `tx_from`. When the user interacts through a contract (e.g. a multisig, smart wallet, or staking service), this is the contract address, not the user's wallet. fee: $ref: '#/components/schemas/wei' required: - tx_hash - tx_from - tx_msg_sender - fee FinalityParams: type: string description: | Indicates the finality status of the data provided. - Finalized data cannot be changed without slashing at least one-third of all validators, providing strong economic guarantees. - Data marked as not_finalized does not have this guarantee and may still change. enum: - not_finalized - finalized Slot: type: integer minimum: 0 description: Slot by number. ConsensusLayerBlockRoot: type: string pattern: ^0x[a-fA-F0-9]{64}$ description: A 32-byte block root represented as a hex string with 0x prefix. ChainView: type: string enum: - latest - finalized description: > - "latest": Refers to the most recent block, which may be subject to reorganization. - "finalized": Refers to the latest block that has been finalized and is not subject to change. validatorIndexPublicKeys: description: > An array containing either validator indices or public keys. Index and public key can be mixed in the same array. Subscribed users (Hobbyist, Business, and Scale tiers) can include up to 100 entries; free trial users and legacy subscription users (Sapphire, Emerald, Diamond) are limited to 20. type: array items: $ref: '#/components/schemas/validatorIndexPublicKey' minItems: 1 maxItems: 100 dashboardID: description: > beaconcha.in dashboard ID. You can find your dashboard ID in the URL of your dashboard page on beaconcha.in (e.g., https://beaconcha.in/dashboard/12345). type: integer x-go-type: '*int' minimum: 0 dashboardGroupID: description: >- Optional beaconcha.in dashboard group ID. If no group ID is provided, all validators in the dashboard are considered. type: integer minimum: 0 nullable: true AddressOrCredential: type: string pattern: ^(0x)?[0-9a-fA-F]{40}$|^(0x)?0[012][0-9a-fA-F]{62}$ description: > Either an execution layer address (20-byte hex string with 0x prefix) or a full 32-byte withdrawal credential. validatorIndex: description: Validator Index type: integer minimum: 0 validatorPublicKey: type: string description: Public key of a validator pattern: ^0x[a-fA-F0-9]{96}$ ExecutionLayerReference: type: object description: | Reference to an execution layer block if one exists for the given slot. This will be null for missed slots. properties: block: $ref: '#/components/schemas/Block' hash: $ref: '#/components/schemas/ExecutionLayerBlockHash' required: - block - hash ConsensusLayerReference: type: object description: | Reference to a consensus layer block if one exists for the given slot. This will be null for the PoW era. nullable: true properties: slot: $ref: '#/components/schemas/Slot' block_root: nullable: true allOf: - $ref: '#/components/schemas/ConsensusLayerBlockRoot' epoch: $ref: '#/components/schemas/Epoch' required: - slot - epoch withdrawalCredentialType: type: string description: > Specifies whether the withdrawal credential is a BLS withdrawal credential or an execution address withdrawal credential. enum: - bls - execution_address withdrawalCredentialPrefix: type: string enum: - '0x00' - '0x01' - '0x02' description: > Hexadecimal prefix indicating the type of withdrawal credential: - "0x00": BLS withdrawal credential - "0x01": Execution address withdrawal credential - "0x02": Execution address withdrawal credential with consolidation support (Electra Fork) Credentials can be upgraded in one direction only: - From "0x00" (BLS) to "0x01" (execution address) - From "0x01" to "0x02" (consolidation-enabled execution address) Downgrades are not permitted. withdrawalCredentialPrimitive: type: string pattern: ^(0x)?0[012][0-9a-fA-F]{62}$ description: >- A full 32-byte withdrawal credential represented as a hex string with 0x prefix. transactionHash: type: string pattern: ^0x[a-fA-F0-9]{64}$ ExecutionLayerAddressDetails: type: object properties: address: $ref: '#/components/schemas/ExecutionLayerAddress' is_contract: type: boolean required: - address - is_contract validatorIndexPublicKey: oneOf: - $ref: '#/components/schemas/validatorIndex' - $ref: '#/components/schemas/validatorPublicKey' Block: type: integer minimum: 0 description: Block by number. ExecutionLayerBlockHash: type: string pattern: ^0x[a-fA-F0-9]{64}$ description: A 32-byte block hash represented as a hex string with 0x prefix. Epoch: type: integer minimum: 0 securitySchemes: ApiKeyAuth: type: http scheme: bearer description: >- Authorization header with value: Bearer YOUR_TOKEN. Refer to the [API Keys](/api/overview#api-keys) section to create your API key. ````