From c882614f3829d0cc89bec94d746e822199d55ac5 Mon Sep 17 00:00:00 2001 From: eric <236061711+eric-stacks@users.noreply.github.com> Date: Thu, 5 Feb 2026 09:43:26 -0500 Subject: [PATCH] add deprecation notice and migration pages --- content/docs/en/apis/ordinals-api/index.mdx | 5 ++ content/docs/en/apis/ordinals-api/meta.json | 2 +- .../docs/en/apis/ordinals-api/migration.mdx | 71 +++++++++++++++++++ content/docs/en/apis/runes-api/index.mdx | 5 ++ content/docs/en/apis/runes-api/meta.json | 2 +- content/docs/en/apis/runes-api/migration.mdx | 45 ++++++++++++ .../docs/en/tools/bitcoin-indexer/index.mdx | 5 ++ .../tools/chainhooks/(overview)/migration.mdx | 11 +++ 8 files changed, 144 insertions(+), 2 deletions(-) create mode 100644 content/docs/en/apis/ordinals-api/migration.mdx create mode 100644 content/docs/en/apis/runes-api/migration.mdx diff --git a/content/docs/en/apis/ordinals-api/index.mdx b/content/docs/en/apis/ordinals-api/index.mdx index de11bac2d..fc5066297 100644 --- a/content/docs/en/apis/ordinals-api/index.mdx +++ b/content/docs/en/apis/ordinals-api/index.mdx @@ -9,6 +9,11 @@ llm: false The Ordinals API provides comprehensive inscription data for Bitcoin ordinals through a high-performance REST interface. Built with cached responses and optimized indexing, it delivers inscription metadata, trading activity, BRC-20 token information, and satoshi-level data with minimal latency. +:::callout +### Deprecation Notice +The Ordinals API will be deprecated on March 1st, 2026. Refer to the [migration guide](/apis/ordinals-api/migration) to migrate your application to using Xverse's Ordinals API instead. +::: + ## Key features - **Complete inscription data** - Metadata, content, and ownership for all ordinals diff --git a/content/docs/en/apis/ordinals-api/meta.json b/content/docs/en/apis/ordinals-api/meta.json index ec20236a6..657e6fc73 100644 --- a/content/docs/en/apis/ordinals-api/meta.json +++ b/content/docs/en/apis/ordinals-api/meta.json @@ -1,5 +1,5 @@ { "title": "Ordinals API", "root": true, - "pages": ["---Ordinals API---", "index", "usage", "---Reference---", "...reference"] + "pages": ["---Ordinals API---", "index", "migration", "usage", "---Reference---", "...reference"] } diff --git a/content/docs/en/apis/ordinals-api/migration.mdx b/content/docs/en/apis/ordinals-api/migration.mdx new file mode 100644 index 000000000..518169c6d --- /dev/null +++ b/content/docs/en/apis/ordinals-api/migration.mdx @@ -0,0 +1,71 @@ +--- +title: Migration guide +description: Guide for migrating to using the L1 APIs from Xverse +llm: true +--- + +As part of the deprecation of Hiro’s L1 APIs for Ordinals, Runes, BRC-20, Ordhooks, and Runehooks, we’re recommending developers move to using the L1 APIs from Xverse, who have built a robust set of tooling for Bitcoin metaprotocols. We’ve put together this guide for developers on how to migrate your applications to using their APIs. + +:::callout +### Using Xverse's L1 APIs +NOTE: The Xverse L1 APIs are in private beta, but we’ve worked with them to create an expedited approval path for those coming from Hiro APIs, so just [fill out this form](https://form.typeform.com/to/HkwDUt9P?typeform-source=docs.xverse.app) and they will get back to you quickly. +::: + +## Timeline +- Announcement date: Feburary 7th, 2026 +- Deprecation effective: March 1st, 2026 + +## What you'll learn + +:::objectives +- Capture and analyze all existing Ordinals and BRC-20 API endpoints. +- Maps the API endpoint equivalent to the applicable endpoint with Xverse. +- Note any differences and changes you'll need to be aware of. +::: + +## Ordinals endpoint mappings + +### List of endpoints and its Xverse endpoint equivalent +| Hiro Endpoint | Description (Hiro) | Key Parameters (Hiro) | Xverse Equivalent Endpoint | Description (Xverse Equivalent) | Key Parameters (Xverse) | Migration Notes | +| --- | --- | --- | --- | --- | --- | --- | +| `GET /inscriptions` | Retrieves a paginated list of all inscriptions. | `limit` (default: 20, max: 100), `offset` (for pagination), `after` (inscription ID for cursor-based pagination), `before` (inscription ID for cursor-based pagination), `sat_ordinal_range` (filter by satoshi ordinal range, e.g., “23-34”), `content_type` (filter by MIME type, e.g., “image/png”), `content_length_range` (filter by byte range, e.g., “100-500”), `tag` (filter by inscription tag). | `GET /inscriptions` | Retrieves a paginated list of inscriptions. | `limit` (default: 20, max: 100), `offset` (for pagination), `after` (inscription ID), `content_type` (MIME type filter). | Direct mapping possible. Xverse supports core pagination and content_type filtering but omits `sat_ordinal_range`, `content_length_range`, and `tag`. Use Xverse’s `after` for cursor pagination. Response fields (e.g., `id`, `content_type`, `content_length`) are compatible. | +| `GET /inscriptions/{inscriptionId}` | Fetches details for a specific inscription by ID. | Path param: `inscriptionId` (string). | `GET /inscriptions/{inscriptionId}` | Fetches details for a specific inscription by ID. | Path param: `inscriptionId` (string). | Direct mapping. Both return inscription metadata (e.g., `id`, `content_type`, `genesis_fee`, `sat_ordinal`). No changes required. | +| `GET /inscriptions/{inscriptionId}/content` | Retrieves the raw content (e.g., image or text) of a specific inscription. | Path param: `inscriptionId` (string). | `GET /inscriptions/{inscriptionId}/content` | Retrieves the raw content of a specific inscription. | Path param: `inscriptionId` (string). | Direct mapping. Supports binary content retrieval; ensure handling of MIME types in responses. | +| `GET /inscriptions/{inscriptionId}/sat` | Retrieves the satoshi details associated with a specific inscription. | Path param: `inscriptionId` (string). | None | N/A | N/A | No direct equivalent in Xverse. Workaround: Use `GET /inscriptions/{inscriptionId}` which includes `sat_ordinal` in the response, or query satoshi details via Xverse’s broader inscription endpoint if available. This is a Hiro-specific feature for granular satoshi-inscription linkage. | +| `GET /inscriptions/block-height/{blockHeight}` | Retrieves all inscriptions in a specific block by height. | Path param: `blockHeight` (integer). | `GET /inscriptions/block/{blockHeight}` | Retrieves inscriptions for a specific block by height. | Path param: `blockHeight` (integer). | Near-direct mapping; note the path difference (`/block-height/` vs. `/block/`). Both support pagination via `limit` and `offset`. | +| `GET /inscriptions/block-hash/{blockHash}` | Retrieves all inscriptions in a specific block by hash. | Path param: `blockHash` (string). | `GET /inscriptions/block/{blockHash}` | Retrieves inscriptions for a specific block by hash. | Path param: `blockHash` (string). | Near-direct mapping; path uses `/block/` in Xverse. Pagination supported. | +| `GET /collections` | Retrieves a paginated list of all collections. | `limit` (default: 20, max: 100), `offset` (for pagination). | `GET /collections` | Retrieves a paginated list of collections. | `limit` (default: 20, max: 100), `offset` (for pagination). | Direct mapping. Responses include collection metadata (e.g., `id`, `name`, `inscription_count`). | +| `GET /collections/{collectionId}` | Fetches details for a specific collection by ID. | Path param: `collectionId` (string). | `GET /collections/{collectionId}` | Fetches details for a specific collection by ID. | Path param: `collectionId` (string). | Direct mapping. Includes fields like `inscription_count` and `total_supply`. | +| `GET /collections/{collectionId}/inscriptions` | Retrieves paginated inscriptions within a specific collection. | Path param: `collectionId` (string); `limit`, `offset`. | `GET /collections/{collectionId}/inscriptions` | Retrieves paginated inscriptions in a specific collection. | Path param: `collectionId` (string); `limit`, `offset`. | Direct mapping. Supports standard pagination. | +| `GET /stats` | Retrieves global Ordinals statistics (e.g., total inscriptions, blocks). | None. | `GET /stats` | Retrieves global Ordinals statistics. | None. | Direct mapping. Both provide aggregates like `total_inscriptions` and `total_size`. | + +For more details, check out the [Xverse Ordinals](https://docs.xverse.app/api/ordinals) reference. + +## Hiro-Specific Functionality for Ordinals Not Available in Xverse + +- `GET /inscriptions/{inscriptionId}/sat`: Dedicated satoshi retrieval for an inscription. Xverse includes basic sat_ordinal in inscription details but not full satoshi metadata. +- Advanced filtering in `GET /inscriptions`: + - `sat_ordinal_range`: Filter by satoshi ordinal range. + - `content_length_range`: Filter by content size range. + - `tag`: Filter by inscription tags. +- No Xverse support for inscription tagging or content-length-based queries, which may necessitate client-side filtering post-retrieval. + +## BRC-20 endpoint mappings + +### List of endpoints and its Xverse endpoint equivalent +| Hiro Endpoint | Description (Hiro) | Key Parameters (Hiro) | Xverse Equivalent Endpoint | Description (Xverse Equivalent) | Key Parameters (Xverse) | Migration Notes | +| --- | --- | --- | --- | --- | --- | --- | +| `GET /ordinals/brc-20/tokens` | Retrieves a paginated list of all BRC-20 tokens. | `limit` (default: 20, max: 100), `offset` (for pagination). | None (partial via address balances) | N/A | N/A | No direct global token list in Xverse. Workaround: Query multiple address balances or use external explorers for token discovery. Responses in Hiro include `ticker`, `max`, `limit`, `supply`; replicate via aggregated address queries if needed. | +| `GET /ordinals/brc-20/tokens/{ticker}` | Fetches detailed information for a specific BRC-20 token by ticker. | Path param: `ticker` (string). | `GET /v1/brc20/ticker/ {ticker}` | Get data and price info for a specific BRC20 by ticker. | Path param: `ticker` (string) token ticker | Xverse includes extra price data | +| `GET /ordinals/brc-20/tokens/{ticker}/holders` | Retrieves a paginated list of holders and their balances for a specific token. | Path param: `ticker` (string); `limit`, `offset`. | None | N/A | N/A | No holder list in Xverse. Workaround: Requires custom indexing of transfer events or third-party tools; Xverse lacks global holder aggregation. | +| `GET /ordinals/brc-20/tokens/{ticker}/events` | Returns the event history (deploys, mints, transfers) for a specific token. | Path param: `ticker` (string); `limit`, `offset`, optional filters like `event_type` (deploy, mint, transfer). | None (partial via address history) | N/A | N/A | No token-specific event history in Xverse. Workaround: Use address-specific transaction history and filter client-side by ticker. | +| `GET /ordinals/brc-20/balances/{address}` | Retrieves BRC-20 token balances for a specific address. | Path param: `address` (string); optional `ticker` filter. | `GET /v1/ordinals/address/{address}/brc20` | Fetches confirmed BRC-20 balances for an address. | Path param: `address` (string); supports `limit` and `offset` (currently ignored, returns full list). | Strong mapping. Both return balances per ticker (e.g., `balance`, `available`). Update path and base URL; test pagination as Xverse may evolve to enforce limits. | + +For more details, check out the [Xverse BRC-20](https://docs.xverse.app/api/brc-20) reference. + +## Hiro-Specific Functionality for BRC-20 Not Available in Xverse + +- Global token listing (`/ordinals/brc-20/tokens`): No equivalent; Xverse prioritizes per-address or per-user data. +- Token holder lists (`/ordinals/brc-20/tokens/{ticker}/holders`): Absent; requires aggregation from balances or external sources. +- Token event history (`/ordinals/brc-20/tokens/{ticker}/events`): No dedicated endpoint; use address history with filtering. +- Xverse offers unique extensions like minting (`/v1/brc20/mint/estimate`, `/v1/brc20/mint/order`, `/v1/brc20/mint/execute`) and deployment (`/v1/brc20/deploy/estimate`, etc.), plus swaps (`/v1/brc20/swaps/quotes`), which Hiro lacks. For full event history, consider supplementing Xverse with Hiro temporarily or custom Bitcoin RPC parsing. \ No newline at end of file diff --git a/content/docs/en/apis/runes-api/index.mdx b/content/docs/en/apis/runes-api/index.mdx index 267203e23..7a0eef07a 100644 --- a/content/docs/en/apis/runes-api/index.mdx +++ b/content/docs/en/apis/runes-api/index.mdx @@ -9,6 +9,11 @@ llm: false The Runes API provides comprehensive data for Bitcoin Runes through a high-performance REST interface. Built with cached responses and optimized indexing, it delivers rune metadata, trading activity, holder information, and etching details with minimal latency. +:::callout +### Deprecation Notice +The Runes API will be deprecated on March 1st, 2026. Refer to the [migration guide](/apis/runes-api/migration) to migrate your application to using Xverse's Runes API instead. +::: + ## Key features - **Complete runes coverage** - Metadata for all etchings and rune activity diff --git a/content/docs/en/apis/runes-api/meta.json b/content/docs/en/apis/runes-api/meta.json index ea8e3a6eb..0252592b9 100644 --- a/content/docs/en/apis/runes-api/meta.json +++ b/content/docs/en/apis/runes-api/meta.json @@ -1,5 +1,5 @@ { "title": "Runes API", "root": true, - "pages": ["---Runes API---", "index", "usage", "---Reference---", "...reference"] + "pages": ["---Runes API---", "index", "migration", "usage", "---Reference---", "...reference"] } diff --git a/content/docs/en/apis/runes-api/migration.mdx b/content/docs/en/apis/runes-api/migration.mdx new file mode 100644 index 000000000..2c9b46480 --- /dev/null +++ b/content/docs/en/apis/runes-api/migration.mdx @@ -0,0 +1,45 @@ +--- +title: Migration guide +description: Guide for migrating to using the L1 APIs from Xverse +llm: true +--- + +As part of the deprecation of Hiro’s L1 APIs for Ordinals, Runes, BRC-20, Ordhooks, and Runehooks, we’re recommending developers move to using the L1 APIs from Xverse, who have built a robust set of tooling for Bitcoin metaprotocols. We’ve put together this guide for developers on how to migrate your applications to using their APIs. + +:::callout +### Using Xverse's L1 APIs +NOTE: The Xverse L1 APIs are in private beta, but we’ve worked with them to create an expedited approval path for those coming from Hiro APIs, so just [fill out this form](https://form.typeform.com/to/HkwDUt9P?typeform-source=docs.xverse.app) and they will get back to you quickly. +::: + +## Timeline +- Announcement date: Feburary 7th, 2026 +- Deprecation effective: March 1st, 2026 + +## What you'll learn + +:::objectives +- Capture and analyze all existing Runes API endpoints. +- Maps the API endpoint equivalent to the applicable endpoint with Xverse. +- Note any differences and changes you'll need to make. +::: + +## Endpoint mappings + +### List of endpoints and its Xverse endpoint equivalent +| Hiro Endpoint | Description (Hiro) | Key Parameters (Hiro) | Xverse Equivalent Endpoint | Description (Xverse Equivalent) | Key Parameters (Xverse) | Migration Notes | +| --- | --- | --- | --- | --- | --- | --- | +| `GET /etchings` | Retrieves a paginated list of all rune etchings. | `limit` (default: 20, max: 100), `offset` (for pagination). | None | N/A | N/A | No direct global etchings list in Xverse. Workaround: Use market data endpoints (e.g., for popular runes) or external explorers to identify etchings, then query individual details via rune-specific calls. Hiro responses include etching metadata like name, supply, and terms. | +| `GET /etchings/{runeId}` | Fetches detailed metadata for a specific rune etching. | Path param: `runeId` (string, e.g., rune identifier). | `GET /v1/runes/{runeId}` (inferred from balances/metadata support) | Retrieves rune metadata and details for a specific rune. | Path param: `runeId` (string). | Strong mapping. Both provide fields like name, divisibility, supply, and etching terms. Update base URL; Xverse may include additional market data (e.g., price). | +| `GET /balances/{address}` | Retrieves rune balances for a specific address. | Path param: `address` (string); optional filters like `runeId`. | `GET /v1/runes/balances/{address}` (via Sats Connect: `runes_getBalance`) | Fetches all rune balances for an address, including amounts and divisibility. | Path param: `address` (string); network (e.g., ‘Mainnet’). | Direct mapping for core functionality. Xverse returns spendable/available balances per rune; supports wallet integration. No explicit pagination, but full lists are provided. | +| `GET /activity/address/{address}` | Retrieves rune activity (transfers, etches) for a specific address. | Path param: `address` (string); `limit`, `offset`, optional `runeId` or event type filters. | `GET /v1/runes/transactions/{address}` (inferred from transaction parsing) | Queries transaction history including rune transfers and activity. | Path param: `address` (string); optional filters for confirmed/unconfirmed. | Partial mapping. Xverse supports rune-inclusive transaction history; filter client-side for rune-specific events. Includes mempool data. | +| `GET /activity/block/{blockHeight}` | Retrieves rune activity within a specific block. | Path param: `blockHeight` (integer). | None | N/A | N/A | No block-specific rune activity in Xverse. Workaround: Use general transaction history endpoints with block filters if available, or aggregate from address queries. | +| `GET /holders/{runeId}` | Lists holders and balances for a specific rune. | Path param: `runeId` (string); `limit`, `offset`. | None | N/A | N/A | No global holder listing in Xverse. Workaround: Requires custom aggregation from multiple balance queries or third-party tools. | + +For more details, check out the [Xverse Runes](https://docs.xverse.app/api/runes) reference. + +## Hiro-Specific Functionality for Runes Not Available in Xverse + +- Global etchings list (`/etchings`): Absent; Xverse focuses on per-rune or per-address data. +- Block-level activity (`/activity/block/{blockHeight}`): No equivalent; use Xverse’s transaction endpoints with block parameters if extended. +- Rune holder aggregation (`/holders/{runeId}`): Not supported; implement via batched balance calls. +- Xverse provides unique capabilities like mint/etch order management (e.g., `runes_estimateMint`, `runes_mint`, `runes_getOrder` via Sats Connect) and rune swaps (e.g., `/v1/swaps/runes/quotes`), which Hiro lacks. For comprehensive activity tracking, supplement Xverse with Bitcoin RPC or Hiro during transition. \ No newline at end of file diff --git a/content/docs/en/tools/bitcoin-indexer/index.mdx b/content/docs/en/tools/bitcoin-indexer/index.mdx index 3ff71f2dc..09c543ec6 100644 --- a/content/docs/en/tools/bitcoin-indexer/index.mdx +++ b/content/docs/en/tools/bitcoin-indexer/index.mdx @@ -9,6 +9,11 @@ llm: false The Bitcoin Indexer connects to your Bitcoin node, processes blocks in real-time, stores metaprotocol data in PostgreSQL, and serves REST APIs for each protocol. +:::callout +### Deprecation Notice +Ongoing maintainence and updates to the Bitcoin Indexer will stop on March 1st, 2026. The [Bitcoin Indexer repo](https://github.com/hirosystems/bitcoin-indexer) will continue to be open-sourced. +::: + ## Key features - **Metaprotocol indexing** - Built-in support for Ordinals, Runes, and BRC-20 with extensible architecture diff --git a/content/docs/en/tools/chainhooks/(overview)/migration.mdx b/content/docs/en/tools/chainhooks/(overview)/migration.mdx index c65781de3..5b55280aa 100644 --- a/content/docs/en/tools/chainhooks/(overview)/migration.mdx +++ b/content/docs/en/tools/chainhooks/(overview)/migration.mdx @@ -20,6 +20,7 @@ Legacy v1 chainhooks remain read-only in the Platform UI, but you manage them th :::prerequisites - Hiro API key for access to both the Platform and Chainhooks API. +- (optional) If you use TypeScript and Node.js, you can install the [Chainhooks client library](https://www.npmjs.com/package/@hirosystems/chainhooks-client) to easily parse incoming Chainhooks v2 payloads ::: @@ -223,6 +224,16 @@ await response.json(); For more details, check out the [Filters](/tools/chainhooks/reference/filters) reference page. +## Replaying past blocks + +Chainhooks v2 does not have the ability to specify a **start block** in a hook’s configuration for past block scans. + +However, you can use the [Replay Block API endpoint](https://docs.hiro.so/en/tools/chainhooks/evaluate) to request any block replay you need at any time. Once requested, you will receive that block’s information through the same webhook payload endpoint you use for real-time updates within a couple seconds. + +This method ensures you have complete control over which blocks you need to replay whenever you need to. + +See [Replay a block](/tools/chainhooks/(chainhook-sdk)/evaluate) for more information. + ## Next steps :::next-steps