Skip to main content

Ordinals API Overview

The Ordinals API provides a service that indexes Bitcoin Ordinals data and offers a REST API to access and query this data.

NOTE:

To explore the detailed documentation for the API endpoints, request and response formats, you can refer to the OpenAPI specification.

The source code for this project is available in our GitHub repository. You can explore the codebase, contribute, and raise issues or pull requests.

Here are the key features of the Ordinals API:

Ordinal Inscription Ingestion: The API helps with the complete ingestion of ordinal inscriptions. Using our endpoitns, you can retrieve the metadata for a particular inscription, all inscriptions held by a particular address, trading activity for inscriptions, and more.

BRC-20 Support: The API offers support for BRC-20 tokens, a fungible token standard built on top of ordinal theory. Retrieve data for a particular BRC-20 token, a user's BRC-20 holdings, marketplace activity, and more.

REST JSON Endpoints with ETag Caching: The API provides easy-to-use REST endpoints that return responses in JSON format. It also supports ETag caching, which allows you to cache responses based on inscriptions. This helps optimize performance and reduce unnecessary requests.

Auto-Scale Server Configurations: The Ordinals API supports three run modes based on the RUN_MODE environment variable:

  • default: This mode runs all background jobs and the API server. It is suitable for running a single instance of the API.
  • readonly: Only the API server runs in this mode. It is designed for auto-scaled clusters with multiple readonly instances and a single writeonly instance. The writeonly instance is responsible for populating the database.
  • writeonly: This mode is used in an auto-scaled environment to consume new inscriptions and push that data to a database. It works in conjunction with multiple readonly instances.

Rate Limiting for Ordinals API

The Rate Limit per Minute(RPM) is applied to all the API endpoints based on the requested token addresses.

EndpointRate per minute(RPM) limit
api.mainnet.hiro.so/ordinals
500