Skip to main content

Relayer (API Mode)

In the standard setup, the Operator Service holds validator keystores locally and registers validators using a deposit data file uploaded to the Vault. In API mode, an external service called a Relayer takes over — it generates validator keys, produces all required signatures, and sends everything to the Operator via API calls. The Operator then submits the registration to the Vault contract. This is useful when:

  • Validator keystores must be managed separately from the Operator Service
  • The signing wallet is a multi-signature setup or hardware security module
  • You're using DVT infrastructure that manages keys across multiple nodes

How Registration Verification Works​

Every time a validator is registered, the Vault contract needs to verify that the registration is authorized. There are two ways this can work:

Default (deposit data file) — You generate validator keys and a deposit data file with the Operator Service, then upload it to your Vault. On each registration, the Vault contract checks that the submitted validator was pre-approved in the uploaded file (using a Merkle proof — a compact cryptographic check against the file contents). This is the standard setup described in Prepare Operator →.

Validators Manager signature (required for API mode) — Instead of checking a deposit data file, the Vault contract verifies a cryptographic signature from a designated wallet called the Validators Manager. The Relayer signs each registration with this wallet using the EIP-712 ↗ standard (a structured way to sign typed data on Ethereum). If the signature is valid, the registration is approved. Since the Relayer provides all data and signatures on demand, you don't need to generate or upload a deposit data file.

How the Operator-Relayer Flow Works​

Once running, the Operator and Relayer communicate automatically:

  1. The Operator monitors your Vault's balance
  2. When enough ETH accumulates (32 ETH per validator), the Operator calculates the next validator index and sends a registration request to the Relayer
  3. The Relayer generates the validator key pair and returns:
    • Deposit signature — proves the validator deposit is valid for the beacon chain
    • Exit signature — pre-signed so the validator can be exited later without needing the Relayer again
    • Validators Manager signature — authorizes the registration with the Vault contract
  4. The Operator requests approval from the StakeWise Oracles (network validators that independently verify the registration is legitimate)
  5. The Operator submits the registration transaction to the Vault contract on-chain
IconExit Signature Index

To produce exit signatures, the Relayer must use the validator index passed in the request. The Operator passes the start validator index — increment it for each subsequent validator in the batch.

Setup​

Prerequisites​

Complete the following steps before proceeding:

  1. Installation completed →
  2. Operator Service prepared →

Configure Validators Manager​

To use API mode, you need to set a custom Validators Manager — the wallet your Relayer will sign with:

  1. Navigate to Settings → Roles → Validators Manager in the Vault UI
  2. Assign the wallet address that your Relayer will use for signing

Start Operator API​

To run the Operator in API mode, use the start-api command:

./operator start-api

This command allows for direct parameter input (e.g., --data-dir) or through environment variables. A basic example of setting environment variables is as follows:

.env
CONSENSUS_ENDPOINTS=https://lighthouse
DATA_DIR=/data
DATABASE_DIR=/database
EXECUTION_ENDPOINTS=https://nethermind
NETWORK=hoodi
VAULT=0x3cc...
RELAYER_ENDPOINT=https://relayer

For additional parameter information, use the --help flag:

./operator start-api --help
IconDocker Configuration

For Docker-specific setup instructions, see the Docker Image tab in Installation →

API Specification​

The Relayer must implement the following endpoints. You can implement your own Relayer using this specification.

Validator Registration​

POST /validators

Request Body:

{
  "vault": "0x1234...",
  "validators_start_index": 20551,
  "validators_batch_size": 10,
  "validators_total": 50
}

Parameters:

  • validators_start_index — validator index for the first validator in the batch.
  • validators_batch_size — number of validators in current batch. Maximum batch size is determined by protocol config, currently 10.
  • validators_total — hint for Relayer. Does not affect Relayer response. Relayer may use this value to allocate larger portions of validators in the background. validators_total should be more than or equal to validators_batch_size.

Response:

{
  "validators": [
    {
      "public_key":  "0xPubKey1",
      "deposit_signature": "0xDepositSig1",
      "amount_gwei": 32000000000,
      "exit_signature": "0xExitSig1"
    }
  ],
  "validators_manager_signature": "0xManagerSig"
}

Response fields:

  • public_key — Validator public key.
  • deposit_signature — Deposit signature for the validator.
  • amount_gwei — Deposit amount in Gwei (always 32 ETH for V3).
  • exit_signature — Exit signature for the validator.
  • validators_manager_signature — EIP-712 ↗ signature from the Validators Manager wallet. See the message structure in the Vault contract ↗.
IconRelayer Example

See demo project relayer-example ↗ — a Python-based FastAPI application that demonstrates how to implement a relayer service for Ethereum staking operations.

Info​

GET /info

Response:

{
  "network": "mainnet"
}

DVT Relayer​

When using a DVT setup, a specialized DVT relayer is required. Unlike a regular relayer, you do not need to set up a dedicated relayer instance. Instead, you can use the public DVT relayer available at: https://mainnet-dvt-relayer.stakewise.io/.

The Operator environment configuration is similar to that of a regular relayer. However, you must specify the relayer type as follows:

.env
RELAYER_TYPE=DVT
# RELAYER_ENDPOINT environment variable is not required
Last updated on