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

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.hoodi.stake.fish/eth/stake/v1/exit-challenge?type=IMMEDIATE&indices=VALIDATOR_INDICES&address=WALLET_ADDRESS" \
    -H "Content-Type: application/json" \
    -H "Authorization: YOUR_PUBLIC_API_KEY"

Explanation of Parameters:

• • type: IMMEDIATE — stakefish broadcasts the exit (/v1/exit-validators); DEFERRED — returns signed exit messages for you to broadcast later (/v1/generate-exit-messages). Smart-contract wallets can only use IMMEDIATE.
  • VALIDATOR_INDICES: List of validator indices to be exited.
  • WALLET_ADDRESS: The validators' withdrawal address; it must be the wallet that signs the challenge. EOAs and ERC-1271 smart-contract wallets are supported.

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. The message expires after 5 minutes for regular wallets, or 1 hour for smart-contract wallets.

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 { hoodi } from 'viem/chains'
 
const walletClient = createWalletClient({
  chain: hoodi,
  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.

Exit Validator

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

curl -X POST "https://api.hoodi.stake.fish/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"
    }'

Explanation of Parameters

• indices: Array of validator indices you want to exit. Validators must be active for at least 256 epochs (approximately 1 day) before they can be exited.
• 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"
  }
]

Exit times vary depending on network conditions and exit queue length — from minutes when the queue is empty to several days during congested periods.

Validator Withdrawal

Validator withdrawals are automated. Once a validator has exited, staked funds are typically returned to your wallet within 1 to 5 days, depending on the exit queue and withdrawal sweep cycle. You can monitor progress on beaconcha.in.

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

Alternative: Generate Exit Messages

You can use the /v1/generate-exit-messages endpoint to generate signed voluntary exit messages for your validators, allowing you to broadcast them independently.