# Node Provisioning API

### What is the Node Provisioning API?

The Node Provisioning API allows partners to programmatically spin-up nodes for staking.  Partners specify the number of nodes needed and receive a transaction to sign that stakes with those node/s. 

| Chain                 | Assets per Node           |
| --------------------- | ------------------------- |
| [ETH2](#ethereum-2-0) | 32-2048 ETH per Validator |

## ETH2

Provision validators with an API request and submit the deposits through a single ETH1 transaction. 

### Integration Environments

Staked supports integration testing on ETH2, as defined below.

| Base URL                           | Target ETH Network |
| ---------------------------------- | ------------------ |
| <https://mainnet.staked.cloud/api> | Mainnet            |
| <https://testnet.staked.cloud/api> | Hoodi              |

## Post ETH2 Provisioning Request

<mark style="color:green;">`POST`</mark> `https://mainnet.staked.cloud/api/provisioning_requests/eth2`

Provision ETH2 validators in our secure cloud environments. The response contains a unique identifier for the provisioning request.

#### Request Headers

| Name      | Type   | Description                                                                                                            |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------------------- |
| X-Api-Key | string | Your API key - (Must have ETH2 access, preferred method of passing api key is now in headers rather than query params) |

#### Query Parameters

| Name     | Type   | Description                                                                                                                                                                                                   |
| -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api\_key | string | <p><strong>\[Deprecated since March '25</strong> (preferred method of passing api key is now in headers rather than query params)<strong>]</strong> </p><p></p><p>Your API Key - (Must have ETH2 access) </p> |

#### Request Body

| Name       | Type   | Description            |
| ---------- | ------ | ---------------------- |
| attributes | object | ETH2 Attributes Object |

{% tabs %}
{% tab title="200 Example of provisioning request response" %}

```javascript
{
    "id": 19705,
    "uuid": "4f1dcf14-3a64-4307-9272-511a99a25075",
    "created": "2025-05-16T16:07:06",
    "status": "CREATED",
    "chain": "ETH2",
    "user_id": "8",
    "partner_id": null,
    "attributes": {
        "amount": "32",
        "validators": [
            {
                "count": 1,
                "provider": "decentralized"
            }
        ],
        "eth1Address": "YourWithdrawalAddressHere",
        "stakingMode": "type0x01",
        "payoutAddress": "YourPayoutAddressHere",
        "feeRecipientGroupKey": null,
        "withdrawalCredentials": null
    }
}
```

{% endtab %}
{% endtabs %}

{% file src="<https://2178620674-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lnwvtb-ynBFEMFOSc4X%2Fuploads%2FVRwCg6imwAtjqkZZMWnF%2FETH2%20Testnet%20-%20Post%20Provisioning%20Request.postman_collection.json?alt=media&token=58ed0941-6b04-4898-ac20-e79fe8b22c6e>" %}
Postman - Provisioning Request
{% endfile %}

#### ETH2 Attributes Object

<table><thead><tr><th width="258">Field</th><th width="290">Description</th><th width="99">Type</th><th>Required</th></tr></thead><tbody><tr><td><code>eth1Address</code></td><td>Ethereum wallet address which will be used to create withdrawal credentials for the validator (consensus layer reward recipient)</td><td><code>string</code></td><td><code>true</code></td></tr><tr><td><code>payoutAddress</code></td><td>Optional: A payable Ethereum address that will receive execution layer payments.<br>Note: if none is provided, payments will be sent to the withdrawal credential.</td><td><code>string</code></td><td><code>false</code></td></tr><tr><td><code>feeRecipientGroupKey</code></td><td>Optional: Specify that these validators should receive execution layer fees on an separate address. <br><strong>Note:</strong> This groupKey and its associated recipient address must be registered and confirmed with Staked in advance before it is valid to be used in provisioning requests.</td><td><code>string</code></td><td><code>false</code></td></tr><tr><td><code>stakingMode</code></td><td><p><code>type0x01</code>  for pre-Pectra staking: max 32 ETH per validator; rewards do not compound automatically. </p><p></p><p><code>type0x02</code>  for post-Pectra staking, max 2048 ETH per validator; rewards compound automatically.</p></td><td><code>string</code></td><td><code>false</code></td></tr><tr><td><code>amount</code></td><td>Deposit amount. This field is ignored if you select <code>type0x01</code> staking mode. It is mandatory if you select <code>type0x02</code> staking mode.</td><td><code>string</code></td><td><p><code>false</code> for <code>type0x01</code> </p><p> </p><p><code>true</code> for <code>type0x02</code></p></td></tr><tr><td><code>validators</code></td><td>Array of validator config objects</td><td><code>array</code></td><td><code>true</code></td></tr></tbody></table>

#### Validator Config Object

| Field    | Description                                          | Type   |
| -------- | ---------------------------------------------------- | ------ |
| provider | Validator provider enum: "decentralized" or "amazon" | String |
| count    | Number of validators to provision                    | Number |

```javascript
// example post request body
{
    "attributes": {
        "eth1Address": "0xYourWithdrawalAddressHere",
        "payoutAddress": "0xYourPayoutAddressHere",
        "feeRecipientGroupKey": "0xYourFeeRecipientHere",
        "stakingMode": "type0x02",
        "amount": "194.123",
        "validators": [
            {
                "count": 1
            }
        ]
    }
}
```

#### Provisioning Response Object

| Field       | Description                                       | Type   |
| ----------- | ------------------------------------------------- | ------ |
| id          | Numbered identifier of provisioning request       | String |
| uuid        | Unique identifier of provisioning request         | String |
| created     | Provisioning request creation datetime            | String |
| status      | Provisioning request status - "CREATED"           | String |
| chain       | Chain identifier - "ETH2"                         | String |
| user\_id    | User identifier - returns null unless using oauth | String |
| partner\_id | Partner identifier associated with api key        | String |
| attributes  | ETH2 attributes object                            | Object |

## Get ETH2 Delegation Objects

<mark style="color:blue;">`GET`</mark> `https://mainnet.staked.cloud/api/delegations/eth2`

After POSTing a provisioning request, use the unique identifier to GET the delegation objects for each validator. Delegation objects contain the information required to submit deposits on ETH1.

#### Request Headers

| Name      | Type   | Description                                                                                                            |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------------------- |
| X-Api-Key | string | Your API key - (Must have ETH2 access, preferred method of passing api key is now in headers rather than query params) |

#### Query Parameters

| Name      | Type   | Description                                                                                                                                                                                                   |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api\_key  | string | <p><strong>\[Deprecated since March '25</strong> (preferred method of passing api key is now in headers rather than query params)<strong>]</strong> </p><p></p><p>Your API Key - (Must have ETH2 access) </p> |
| filters   | string | provisioning\_request\_uuid:YOUR UUID                                                                                                                                                                         |
| page      | number | Page of results to fetch                                                                                                                                                                                      |
| per\_page | number | Number of results per page                                                                                                                                                                                    |

{% tabs %}
{% tab title="200 Paginated results containing ETH2 delegation objects." %}

```javascript
{
    "results": [
        {
            "id": 4308,
            "address": "82fcdaa3d3f1429dea23b02eeae00bfff41ec9c1d0281a1b4d58d782111eef691d972af56799fda43a6a46fdac49bd65",
            "chain": "ETH2",
            "attributes": {
                "cloud": "amazon",
                "count": 1,
                "index": 1,
                "depositInput": "22895118000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000012020e35863f9077de93ac5f59bbb8adea7cfd0a4cc02795a0d43ce87cd82b9f1b9000000000000000000000000000000000000000000000000000000000000003082fcdaa3d3f1429dea23b02eeae00bfff41ec9c1d0281a1b4d58d782111eef691d972af56799fda43a6a46fdac49bd650000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000200027662cfd6fa4cfe93b5d34c233756e2b972c7b0a0e11f2e4500d1f131e604d0000000000000000000000000000000000000000000000000000000000000060863fc2373413eac068f088acad56c7f5125c852fc45ba531cccfa50db1c375892c56d9d8d6610e9d2954c9232e0ac97009faaa67ae24dacb853002a37baa257651f0bc3ec915b3014c916c18c28fdc92c71b5b3a251c859410ed9651225e9fd5",
                "validatorKey": "82fcdaa3d3f1429dea23b02eeae00bfff41ec9c1d0281a1b4d58d782111eef691d972af56799fda43a6a46fdac49bd65"
            },
            "amount": "0",
            "created": "2020-11-14T19:51:14",
            "status": "CREATED",
            "user_id": null,
            "partner_id": "18",
            "provisioning_request_uuid": "693c10d8-70e5-4a5d-aeb0-6c53ea625433",
            "provisioning_request_id": "163"
        },
        ...
    ],
    "page": 1,
    "pages": 9,
    "per_page": 10,
    "total": 86
}
```

{% endtab %}
{% endtabs %}

{% file src="<https://2178620674-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lnwvtb-ynBFEMFOSc4X%2Fuploads%2FsBt1bqKSz7ktayP0dZBW%2FETH2%20Testnet%20-%20Delegation%20Collection.postman_collection.json?alt=media&token=7db37711-aaf1-4f0b-9b2c-7df137d02843>" %}
Postman - Delegation Objects
{% endfile %}

{% hint style="info" %}
Validators are provisioned asynchronously, meaning the GET request will fill-in over time as our infrastructure fulfills the associated provisioning request. Use the "total" field in the response object to track the number of validators provisioned at any given time.
{% endhint %}

#### Paginated Response Object

| Field     | Description                      | Type   |
| --------- | -------------------------------- | ------ |
| results   | Array of ETH2 delegation objects | Array  |
| page      | Page of fetched results          | Number |
| pages     | Total number of pages            | Number |
| per\_page | Number of results per page       | Number |
| total     | Number of results in total       | Number |

#### ETH2 Delegation Object

| Field                       | Description                                         | Type   |
| --------------------------- | --------------------------------------------------- | ------ |
| id                          | Identifier of delegation object                     | Number |
| address                     | Validator public key                                | String |
| chain                       | Chain identifier - "ETH2"                           | String |
| attributes                  | ETH2 delegation attributes object                   | Object |
| amount                      | Amount currently delegated                          | String |
| created                     | Delegation object creation time                     | String |
| status                      | ETH2 delegation status enum                         | String |
| user\_id                    | User identifier - returns null unless using oauth   | String |
| partner\_id                 | Partner identifier associated with api key          | String |
| provisioning\_request\_uuid | Associated provisioning request unique identifier   | String |
| provisioning\_request\_id   | Associated provisioning request numbered identifier | String |

#### ETH2 Delegation Attributes Object

| Field        | Description                                                   | Type   |
| ------------ | ------------------------------------------------------------- | ------ |
| cloud        | Validator cloud configuration                                 | String |
| count        | Total number of validators in associated provisioning request | Number |
| index        | Index of validator in associated provisioning request         | Number |
| depositInput | Validator deposit transaction data                            | String |
| validatorKey | Validator public key                                          | String |

#### ETH2 Delegation Status Enum

| Value     | Definition                                     | Time Period |
| --------- | ---------------------------------------------- | ----------- |
| CREATED   | Validator was provisioned through Staked API   | n /a        |
| DEPOSITED | Deposit is waiting to be seen by ETH2 chain    | 0-6 Hours   |
| PENDING   | Validator is in the queue waiting to go live   | 0-6 Days    |
| ACTIVE    | Validator is participating and earning rewards | n / a       |

### Submit Deposits through the Batching Contract

The canonical [ETH2 deposit contract](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/phase0/deposit-contract.md), used to convert ETH1 to ETH2, only supports one deposit transaction at a time. Since 32 ETH is required for each validator, depositors with large amounts of ETH would have to broadcast many deposit transactions.

To simplify submitting deposits, we have created a batching contract which takes up to 185 deposits at once and submits each to the deposit contract. Integrators can therefore stake up to 5920 ETH in one Ethereum transaction, and leave behind the hassle of tracking many individually broadcasted transactions.

#### Batching Contract Deployments

| ETH2 Network | Batching Contract Address                                                                                                   |
| ------------ | --------------------------------------------------------------------------------------------------------------------------- |
| Mainnet      | [0x39DC6a99209B5e6B81dC8540C86Ff10981ebDA29](https://etherscan.io/address/0x39DC6a99209B5e6B81dC8540C86Ff10981ebDA29)       |
| Holesky      | [0x2f19e60594131db0b5b88e55ac2910f484e9c8f5](https://hoodi.etherscan.io/address/0x2f19e60594131db0b5b88e55ac2910f484e9c8f5) |

{% file src="<https://2178620674-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Lnwvtb-ynBFEMFOSc4X%2F-MMH0qI27ORfGxBDOG1k%2F-MMH0vus1NgeqpoD4U3j%2FBatchDeposit.json?alt=media&token=c2561bc3-0d68-40cf-bef4-299c7f422f2b>" %}

The batching contract contains an external payable function, `batchDeposits`, which loops over each validator's deposit and sends them to the deposit contract. The function arguments are passed as a 2-d array where the array at `[i]` represents the deposit arguments for validator `i`.

{% hint style="success" %}
For release notifications of the ETH2 API and developer tools, [click here](https://share.hsforms.com/1kMyIbkmCR8K14UzIkt8Zsw3zgh0).
{% endhint %}

##