API docs by Redocly

Ordinals API (v4.0.2)

Download OpenAPI specification:Download

The Ordinals API is a service that indexes Bitcoin Ordinals data and exposes it via REST API endpoints.

Here are the key features of the Ordinals API:

  • Ordinal Inscription Ingestion: The Ordinals API helps with the complete ingestion of ordinal inscriptions. Using our endpoints, 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 Ordinals API also 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 Ordinals 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.

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

Source Repository

Inscriptions

Endpoints to query ordinal inscriptions

List of Inscriptions

Retrieves a list of inscriptions with options to filter and sort results

query Parameters
Block Hash (string) or Block Height (string) (Block Identifier)
Examples:
  • genesis_block=777654 -
  • genesis_block=0000000000000000000452773967cdd62297137cdaf79950c5e8bb0c62075133 -

Bitcoin block identifier (height or hash)

from_genesis_block_height
string (Block Height) ^[0-9]+$
Example: from_genesis_block_height=777678

Bitcoin block height

to_genesis_block_height
string (Block Height) ^[0-9]+$
Example: to_genesis_block_height=777678

Bitcoin block height

from_genesis_timestamp
integer (Timestamp)
Example: from_genesis_timestamp=1677731361

Block UNIX epoch timestamp (milliseconds)

to_genesis_timestamp
integer (Timestamp)
Example: to_genesis_timestamp=1677731361

Block UNIX epoch timestamp (milliseconds)

from_sat_ordinal
integer (Ordinal Number) [ 0 .. 2099999997690000 )
Example: from_sat_ordinal=257418248345364

Ordinal number that uniquely identifies a satoshi

to_sat_ordinal
integer (Ordinal Number) [ 0 .. 2099999997690000 )
Example: to_sat_ordinal=257418248345364

Ordinal number that uniquely identifies a satoshi

from_sat_coinbase_height
string (Block Height) ^[0-9]+$
Example: from_sat_coinbase_height=777678

Bitcoin block height

to_sat_coinbase_height
string (Block Height) ^[0-9]+$
Example: to_sat_coinbase_height=777678

Bitcoin block height

from_number
integer (Inscription Number)
Example: from_number=10500

Inscription number

to_number
integer (Inscription Number)
Example: to_number=10500

Inscription number

id
Array of strings (Inscription IDs)
Example: id=38c46a8bf7ec90bc7f6b797e7dc84baa97f4e5fd4286b92fe1b50176d03b18dci0&id=e3af144354367de58c675e987febcb49f17d6c19e645728b833fe95408feab85i0

Array of inscription IDs

number
Array of integers (Inscription Numbers)
Example: number=10500&number=65

Array of inscription numbers

output
string (Transaction Output) ^[a-fA-F0-9]{64}:[0-9]+$
Example: output=8f46f0d4ef685e650727e6faf7e30f23b851a7709714ec774f7909b3fb5e604c:0

An UTXO for a Bitcoin transaction

address
Array of strings (Addresses)
Example: address=bc1p8aq8s3z9xl87e74twfk93mljxq6alv4a79yheadx33t9np4g2wkqqt8kc5&address=bc1pscktlmn99gyzlvymvrezh6vwd0l4kg06tg5rvssw0czg8873gz5sdkteqj

Array of Bitcoin addresses

genesis_address
Array of strings (Addresses)
Example: genesis_address=bc1p8aq8s3z9xl87e74twfk93mljxq6alv4a79yheadx33t9np4g2wkqqt8kc5&genesis_address=bc1pscktlmn99gyzlvymvrezh6vwd0l4kg06tg5rvssw0czg8873gz5sdkteqj

Array of Bitcoin addresses

mime_type
Array of strings (MIME Types)
Example: mime_type=image/png&mime_type=image/jpeg

Array of inscription MIME types

Array of Rarity (string) or Rarity (string) or Rarity (string) or Rarity (string) or Rarity (string) or Rarity (string) (Rarity)
Example: rarity=common&rarity=uncommon

