Skip to main content
API docs by Redocly

Codefi Staking API (3.5.0)

Download OpenAPI specification:Download

License: Apache 2.0

Staking

Staking operations.

Initiate staking by idempotently reserving validators.

Reserves a validator for the specific client. Requires an idempotent key.

It takes the supplied withdrawal_pubkey, the amount which must be equal to 32,000,000,000 Gwei (32 ETH), with the following optional fields: a vault_name, a fee_recipient ETH1 address and builder_relays with the array of MEV relay addresses.

It returns the deposit payload for the user to send.

Filtering options available. Customer can choose CloudProvider(s), Region(s) and ClientType(s) (see documentation for full list of possibilities) If omitted, validators allocated as per default.

Authorizations:
token
header Parameters
Idempotency-Key
required
string <uuid>
Example: f1c971b4-7114-4c4b-8ad2-a6f9e33e2cd0

the unique idempotency key for this request

Request Body schema: application/json
required

Withdrawal Public Key, the pledged Amount of 32,000,000,000 Gwei (32 ETH) and an option vault name.

withdrawal_pubkey
required
string (PublicKey) ^(0x[a-fA-F0-9]{96})|(0x[a-fA-F0-9]{40})$

Unique validator BLS public key: 48-bytes, hex-encoded, optional 0x prefix, case insensitive. Alternatively, 20-bytes with same spec.

amount
required
string (Gwei) ^[0-9]+$
vault_name
string^[ a-zA-Z0-9_-]{3,20}$
fee_recipient
string (Eth1Address) ^0x[a-fA-F0-9]{40}$

An ethereum 1 address, uniquely identifying them. 20-bytes, hex encoded with 0x prefix, case insensitive.

