Overview

Key concepts

New validator provisioning: requires at least 32 ETH.
Adding stake: you can add any amount to an existing validator, as long as the added stake does not increase the total amount per validator to more than 2048 ETH.
Pectra vs pre‑Pectra: use validatorType to distinguish validator types while keeping requests backward compatible.
Go-live providers: FIGMENT and BLOCKDAEMON.

Relevant endpoints

Stake: POST /v2/transactions/stake
Unstake: POST /v2/transactions/unstake
List transactions: GET /v2/transactions
List wallet balances: GET /v2/wallets, GET /v2/vaults/{vaultId}/wallets, GET /v2/wallets/{walletId}
Get staking positions: GET /v2/wallets/{walletId}/staking/positions

Workflows

Stake (provision or add stake)

Endpoint POST /v2/transactions/stake

When to use which fields

Provision a new Pectra validator
- Provide: validatorType, stakingProvider
- Omit: stakingPositionId
Add stake to an existing validator position
- Provide: stakingPositionId, amount
- Omit: validatorType, stakingProvider

Request body additions

Add a parameters object to specify Pectra‑specific behavior.

Example: Provision a new Pectra validator

{
  "source": {
    "type": "WALLET",
    "id": "1c920f4241b78a1d483a29f3c24b6c4c"
  },
  "amount": "32",
  "assetType": "ETH",
  "description": "Internal 9876543210",
  "idempotentId": "9876543210",
  "parameters": {
    "validatorType": "0x02",
    "stakingProvider": "FIGMENT"
  }
}

Example: Add stake to an existing staking position

{
  "source": {
    "type": "WALLET",
    "id": "1c920f4241b78a1d483a29f3c24b6c4c"
  },
  "amount": "35",
  "assetType": "ETH",
  "description": "Add stake to existing position",
  "idempotentId": "9876543211",
  "parameters": {
    "stakingPositionId": "FuS3FPfJDKSNot99ECLXtp3rueq36hMNStJkPJwWodLh"
  }
}

Response

A successful request returns 201 Created with a transaction id.

Unstake (partial or full)

Endpoint POST /v2/transactions/unstake

Request rules

stakingPositionId is required.
For partial unstake, provide amount and set isFullAmount to false.
For full unstake, set isFullAmount to true. (In this case, amount is optional and may be ignored.)

Example: Partial unstake

{
  "source": {
    "type": "WALLET",
    "id": "1c920f4241b78a1d483a29f3c24b6c4c"
  },
  "amount": "5",
  "assetType": "ETH",
  "idempotentId": "123456789",
  "isFullAmount": false,
  "description": "Unstake 5 ETH",
  "stakingPositionId": "FuS3FPfJDKSNot99ECLXtp3rueq36hMNStJkPJwWodLh"
}

Response

A successful request returns 201 OK with a transaction id.

Consolidate to Pectra validator

Endpoint POST /v2/transactions/consolidate-stake Request rules

Enter source walletId and assetType in the request body. Use ETH in Production and ETHHOODI in staging
You can consolidate across wallets and vaults but not across different validator providers (e.g. do NOT consolidate a Figment validator to a BlockDaemon validator)
You can consolidate from Pectra to Pectra validators and Non-Pectra to Pectra validators; you cannot consolidate to non-Pectra validators

Example: Consolidate request

{
  "source": {
    "type": "WALLET",
    "id": "1c920f4241b78a1d483a29f3c24b6c4c"
  },
  "assetType": "ETH",
  "description": "Consolidate Stake",
  "idempotentId": "12838927347",
  "sourceStakingPosition": "0xa1d1...",
  "targetStakingPosition": "0x9647..."
}

Response A successful request returns a 201

List transactions

This endpoint retrieves a list of all transactions for an org (deposits, withdrawals, rewards). Endpoint GET /v2/transactions

Rewards behavior

For rewards, this endpoint will continue to return:

DELEGATION_REWARD
STAKING_REWARD

List wallet balances

This endpoint retrieves wallet balances for either a single wallet or all wallets in a vault. Endpoints

List all wallets for all vaults

Expected behavior

The response includes a list of balance types per wallet.
For Pectra, stakedBalance will include rewards that auto‑compound.

{
  "data": {
    "walletId": "3d293c0d64c703023692216e9b4f5280",
    "walletName": "Bitcoin Mainnet - Wallet 1",
    "depositAddress": {
      "address": "2N19AcihQ1a4MxQW658UFHTioUNnMkiHPkw",
      "addressId": "a33f83d96ca95cac000a344aa478a8b8",
      "addressSignaturePayload": "7b225465787441646472657373223a22324e313941636968513161344d78515736353855464854696f554e6e4d6b6948506b77227d",
      "signature": "1642000aa9cca8e8610981aefbdb204b361c9dca3fa067b88fdacfba7a0f620d721378a33f4bbadad3923e633a4d712646d1e8e314e9fcb4aa4102c0581f6503"
    },
    "assets": [
      {
        "assetType": "BTC",
        "availableBalance": {
          "quantity": "10.00000000",
          "assetType": "BTC",
          "currentPrice": "9751.01",
          "currentUSDValue": "97510.1"
        },
        "totalBalance": {
          "quantity": "10.45234733",
          "assetType": "BTC",
          "currentPrice": "9751.01",
          "currentUSDValue": "101920.94"
        },
        "stakedBalance": {
          "quantity": "32.00000000",
          "assetType": "BTC",
          "currentPrice": "9751.01",
          "currentUSDValue": "312032.32"
        },
        "unclaimedBalance": {
          "quantity": "0",
          "assetType": "BTC",
          "currentPrice": "9751.01",
          "currentUSDValue": "0"
        }
      }
    ],
    "vaultId": "1c920f4241b78a1d483a29f3c24b6c4c",
    "vaultName": "Long Hold Vault",
    "isDefault": true,
    "isArchived": false,
    "networkId": "BTC",
    "type": "WALLET"
  }
}

Get staking positions

This endpoint retrieves the staking positions (stake accounts) associated with a wallet. Endpoint Staking positions for a wallet

Expected behavior

The response includes validator positions and the amount staked for each position

Common pitfalls

Do not include validatorType and stakingProvider when adding stake to an existing position.
Ensure you include stakingPositionId when adding stake or unstaking from a specific position.
Ensure validator total does not exceed 2048 ETH after adding stake.

​Overview

​Key concepts

​Relevant endpoints

​Workflows

​Stake (provision or add stake)

​When to use which fields

​Request body additions

​Example: Provision a new Pectra validator

​Example: Add stake to an existing staking position

​Response

​Unstake (partial or full)

​Request rules

​Example: Partial unstake

​Response

​Consolidate to Pectra validator

​List transactions

​Rewards behavior

​List wallet balances

​Expected behavior

​Get staking positions

​Expected behavior

​Common pitfalls

Overview

Key concepts

Relevant endpoints

Workflows

Stake (provision or add stake)

When to use which fields

Request body additions

Example: Provision a new Pectra validator

Example: Add stake to an existing staking position

Response

Unstake (partial or full)

Request rules

Example: Partial unstake

Response

Consolidate to Pectra validator

List transactions

Rewards behavior

List wallet balances

Expected behavior

Get staking positions

Expected behavior

Common pitfalls