Staking

This document details the Balance Custody Staking API, enabling secure staking transactions and validator management for supported assets.

• API URL

• Authentication

• API Endpoints

  • POST /api/v2/staking/transactions

    • Accepted parameters

    • Response Format

    • Examples

  • POST /api/v2/staking/eth/validators/:validator_pubkey/exits

    • Accepted parameters

    • Response Format

    • Examples

API URL

You will receive your warm wallet integration URL from your point of contact at Balance, and will look like:

YOUR_CUSTOM_SUBDOMAIN.balancecustody.ca

---

Authentication

Due to the nature of the information exposed, every endpoint in this API requires authentication.

For more information on authentication go to Authentication doc.

---

API Endpoints

For brevity, the curl examples below do not include headers. See the Authentication Docs for required headers.

Response data is for example purposes only and does not represent real accounts.

POST /api/v2/staking/transactions

Creates a staking transaction for a given asset.

Note that this API is only supported if your account is configured for staking to a provider with established API credentials and configuration such as Attestant.

Accepted parameters:

Accepts the following parameters as JSON-encoded POST request body. Must specify the Content-Type: application/json header with the request.

asset

Required. String. Lowercase asset to be transferred.

Currently only the following assets are supported for this API call:

• eth - Ethereum

amount

Required. String. Specifies the amount to be staked, in base unit (e.g. wei). Currently only supports the following value: "32000000000000000000" (i.e. equal to 32 ETH).

source_wallet_id

Required. Integer. ID of the wallet from which the funds are to be withdrawn.

destination_id

Required. Integer. This must be the ID of the Ethereum (ETH) staking contract external account that is configured for your instance by Balance. Note that the default beneficiary entity needs to be set on this external account.

withdrawal_wallet_id

Required. Integer. ID of the wallet where staking rewards are to be sent. Can be a warm or offline wallet ID or an external account ID.

fee

Optional. String or integer. Specifies the fee rate or preset. Valid values are:

• slow - we recommend specifying this if you're ok with waiting for hours / days for your transaction to be included in a block, or potentially be dropped out of the mempool during periods of high congestion.

• medium - recommended preset, your transaction should be included in the next block in most cases

• fast - we recommend using this if you want to ensure your transaction is included in the next block during periods of high congestion.

You can also specify a fee rate, in the fee rate unit. In the case of Ethereum (ETH) that unit is gwei. Our backend will perform additional validation on this value to ensure it is within reasonable bounds.

group_id

Optional. String (max 256 characters). Specifies the Group ID with which an Attestant validator is to be configured.

notes

Optional. String. Any notes for your own records. These have no effect on the on-chain transactions.

beneficiary_entities

Required if travel rule is applicable. An object of type Originator Entity.

Response Format:

The response format is the standard Transaction struct, which can be found in GET /api/v1/transactions/:id.

Once the transaction has been generated and broadcast (after all applicable approvals and checks are done), you will receive the following fields from the GET /api/v1/transactions/:id API call, that are specific to the staking transactions:

withdrawal_wallet

A wallet struct (definition can be found in the GET /api/v1/wallets/:id API call) specifying the wallet where ETH staking rewards will be deposited.

validator_pubkey

The public key of the validator once it has been allocated. Note that this field will not be immediately available until the transaction has been approved, validator has been allocated and transaction has been generated. We suggest polling the GET /api/v1/transactions/:id API call to look for this field.

Examples:

Example request body:

{
  "asset": "eth",
  "amount": "32000000000000000000",
  "source_wallet_id": 1,
  "destination_id": 2,
  "withdrawal_wallet_id": 3
}

Example request body with group ID:

{
  "asset": "eth",
  "amount": "32000000000000000000",
  "source_wallet_id": 1,
  "destination_id": 2,
  "withdrawal_wallet_id": 3,
  "group_id": "foobar"
}

Example request body with custom fee preset:

