Guides

Exit & Validator Withdrawal

Suggest Edits

This guide will walk you through the process of exiting and withdrawing validators using the stakefish API.

🚧

Important:

This exit process is exclusively for Client staking. All validator exits must be confirmed by customers (wallet signing).

Verify Wallet Ownership

Your customer must confirm control over their wallet and sign confirmation message with their wallet.

Generate Message

To generate the message for your customer to sign, send the following GET request to stakefish API:

curl -X GET "https://api.testnet.stake.fish/v1/eth/stake/v1/exit-challenge?type=IMMEDIATE&indices=VALIDATOR_INDICES&address=WALLET_ADDRESS" \
    -H "Content-Type: application/json" \
    -H "Authorization: YOUR_PUBLIC_API_KEY"

📘

Important

This API requires Public API Key.

Explanation of Parameters:

  • type: Specify IMMEDIATE or DEFERRED.
  • VALIDATOR_INDICES: List of validator indices to be exited.
  • WALLET_ADDRESS: The address of the wallet from which Ether will be withdrawn.

Example Response:

You will receive a response like this:

{
  "challenge": "I confirm I request to voluntarily exit validator(s) with indexes: 1754303 and my request is valid for 5 min (2024-09-06 13:50:06 UTC)."
}

This message must be signed by your customer before proceeding with the exit. Note that the message expires in 5 minutes.

Customer Signs Message

Your customer needs to sign the generated message with their wallet. Here's how they can do it using the viem library:

import { createWalletClient, custom } from 'viem'
import { holesky } from 'viem/chains'
 
const walletClient = createWalletClient({
  chain: holesky,
  transport: custom(window.ethereum!),
})
 
const [account] = await walletClient.getAddresses()

const signature = await walletClient.signMessage({ 
  account,
  message: "I confirm I request to voluntarily exit validator(s) with indexes: 1754303 and my request is valid for 5 min (2024-09-06 13:50:06 UTC).",
})
// Example output: "0x01b819c23d7e4414e611b15f7b611e95076f2bce726b31bcab68bbc66e2ffa0933b7df6bab0ddcb13039e5bbe076caa9672cdf18a2d4fc58d6b97089aaea06c71b"

If your customer uses MetaMask browser extension, they will see a popup asking to sign the message. They need to click the "Sign" button.

MetaMask Sign Popup

Exit Validator

To initiate the exit of a validator, use the following API request:

curl -X POST "https://api.testnet.stake.fish/v1/eth/stake/v1/exit-validators" \
    -H "Content-Type: application/json" \
    -H "Authorization: YOUR_PUBLIC_API_KEY" \
    --data '{
        "indices": [1754303],
        "message": "I confirm I request to voluntarily exit validator(s) with indexes: 1754303 and my request is valid for 5 min (2024-09-06 13:50:06 UTC).",
        "signature": "0x01b819c23d7e4414e611b15f7b611e95076f2bce726b31bcab68bbc66e2ffa0933b7df6bab0ddcb13039e5bbe076caa9672cdf18a2d4fc58d6b97089aaea06c71b"
    }'

📘

Important

This API requires Public API Key.

Explanation of Parameters

  • indices: Array of validator indices you want to exit. Validators must be active for at least one day before exiting.
  • message: The message signed by your customer's wallet.
  • signature: The signature generated in the previous step.

Example Response:

After sending the POST request, you’ll receive a response like this:

[
  {
    "pubkey": "0x11111111111111111111111111111111111111111111111111111111111111111111111111111111",
    "validatorIndex": "10487",
    "successful": true
  },
  {
    "pubkey": "0x22222222222222222222222222222222222222222222222222222222222222222222222222222222",
    "validatorIndex": "20250",
    "successful": true
  },
  {
    "pubkey": "0x33333333333333333333333333333333333333333333333333333333333333333333333333333333",
    "validatorIndex": "50423",
    "successful": false,
    "reason": "Validator #50423 is already exiting"
  }
]

Validator exit process typically takes 3 to 5 days.

Validator Withdrawal

Validator withdrawals are automated. Once a validator has exited, the staked funds will be returned to your wallet within 1 to 5 days, depending on latest validator withdrawal window.

To check your withdrawal progress, refer to the Monitoring Your Validator guide or visit the beaconcha.in:

BeaconCha.in Ethereum Explorer

Updated 2 months ago