Ctrlk
Quick LinksPlatform
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Bitcoin Staking

Endpoints for retrieving STX-staking positions, bonds, and registered staking signers.

Endpoints for retrieving STX-staking positions, bonds, and registered staking signers.

Get a staking summary for a principal.

get
/extended/v3/principals/{principal}/staking

One-call summary for a principal: STX-staking position plus bond aggregate.

Path parameters
principalstringRequired

Stacks address (standard or contract principal).

Responses
200

Staking summary for the principal

application/json
get/extended/v3/principals/{principal}/staking
GET /extended/v3/principals/{principal}/staking HTTP/1.1
Host: api.private-1.hiro.so
Accept: */*
200

Staking summary for the principal

{
  "stx": {
    "locked": "0",
    "rewards": {
      "btc": {
        "accrued": "0",
        "claimed": "0",
        "claimable": "0"
      }
    }
  },
  "bonds": {
    "count": 1,
    "locked": {
      "btc": "50000000",
      "stx": "25000000"
    },
    "rewards": {
      "btc": {
        "accrued": "244960",
        "claimed": "0",
        "claimable": "244960"
      }
    }
  }
}

Get the bond positions for a principal.

get
/extended/v3/principals/{principal}/staking/bonds

The principal's bond positions, cursor-paginated.

Path parameters
principalstringRequired

Stacks address (standard or contract principal).

Query parameters
cursorstringOptional

Opaque cursor for the next page of results.

limitintegerOptional

Maximum number of results to return.

Default: 20
Responses
200

Cursor-paginated list of the principal's bond positions

application/json
totalintegerRequired
limitintegerRequired
get/extended/v3/principals/{principal}/staking/bonds
GET /extended/v3/principals/{principal}/staking/bonds HTTP/1.1
Host: api.private-1.hiro.so
Accept: */*
200

Cursor-paginated list of the principal's bond positions

{
  "total": 1,
  "limit": 20,
  "cursor": {
    "next": null,
    "previous": null,
    "current": "10"
  },
  "results": [
    {
      "bond_index": 10,
      "status": "enrolled",
      "active": true,
      "enrollment": {
        "tx_id": "0x6e22054060fc271a96edf03dc4a6ca425a19bf0aba9d0e58ed7701490c95843b",
        "btc_lockup": {
          "amount": "50000000"
        }
      },
      "locked": {
        "btc": "50000000",
        "stx": "25000000"
      },
      "rewards": {
        "btc": {
          "accrued": "333856",
          "claimed": "0",
          "claimable": "333856"
        }
      }
    }
  ]
}

List bonds.

get
/extended/v3/staking/bonds

List of bonds, cursor-paginated.

Query parameters
cursorstringOptional

Opaque cursor for the next page of results.

limitintegerOptional

Maximum number of results to return.

Default: 20
Responses
200

Cursor-paginated list of bonds

application/json
totalintegerRequired
limitintegerRequired
get/extended/v3/staking/bonds
GET /extended/v3/staking/bonds HTTP/1.1
Host: api.private-1.hiro.so
Accept: */*
200

Cursor-paginated list of bonds

{
  "total": 12,
  "limit": 20,
  "cursor": {
    "next": null,
    "previous": null,
    "current": "11"
  },
  "results": [
    {
      "index": 11,
      "pox_version": "pox5",
      "status": "upcoming",
      "parameters": {
        "target_rate_bps": 1000,
        "stx_value_ratio": 1000,
        "minimum_stx_ratio": 500,
        "btc_capacity": "6491000000"
      },
      "registrations": {
        "allowed_count": 15,
        "registered_count": 0
      },
      "schedule": {
        "activation": {
          "bitcoin_height": 660,
          "pox_cycle": 33
        },
        "unlock": {
          "bitcoin_height": 900,
          "pox_cycle": 45
        }
      },
      "balances": {
        "locked": {
          "btc": "0",
          "stx": "0"
        },
        "paid_out": {
          "btc": "0"
        }
      }
    },
    {
      "index": 10,
      "pox_version": "pox5",
      "status": "active",
      "parameters": {
        "target_rate_bps": 1000,
        "stx_value_ratio": 1000,
        "minimum_stx_ratio": 500,
        "btc_capacity": "50000000"
      },
      "registrations": {
        "allowed_count": 1,
        "registered_count": 1
      },
      "schedule": {
        "activation": {
          "bitcoin_height": 620,
          "pox_cycle": 31
        },
        "unlock": {
          "bitcoin_height": 860,
          "pox_cycle": 43
        }
      },
      "balances": {
        "locked": {
          "btc": "50000000",
          "stx": "25000000"
        },
        "paid_out": {
          "btc": "0"
        }
      }
    }
  ]
}

Get bond detail.

get
/extended/v3/staking/bonds/{bond_index}

Bond detail for a given bond index, including the registering transaction and Bitcoin block position.

Path parameters
bond_indexintegerRequired

Bond index.

Responses
200

Bond detail

application/json
indexintegerOptional
pox_versionstringOptional
statusstring · enumOptionalPossible values:
get/extended/v3/staking/bonds/{bond_index}
GET /extended/v3/staking/bonds/{bond_index} HTTP/1.1
Host: api.private-1.hiro.so
Accept: */*

