Skip to main content

​
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



​
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

​
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.