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.
Retrieves a list of inscriptions with options to filter and sort results
Block Hash (string) or Block Height (string) (Block Identifier) Examples:
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 |
{- "limit": 20,
- "offset": 0,
- "total": 1,
- "results": [
- {
- "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": [
- "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218i0"
]
}
]
}
Retrieves a list of inscription transfers that ocurred at a specific Bitcoin block
required | Block Hash (string) or Block Height (string) (Block Identifier) Examples:
Bitcoin block identifier (height or hash) |
offset | integer (Offset) >= 0 Result offset |
limit | integer (Limit) [ 1 .. 60 ] Results per page |
{- "limit": 20,
- "offset": 0,
- "total": 1,
- "results": [
- {
- "id": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218i0",
- "number": 248751,
- "from": {
- "block_height": 778921,
- "block_hash": "0000000000000000000452773967cdd62297137cdaf79950c5e8bb0c62075133",
- "address": "bc1pvwh2dl6h388x65rqq47qjzdmsqgkatpt4hye6daf7yxvl0z3xjgq247aq8",
- "tx_id": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218",
- "location": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218:0:0",
- "output": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218:0",
- "value": "546",
- "offset": "0",
- "timestamp": 1677733170000
}, - "to": {
- "block_height": 778921,
- "block_hash": "0000000000000000000452773967cdd62297137cdaf79950c5e8bb0c62075133",
- "address": "bc1pvwh2dl6h388x65rqq47qjzdmsqgkatpt4hye6daf7yxvl0z3xjgq247aq8",
- "tx_id": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218",
- "location": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218:0:0",
- "output": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218:0",
- "value": "546",
- "offset": "0",
- "timestamp": 1677733170000
}
}
]
}
Retrieves a single inscription
required | Inscription ID (string) or Inscription Number (integer) (Inscription Identifier) Examples:
Inscription unique identifier (number or ID) |
{- "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": [
- "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218i0"
]
}
Retrieves the contents of a single inscription
required | Inscription ID (string) or Inscription Number (integer) (Inscription Identifier) Examples:
Inscription unique identifier (number or ID) |
{ }
Retrieves all transfers for a single inscription
required | Inscription ID (string) or Inscription Number (integer) (Inscription Identifier) Examples:
Inscription unique identifier (number or ID) |
offset | integer (Offset) >= 0 Result offset |
limit | integer (Limit) [ 1 .. 60 ] Results per page |
{- "limit": 20,
- "offset": 0,
- "total": 1,
- "results": [
- {
- "block_height": 778921,
- "block_hash": "0000000000000000000452773967cdd62297137cdaf79950c5e8bb0c62075133",
- "address": "bc1pvwh2dl6h388x65rqq47qjzdmsqgkatpt4hye6daf7yxvl0z3xjgq247aq8",
- "tx_id": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218",
- "location": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218:0:0",
- "output": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218:0",
- "value": "546",
- "offset": "0",
- "timestamp": 1677733170000
}
]
}
Retrieves ordinal information for a single satoshi
ordinal required | integer (Ordinal Number) [ 0 .. 2099999997690000 ) Example: 257418248345364 Ordinal number that uniquely identifies a satoshi |
{- "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"
}
Retrieves all inscriptions associated with a single satoshi
ordinal required | integer (Ordinal Number) [ 0 .. 2099999997690000 ) Example: 257418248345364 Ordinal number that uniquely identifies a satoshi |
offset | integer (Offset) >= 0 Result offset |
limit | integer (Limit) [ 1 .. 60 ] Results per page |
{- "limit": 20,
- "offset": 0,
- "total": 1,
- "results": [
- {
- "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": [
- "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218i0"
]
}
]
}
Retrieves information for BRC-20 tokens
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 |
{- "limit": 20,
- "offset": 0,
- "total": 1,
- "results": [
- {
- "id": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218i0",
- "number": 248751,
- "block_height": 752860,
- "tx_id": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218",
- "address": "bc1pvwh2dl6h388x65rqq47qjzdmsqgkatpt4hye6daf7yxvl0z3xjgq247aq8",
- "ticker": "PEPE",
- "max_supply": "21000000",
- "mint_limit": "100000",
- "decimals": 18,
- "deploy_timestamp": 1677733170000,
- "minted_supply": "1000000",
- "tx_count": 300000
}
]
}
Retrieves information for a BRC-20 token including supply and holders
ticker required | string |
{- "token": {
- "id": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218i0",
- "number": 248751,
- "block_height": 752860,
- "tx_id": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218",
- "address": "bc1pvwh2dl6h388x65rqq47qjzdmsqgkatpt4hye6daf7yxvl0z3xjgq247aq8",
- "ticker": "PEPE",
- "max_supply": "21000000",
- "mint_limit": "100000",
- "decimals": 18,
- "deploy_timestamp": 1677733170000,
- "minted_supply": "1000000",
- "tx_count": 300000
}, - "supply": {
- "max_supply": "21000000",
- "minted_supply": "1000000",
- "holders": 240
}
}
Retrieves a list of holders and their balances for a BRC-20 token
ticker required | string |
offset | integer (Offset) >= 0 Result offset |
limit | integer (Limit) [ 1 .. 60 ] Results per page |
{- "limit": 20,
- "offset": 0,
- "total": 1,
- "results": [
- {
- "address": "bc1pvwh2dl6h388x65rqq47qjzdmsqgkatpt4hye6daf7yxvl0z3xjgq247aq8",
- "overall_balance": "2000.00000"
}
]
}
Retrieves BRC-20 token balances for a Bitcoin address
address required | string (Address) Example: bc1p8aq8s3z9xl87e74twfk93mljxq6alv4a79yheadx33t9np4g2wkqqt8kc5 Bitcoin address |
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 |
{- "limit": 20,
- "offset": 0,
- "total": 1,
- "results": [
- {
- "ticker": "PEPE",
- "available_balance": "1500.00000",
- "transferrable_balance": "500.00000",
- "overall_balance": "2000.00000"
}
]
}
Retrieves BRC-20 activity filtered by ticker, address, operation, or at a specific block height
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 |
{- "limit": 20,
- "offset": 0,
- "total": 1,
- "results": [
- {
- "operation": "deploy",
- "ticker": "PEPE",
- "inscription_id": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218i0",
- "block_height": 778921,
- "block_hash": "0000000000000000000452773967cdd62297137cdaf79950c5e8bb0c62075133",
- "tx_id": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218",
- "location": "1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218:0:0",
- "address": "bc1pvwh2dl6h388x65rqq47qjzdmsqgkatpt4hye6daf7yxvl0z3xjgq247aq8",
- "timestamp": 1677733170000,
- "mint": {
- "amount": "1000000"
}, - "deploy": {
- "max_supply": "21000000",
- "mint_limit": "100000",
- "decimals": 18
}, - "transfer": {
- "amount": "1000000",
- "from_address": "bc1pvwh2dl6h388x65rqq47qjzdmsqgkatpt4hye6daf7yxvl0z3xjgq247aq8"
}, - "transfer_send": {
- "amount": "1000000",
- "from_address": "bc1pvwh2dl6h388x65rqq47qjzdmsqgkatpt4hye6daf7yxvl0z3xjgq247aq8",
- "to_address": "bc1pvwh2dl6h388x65rqq47qjzdmsqgkatpt4hye6daf7yxvl0z3xjgq247aq8"
}
}
]
}
Retrieves statistics on the number of inscriptions revealed per block
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 |
{- "results": [
- {
- "block_height": "778921",
- "block_hash": "0000000000000000000452773967cdd62297137cdaf79950c5e8bb0c62075133",
- "inscription_count": "100",
- "inscription_count_accum": "3100",
- "timestamp": 1677733170000
}
]
}