{
  "index": 10,
  "pox_version": "pox5",
  "status": "active",
  "parameters": {
    "target_rate_bps": 1000,
    "stx_value_ratio": 1000,
    "minimum_stx_ratio": 500,
    "btc_capacity": "50000000"
  },
  "registrations": {
    "allowed_count": 1,
    "registered_count": 1
  },
  "schedule": {
    "activation": {
      "bitcoin_height": 620,
      "pox_cycle": 31
    },
    "unlock": {
      "bitcoin_height": 860,
      "pox_cycle": 43
    }
  },
  "balances": {
    "locked": {
      "btc": "50000000",
      "stx": "25000000"
    },
    "paid_out": {
      "btc": "0"
    }
  },
  "transaction": {
    "tx_id": "0xb054c06595f6f41fecbc9230ba0443a28713b1c4f94f639cf8da3b797bd5269c",
    "block": {
      "height": 13669,
      "hash": "0x110e51dd809ef8afc1d6d944fd3119706d4ce6bc7b9fda5a665a1ebfd5e75eb7",
      "index_hash": "0x1a93a2a720997c81a412111a131fac1c997b47f9c536c641d6a4c98c00ef31c6",
      "time": 1781803716,
      "tx_index": 1
    },
    "bitcoin_block": {
      "height": 629,
      "time": 1781803667
    }
  }
}

List allowlist entries for a bond.

get
/extended/v3/staking/bonds/{bond_index}/allowlist

Allowlist entries for a given bond, cursor-paginated.

Path parameters
bond_indexintegerRequired

Bond index.

Query parameters
cursorstringOptional
limitintegerOptionalDefault: 20
Responses
200

Cursor-paginated list of allowlist entries

application/json
totalintegerRequired
limitintegerRequired
get/extended/v3/staking/bonds/{bond_index}/allowlist
GET /extended/v3/staking/bonds/{bond_index}/allowlist HTTP/1.1
Host: api.private-1.hiro.so
Accept: */*
200

Cursor-paginated list of allowlist entries

{
  "total": 1,
  "limit": 20,
  "cursor": {
    "next": null,
    "previous": null,
    "current": "13669:2147483647:1"
  },
  "results": [
    {
      "staker": "ST1MV5EGTM2NSPF3MSZ2SMYRXJJH1GG6CEMP9N117",
      "max_sats": "50000000"
    }
  ]
}

Get a single allowlist entry.

get
/extended/v3/staking/bonds/{bond_index}/allowlist/{principal}

Single allowlist entry for a principal on a given bond.

Path parameters
bond_indexintegerRequired

Bond index.

principalstringRequired

Stacks address (standard or contract principal).

Responses
200

Allowlist entry

application/json
stakerstringOptional
max_satsstringOptional

Maximum BTC the staker may lock (sats).

get/extended/v3/staking/bonds/{bond_index}/allowlist/{principal}
GET /extended/v3/staking/bonds/{bond_index}/allowlist/{principal} HTTP/1.1
Host: api.private-1.hiro.so
Accept: */*

{
  "staker": "ST1MV5EGTM2NSPF3MSZ2SMYRXJJH1GG6CEMP9N117",
  "max_sats": "50000000"
}

List registrations for a bond.

get
/extended/v3/staking/bonds/{bond_index}/registrations

Registrations for a given bond, cursor-paginated.

Path parameters
bond_indexintegerRequired

Bond index.

Query parameters
cursorstringOptional
limitintegerOptionalDefault: 20
Responses
200

Cursor-paginated list of registrations