{
  "asset": "eth",
  "amount": "32000000000000000000",
  "source_wallet_id": 1,
  "destination_id": 2,
  "withdrawal_wallet_id": 3,
  "fee": "fast"
}

Example request body with custom fee rate of 15 Gwei and notes:

{
  "asset": "eth",
  "amount": "32000000000000000000",
  "source_wallet_id": 1,
  "destination_id": 2,
  "withdrawal_wallet_id": 3,
  "fee": 15,
  "notes": "foo bar"
}

Example response body:

{
    "amounts": { "eth": 32.0 },
    "beneficiary_entities": [],
    "beneficiary_entity": {},
    "block": { "eth": 8014743 },
    "cad_rates": { "eth": 1594.09107 },
    "completed_at": "2022-11-25T01:57:27.000Z",
    "created_at": "2022-11-25T01:57:20.000Z",
    "destination": {
        "addresses": { "eth": "0xff50ed3d0ec03ac01d4c79aad74928bff48a7b2b" },
        "custom_id": "eth2-deposit-contract",
        "description": "An executed Staking Service Agreement with the provider as well as the appointment of Balance as an Authorized Person under the agreement are needed as prerequisites.",
        "id": 193,
        "name": "ETH Staking Service Provider",
        "type": "external_account"
    },
    "fee_units": { "eth": "gwei" },
    "fees": { "eth": 0.00000124812567414 },
    "id": 6299,
    "is_batched": false,
    "notes": "32 ETH to be staked with ETH Staking Service Provider with the withdrawal account set to Test Withdrawal Wallet at 0x58aCD2a994C8F20095b53b682d6dba0907E6Ec0B",
    "originator_entity": {},
    "regulatory_status": "completed",
    "requested_by": "Satoshi Nakamoto",
    "source": {
        "balance": { "eth": 38.1919651569535 },
        "custom_id": "Operating Wallet ID",
        "description": "",
        "funding_addresses": { "eth": "0x0CDE25dB916Bf4fef6BeFE384c69294515f2819E" },
        "id": 3,
        "kind": "warm",
        "name": "Operations Wallet",
        "type": "wallet"
    },
    "status": "completed",
    "transaction_ids": [{
        "currency": "eth",
        "transaction_id": "0xd5d67ced79b816bd7a8418df1603c5b74c0177a1ab5584a87767bd943a6c4695"
    }],
    "type": "transaction",
    "validator_pubkey": "0xaae1e03655adef16d1d685050f329c920f08d9acc62a26d86be5384c2e2dd91d46b84eee7f12e721e93bfdcb3571ecb8",
    "withdrawal_wallet": {
        "balance": { "eth": 0.418593319 },
        "custom_id": "test-withdrawal-wallet",
        "description": "",
        "funding_addresses": { "eth": "0x58aCD2a994C8F20095b53b682d6dba0907E6Ec0B" },
        "id": 1259,
        "kind": "warm",
        "name": "Test Withdrawal Wallet",
        "type": "wallet"
    }
}

Example curl command:

curl -XPOST \
     -d '{"asset":"eth","amount":"32000000000000000000","source_wallet_id":1,"destination_id":2,"withdrawal_wallet_id":3}' \
     https://your_custom_subdomain.balancecustody.ca/api/v2/staking/transactions

POST /api/v2/staking/eth/validators/:validator_pubkey/exits

Exits the validator with the given pubkey.

Note that this API is only supported if your account is configured for staking to a provider with established API credentials and configuration such as Attestant.

Accepted parameters:

None

Response Format:

Upon success you will receive a 200 response code, with no body.

Examples:

Example curl command:

curl -XPOST \
     https://your_custom_subdomain.balancecustody.ca/api/v2/staking/eth/validators/0xad8c768353f336e660e0162c93bdb8091f4fe8ddb4c810f2df46e0ecd46c786334f3f807f3fecb32c11f3a80db467bc1/exits