builder_relays
Array of strings (BuilderRelayAddress) [^(?:https?://)((0x[a-fA-F0-9]{96})|(0x[a-fA-F...]
cloud_providers
Array of strings (CloudProvider)
Items Enum: "azure" "aws"
regions
Array of strings (Region)
Items Enum: "as-japan" "as-singapore" "eu-sweden" "eu-ireland" "us-east" "us-central"
client_types
Array of strings (ClientType)
Items Enum: "teku" "lighthouse"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "chain_deposit_configuration": {
    },
  • "stake": {
    },
  • "fee_recipient": "0x93247f2209abcacf57b75a51dafae777f9dd38bc"
}

Initiate staking by idempotently reserving validators. Deprecated

Reserves a validator for the specific client. Requires an idempotent key.

It takes the supplied withdrawal_pubkey, the amount which must be equal to 32,000,000,000 Gwei (32 ETH), with the following optional fields: a vault_name, a fee_recipient ETH1 address and builder_relays with the array of MEV relay addresses.

It returns the deposit payload for the user to send.

Filtering options available. Customer can choose CloudProvider(s), Region(s) and ClientType(s) (see documentation for full list of possibilities) If omitted, validators allocated as per default.

Authorizations:
token
header Parameters
Idempotency-Key
required
string <uuid>
Example: f1c971b4-7114-4c4b-8ad2-a6f9e33e2cd0

the unique idempotency key for this request

Request Body schema: application/json
required

Withdrawal Public Key, the pledged Amount of 32,000,000,000 Gwei (32 ETH) and an option vault name.

withdrawal_pubkey
required
string (PublicKey) ^(0x[a-fA-F0-9]{96})|(0x[a-fA-F0-9]{40})$

Unique validator BLS public key: 48-bytes, hex-encoded, optional 0x prefix, case insensitive. Alternatively, 20-bytes with same spec.

amount
required
string (Gwei) ^[0-9]+$
vault_name
string^[ a-zA-Z0-9_-]{3,20}$
fee_recipient
string (Eth1Address) ^0x[a-fA-F0-9]{40}$

An ethereum 1 address, uniquely identifying them. 20-bytes, hex encoded with 0x prefix, case insensitive.

builder_relays
Array of strings (BuilderRelayAddress) [^(?:https?://)((0x[a-fA-F0-9]{96})|(0x[a-fA-F...]
cloud_providers
Array of strings (CloudProvider)
Items Enum: "azure" "aws"
regions
Array of strings (Region)
Items Enum: "as-japan" "as-singapore" "eu-sweden" "eu-ireland" "us-east" "us-central"
client_types
Array of strings (ClientType)
Items Enum: "teku" "lighthouse"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "chain_deposit_configuration": {
    },
  • "stake": {
    },
  • "fee_recipient": "0x93247f2209abcacf57b75a51dafae777f9dd38bc"
}

Initiate staking by idempotently reserving validators.

Reserves validators for the specific client. Requires an idempotent key.

It takes the supplied withdrawal_pubkey, the amount which must equal to or a multiple of 32,000,000,000 Gwei (32 ETH), with the following optional fields: a vault_name, a fee_recipient ETH1 address and builder_relays with the array of MEV relay addresses.

It returns the deposit payloads for the user to send.

Filtering options available. Customer can choose CloudProvider(s), Region(s) and ClientType(s) (see documentation for full list of possibilities) If omitted, validators allocated as per default.

Authorizations:
token
header Parameters
Idempotency-Key
required
string <uuid>
Example: f1c971b4-7114-4c4b-8ad2-a6f9e33e2cd0

the unique idempotency key for this request

Request Body schema: application/json
required

Withdrawal Public Key, the pledged Amount of 32,000,000,000 Gwei (32 ETH) and an option vault name.

withdrawal_pubkey
required
string (PublicKey) ^(0x[a-fA-F0-9]{96})|(0x[a-fA-F0-9]{40})$

Unique validator BLS public key: 48-bytes, hex-encoded, optional 0x prefix, case insensitive. Alternatively, 20-bytes with same spec.

amount
required
string (Gwei) ^[0-9]+$
vault_name
string^[ a-zA-Z0-9_-]{3,20}$
fee_recipient
string (Eth1Address) ^0x[a-fA-F0-9]{40}$

An ethereum 1 address, uniquely identifying them. 20-bytes, hex encoded with 0x prefix, case insensitive.

builder_relays
Array of strings (BuilderRelayAddress) [^(?:https?://)((0x[a-fA-F0-9]{96})|(0x[a-fA-F...]
cloud_providers
Array of strings (CloudProvider)
Items Enum: "azure" "aws"
regions
Array of strings (Region)
Items Enum: "as-japan" "as-singapore" "eu-sweden" "eu-ireland" "us-east" "us-central"
client_types
Array of strings (ClientType)
Items Enum: "teku" "lighthouse"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "chain_deposit_configuration": {
    },
  • "stakes": [
    ],
  • "fee_recipient": "0x93247f2209abcacf57b75a51dafae777f9dd38bc"
}

Get deposit payload for the previously reserved stake.

It returns the deposit payloads for the the previously reserved stake.

Authorizations:
token
path Parameters
stakeID
required
string (UUID) ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}...
Example: deadbeef-cafe-1337-2021-339ab8909701

Stake ID

Responses

Response samples

Content type
application/json
{
  • "chain_deposit_configuration": {
    },
  • "stakes": [
    ],
  • "fee_recipient": "0x93247f2209abcacf57b75a51dafae777f9dd38bc"
}

Initiate staking by bulk reserving validators. Deprecated

Splits the amount into 32 ETH divisions, reserves a validator_key for the specific client, takes the supplied withdrawal_key, generates and returns the deposit payload for the user to send.

Authorizations:
token
path Parameters
vaultID
required
string (UUID) ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}...
Example: deadbeef-cafe-1337-2021-339ab8909701

Vault ID

Request Body schema: application/json
required

Withdrawal credentials and pledged amount in multiples of 32 Eth, given in Gwei (32 Eth = 32000000000 Gwei).

Array
withdrawal_pubkey
required
string (PublicKey) ^(0x[a-fA-F0-9]{96})|(0x[a-fA-F0-9]{40})$

Unique validator BLS public key: 48-bytes, hex-encoded, optional 0x prefix, case insensitive. Alternatively, 20-bytes with same spec.

amount
required
string (Gwei) ^[0-9]+$

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "chain_deposit_configuration": {
    },
  • "stakes": [
    ],
  • "fee_recipient": "0x93247f2209abcacf57b75a51dafae777f9dd38bc"
}

Request a signed voluntary exit message with optional encryption. Deprecated

Initiate voluntary validator exit

This endpoint initiates the voluntary validator exit by requesting a signed voluntary exit message.

The are two possible cases: the Default and Open PGP cyphered.

Default voluntary exit

The successful response object has two fields:exit_transaction and fork_version.

Open PGP cyphered voluntary exit

The successful response object has the same exit_transaction and fork_version fields as in the previous case. The difference is that exit_transaction is an 0x-prefixed hex encoded string which contains a signed voluntary exit message encrypted as an ASCII armored message.

The customer should manually provide their armored PGP public key, and set the cypher query parameter to openpgp.

Summary of applied rules

  • No PGP public key given and the cypher=openpgp -> 400 - bad request
  • PGP public key given and cypher is not specified -> 400 - bad request
  • PGP public key given and cypher=openpgp -> Open PGP cyphered.
  • No PGP public key given and cypher is not specified -> default.