application/json
totalintegerRequired
limitintegerRequired
get/extended/v3/staking/bonds/{bond_index}/registrations
GET /extended/v3/staking/bonds/{bond_index}/registrations HTTP/1.1
Host: api.private-1.hiro.so
Accept: */*
200

Cursor-paginated list of registrations

{
  "total": 1,
  "limit": 20,
  "cursor": {
    "next": null,
    "previous": null,
    "current": "14361:2147483647:1"
  },
  "results": [
    {
      "staker": "ST1MV5EGTM2NSPF3MSZ2SMYRXJJH1GG6CEMP9N117",
      "signer": "ST3NBRSFKX28FQ2ZJ1MAKX58HKHSDGNV5N7R21XCP.signer-manager",
      "type": "l1",
      "balances": {
        "btc": "50000000",
        "stx": "25000000"
      }
    }
  ]
}

Get a single registration.

get
/extended/v3/staking/bonds/{bond_index}/registrations/{principal}

Single registration for a principal on a given bond, including L1 lockup transactions.

Path parameters
bond_indexintegerRequired

Bond index.

principalstringRequired

Stacks address (standard or contract principal).

Responses
200

Registration

application/json
stakerstringOptional
signerstringOptional
typestringOptional
get/extended/v3/staking/bonds/{bond_index}/registrations/{principal}
GET /extended/v3/staking/bonds/{bond_index}/registrations/{principal} HTTP/1.1
Host: api.private-1.hiro.so
Accept: */*

{
  "staker": "ST1MV5EGTM2NSPF3MSZ2SMYRXJJH1GG6CEMP9N117",
  "signer": "ST3NBRSFKX28FQ2ZJ1MAKX58HKHSDGNV5N7R21XCP.signer-manager",
  "type": "l1",
  "balances": {
    "btc": "50000000",
    "stx": "25000000"
  },
  "l1_lockup": {
    "transactions": [
      {
        "tx_id": "0xc67223b01f1dc85ad258534186a309b4112048dfcd63be83cbc99ec31f431c5e",
        "output_index": 0
      }
    ]
  }
}

List registered staking signers.

get
/extended/v3/staking/signers

Registered signers, cursor-paginated.

Query parameters
cursorstringOptional
limitintegerOptionalDefault: 100
Responses
200

Cursor-paginated list of registered signers

application/json
totalintegerRequired
limitintegerRequired
get/extended/v3/staking/signers
GET /extended/v3/staking/signers HTTP/1.1
Host: api.private-1.hiro.so
Accept: */*
200

Cursor-paginated list of registered signers

{
  "total": 3,
  "limit": 100,
  "cursor": {
    "next": null,
    "previous": null,
    "current": "ST3AM1A56AK2C1XAFJ4115ZSV26EB49BVQ10MGCS0.signer-manager"
  },
  "results": [
    {
      "signer": "ST3AM1A56AK2C1XAFJ4115ZSV26EB49BVQ10MGCS0.signer-manager",
      "signer_key": "0x028efa20fa5706567008ebaf48f7ae891342eeb944d96392f719c505c89f84ed8d"
    },
    {
      "signer": "ST3NBRSFKX28FQ2ZJ1MAKX58HKHSDGNV5N7R21XCP.signer-manager",
      "signer_key": "0x029fb154a570a1645af3dd43c3c668a979b59d21a46dd717fd799b13be3b2a0dc7"
    },
    {
      "signer": "ST3PF13W7Z0RRM42A8VZRVFQ75SV1K26RXEP8YGKJ.signer-manager",
      "signer_key": "0x023f19d77c842b675bd8c858e9ac8b0ca2efa566f17accf8ef9ceb5a992dc67836"
    }
  ]
}

Get a registered staking signer.

get
/extended/v3/staking/signers/{principal}

Signer plus registration transaction block position (Stacks block and Bitcoin block).

Path parameters
principalstringRequired

Signer principal (standard or contract principal).

Responses
200

Signer with registration tx block position

application/json
signerstringOptional
signer_keystringOptional

Hex-encoded compressed Secp256k1 public key (33 bytes).

get/extended/v3/staking/signers/{principal}
GET /extended/v3/staking/signers/{principal} HTTP/1.1
Host: api.private-1.hiro.so
Accept: */*

{
  "signer": "ST3NBRSFKX28FQ2ZJ1MAKX58HKHSDGNV5N7R21XCP.signer-manager",
  "signer_key": "0x029fb154a570a1645af3dd43c3c668a979b59d21a46dd717fd799b13be3b2a0dc7",
  "transaction": {
    "tx_id": "0xc6187fb9f855f0ab567aea886c8924ca2591c7db0a43dc3e17903514d77481e4",
    "block": {
      "height": 288,
      "hash": "0x02895a0cb41d5eded36865c80774f8f5dc2d0453bb89929ef9e18d48fa7ac045",
      "index_hash": "0xc55c2f28053f317f512a9d1d4b35197c1a114dc91fd69db8b69cc118b4976eb7",
      "time": 1781758251,
      "tx_index": 0
    },
    "bitcoin_block": {
      "height": 202,
      "time": 1781758236
    }
  }
}
PreviousModels
NextStacks Mesh API

Last updated

Was this helpful?