Array of satoshi rarity values

recursive
boolean (Recursive)

Whether or not the inscription is recursive

cursed
boolean (Cursed)

Whether or not the inscription is cursed

offset
integer (Offset) >= 0

Result offset

limit
integer (Limit) [ 1 .. 60 ]

Results per page

Order By (string) or Order By (string) or Order By (string) or Order By (string) (Order By)

Parameter to order results by

Order (string) or Order (string) (Order)

Results order

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "total": 1,
  • "results": [
    ]
}

Transfers per block

Retrieves a list of inscription transfers that ocurred at a specific Bitcoin block

query Parameters
required
Block Hash (string) or Block Height (string) (Block Identifier)
Examples:
  • block=777654 -
  • block=0000000000000000000452773967cdd62297137cdaf79950c5e8bb0c62075133 -

Bitcoin block identifier (height or hash)

offset
integer (Offset) >= 0

Result offset

limit
integer (Limit) [ 1 .. 60 ]

Results per page

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "total": 1,
  • "results": [
    ]
}

Specific Inscription

Retrieves a single inscription

path Parameters
required
Inscription ID (string) or Inscription Number (integer) (Inscription Identifier)
Examples:
  • 145000 -
  • 38c46a8bf7ec90bc7f6b797e7dc84baa97f4e5fd4286b92fe1b50176d03b18dci0 -

Inscription unique identifier (number or ID)

Responses

Response samples

Content type
application/json
{
  • "id": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218i0",
  • "number": 248751,
  • "address": "bc1pvwh2dl6h388x65rqq47qjzdmsqgkatpt4hye6daf7yxvl0z3xjgq247aq8",
  • "genesis_address": "bc1pvwh2dl6h388x65rqq47qjzdmsqgkatpt4hye6daf7yxvl0z3xjgq247aq8",
  • "genesis_block_height": 778921,
  • "genesis_block_hash": "0000000000000000000452773967cdd62297137cdaf79950c5e8bb0c62075133",
  • "genesis_tx_id": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218",
  • "genesis_fee": "3179",
  • "genesis_timestamp": 0,
  • "tx_id": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218",
  • "location": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218:0:0",
  • "output": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218:0",
  • "value": "546",
  • "offset": "0",
  • "sat_ordinal": "1232735286933201",
  • "sat_rarity": "common",
  • "sat_coinbase_height": 430521,
  • "mime_type": "text/plain",
  • "content_type": "text/plain;charset=utf-8",
  • "content_length": 59,
  • "timestamp": 1677733170000,
  • "curse_type": "p2wsh",
  • "recursive": true,
  • "recursion_refs": [
    ],
  • "parent": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218i0",
  • "metadata": { }
}

Inscription content

Retrieves the contents of a single inscription

path Parameters
required
Inscription ID (string) or Inscription Number (integer) (Inscription Identifier)
Examples:
  • 145000 -
  • 38c46a8bf7ec90bc7f6b797e7dc84baa97f4e5fd4286b92fe1b50176d03b18dci0 -

Inscription unique identifier (number or ID)

Responses

Response samples

Content type
application/json
{ }

Inscription transfers

Retrieves all transfers for a single inscription

path Parameters
required
Inscription ID (string) or Inscription Number (integer) (Inscription Identifier)
Examples:
  • 145000 -
  • 38c46a8bf7ec90bc7f6b797e7dc84baa97f4e5fd4286b92fe1b50176d03b18dci0 -

Inscription unique identifier (number or ID)

query Parameters
offset
integer (Offset) >= 0

Result offset

limit
integer (Limit) [ 1 .. 60 ]

Results per page

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "total": 1,
  • "results": [
    ]
}

Satoshis

Endpoints to query Satoshi ordinal and rarity information

Satoshi Ordinal

Retrieves ordinal information for a single satoshi

path Parameters
ordinal
required
integer (Ordinal Number) [ 0 .. 2099999997690000 )
Example: 257418248345364