Authorizations:
token
path Parameters
validatorID
required
string (ValidatorID)
Examples:
  • 2.5552491662185297e+115 - Validator BlS Public Key
  • 42 - Validator Index

Validator identifier

query Parameters
cypher
string
Value: "openpgp"

Cypher type. The only available option at the moment is openpgp.

Responses

Response samples

Content type
application/json
Example
{
  • "exit_transaction": {
    },
  • "fork_version": "0x00000001"
}

Request a signed voluntary exit message with optional encryption.

Get Signed Voluntary Exit Message

This endpoint prepares a signed voluntary exit message. It won't submit the message to the consensus client.

The are two possible cases: the Default and Open PGP cyphered.

Default voluntary exit

The successful response object has two fields:exit_transaction and fork_version.

Open PGP cyphered voluntary exit

The successful response object has the same exit_transaction and fork_version fields as in the previous case. The difference is that exit_transaction is an 0x-prefixed hex encoded string which contains a signed voluntary exit message encrypted as an ASCII armored message.

The customer should manually provide their armored PGP public key, and set the cypher query parameter to openpgp.

Summary of applied rules

  • No PGP public key given and the cypher=openpgp -> 400 - bad request
  • PGP public key given and cypher is not specified -> 400 - bad request
  • PGP public key given and cypher=openpgp -> Open PGP cyphered.
  • No PGP public key given and cypher is not specified -> default.
Authorizations:
token
path Parameters
validatorID
required
string (ValidatorID)
Examples:
  • 2.5552491662185297e+115 - Validator BlS Public Key
  • 42 - Validator Index

Validator identifier

query Parameters
cypher
string
Value: "openpgp"

Cypher type. The only available option at the moment is openpgp.

Responses

Response samples

Content type
application/json
Example
{
  • "exit_transaction": {
    },
  • "fork_version": "0x00000001"
}

Request a signed voluntary exit message with optional encryption.

Submit voluntary validator exit

This endpoint submits the voluntary validator exit by preparing and submitting a signed voluntary exit message. It will submit the message to the consensus client. It does not support cyphering.

Authorizations:
token
path Parameters
validatorID
required
string (ValidatorID)
Examples:
  • 2.5552491662185297e+115 - Validator BlS Public Key
  • 42 - Validator Index

Validator identifier

query Parameters
cypher
string
Value: "openpgp"

Cypher type. The only available option at the moment is openpgp.

Responses

Response samples

Content type
application/json
Example
{
  • "code": 400,
  • "message": "api error: code 400: bad request: cannot initiate validator voluntary exit: validator is not active"
}

Vault

Create a validator vault. Deprecated

Create a validator vault.

Authorizations:
token
Request Body schema: application/json
required

A vault object, only sets the required element name.

id
string (UUID) ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}...

Unique identifier.

name
required
string^[ a-zA-Z0-9_-]{3,20}$

Responses

Request samples

Content type
application/json
{
  • "id": "deadbeef-cafe-1337-2021-339ab8909701",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "deadbeef-cafe-1337-2021-339ab8909701",
  • "name": "string"
}

Keys

Get withdrawal public keys. Deprecated

Return paginated withdrawal public keys with name.

Authorizations:
token
query Parameters
offset
integer >= 0
Default: 0

The number of items to skip before starting to collect the result set.

limit
integer [ 1 .. 500 ]
Default: 100

The numbers of items to return.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add withdrawal public key. Deprecated

Add withdrawal public key with name.

Authorizations:
token
Request Body schema: application/json
required

Withdrawal public key with label.

id
string (UUID) ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}...

Unique identifier.

name
required
string^[ a-zA-Z0-9_-]{3,20}$
status
string
public_key
required
string (PublicKey) ^(0x[a-fA-F0-9]{96})|(0x[a-fA-F0-9]{40})$

Unique validator BLS public key: 48-bytes, hex-encoded, optional 0x prefix, case insensitive. Alternatively, 20-bytes with same spec.

Responses

Request samples

Content type
application/json
{
  • "id": "deadbeef-cafe-1337-2021-339ab8909701",
  • "name": "string",
  • "status": "string",
  • "public_key": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
}

Response samples

Content type
application/json
{
  • "id": "deadbeef-cafe-1337-2021-339ab8909701",
  • "name": "string",
  • "status": "string",
  • "public_key": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
}

Healthcheck

Readiness Probe

Readiness status

Authorizations:
token

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Liveness Probe

Liveness status

Authorizations:
token

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}