API Mode

Operator V3 Documentation

This page covers Operator Service V3. If your Vault version is 5+ on Ethereum or 3+ on Gnosis, refer to the V4 Relayer (API Mode) →.

In the standard setup, the Operator Service holds the validator keystores and the hot wallet locally. In API mode, both are managed externally — the Operator Service delegates all signing and key operations via API calls. This is useful when:

• The hot wallet is managed outside the Operator Service (e.g., multi-signature setup or hardware security module)
• Validator keystores are managed by an external system
• You want to fully isolate key management from the Operator Service

Prerequisites

Complete the following steps before proceeding:

1. Installation → completed
2. Hot wallet address set in the Vault settings

Start Operator Service

In V3, use the start-api command:

./operator start-api \
  --vault=0x834F27bC8670491b75af512d943f01D5383F87Cf \
  --consensus-endpoints=https://consensus-node \
  --execution-endpoints=https://execution-node

This command allows for direct parameter input or through environment variables. A basic example of setting environment variables:

.env

CONSENSUS_ENDPOINTS=https://lighthouse
DATA_DIR=/data
DATABASE_DIR=/database
EXECUTION_ENDPOINTS=https://nethermind
NETWORK=mainnet
VAULT=0x3cc...

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

./operator start-api --help

Docker Configuration

For Docker-specific setup instructions, see Installation →

API Endpoints

The external service must implement the following endpoint to handle validator registration:

Validator Registration

POST /register

Request Body:

{
  "vault": "0x1234...",
  "validators_start_index": 20551,
  "amounts": [32000000000]
}

Parameters:

• vault - Address of the vault contract to which the validators will be registered.
• validators_start_index - Validator index for the first validator in the batch.
• amounts - List of deposit amounts for each validator (32 ETH). Value provided in Gwei.

Response:

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

Response fields:

• public_key - Validator public key.
• deposit_signature - Deposit signature for the validator.
• amount - Deposit amount in Gwei (always 32 ETH for V3).
• exit_signature - Exit signature for the validator.
• validators_manager_signature - EIP-712 ↗ signature from the hot wallet.

V3 Limitations

V3 API mode only supports validator registration. Features like validator funding, partial withdrawals, and consolidation are available in V4 Relayer (API Mode) →.

Info

GET /info

Response:

{
  "network": "mainnet"
}