Skip to main content

Ethereum integration

The API creates staking and validator-operation resources, while your client signs and broadcasts Ethereum transactions.

Flow overview​

Create a stake​

  1. Create a single-validator stake with POST /v1/ethereum/stakes and an Idempotency-Key.
  2. Use the returned deposit data to prepare, sign, and broadcast the deposit transaction.
  3. Report the broadcast transaction hash with PUT /v1/ethereum/stakes/{stakeId}/submission.
  4. Poll GET /v1/ethereum/stakes/{stakeId} while transaction.status is submitted. Stop when it changes to confirmed or failed.

The withdrawal address becomes part of the validator withdrawal credentials. Validate it before creating the stake.

Exit a validator​

  1. Create an exit request with POST /v1/ethereum/validators/{pubkey}/exit-requests and an Idempotency-Key.
  2. Sign and broadcast the transaction represented by the request.
  3. Report the transaction hash with PUT /v1/ethereum/validators/{pubkey}/exit-requests/{requestId}/submission.
  4. Poll GET /v1/ethereum/validators/{pubkey}/exit-requests/{requestId} while status is submitted. Stop when it changes to confirmed or failed.

Cancel an unsubmitted exit request with DELETE /v1/ethereum/validators/{pubkey}/exit-requests/{requestId}. Consult the API Reference for the states in which cancellation is accepted.

Request a partial withdrawal​

  1. Create a request with POST /v1/ethereum/validators/{pubkey}/withdrawal-requests and an Idempotency-Key. Send amountGwei as a positive integer string.
  2. Broadcast the transaction represented by the request, then report its hash with PUT /v1/ethereum/validators/{pubkey}/withdrawal-requests/{requestId}/submission.
  3. If submission returns 202 Accepted, follow Retry-After, then poll GET /v1/ethereum/validators/{pubkey}/withdrawal-requests/{requestId} while status is submitted. Stop when it changes to confirmed or failed.

Use GET /v1/ethereum/validators/{pubkey}/withdrawal-capacity only when your application needs to show the validator's current eligibility or available amount before creating a request. The create endpoint performs the authoritative validation.