Ordinal number that uniquely identifies a satoshi

Responses

Response samples

Content type
application/json
{
  • "coinbase_height": 752860,
  • "cycle": 0,
  • "decimal": "752860.20444193",
  • "degree": "0°122860′892″20444193‴",
  • "inscription_id": "ff4503ab9048d6d0ff4e23def81b614d5270d341ce993992e93902ceb0d4ed79i0",
  • "epoch": 3,
  • "name": "ahehcbywzae",
  • "offset": 20444193,
  • "percentile": "91.15654869285287%",
  • "period": 373,
  • "rarity": "common"
}

Satoshi Inscriptions

Retrieves all inscriptions associated with a single satoshi

path Parameters
ordinal
required
integer (Ordinal Number) [ 0 .. 2099999997690000 )
Example: 257418248345364

Ordinal number that uniquely identifies a satoshi

query Parameters
offset
integer (Offset) >= 0

Result offset

limit
integer (Limit) [ 1 .. 60 ]

Results per page

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "total": 1,
  • "results": [
    ]
}

BRC-20

Endpoints to query BRC-20 token balances and events

BRC-20 Tokens

Retrieves information for BRC-20 tokens

query Parameters
ticker
Array of strings
Order By (string) or Order By (string) (Order By)

Parameter to order results by

offset
integer (Offset) >= 0

Result offset

limit
integer (Limit) [ 1 .. 60 ]

Results per page

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "total": 1,
  • "results": [
    ]
}

BRC-20 Token Details

Retrieves information for a BRC-20 token including supply and holders

path Parameters
ticker
required
string

Responses

Response samples

Content type
application/json
{
  • "token": {
    },
  • "supply": {
    }
}

BRC-20 Token Holders

Retrieves a list of holders and their balances for a BRC-20 token

path Parameters
ticker
required
string
query Parameters
offset
integer (Offset) >= 0

Result offset

limit
integer (Limit) [ 1 .. 60 ]

Results per page

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "total": 1,
  • "results": [
    ]
}

BRC-20 Balances

Retrieves BRC-20 token balances for a Bitcoin address

path Parameters
address
required
string (Address)
Example: bc1p8aq8s3z9xl87e74twfk93mljxq6alv4a79yheadx33t9np4g2wkqqt8kc5

Bitcoin address

query Parameters
ticker
Array of strings
block_height
string (Block Height) ^[0-9]+$
Example: block_height=777678

Bitcoin block height

offset
integer (Offset) >= 0

Result offset

limit
integer (Limit) [ 1 .. 60 ]

Results per page

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "total": 1,
  • "results": [
    ]
}

BRC-20 Activity

Retrieves BRC-20 activity filtered by ticker, address, operation, or at a specific block height

query Parameters
ticker
Array of strings
block_height
string (Block Height) ^[0-9]+$
Example: block_height=777678

Bitcoin block height

Array of Operation (string) or Operation (string) or Operation (string) or Operation (string) (Operation)
address
string (Address)
Example: address=bc1p8aq8s3z9xl87e74twfk93mljxq6alv4a79yheadx33t9np4g2wkqqt8kc5

Bitcoin address

offset
integer (Offset) >= 0

Result offset

limit
integer (Limit) [ 1 .. 60 ]

Results per page

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "total": 1,
  • "results": [
    ]
}

Statistics

Endpoints to query statistics on ordinal inscription data

Inscription Count per Block

Retrieves statistics on the number of inscriptions revealed per block

query Parameters
from_block_height
string (Block Height) ^[0-9]+$
Example: from_block_height=777678

Bitcoin block height

to_block_height
string (Block Height) ^[0-9]+$
Example: to_block_height=777678

Bitcoin block height

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Status

API Status

Displays the status of the API

Responses

Response samples

Content type
application/json
{
  • "server_version": "",
  • "status": "string",
  • "block_height": 0,
  • "max_inscription_number": 0,
  • "max_cursed_inscription_number": 0
}