---
updatedAt: 2026-05-20T06:31:13.000Z
---

Fetch the complete documentation index at: https://docs.blockdaemon.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# Post Top up Intent

Adds additional balance to one or more eligible validators and returns an unsigned transaction.
Only withdrawal credentials of type **0x02** are supported.
If a validator uses 0x01 credentials or if the combined value of the additional deposit and the validator's current effective balance exceeds **2048 ETH**, the deposit will not be processed.

The unsigned transaction remains valid for up to 90 days or until it is signed and confirmed on the network.

Through the Blockdaemon [batch deposit contract](https://gitlab.com/Blockdaemon/open-source/eth2-batch-deposit-contract),
a single transaction can top up up to 250 validators simultaneously,
delivering over 50% gas fee savings compared to submitting separate transactions for each validator.

To complete the staking process, you must sign an Ethereum transaction
with a [data field](https://ethereum.org/en/developers/docs/transactions/#the-data-field)
set to match the returned `unsigned_transaction` property of the response.
The `recipient` of the transaction must be set to the `contract_address`
property of the response. The account signing the transaction must have
the sufficient balance to top up the requested number of validators and
this amount must be provided as the value of the signed transaction.


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "version": "1.0.0",
    "title": "Staking API",
    "description": "The Blockdaemon Staking API simplifies and streamlines institutional cryptocurrency staking. The API allows developers to interact with blockchain networks and perform various staking-related operations, such as delegating and undelegating tokens, in a single, unified interface.\n\nWith the Staking API, you can quickly and easily build and deploy applications that automate staking activities and increase efficiency in your blockchain operations.",
    "contact": {
      "name": "Blockdaemon",
      "email": "info@blockdaemon.com",
      "url": "https://blockdaemon.com"
    },
    "x-logo": {
      "url": "https://assets-global.website-files.com/633c5e06513fa35f3391a5f9/645d33beb6fa65f6cfb95eb8_BD%20Logo%20Stack%20-%20Purple.svg",
      "backgroundColor": "#fafafa",
      "altText": "Blockdaemon logo"
    }
  },
  "x-readme": {
    "explorer-enabled": false
  },
  "servers": [
    {
      "url": "https://svc.blockdaemon.com/boss"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "description": "When signing up for a staking account, you are provided with an API key.\n\nTo authenticate a Staking API request, pass your API key in the `X-API-Key` header.",
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY"
      }
    },
    "parameters": {
      "EthereumNetwork": {
        "name": "network",
        "in": "path",
        "description": "Ethereum network",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/EthereumNetwork"
        }
      }
    },
    "responses": {
      "InternalServerError": {
        "description": "Internal server error.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "InvalidRequest": {
        "description": "Invalid request.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "description": "Error response envelope",
              "required": [
                "code",
                "message"
              ],
              "properties": {
                "code": {
                  "type": "integer",
                  "format": "int32",
                  "description": "Error code",
                  "example": 400
                },
                "message": {
                  "type": "string",
                  "description": "Error Message",
                  "example": "Detailed human-readable diagnostic message regarding any invalid request parameters"
                }
              }
            }
          }
        }
      },
      "NoValidatorsError": {
        "description": "Insufficient validators available to process Stake Intent request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Header 'X-API-Key' missing.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/UnauthorizedError"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Error response envelope",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "format": "int32",
            "description": "Error code",
            "example": 500
          },
          "message": {
            "type": "string",
            "description": "Error Message",
            "example": "A descriptive error message"
          }
        }
      },
      "EthereumAddress": {
        "type": "string",
        "description": "Hex-encoded Ethereum [account or smart contract address](https://ethereum.org/en/developers/docs/accounts/).",
        "format": "hex",
        "pattern": "^0x[a-fA-F0-9]{40}$",
        "example": "0x00000000219ab540356cBB839Cbe05303d7705Fa"
      },
      "EthereumNetwork": {
        "type": "string",
        "description": "Ethereum network",
        "enum": [
          "mainnet",
          "hoodi"
        ]
      },
      "EthereumWithdrawalCredentials": {
        "type": "string",
        "format": "hex",
        "pattern": "^0x0(0|1)[a-fA-F0-9]{62}$",
        "example": "0x0092c20062cee70389f1cb4fa566a2be5e2319ff43965db26dbaa3ce90b9df99",
        "description": "Hexadecimal encoded [withdrawal credentials](https://github.com/ethereum/consensus-specs/blob/master/specs/phase0/validator.md#withdrawal-credentials) which can be either a BLS public key or an Ethereum account address.\n\nThis parameter currently accepts ETH1 and BLS withdrawal credentials, but it is considered deprecated after the Capella/Shanghai fork. All users are now advised to use an ETH1 withdrawal address, specified through the `withdrawal_address` parameter as this is required to enable the ongoing accrual of rewards.\n\nFor more information regarding creating withdrawal credentials, please see the official [Ethereum Launchpad FAQ](https://launchpad.ethereum.org/en/faq#withdrawal-credentials)."
      },
      "Gwei": {
        "type": "string",
        "description": "Amount of ETH (denominated in Gwei).",
        "pattern": "^[1-9]\\d{10,}$",
        "example": "32000000000"
      },
      "PublicKey": {
        "type": "string",
        "description": "A BLS public Key.",
        "format": "base64",
        "example": "0xa1d1ad0714035353258038e964ae9675dc0252ee22cea896825c01458e1807bfad2f9969338798548d9858a571f7425c"
      },
      "UnauthorizedError": {
        "type": "object",
        "description": "Error response envelope",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "format": "int32",
            "description": "Error code",
            "example": 401
          },
          "message": {
            "type": "string",
            "description": "Error Message",
            "example": "A human-readable diagnostic message detailing any authorization failure"
          }
        }
      },
      "UnsignedTransaction": {
        "type": "string",
        "format": "base64",
        "description": "Generated unsigned transaction smart contract call data.",
        "example": "0x22895118000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000120087fed394b43849eebef1e88873cd9efdbe33136656e5148e659b8b2f33625d40000000000000000000000000000000000000000000000000000000000000030b81748644e23c4d950f9dd709f3eb73d5eacd9657997e1d9dde7c4ebd8a6519ecb9d0a7fb603d3b68e023278f9650122000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020010000000000000000000000c509bb854c526af4cee5e037089f7aa8e091d8870000000000000000000000000000000000000000000000000000000000000060b36b79b4b206c0310472c117fa40c05342b5dc3e89f98f42c9da3ce6450d4c603cad55248017fd4eca3ab277cca64569193e4d487f5b2ea78a2bcdc81926c313c05842a3af318967a775783bba22519e8b8886587efa99aa7dab5784f792b187\n"
      },
      "EthereumGas": {
        "type": "integer",
        "description": "Gas estimation of the transaction",
        "format": "uint64",
        "example": 1001
      },
      "ExpirationTime": {
        "type": "integer",
        "description": "Transaction expiration time",
        "format": "int64",
        "example": 1689939023
      },
      "EthereumTopUpIntent": {
        "type": "object",
        "description": "Ethereum validator top up intent",
        "required": [
          "network",
          "contract_address",
          "estimated_gas",
          "unsigned_transaction",
          "total_amount",
          "expiration_time",
          "top_ups"
        ],
        "properties": {
          "network": {
            "$ref": "#/components/schemas/EthereumNetwork"
          },
          "contract_address": {
            "$ref": "#/components/schemas/EthereumAddress"
          },
          "estimated_gas": {
            "$ref": "#/components/schemas/EthereumGas"
          },
          "total_amount": {
            "$ref": "#/components/schemas/Gwei"
          },
          "unsigned_transaction": {
            "$ref": "#/components/schemas/UnsignedTransaction"
          },
          "expiration_time": {
            "$ref": "#/components/schemas/ExpirationTime"
          },
          "top_ups": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EthereumTopUp"
            }
          }
        }
      },
      "EthereumTopUp": {
        "type": "object",
        "description": "Ethereum validator top up",
        "required": [
          "public_key",
          "amount",
          "withdrawal_credentials",
          "fee_recipient"
        ],
        "properties": {
          "public_key": {
            "$ref": "#/components/schemas/PublicKey"
          },
          "amount": {
            "$ref": "#/components/schemas/Gwei"
          },
          "withdrawal_credentials": {
            "$ref": "#/components/schemas/EthereumWithdrawalCredentials"
          },
          "fee_recipient": {
            "$ref": "#/components/schemas/EthereumAddress"
          }
        }
      },
      "NewEthereumTopUpIntent": {
        "type": "object",
        "description": "Request object to create a new Ethereum Top Up Intent.",
        "required": [
          "top_ups"
        ],
        "properties": {
          "top_ups": {
            "type": "array",
            "description": "Top ups for Ethereum 0x02 validators.",
            "minItems": 1,
            "maxItems": 1000,
            "additionalProperties": false,
            "items": {
              "$ref": "#/components/schemas/NewEthereumTopUp"
            }
          }
        }
      },
      "NewEthereumTopUp": {
        "type": "object",
        "description": "Required data for Ethereum validator top up",
        "required": [
          "public_key",
          "amount"
        ],
        "properties": {
          "public_key": {
            "$ref": "#/components/schemas/PublicKey"
          },
          "amount": {
            "$ref": "#/components/schemas/Gwei"
          }
        }
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/v1/ethereum/{network}/topup-intents": {
      "parameters": [
        {
          "$ref": "#/components/parameters/EthereumNetwork"
        }
      ],
      "post": {
        "summary": "Post Top up Intent",
        "operationId": "postEthereumTopUpIntent",
        "tags": [
          "Ethereum"
        ],
        "description": "Adds additional balance to one or more eligible validators and returns an unsigned transaction.\nOnly withdrawal credentials of type **0x02** are supported.\nIf a validator uses 0x01 credentials or if the combined value of the additional deposit and the validator's current effective balance exceeds **2048 ETH**, the deposit will not be processed.\n\nThe unsigned transaction remains valid for up to 90 days or until it is signed and confirmed on the network.\n\nThrough the Blockdaemon [batch deposit contract](https://gitlab.com/Blockdaemon/open-source/eth2-batch-deposit-contract),\na single transaction can top up up to 250 validators simultaneously,\ndelivering over 50% gas fee savings compared to submitting separate transactions for each validator.\n\nTo complete the staking process, you must sign an Ethereum transaction\nwith a [data field](https://ethereum.org/en/developers/docs/transactions/#the-data-field)\nset to match the returned `unsigned_transaction` property of the response.\nThe `recipient` of the transaction must be set to the `contract_address`\nproperty of the response. The account signing the transaction must have\nthe sufficient balance to top up the requested number of validators and\nthis amount must be provided as the value of the signed transaction.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NewEthereumTopUpIntent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EthereumTopUpIntent"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          },
          "503": {
            "$ref": "#/components/responses/NoValidatorsError"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      }
    }
  },
  "tags": [
    {
      "name": "Ethereum",
      "description": "Ethereum endpoints"
    }
  ]
}
```