From c14c899a4d98ee6f24528c95d8f59d31bb36b230 Mon Sep 17 00:00:00 2001 From: Rafa Cardenas <253999660+rafa-stacks@users.noreply.github.com> Date: Wed, 19 Aug 2026 15:15:56 -0600 Subject: [PATCH 1/3] start v3 page --- .../en/apis/stacks-blockchain-api/meta.json | 1 + .../v1-to-v3-migration.mdx | 323 ++++++++++++++++++ 2 files changed, 324 insertions(+) create mode 100644 content/docs/en/apis/stacks-blockchain-api/v1-to-v3-migration.mdx diff --git a/content/docs/en/apis/stacks-blockchain-api/meta.json b/content/docs/en/apis/stacks-blockchain-api/meta.json index 1233034b6..854684f89 100644 --- a/content/docs/en/apis/stacks-blockchain-api/meta.json +++ b/content/docs/en/apis/stacks-blockchain-api/meta.json @@ -7,6 +7,7 @@ "usage", "architecture", "pagination", + "v1-to-v3-migration", "none-handling", "websockets", "---Reference---", diff --git a/content/docs/en/apis/stacks-blockchain-api/v1-to-v3-migration.mdx b/content/docs/en/apis/stacks-blockchain-api/v1-to-v3-migration.mdx new file mode 100644 index 000000000..9aa42e4f1 --- /dev/null +++ b/content/docs/en/apis/stacks-blockchain-api/v1-to-v3-migration.mdx @@ -0,0 +1,323 @@ +--- +title: Migrating from v1 to v3 +sidebarTitle: v1 to v3 migration +description: Map every deprecated /extended/v1 endpoint to its /extended/v3 replacement. +--- + +## Overview + +Most `/extended/v1` endpoints are now deprecated in favor of `/extended/v3`. The v3 API is a +redesign, not a rename: it uses cursor-based pagination, splits large "kitchen sink" responses +into focused resources, and nests related fields into objects instead of flattening them into +prefixed keys. + +Deprecated endpoints still work today. Every response from one carries a `Warning` header: + +``` +Warning: 299 - "Deprecated: See https://docs.hiro.so/stacks/api for more information" +``` + +At the sunset date, deprecated endpoints stop executing and return `410 Gone` instead. Migrate +before then. + +## What changed in v3 + +Before mapping endpoints one by one, these are the cross-cutting changes you will hit on almost +every route. + +### Cursor pagination replaces offsets + +v1 list endpoints take `limit` and `offset` and return `{ limit, offset, total, results }`. v3 +list endpoints take `limit` and `cursor`, and return `{ limit, total, cursor: { next, previous, +current }, results }`. See [Pagination](/en/apis/stacks-blockchain-api/pagination) for the full +walkthrough. + +The practical consequence: you cannot jump to an arbitrary page. Walk the list with +`cursor.next` until it is `null`. + +### Summaries by default, details on request + +v3 list endpoints return a *summary* of each object (the fields most callers need) rather than +the full record. The single-resource endpoints return the full record, and the heavy fields are +opt-in via `?include=`: + +```terminal +$ curl 'https://api.hiro.so/extended/v3/transactions/{tx_id}?include=function_args,post_conditions,result,source_code' +``` + +Available `include` values on `GET /extended/v3/transactions/{tx_id}`: `function_args`, +`source_code`, `post_conditions`, `result`. They may be repeated (`?include=a&include=b`) or +comma-separated (`?include=a,b`). + +This replaces the v1 `exclude_function_args` pattern, inverted: v1 sent everything unless you +opted out, v3 sends the lean payload unless you opt in. + +### Nested objects replace prefixed fields + +v1 flattened everything into the top level (`block_height`, `burn_block_time`, +`execution_cost_runtime`, `pending_balance_inbound`). v3 groups them (`block.height`, +`bitcoin_block.time`, `execution_cost.runtime`, `mempool.inbound`). + +### Microblock and unanchored fields are gone + +Microblocks were removed in the Nakamoto upgrade. v3 has no `microblock_hash`, +`microblock_sequence`, `microblock_canonical`, `is_unanchored`, or `unanchored` query parameter. +There is also no `canonical` field. v3 only returns canonical data. + +### ISO timestamp duplicates are gone + +v1 returned both `burn_block_time` and `burn_block_time_iso`. v3 returns Unix seconds only +(`block.time`, `bitcoin_block.time`). Format them client-side. + +:::callout +type: warn +### v3 list endpoints do not support filtering yet +`GET /extended/v1/tx` accepts `type`, `from_address`, `to_address`, `contract_id`, +`function_name`, `nonce`, `start_time`, `end_time`, `sort_by`, and `order`. +`GET /extended/v3/transactions` accepts only `limit` and `cursor`. The same applies to the +mempool endpoints (`sender_address`, `recipient_address`, `address`, `order_by` are not +available in v3). If you depend on server-side filtering, keep using the v1 endpoint until a +v3 equivalent ships, and filter client-side where you can. +::: + +## Transactions + +| Deprecated v1 endpoint | v3 replacement | +| --- | --- | +| `GET /extended/v1/tx` | `GET /extended/v3/transactions` | +| `GET /extended/v1/tx/{tx_id}` | `GET /extended/v3/transactions/{tx_id}` | +| `GET /extended/v1/tx/{tx_id}/raw` | Stacks node RPC `GET /v3/transaction/{tx_id}` | +| `GET /extended/v1/tx/mempool` | `GET /extended/v3/mempool/transactions` | +| `GET /extended/v1/tx/block/{block_hash}` | `GET /extended/v3/blocks/{height_or_hash}/transactions` | +| `GET /extended/v1/tx/block_height/{height}` | `GET /extended/v3/blocks/{height_or_hash}/transactions` | +| `GET /extended/v1/tx/events` | No direct replacement — see [Endpoints without a v3 replacement](#endpoints-without-a-v3-replacement) | + +The two v1 "transactions in a block" endpoints collapse into one: `{height_or_hash}` accepts a +block height, a block hash, or the literal `latest`. + +### Transaction field mapping + +| v1 field | v3 field | +| --- | --- | +| `tx_type` | `type` | +| `tx_status` | `status` | +| `tx_result` | `result` (only with `?include=result`) | +| `sender_address` | `sender.address` | +| `nonce` | `sender.nonce` | +| `sponsor_address` / `sponsor_nonce` | `sponsor.address` / `sponsor.nonce` (`sponsor` is `null` when unsponsored) | +| `sponsored` | Removed — check `sponsor !== null` | +| `block_hash` | `block.hash` | +| `block_height` | `block.height` | +| `block_time` | `block.time` | +| `tx_index` | `block.tx_index` | +| `parent_block_hash` | `parent_block.hash` (single-transaction endpoint only) | +| `burn_block_height` | `bitcoin_block.height` | +| `burn_block_time` | `bitcoin_block.time` | +| `block_time_iso`, `burn_block_time_iso` | Removed — derive from the Unix timestamps | +| `execution_cost_read_count` (and siblings) | `execution_cost.read_count` (and siblings) | +| `contract_call.function_args` | Same path, only with `?include=function_args` | +| `smart_contract.source_code` | Same path, only with `?include=source_code` | +| `post_conditions` | Same field, only with `?include=post_conditions` | +| `post_condition_mode`, `anchor_mode` | Removed | +| `canonical`, `is_unanchored`, `microblock_*` | Removed | +| — | `block.index_hash` (new) | +| — | `vm_error` (new) | + +`status` gained a `problematic_skipped` value in Epoch 4.0 alongside `success`, +`abort_by_response`, and `abort_by_post_condition`. + +Mempool transactions use `receipt_time` and `receipt_block_height` in place of block fields, and +their `status` is one of `pending` or the `dropped_*` values. + +## Accounts and principals + +The v1 "address" resource is the v3 "principal" resource. + +| Deprecated v1 endpoint | v3 replacement | +| --- | --- | +| `GET /extended/v1/address/{principal}/stx` | `GET /extended/v3/principals/{principal}/balances/stx` | +| `GET /extended/v1/address/{principal}/balances` | Split across `/balances/stx`, `/balances/ft`, and `/balances/nft` | +| `GET /extended/v1/address/{principal}/transactions` | `GET /extended/v3/principals/{principal}/transactions` | +| `GET /extended/v1/address/{principal}/transactions_with_transfers` | `GET /extended/v3/principals/{principal}/transactions` | +| `GET /extended/v1/address/{principal}/{tx_id}/with_transfers` | `GET /extended/v3/principals/{principal}/transactions/{tx_id}/balance-changes` | +| `GET /extended/v1/address/{principal}/mempool` | `GET /extended/v3/principals/{principal}/mempool/transactions` | +| `GET /extended/v1/address/{principal}/nonces` | `GET /extended/v3/principals/{principal}/nonces` | +| `GET /extended/v1/address/{principal}/assets` | No direct replacement — closest is `GET /extended/v3/principals/{principal}/balance-changes` | +| `GET /extended/v1/address/{principal}/stx_inbound` | No direct replacement | +| `GET /extended/v1/tokens/nft/holdings?principal=` | `GET /extended/v3/principals/{principal}/balances/nft` | + +### STX balance field mapping + +`GET /extended/v1/address/{principal}/stx` → `GET /extended/v3/principals/{principal}/balances/stx` + +| v1 field | v3 field | +| --- | --- | +| `balance` | `balance` | +| — | `available` (new — `balance` minus locked STX) | +| `locked` | `locked.amount` (`locked` is `null` when nothing is locked) | +| `lock_tx_id` | `locked.lock_tx_id` | +| `lock_height` | `locked.stacks_lock_height` | +| `burnchain_lock_height` | `locked.burn_lock_height` | +| `burnchain_unlock_height` | `locked.burn_unlock_height` | +| — | `locked.pox_version` (new) | +| `estimated_balance` | `mempool.estimated_balance` (`mempool` is `null` when nothing is pending) | +| `pending_balance_inbound` | `mempool.inbound` | +| `pending_balance_outbound` | `mempool.outbound` | +| `total_sent`, `total_received`, `total_fees_sent`, `total_miner_rewards_received` | Removed | +| `token_offering_locked` | Removed | + +:::callout +type: warn +### `estimated_balance` changed meaning +In v1, `estimated_balance` was the **total** balance plus the pending mempool delta. In v3, +`mempool.estimated_balance` is the **available** (spendable) balance plus the pending delta, so +locked STX is excluded. If you were subtracting `locked` yourself, stop. +::: + +v1 accepted `until_block` and `unanchored` on the balance endpoints. v3 always reports the +current chain tip. + +### FT and NFT balances + +`GET /extended/v1/address/{principal}/balances` returned FT and NFT balances as objects keyed by +asset identifier, with the NFT entry being a count. v3 returns cursor-paginated arrays instead: + +- `GET /extended/v3/principals/{principal}/balances/ft` — `{ asset_identifier, balance }` per + token, sorted by balance descending. +- `GET /extended/v3/principals/{principal}/balances/ft/{asset_identifier}` — a single token's + balance; returns zero rather than 404 when the principal does not hold it. +- `GET /extended/v3/principals/{principal}/balances/nft` — one entry per owned NFT *instance*, + `{ asset_identifier, value: { hex, repr } }`, not a per-collection count. + +The v1 `total_sent` / `total_received` counters on each token are not carried over. + +### Nonce field mapping + +`GET /extended/v1/address/{principal}/nonces` → `GET /extended/v3/principals/{principal}/nonces` + +| v1 field | v3 field | +| --- | --- | +| `possible_next_nonce` | `next_nonce` | +| `last_executed_tx_nonce` | `last_confirmed_nonce` | +| `last_mempool_tx_nonce` | `mempool.last_nonce` | +| `detected_mempool_nonces` | `mempool.pending_nonces` | +| `detected_missing_nonces` | `mempool.missing_nonces` | + +The v1 endpoint accepted `block_height` and `block_hash` to read the nonce at a past block. v3 +only reports current nonce state. + +### Account transactions and transfers + +v1 had three overlapping endpoints. v3 has two, with a cleaner split between "which transactions +touched this principal" and "what changed for this principal". + +`GET /extended/v3/principals/{principal}/transactions` returns, per transaction: + +- `transaction` — the transaction summary (same shape as `GET /extended/v3/transactions`). +- `involvement` — `sender`, `sponsor`, or `affected`. +- `balance_changes.stx` — `{ sent, received, net }` in micro-STX, fee included in `sent`. +- `affected_balances` — `{ stx, ft, nft }` booleans telling you whether it is worth fetching the + detailed balance changes. + +For the FT and NFT detail that v1 packed into `stx_transfers` / `ft_transfers` / `nft_transfers`, +call `GET /extended/v3/principals/{principal}/transactions/{tx_id}/balance-changes`, or fetch +several transactions at once with +`GET /extended/v3/principals/{principal}/balance-changes?tx_id=A,B,C` (up to 50 IDs). + +Each balance change is `{ asset: { type, identifier? }, balance_change: { sent, received, net } }`, +where `type` is `stx`, `ft`, or `nft`. + +## Blocks + +Blocks did not move to v3 — only the *transactions in a block* did. The v1 block endpoints are +superseded by v2. + +| Deprecated v1 endpoint | Replacement | +| --- | --- | +| `GET /extended/v1/block` | `GET /extended/v2/blocks` | +| `GET /extended/v1/block/{hash}` | `GET /extended/v2/blocks/{height_or_hash}` | +| `GET /extended/v1/block/by_height/{height}` | `GET /extended/v2/blocks/{height_or_hash}` | +| `GET /extended/v1/block/by_burn_block_height/{burn_block_height}` | `GET /extended/v2/burn-blocks/{height_or_hash}/blocks` | +| `GET /extended/v1/block/by_burn_block_hash/{burn_block_hash}` | `GET /extended/v2/burn-blocks/{height_or_hash}/blocks` | + +The v1 block responses embedded a `txs` array of transaction IDs. In v2 the block object carries +a `tx_count`; fetch the transactions from +`GET /extended/v3/blocks/{height_or_hash}/transactions`. + +## Smart contracts + +| Deprecated v1 endpoint | Replacement | +| --- | --- | +| `GET /extended/v1/contract/{contract_id}/events` | `GET /extended/v2/smart-contracts/{contract_id}/logs` | + +## Fees + +| Deprecated v1 endpoint | Replacement | +| --- | --- | +| `POST /extended/v1/fee_rate` | Stacks node RPC `POST /v2/fees/transaction` | + +## STX supply + +The plain-text and legacy-shaped variants are deprecated in favor of the single JSON endpoint, +which is **not** deprecated. + +| Deprecated v1 endpoint | Replacement | +| --- | --- | +| `GET /extended/v1/stx_supply/total/plain` | `GET /extended/v1/stx_supply` → `total_stx` | +| `GET /extended/v1/stx_supply/circulating/plain` | `GET /extended/v1/stx_supply` → `unlocked_stx` | +| `GET /extended/v1/stx_supply/legacy_format` | `GET /extended/v1/stx_supply` | + +## Endpoints without a v3 replacement + +These are deprecated with no successor. Plan around them rather than swapping a URL. + +| Deprecated endpoint | Notes | +| --- | --- | +| `GET /extended/v1/tx/events` | Global event feed filtered by principal, transaction, or event type. Per-transaction events are available at `GET /extended/v3/transactions/{tx_id}/events`, and per-principal asset movement at `GET /extended/v3/principals/{principal}/balance-changes`. | +| `GET /extended/v1/address/{principal}/assets` | Closest equivalent is `GET /extended/v3/principals/{principal}/balance-changes`, which reports net balance deltas rather than raw asset events. | +| `GET /extended/v1/address/{principal}/stx_inbound` | Inbound STX transfers with memos, including `send-many-memo` bulk sends. No v3 equivalent. | +| `GET /extended/v1/microblock` | Microblocks were removed in the Nakamoto upgrade and are no longer produced. | +| `GET /extended/v1/microblock/{hash}` | Same. | +| `GET /extended/v1/microblock/unanchored/txs` | Same. | +| `GET /extended/v1/faucets/btc/{address}` | Testnet-only BTC balance helper. No replacement. | + +## Also deprecated: v2 endpoints + +A handful of `/extended/v2` routes are deprecated alongside v1 and move to v3. If you already +migrated from v1 to v2, these are your next hop. + +| Deprecated v2 endpoint | v3 replacement | +| --- | --- | +| `GET /extended/v2/addresses/{address}/transactions` | `GET /extended/v3/principals/{principal}/transactions` | +| `GET /extended/v2/addresses/{address}/transactions/{tx_id}/events` | `GET /extended/v3/principals/{principal}/transactions/{tx_id}/balance-changes` | +| `GET /extended/v2/addresses/{principal}/balances/stx` | `GET /extended/v3/principals/{principal}/balances/stx` | +| `GET /extended/v2/addresses/{principal}/balances/ft` | `GET /extended/v3/principals/{principal}/balances/ft` | +| `GET /extended/v2/addresses/{principal}/balances/ft/{token}` | `GET /extended/v3/principals/{principal}/balances/ft/{asset_identifier}` | +| `GET /extended/v2/blocks/{height_or_hash}/transactions` | `GET /extended/v3/blocks/{height_or_hash}/transactions` | + +## Endpoints that are not deprecated + +Not everything under `/extended/v1` is going away. These remain the supported way to fetch their +data today: + +- **Transactions** — `GET /extended/v1/tx/multiple`, `GET /extended/v1/tx/mempool/stats` +- **Smart contracts** — `GET /extended/v1/contract/by_trait`, + `GET /extended/v1/contract/{contract_id}` +- **Tokens** — `GET /extended/v1/tokens/nft/history`, `GET /extended/v1/tokens/nft/mints`, + `GET /extended/v1/tokens/ft/{token}/holders` +- **Info** — `GET /extended/v1/stx_supply`, `GET /extended/v1/info/network_block_times`, + `GET /extended/v1/info/network_block_time/{network}` +- **Burnchain** — `GET /extended/v1/burnchain/reward_slot_holders`, + `GET /extended/v1/burnchain/rewards` (and their per-address variants) +- **Stacking** — the `GET /extended/v1/pox4/*` family +- **Search** — `GET /extended/v1/search/{id}` +- **BNS** — the `GET /v1/names/*`, `GET /v1/namespaces/*`, `GET /v1/addresses/*`, and + `GET /v2/prices/*` families +- **Status** — `GET /extended` + +:::callout +type: help +### Need help migrating? +Reach out on the #api channel on [Discord](https://stacks.chat/) +under the Hiro Developer Tools section. +::: From 82feea37098704fac1c3219f69aecdb6b636e258 Mon Sep 17 00:00:00 2001 From: Rafa Cardenas <253999660+rafa-stacks@users.noreply.github.com> Date: Wed, 19 Aug 2026 15:34:41 -0600 Subject: [PATCH 2/3] fix mapping --- .../v1-to-v3-migration.mdx | 20 +++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/content/docs/en/apis/stacks-blockchain-api/v1-to-v3-migration.mdx b/content/docs/en/apis/stacks-blockchain-api/v1-to-v3-migration.mdx index 9aa42e4f1..98dd0bf25 100644 --- a/content/docs/en/apis/stacks-blockchain-api/v1-to-v3-migration.mdx +++ b/content/docs/en/apis/stacks-blockchain-api/v1-to-v3-migration.mdx @@ -104,7 +104,8 @@ block height, a block hash, or the literal `latest`. | `tx_result` | `result` (only with `?include=result`) | | `sender_address` | `sender.address` | | `nonce` | `sender.nonce` | -| `sponsor_address` / `sponsor_nonce` | `sponsor.address` / `sponsor.nonce` (`sponsor` is `null` when unsponsored) | +| `sponsor_address` | `sponsor.address` (`sponsor` is `null` when unsponsored) | +| `sponsor_nonce` | `sponsor.nonce` (`sponsor` is `null` when unsponsored) | | `sponsored` | Removed — check `sponsor !== null` | | `block_hash` | `block.hash` | | `block_height` | `block.height` | @@ -113,13 +114,17 @@ block height, a block hash, or the literal `latest`. | `parent_block_hash` | `parent_block.hash` (single-transaction endpoint only) | | `burn_block_height` | `bitcoin_block.height` | | `burn_block_time` | `bitcoin_block.time` | -| `block_time_iso`, `burn_block_time_iso` | Removed — derive from the Unix timestamps | -| `execution_cost_read_count` (and siblings) | `execution_cost.read_count` (and siblings) | +| `block_time_iso` | Removed — derive from `block.time` | +| `burn_block_time_iso` | Removed — derive from `bitcoin_block.time` | +| `execution_cost_*` | `execution_cost.*` — e.g. `execution_cost_runtime` becomes `execution_cost.runtime` | | `contract_call.function_args` | Same path, only with `?include=function_args` | | `smart_contract.source_code` | Same path, only with `?include=source_code` | | `post_conditions` | Same field, only with `?include=post_conditions` | -| `post_condition_mode`, `anchor_mode` | Removed | -| `canonical`, `is_unanchored`, `microblock_*` | Removed | +| `post_condition_mode` | Removed | +| `anchor_mode` | Removed | +| `canonical` | Removed — v3 only returns canonical data | +| `is_unanchored` | Removed | +| `microblock_*` | Removed — microblocks no longer exist | | — | `block.index_hash` (new) | | — | `vm_error` (new) | @@ -163,7 +168,10 @@ The v1 "address" resource is the v3 "principal" resource. | `estimated_balance` | `mempool.estimated_balance` (`mempool` is `null` when nothing is pending) | | `pending_balance_inbound` | `mempool.inbound` | | `pending_balance_outbound` | `mempool.outbound` | -| `total_sent`, `total_received`, `total_fees_sent`, `total_miner_rewards_received` | Removed | +| `total_sent` | Removed | +| `total_received` | Removed | +| `total_fees_sent` | Removed | +| `total_miner_rewards_received` | Removed | | `token_offering_locked` | Removed | :::callout From 28ced1d69cbb0591abb9f5570abc2d663d2c06bf Mon Sep 17 00:00:00 2001 From: Rafa Cardenas <253999660+rafa-stacks@users.noreply.github.com> Date: Tue, 1 Sep 2026 13:20:15 -0600 Subject: [PATCH 3/3] update v3 docs and api reference --- .../reference/info/meta.json | 7 +- .../reference/info/network-block-time.mdx | 12 - .../info/network-given-block-time.mdx | 12 - .../info/total-and-unlocked-stx-supply.mdx | 12 - .../reference/names/historical-zonefile.mdx | 12 - .../reference/names/meta.json | 16 - .../reference/names/name-details.mdx | 12 - .../reference/names/name-price.mdx | 12 - .../reference/names/name-subdomains.mdx | 12 - .../reference/names/name-zonefile.mdx | 12 - .../reference/names/names.mdx | 12 - .../reference/names/namespace-names.mdx | 12 - .../reference/names/namespace-price.mdx | 12 - .../reference/names/namespaces.mdx | 12 - .../reference/names/owned-by-address.mdx | 12 - .../reference/non-fungible-tokens/history.mdx | 12 - .../reference/non-fungible-tokens/meta.json | 7 - .../reference/non-fungible-tokens/mints.mdx | 12 - .../reference/smart-contracts/by-trait.mdx | 12 - .../smart-contracts/get-smart-contract.mdx | 12 + .../reference/smart-contracts/info.mdx | 12 - .../reference/smart-contracts/meta.json | 7 +- .../reference/stacking-rewards/meta.json | 11 - .../recent-burnchain-reward-recipient.mdx | 12 - .../recent-burnchain-reward-recipients.mdx | 12 - .../recent-reward-slot-holder-entries.mdx | 12 - .../recent-reward-slot-holders.mdx | 12 - .../total-burnchain-rewards-for-recipient.mdx | 12 - .../reference/staking/get-cycle-signers.mdx | 12 + .../reference/staking/meta.json | 1 + .../reference/tokens/get-ft-total-supply.mdx | 12 + .../tokens/get-fungible-token-holders.mdx | 12 + .../tokens/get-nft-instance-history.mdx | 12 + .../reference/tokens/get-stx-holders.mdx | 12 + .../reference/tokens/get-stx-total-supply.mdx | 12 + .../reference/tokens/holders.mdx | 12 - .../reference/tokens/meta.json | 8 +- .../get-principal-ft-transfers.mdx | 12 + .../get-principal-inbound-stx-transfers.mdx | 12 + .../get-principal-outbound-stx-transfers.mdx | 12 + .../reference/transactions/meta.json | 3 + .../v1-to-v3-migration.mdx | 289 ++++++++++++++++-- 42 files changed, 397 insertions(+), 348 deletions(-) delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/info/network-block-time.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/info/network-given-block-time.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/info/total-and-unlocked-stx-supply.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/names/historical-zonefile.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/names/meta.json delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/names/name-details.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/names/name-price.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/names/name-subdomains.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/names/name-zonefile.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/names/names.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/names/namespace-names.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/names/namespace-price.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/names/namespaces.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/names/owned-by-address.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/non-fungible-tokens/history.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/non-fungible-tokens/meta.json delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/non-fungible-tokens/mints.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/smart-contracts/by-trait.mdx create mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/smart-contracts/get-smart-contract.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/smart-contracts/info.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/meta.json delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/recent-burnchain-reward-recipient.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/recent-burnchain-reward-recipients.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/recent-reward-slot-holder-entries.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/recent-reward-slot-holders.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/total-burnchain-rewards-for-recipient.mdx create mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/staking/get-cycle-signers.mdx create mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/tokens/get-ft-total-supply.mdx create mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/tokens/get-fungible-token-holders.mdx create mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/tokens/get-nft-instance-history.mdx create mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/tokens/get-stx-holders.mdx create mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/tokens/get-stx-total-supply.mdx delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/tokens/holders.mdx create mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/transactions/get-principal-ft-transfers.mdx create mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/transactions/get-principal-inbound-stx-transfers.mdx create mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/transactions/get-principal-outbound-stx-transfers.mdx diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/info/meta.json b/content/docs/en/apis/stacks-blockchain-api/reference/info/meta.json index a010230ef..0021087d5 100644 --- a/content/docs/en/apis/stacks-blockchain-api/reference/info/meta.json +++ b/content/docs/en/apis/stacks-blockchain-api/reference/info/meta.json @@ -1,10 +1,5 @@ { "title": "Info", - "pages": [ - "status", - "network-block-time", - "network-given-block-time", - "total-and-unlocked-stx-supply" - ], + "pages": ["status"], "defaultOpen": false } diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/info/network-block-time.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/info/network-block-time.mdx deleted file mode 100644 index d81134907..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/info/network-block-time.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get the network target block time -sidebarTitle: The network target block time -description: Retrieves the target block times for mainnet and testnet. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/info/network-given-block-time.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/info/network-given-block-time.mdx deleted file mode 100644 index c410f8842..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/info/network-given-block-time.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get a given network's target block time -sidebarTitle: A given network's target block time -description: Retrieves the target block time for a given network. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/info/total-and-unlocked-stx-supply.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/info/total-and-unlocked-stx-supply.mdx deleted file mode 100644 index 8e8be01aa..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/info/total-and-unlocked-stx-supply.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get total and unlocked STX supply -sidebarTitle: Total and unlocked STX supply -description: Retrieves the total and unlocked STX supply. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/names/historical-zonefile.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/names/historical-zonefile.mdx deleted file mode 100644 index 7ebe1ae4f..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/names/historical-zonefile.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get historical zone file -sidebarTitle: Historical zone file -description: Retrieves the historical zone file for a specific name. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/names/meta.json b/content/docs/en/apis/stacks-blockchain-api/reference/names/meta.json deleted file mode 100644 index 8c03640e4..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/names/meta.json +++ /dev/null @@ -1,16 +0,0 @@ -{ - "title": "Names", - "pages": [ - "namespaces", - "names", - "namespace-names", - "namespace-price", - "name-price", - "name-details", - "name-subdomains", - "name-zonefile", - "historical-zonefile", - "owned-by-address" - ], - "defaultOpen": false -} diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/names/name-details.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/names/name-details.mdx deleted file mode 100644 index 2f391f295..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/names/name-details.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get name details -sidebarTitle: Name details -description: Retrieves details of a given name including the address, status and last transaction ID. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/names/name-price.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/names/name-price.mdx deleted file mode 100644 index b9361e5bf..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/names/name-price.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get Name Price -sidebarTitle: Name Price -description: Retrieves the price of a name. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/names/name-subdomains.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/names/name-subdomains.mdx deleted file mode 100644 index f92217200..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/names/name-subdomains.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get name subdomains -sidebarTitle: Name subdomains -description: Retrieves the list of subdomains for a specific name. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/names/name-zonefile.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/names/name-zonefile.mdx deleted file mode 100644 index 40364f793..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/names/name-zonefile.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get name zone file -sidebarTitle: Name zone file -description: Retrieves the zone file for a specific name. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/names/names.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/names/names.mdx deleted file mode 100644 index 24a64c229..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/names/names.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get all names -sidebarTitle: All names -description: Retrieves a list of all names known to the node. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/names/namespace-names.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/names/namespace-names.mdx deleted file mode 100644 index a4c1c7a91..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/names/namespace-names.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get namespace names -sidebarTitle: Namespace names -description: Retrieves a list of names within a given namespace. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/names/namespace-price.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/names/namespace-price.mdx deleted file mode 100644 index 3bdf08129..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/names/namespace-price.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get Namespace Price -sidebarTitle: Namespace Price -description: Retrieves the price of a namespace. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/names/namespaces.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/names/namespaces.mdx deleted file mode 100644 index 91c2b530e..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/names/namespaces.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get all namespaces -sidebarTitle: All namespaces -description: Retrieves a list of all namespaces known to the node. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/names/owned-by-address.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/names/owned-by-address.mdx deleted file mode 100644 index 3d13ada3b..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/names/owned-by-address.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get names owned by address -sidebarTitle: Names owned by address -description: Retrieves the list of names owned by a specific address. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/non-fungible-tokens/history.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/non-fungible-tokens/history.mdx deleted file mode 100644 index 4e9c4f88f..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/non-fungible-tokens/history.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get non-fungible token history -sidebarTitle: Non-fungible token history -description: Retrieves the history of a non-fungible token. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/non-fungible-tokens/meta.json b/content/docs/en/apis/stacks-blockchain-api/reference/non-fungible-tokens/meta.json deleted file mode 100644 index 34ed16d93..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/non-fungible-tokens/meta.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "title": "Non-fungible tokens", - "pages": [ - "..." - ], - "defaultOpen": false -} diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/non-fungible-tokens/mints.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/non-fungible-tokens/mints.mdx deleted file mode 100644 index 49f8af4ec..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/non-fungible-tokens/mints.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get non-fungible token mints -sidebarTitle: Non-fungible token mints -description: Retrieves a list of non-fungible token mints for a given asset identifier. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/smart-contracts/by-trait.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/smart-contracts/by-trait.mdx deleted file mode 100644 index 19cffbc4b..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/smart-contracts/by-trait.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get contracts by trait -sidebarTitle: Contracts by trait -description: Retrieves a list of contracts based on the following traits listed in JSON format - functions, variables, maps, fungible tokens and non-fungible tokens. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/smart-contracts/get-smart-contract.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/smart-contracts/get-smart-contract.mdx new file mode 100644 index 000000000..670d14385 --- /dev/null +++ b/content/docs/en/apis/stacks-blockchain-api/reference/smart-contracts/get-smart-contract.mdx @@ -0,0 +1,12 @@ +--- +title: Get smart contract +sidebarTitle: Smart contract +description: Retrieves a deployed smart contract, along with the transaction that deployed it. Only successfully deployed contracts are returned; a contract id whose deploy transaction failed is not found. +full: true +--- + + diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/smart-contracts/info.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/smart-contracts/info.mdx deleted file mode 100644 index d61f7cfe4..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/smart-contracts/info.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get contract info -sidebarTitle: Contract info -description: Retrieves details for a specific smart contract. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/smart-contracts/meta.json b/content/docs/en/apis/stacks-blockchain-api/reference/smart-contracts/meta.json index a28fe9fe2..cca29cf3f 100644 --- a/content/docs/en/apis/stacks-blockchain-api/reference/smart-contracts/meta.json +++ b/content/docs/en/apis/stacks-blockchain-api/reference/smart-contracts/meta.json @@ -1,10 +1,5 @@ { "title": "Smart Contracts", - "pages": [ - "status", - "info", - "by-trait", - "get-smart-contract-logs" - ], + "pages": ["status", "get-smart-contract", "get-smart-contract-logs"], "defaultOpen": false } diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/meta.json b/content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/meta.json deleted file mode 100644 index c8362621e..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/meta.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "title": "Stacking Rewards", - "pages": [ - "recent-reward-slot-holders", - "recent-reward-slot-holder-entries", - "recent-burnchain-reward-recipients", - "recent-burnchain-reward-recipient", - "total-burnchain-rewards-for-recipient" - ], - "defaultOpen": false -} diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/recent-burnchain-reward-recipient.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/recent-burnchain-reward-recipient.mdx deleted file mode 100644 index 72c000445..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/recent-burnchain-reward-recipient.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get recent burnchain reward for the given recipient -sidebarTitle: Recent burnchain reward for the given recipient -description: Retrieves a list of recent burnchain (e.g. Bitcoin) rewards for the given recipient with the associated amounts and block info. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/recent-burnchain-reward-recipients.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/recent-burnchain-reward-recipients.mdx deleted file mode 100644 index 40abec579..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/recent-burnchain-reward-recipients.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get recent burnchain reward recipients -sidebarTitle: Recent burnchain reward recipients -description: Retrieves a list of recent burnchain (e.g. Bitcoin) reward recipients with the associated amounts and block info. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/recent-reward-slot-holder-entries.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/recent-reward-slot-holder-entries.mdx deleted file mode 100644 index 35e20fca6..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/recent-reward-slot-holder-entries.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get recent reward slot holder entries -sidebarTitle: Recent reward slot holder entries -description: Retrieves a list of the Bitcoin addresses that would validly receive Proof-of-Transfer commitments for a given reward slot holder recipient address. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/recent-reward-slot-holders.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/recent-reward-slot-holders.mdx deleted file mode 100644 index cc9eb15a8..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/recent-reward-slot-holders.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get recent reward slot holders -sidebarTitle: Recent reward slot holders -description: Retrieves a list of the Bitcoin addresses that would validly receive Proof-of-Transfer commitments. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/total-burnchain-rewards-for-recipient.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/total-burnchain-rewards-for-recipient.mdx deleted file mode 100644 index fc4bd3183..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/stacking-rewards/total-burnchain-rewards-for-recipient.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get total burnchain rewards for the given recipient -sidebarTitle: Total burnchain rewards for the given recipient -description: Retrieves the total burnchain (e.g. Bitcoin) rewards for a given recipient address. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-cycle-signers.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-cycle-signers.mdx new file mode 100644 index 000000000..7a3bae0f0 --- /dev/null +++ b/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-cycle-signers.mdx @@ -0,0 +1,12 @@ +--- +title: Get cycle signers +sidebarTitle: Cycle signers +description: "Get the signer set of a PoX cycle, including each signer's weight, staked amount, and the signer manager contracts whose registered signing key (via `register-signer`) was this key when the cycle's reward set was calculated. Each manager also lists its live `grant-signer-key` authorizations, and keys registered after the reward set was calculated are surfaced as pending updates that take effect next cycle." +full: true +--- + + diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/staking/meta.json b/content/docs/en/apis/stacks-blockchain-api/reference/staking/meta.json index a6043b466..96e33e9a9 100644 --- a/content/docs/en/apis/stacks-blockchain-api/reference/staking/meta.json +++ b/content/docs/en/apis/stacks-blockchain-api/reference/staking/meta.json @@ -9,6 +9,7 @@ "get-bond-allowlist-entry", "get-bond-registrations", "get-bond-registration", + "get-cycle-signers", "get-staking-signers", "get-staking-signer", "get-staking-signer-stakers" diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/tokens/get-ft-total-supply.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/tokens/get-ft-total-supply.mdx new file mode 100644 index 000000000..d40324932 --- /dev/null +++ b/content/docs/en/apis/stacks-blockchain-api/reference/tokens/get-ft-total-supply.mdx @@ -0,0 +1,12 @@ +--- +title: Get total fungible token supply +sidebarTitle: Total fungible token supply +description: "Retrieves the total supply of a fungible token: the sum of every holder balance, equivalent to the token's mints minus its burns. Returns a zero supply for a token with no recorded balances." +full: true +--- + + diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/tokens/get-fungible-token-holders.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/tokens/get-fungible-token-holders.mdx new file mode 100644 index 000000000..cd4e65e3a --- /dev/null +++ b/content/docs/en/apis/stacks-blockchain-api/reference/tokens/get-fungible-token-holders.mdx @@ -0,0 +1,12 @@ +--- +title: Get fungible token holders +sidebarTitle: Fungible token holders +description: "Retrieves the principals holding a given fungible token, sorted by balance descending. Balances are in the token's own base units." +full: true +--- + + diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/tokens/get-nft-instance-history.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/tokens/get-nft-instance-history.mdx new file mode 100644 index 000000000..f64fd7a82 --- /dev/null +++ b/content/docs/en/apis/stacks-blockchain-api/reference/tokens/get-nft-instance-history.mdx @@ -0,0 +1,12 @@ +--- +title: Get non-fungible token history +sidebarTitle: Non-fungible token history +description: "Retrieves the event history of a single non-fungible token instance, newest first. Useful for determining an asset's ownership history. Mints have a null `sender` and burns a null `recipient`. The instance is addressed by a SIP-009 token id, or by its serialized Clarity value when the collection is not keyed by a `uint`." +full: true +--- + + diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/tokens/get-stx-holders.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/tokens/get-stx-holders.mdx new file mode 100644 index 000000000..802be1ad9 --- /dev/null +++ b/content/docs/en/apis/stacks-blockchain-api/reference/tokens/get-stx-holders.mdx @@ -0,0 +1,12 @@ +--- +title: Get STX holders +sidebarTitle: STX holders +description: "Retrieves the principals holding STX, sorted by balance descending. Balances are the total µSTX held, including any STX locked for stacking — they are not the spendable balance reported as `available` by a principal's STX balance." +full: true +--- + + diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/tokens/get-stx-total-supply.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/tokens/get-stx-total-supply.mdx new file mode 100644 index 000000000..d01784faa --- /dev/null +++ b/content/docs/en/apis/stacks-blockchain-api/reference/tokens/get-stx-total-supply.mdx @@ -0,0 +1,12 @@ +--- +title: Get total STX supply +sidebarTitle: Total STX supply +description: "Retrieves the total liquid STX supply in micro-STX (µSTX) at the current chain tip: all STX minted (including vesting schedule unlocks) plus matured miner coinbase rewards, minus burned STX." +full: true +--- + + diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/tokens/holders.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/tokens/holders.mdx deleted file mode 100644 index 5907dd425..000000000 --- a/content/docs/en/apis/stacks-blockchain-api/reference/tokens/holders.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Get fungible token holders -sidebarTitle: Fungible token holders -description: Retrieves the list of fungible token holders for a given token ID. -full: true ---- - - diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/tokens/meta.json b/content/docs/en/apis/stacks-blockchain-api/reference/tokens/meta.json index 0e8a8d32a..92d8333ce 100644 --- a/content/docs/en/apis/stacks-blockchain-api/reference/tokens/meta.json +++ b/content/docs/en/apis/stacks-blockchain-api/reference/tokens/meta.json @@ -1,5 +1,11 @@ { "title": "Tokens", - "pages": ["..."], + "pages": [ + "get-stx-total-supply", + "get-stx-holders", + "get-ft-total-supply", + "get-fungible-token-holders", + "get-nft-instance-history" + ], "defaultOpen": false } diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/transactions/get-principal-ft-transfers.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/transactions/get-principal-ft-transfers.mdx new file mode 100644 index 000000000..c910b0146 --- /dev/null +++ b/content/docs/en/apis/stacks-blockchain-api/reference/transactions/get-principal-ft-transfers.mdx @@ -0,0 +1,12 @@ +--- +title: Get fungible token transfers +sidebarTitle: Fungible token transfers +description: "Returns a principal's transfer history for a single fungible token as one feed, newest first, combining the events that credit it and the events that debit it. Includes mints (which have a null `sender`) and burns (which have a null `recipient`). A transaction that moves the token several times for this principal yields one result per event. Amounts are in the token's own base units." +full: true +--- + + diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/transactions/get-principal-inbound-stx-transfers.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/transactions/get-principal-inbound-stx-transfers.mdx new file mode 100644 index 000000000..7fe9050e9 --- /dev/null +++ b/content/docs/en/apis/stacks-blockchain-api/reference/transactions/get-principal-inbound-stx-transfers.mdx @@ -0,0 +1,12 @@ +--- +title: Get inbound STX transfers +sidebarTitle: Inbound STX transfers +description: "Returns the individual inbound STX events crediting a principal. Includes native stx-transfer transactions, `send-many-memo` bulk-send legs, any other STX transfer event crediting the principal, and STX mints (which have a null `sender`), each with its own sender, amount, and memo. A transaction that credits the principal multiple times yields one result per event." +full: true +--- + + diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/transactions/get-principal-outbound-stx-transfers.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/transactions/get-principal-outbound-stx-transfers.mdx new file mode 100644 index 000000000..f09090a1b --- /dev/null +++ b/content/docs/en/apis/stacks-blockchain-api/reference/transactions/get-principal-outbound-stx-transfers.mdx @@ -0,0 +1,12 @@ +--- +title: Get outbound STX transfers +sidebarTitle: Outbound STX transfers +description: "Returns the individual outbound STX events debiting a principal. Includes native stx-transfer transactions, `send-many-memo` bulk-send legs, any other STX transfer event debiting the principal, and STX burns (which have a null `recipient`), each with its own recipient, amount, and memo. A transaction that debits the principal multiple times yields one result per event." +full: true +--- + + diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/transactions/meta.json b/content/docs/en/apis/stacks-blockchain-api/reference/transactions/meta.json index 088e26214..444223c8f 100644 --- a/content/docs/en/apis/stacks-blockchain-api/reference/transactions/meta.json +++ b/content/docs/en/apis/stacks-blockchain-api/reference/transactions/meta.json @@ -7,6 +7,9 @@ "get-principal-transactions", "get-principal-transaction-balance-changes", "get-principal-balance-changes", + "get-principal-inbound-stx-transfers", + "get-principal-outbound-stx-transfers", + "get-principal-ft-transfers", "get-principal-mempool-transactions", "get-transactions", "get-transaction", diff --git a/content/docs/en/apis/stacks-blockchain-api/v1-to-v3-migration.mdx b/content/docs/en/apis/stacks-blockchain-api/v1-to-v3-migration.mdx index 98dd0bf25..754ff2426 100644 --- a/content/docs/en/apis/stacks-blockchain-api/v1-to-v3-migration.mdx +++ b/content/docs/en/apis/stacks-blockchain-api/v1-to-v3-migration.mdx @@ -148,9 +148,25 @@ The v1 "address" resource is the v3 "principal" resource. | `GET /extended/v1/address/{principal}/mempool` | `GET /extended/v3/principals/{principal}/mempool/transactions` | | `GET /extended/v1/address/{principal}/nonces` | `GET /extended/v3/principals/{principal}/nonces` | | `GET /extended/v1/address/{principal}/assets` | No direct replacement — closest is `GET /extended/v3/principals/{principal}/balance-changes` | -| `GET /extended/v1/address/{principal}/stx_inbound` | No direct replacement | +| `GET /extended/v1/address/{principal}/stx_inbound` | `GET /extended/v3/principals/{principal}/transfers/stx/inbound` | | `GET /extended/v1/tokens/nft/holdings?principal=` | `GET /extended/v3/principals/{principal}/balances/nft` | +v3 also adds two transfer feeds with no v1 counterpart: + +- `GET /extended/v3/principals/{principal}/transfers/stx/outbound` — the debit side of + `stx_inbound`. +- `GET /extended/v3/principals/{principal}/transfers/ft/{asset_identifier}` — a principal's + history for one fungible token, credits and debits interleaved in a single feed, newest first, + in the token's own base units. + +All three transfer endpoints return one result per *event* rather than per transaction, so a +transaction that moves the asset several times for this principal yields several rows. Mints have +a `null` sender and burns a `null` recipient. + +`GET /extended/v3/principals/{principal}/balances/nft` accepts an optional `asset_identifier` +query parameter, which replaces the v1 `asset_identifiers` array filter. It takes a single asset +class, not a list. + ### STX balance field mapping `GET /extended/v1/address/{principal}/stx` → `GET /extended/v3/principals/{principal}/balances/stx` @@ -256,7 +272,66 @@ a `tx_count`; fetch the transactions from | Deprecated v1 endpoint | Replacement | | --- | --- | +| `GET /extended/v1/contract/{contract_id}` | `GET /extended/v3/smart-contracts/{contract_id}` | | `GET /extended/v1/contract/{contract_id}/events` | `GET /extended/v2/smart-contracts/{contract_id}/logs` | +| `GET /extended/v1/contract/by_trait` | None — see [Endpoints without a v3 replacement](#endpoints-without-a-v3-replacement) | + +### Contract field mapping + +`GET /extended/v1/contract/{contract_id}` → `GET /extended/v3/smart-contracts/{contract_id}` + +| v1 field | v3 field | +| --- | --- | +| `contract_id` | `contract_id` | +| `clarity_version` | `clarity_version` | +| `tx_id` | `tx_id` | +| `block_height` | `block.height` | +| `source_code` | `source_code`, only with `?include=source_code` | +| `abi` | Removed — use the Stacks node RPC `GET /v2/contracts/interface/{address}/{name}` | +| `canonical` | Removed — v3 returns canonical data only | +| — | `block.hash`, `block.index_hash`, `block.time`, `block.tx_index` (new) | +| — | `bitcoin_block` (new: height, time) | + +:::callout +type: warn +### Failed deployments are no longer returned +v1 wrote a row for every contract-deploy transaction, successful or not, and returned it with +`abi: null` and no indication that the deploy had aborted. v3 returns only contracts that were +successfully deployed; a contract id whose deploy transaction failed responds `404`. +::: + +## Stacking rewards + +The burnchain reward endpoints report the Bitcoin reward addresses and BTC payouts of the pox-1 +through pox-4 reward model. That model is keyed on the `pox-addr` a stacker supplies when +stacking, and pox-5 has no such address: stakers lock BTC or sBTC against a bond, and rewards +accrue as **sBTC on the Stacks layer** rather than as BTC sent to a burnchain address. + +These endpoints therefore serve historical pox-4-and-earlier data only. No new records are +written to them once the last pox-4 lock unlocks. + +| Deprecated v1 endpoint | Replacement | +| --- | --- | +| `GET /extended/v1/burnchain/reward_slot_holders` | None — reward slots do not exist in pox-5. The nearest concept is the cycle signer set, `GET /extended/v3/staking/cycles/{cycle_number}/signers` | +| `GET /extended/v1/burnchain/reward_slot_holders/{address}` | None | +| `GET /extended/v1/burnchain/rewards` | No global feed. Per-bond payouts: `GET /extended/v3/staking/bonds` → `balances.paid_out.btc` | +| `GET /extended/v1/burnchain/rewards/{address}` | `GET /extended/v3/principals/{principal}/staking/bonds` → `rewards.btc` | +| `GET /extended/v1/burnchain/rewards/{address}/total` | `GET /extended/v3/principals/{principal}/staking` → `bonds.rewards.btc` and `stx.rewards.btc` | + +:::callout +type: warn +### These are not drop-in replacements +Three things change at once. The lookup key flips from a **Bitcoin address** to a **Stacks +principal** — the v1 endpoints accept either and convert a STX address to its Bitcoin +equivalent, and pox-5 has no such relationship to convert through. The asset flips from **BTC on +Bitcoin** to **sBTC on Stacks** (both denominated in sats, so amounts look interchangeable when +they are not). And the granularity flips from **per-burn-block payout events** to **running +`accrued` / `claimed` / `claimable` totals per position** — v3 has no per-block reward history. +::: + +For per-burn-block BTC payouts under the current model, see +`GET /extended/v2/burn-blocks/{height_or_hash}/pox-transactions` and +`GET /extended/v2/addresses/{burnchain_address}/pox-transactions`, which are not deprecated. ## Fees @@ -266,14 +341,169 @@ a `tx_count`; fetch the transactions from ## STX supply -The plain-text and legacy-shaped variants are deprecated in favor of the single JSON endpoint, -which is **not** deprecated. +All four v1 supply endpoints — including the JSON one — are deprecated in favor of a single v3 +endpoint. | Deprecated v1 endpoint | Replacement | | --- | --- | -| `GET /extended/v1/stx_supply/total/plain` | `GET /extended/v1/stx_supply` → `total_stx` | -| `GET /extended/v1/stx_supply/circulating/plain` | `GET /extended/v1/stx_supply` → `unlocked_stx` | -| `GET /extended/v1/stx_supply/legacy_format` | `GET /extended/v1/stx_supply` | +| `GET /extended/v1/stx_supply` | `GET /extended/v3/tokens/stx/supply` | +| `GET /extended/v1/stx_supply/total/plain` | `GET /extended/v3/tokens/stx/supply` → `total` | +| `GET /extended/v1/stx_supply/circulating/plain` | `GET /extended/v3/tokens/stx/supply` → `total` | +| `GET /extended/v1/stx_supply/legacy_format` | `GET /extended/v3/tokens/stx/supply` | + +### Supply field mapping + +| v1 field | v3 field | +| --- | --- | +| `total_stx` | `total` | +| `total_stx_year_2050` | `projected_total_2050` | +| `unlocked_stx` | Removed | +| `unlocked_percent` | Removed | +| `block_height` | Removed | + +:::callout +type: warn +### Units and definition both changed +v1 returned decimal **STX** strings (`"1470469916.700000"`). v3 returns string-quoted integer +**micro-STX** (`"1470469916700000"`). Multiply by 10^6 when comparing against stored v1 values. + +The quantity itself is also defined differently. v1 `total_stx` was the circulating supply at a +given block height, with `unlocked_stx` tracking the unlocked portion separately. v3 `total` is +the total **liquid** supply at the current chain tip: all STX minted (vesting unlocks included) +plus matured miner coinbase rewards, minus burned STX. There is no separate locked/unlocked +split, and v3 always reports the chain tip — the v1 `height` and `unanchored` query parameters +are gone. +::: + +## Fungible tokens + +| Deprecated v1 endpoint | v3 replacement | +| --- | --- | +| `GET /extended/v1/tokens/ft/{token}/holders` | `GET /extended/v3/tokens/ft/{asset_identifier}/holders` | +| `GET /extended/v1/tokens/ft/stx/holders` | `GET /extended/v3/tokens/stx/holders` | + +v1 took the literal string `stx` in the `token` path parameter to mean STX holders. v3 splits +that into its own route, matching how `/tokens/stx/supply` is already separated, and validates +`{asset_identifier}` as a real Clarity asset identifier. + +### Holder field mapping + +| v1 field | v3 field | +| --- | --- | +| `address` | `principal` | +| `balance` | `balance` | +| `total_supply` | Moved to `GET /extended/v3/tokens/ft/{asset_identifier}/supply` → `total` | + +The v1 response fused `total_supply` into the paginated envelope as an extra top-level field. In +v3 the holders response is the standard cursor envelope and nothing else, and supply is its own +endpoint — `{ asset_identifier, total }` for fungible tokens, or the existing +`/tokens/stx/supply` for STX. + +:::callout +type: warn +### Zero balances are no longer holders +`ft_balances` rows are never deleted, so a principal that has spent its entire position stays in +the table with a `0` balance. v1 listed those rows and counted them in `total`; v3 filters them +out, matching `GET /extended/v3/principals/{principal}/balances/ft`. Expect a smaller `total` +than v1 reported for the same token. + +Sort order also changed: v1 ordered by `balance DESC` with no tiebreaker, so holders with equal +balances came back in an arbitrary order and offset paging could skip or repeat them. v3 orders +by `(balance DESC, principal ASC)`, which is what makes the cursor stable. +::: + +Balances are in the token's own base units. This API does not know a token's decimal precision — +fetch that from the Token Metadata API. + +For `/tokens/stx/holders`, the balance is the **total** µSTX held, including STX locked for +stacking. It is not the spendable figure that `GET /extended/v3/principals/{principal}/balances/stx` +reports as `available`. + +## Non-fungible tokens + +| Deprecated v1 endpoint | v3 replacement | +| --- | --- | +| `GET /extended/v1/tokens/nft/history` | `GET /extended/v3/tokens/nft/{asset_identifier}/{value}/history` | + +`asset_identifier` moved from a query parameter into the path, matching the fungible token routes. +The token instance moved into the path too, and is accepted in two forms: + +- **A plain integer** — a SIP-009 token id, e.g. `.../the-explorer-guild/2051/history`. This is + the form to use for almost every collection. +- **A `0x`-prefixed serialized Clarity value** — required for assets not keyed by a `uint`. BNS + names are the notable case: `bns.clar` defines them as + `{ name: (buff 48), namespace: (buff 20) }`, a tuple, so they have no integer id. + +:::callout +type: warn +### The `0x` prefix is required for the hex form +v1 accepted `value` with or without it. In a path segment a bare hex string is ambiguous with a +decimal token id — and a serialized `uint` happens to be all decimal digits — so hex stripped of +its prefix is read as a (very large) token id and resolves to an empty page rather than erroring. +Always send the prefix. + +To tell which form a collection needs, look at `value.repr` from +`GET /extended/v3/principals/{principal}/balances/nft`: a `repr` like `u2051` means the integer +form works. +::: + +### Field mapping + +| v1 field | v3 field | +| --- | --- | +| `asset_event_type` | Removed — a mint has a null `sender`, a burn a null `recipient` | +| `sender` | `sender` (null on mints) | +| `recipient` | `recipient` (null on burns) | +| `event_index` | `transaction.event_index` | +| `tx_id` | `transaction.tx_id` | +| `value` | `value` (mints only — for history it is the request parameter) | +| `tx` | Removed — the `tx_metadata` parameter is gone | +| — | `block` (new: height, hash, index_hash, time, tx_index) | + +:::callout +type: warn +### `tx_metadata` has no v3 equivalent +v1 could inline a full transaction object into each row via `tx_metadata=true`. v3 returns the +transaction id and event index only; fetch the transaction separately from +`GET /extended/v3/transactions/{tx_id}` when you need its detail. The `unanchored` parameter is +also gone, as everywhere else in v3. +::: + +## Network block times + +| Deprecated v1 endpoint | Replacement | +| --- | --- | +| `GET /extended/v1/info/network_block_times` | None | +| `GET /extended/v1/info/network_block_time/{network}` | None | + +These return hardcoded legacy values (600s mainnet, 120s testnet) that no longer reflect actual +Stacks block production since the Nakamoto upgrade. For real block timing, use +`GET /extended/v2/blocks/average-times`, which is not deprecated. + +## BNS + +All BNS endpoints are deprecated. They are no longer maintained. + +| Deprecated endpoint | Replacement | +| --- | --- | +| `GET /v1/names` | None | +| `GET /v1/names/{name}` | None | +| `GET /v1/names/{name}/subdomains` | None | +| `GET /v1/names/{name}/zonefile` | None | +| `GET /v1/names/{name}/zonefile/{zoneFileHash}` | None | +| `GET /v1/namespaces` | None | +| `GET /v1/namespaces/{tld}/names` | None | +| `GET /v2/prices/names/{name}` | None | +| `GET /v2/prices/namespaces/{tld}` | None | +| `GET /v1/addresses/{blockchain}/{address}` | `GET /extended/v3/principals/{principal}/balances/nft?asset_identifier=SP000000000000000000002Q6VF78.bns::names` | + +:::callout +type: warn +### Names-owned lookups are not equivalent +Querying NFT balances filtered to the BNS asset class returns only **NFT-backed names**. It does +not include subdomains, nor names imported from Blockstack v1, both of which +`GET /v1/addresses/{blockchain}/{address}` did return. +::: ## Endpoints without a v3 replacement @@ -281,12 +511,13 @@ These are deprecated with no successor. Plan around them rather than swapping a | Deprecated endpoint | Notes | | --- | --- | -| `GET /extended/v1/tx/events` | Global event feed filtered by principal, transaction, or event type. Per-transaction events are available at `GET /extended/v3/transactions/{tx_id}/events`, and per-principal asset movement at `GET /extended/v3/principals/{principal}/balance-changes`. | +| `GET /extended/v1/tx/events` | Global event feed filtered by principal, transaction, or event type. Several v3 endpoints cover parts of it: per-transaction events at `GET /extended/v3/transactions/{tx_id}/events`, a principal's history for one fungible token at `GET /extended/v3/principals/{principal}/transfers/ft/{asset_identifier}`, a principal's STX transfers at `GET /extended/v3/principals/{principal}/transfers/stx/{inbound,outbound}`, and per-principal asset movement at `GET /extended/v3/principals/{principal}/balance-changes`. There is no single global event feed. | | `GET /extended/v1/address/{principal}/assets` | Closest equivalent is `GET /extended/v3/principals/{principal}/balance-changes`, which reports net balance deltas rather than raw asset events. | -| `GET /extended/v1/address/{principal}/stx_inbound` | Inbound STX transfers with memos, including `send-many-memo` bulk sends. No v3 equivalent. | +| `GET /extended/v1/contract/by_trait` | Searches deployed contracts by Clarity trait ABI. No v3 equivalent. To look up a specific contract you already know, use `GET /extended/v3/smart-contracts/{contract_id}`. | | `GET /extended/v1/microblock` | Microblocks were removed in the Nakamoto upgrade and are no longer produced. | | `GET /extended/v1/microblock/{hash}` | Same. | | `GET /extended/v1/microblock/unanchored/txs` | Same. | +| `GET /extended/v1/tokens/nft/mints` | Mint events for an asset class. Retired rather than migrated — the endpoint serves negligible traffic. A single instance's mint is the oldest entry in `GET /extended/v3/tokens/nft/{asset_identifier}/{value}/history`, but there is no collection-wide mint feed. | | `GET /extended/v1/faucets/btc/{address}` | Testnet-only BTC balance helper. No replacement. | ## Also deprecated: v2 endpoints @@ -305,23 +536,31 @@ migrated from v1 to v2, these are your next hop. ## Endpoints that are not deprecated -Not everything under `/extended/v1` is going away. These remain the supported way to fetch their -data today: - -- **Transactions** — `GET /extended/v1/tx/multiple`, `GET /extended/v1/tx/mempool/stats` -- **Smart contracts** — `GET /extended/v1/contract/by_trait`, - `GET /extended/v1/contract/{contract_id}` -- **Tokens** — `GET /extended/v1/tokens/nft/history`, `GET /extended/v1/tokens/nft/mints`, - `GET /extended/v1/tokens/ft/{token}/holders` -- **Info** — `GET /extended/v1/stx_supply`, `GET /extended/v1/info/network_block_times`, - `GET /extended/v1/info/network_block_time/{network}` -- **Burnchain** — `GET /extended/v1/burnchain/reward_slot_holders`, - `GET /extended/v1/burnchain/rewards` (and their per-address variants) -- **Stacking** — the `GET /extended/v1/pox4/*` family -- **Search** — `GET /extended/v1/search/{id}` -- **BNS** — the `GET /v1/names/*`, `GET /v1/namespaces/*`, `GET /v1/addresses/*`, and - `GET /v2/prices/*` families -- **Status** — `GET /extended` +Most of `/extended/v1` is now deprecated, but these routes are not. They remain the supported way +to fetch their data today: + +| Area | Endpoint | +| --- | --- | +| Transactions | `GET /extended/v1/tx/multiple` | +| Transactions | `GET /extended/v1/tx/mempool/stats` | +| Stacking | `GET /extended/v1/pox4/events` | +| Stacking | `GET /extended/v1/pox4/tx/{tx_id}` | +| Stacking | `GET /extended/v1/pox4/stacker/{principal}` | +| Stacking | `GET /extended/v1/pox4/{pool_principal}/delegations` | +| Search | `GET /extended/v1/search/{id}` | +| Faucets | `POST /extended/v1/faucets/stx` | +| Faucets | `POST /extended/v1/faucets/btc` | +| Faucets | `POST /extended/v1/faucets/sbtc` | +| Status | `GET /extended` | + +The `pox4` prefix also accepts `pox2` and `pox3` for historical data. Faucet endpoints are +testnet-only. + +Outside `/extended/v1`, these `/extended/v2` routes are also current and have no v3 successor +yet: `GET /extended/v2/blocks` and its siblings, `GET /extended/v2/burn-blocks/*`, +`GET /extended/v2/block-tenures/{tenure_height}/blocks`, `GET /extended/v2/pox/cycles*`, +`GET /extended/v2/mempool/fees`, `GET /extended/v2/smart-contracts/*`, and the two +`pox-transactions` routes noted under [Stacking rewards](#stacking-rewards). :::callout type: help