|
| 1 | +--- |
| 2 | +title: Migration guide |
| 3 | +description: Guide for migrating to using the L1 APIs from Xverse |
| 4 | +llm: true |
| 5 | +--- |
| 6 | + |
| 7 | +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. |
| 8 | + |
| 9 | +:::callout |
| 10 | +### Using Xverse's L1 APIs |
| 11 | +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. |
| 12 | +::: |
| 13 | + |
| 14 | +## Timeline |
| 15 | +- Announcement date: Feburary 7th, 2026 |
| 16 | +- Deprecation effective: March 1st, 2026 |
| 17 | + |
| 18 | +## What you'll learn |
| 19 | + |
| 20 | +:::objectives |
| 21 | +- Capture and analyze all existing Ordinals and BRC-20 API endpoints. |
| 22 | +- Maps the API endpoint equivalent to the applicable endpoint with Xverse. |
| 23 | +- Note any differences and changes you'll need to be aware of. |
| 24 | +::: |
| 25 | + |
| 26 | +## Ordinals endpoint mappings |
| 27 | + |
| 28 | +### List of endpoints and its Xverse endpoint equivalent |
| 29 | +| Hiro Endpoint | Description (Hiro) | Key Parameters (Hiro) | Xverse Equivalent Endpoint | Description (Xverse Equivalent) | Key Parameters (Xverse) | Migration Notes | |
| 30 | +| --- | --- | --- | --- | --- | --- | --- | |
| 31 | +| `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. | |
| 32 | +| `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. | |
| 33 | +| `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. | |
| 34 | +| `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. | |
| 35 | +| `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`. | |
| 36 | +| `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. | |
| 37 | +| `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`). | |
| 38 | +| `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`. | |
| 39 | +| `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. | |
| 40 | +| `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`. | |
| 41 | + |
| 42 | +For more details, check out the [Xverse Ordinals](https://docs.xverse.app/api/ordinals) reference. |
| 43 | + |
| 44 | +## Hiro-Specific Functionality for Ordinals Not Available in Xverse |
| 45 | + |
| 46 | +- `GET /inscriptions/{inscriptionId}/sat`: Dedicated satoshi retrieval for an inscription. Xverse includes basic sat_ordinal in inscription details but not full satoshi metadata. |
| 47 | +- Advanced filtering in `GET /inscriptions`: |
| 48 | + - `sat_ordinal_range`: Filter by satoshi ordinal range. |
| 49 | + - `content_length_range`: Filter by content size range. |
| 50 | + - `tag`: Filter by inscription tags. |
| 51 | +- No Xverse support for inscription tagging or content-length-based queries, which may necessitate client-side filtering post-retrieval. |
| 52 | + |
| 53 | +## BRC-20 endpoint mappings |
| 54 | + |
| 55 | +### List of endpoints and its Xverse endpoint equivalent |
| 56 | +| Hiro Endpoint | Description (Hiro) | Key Parameters (Hiro) | Xverse Equivalent Endpoint | Description (Xverse Equivalent) | Key Parameters (Xverse) | Migration Notes | |
| 57 | +| --- | --- | --- | --- | --- | --- | --- | |
| 58 | +| `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. | |
| 59 | +| `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 | |
| 60 | +| `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. | |
| 61 | +| `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. | |
| 62 | +| `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. | |
| 63 | + |
| 64 | +For more details, check out the [Xverse BRC-20](https://docs.xverse.app/api/brc-20) reference. |
| 65 | + |
| 66 | +## Hiro-Specific Functionality for BRC-20 Not Available in Xverse |
| 67 | + |
| 68 | +- Global token listing (`/ordinals/brc-20/tokens`): No equivalent; Xverse prioritizes per-address or per-user data. |
| 69 | +- Token holder lists (`/ordinals/brc-20/tokens/{ticker}/holders`): Absent; requires aggregation from balances or external sources. |
| 70 | +- Token event history (`/ordinals/brc-20/tokens/{ticker}/events`): No dedicated endpoint; use address history with filtering. |
| 71 | +- 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. |
0 commit comments