Ordinals API

Introduction

In order to use the Ordiscan API you first need to create an account and obtain an API key.

Your API key is used to authenticate all your requests to the Ordiscan API. You need to pass it as a Bearer token in the "Authorization" header:

Example request:

GET

/v1/inscription/{inscription_id}

curl -G https://api.ordiscan.com/v1/inscription/b61b0172d95e266c18aea0c624db987e971a5d6d4ebc2aaed85da4642d635735i0 \
  -H "Authorization: Bearer {token}"

Pricing Plans:

Free

/month

No strings attached.

200 requests /month

100 requests /minute

Standard

$59

/month

Billed monthly. Cancel anytime.

1M requests /month

100 requests /minute

Pro

$199

/month

Billed monthly. Cancel anytime.

5M requests /month

300 requests /minute

Inscriptions

Properties

Name
inscription_id
Type
string
Description
Unique identifier for the inscription.
Name
inscription_number
Type
number
Description
The inscription number.
Name
content_type
Type
string
Description
The inscription content type.
Name
owner_address
Type
string
Description
The current owner of the inscription (Bitcoin address).
Name
owner_output
Type
string
Description
The current tx output associated with the inscription.
Name
genesis_address
Type
string
Description
The initial owner of the inscription (Bitcoin address).
Name
genesis_output
Type
string
Description
The initial tx output associated with the inscription.
Name
timestamp
Type
string
Description
A datetime string for when the inscription was created.
Name
content_url
Type
string
Description
URL to the inscription content (can be a text file, image, video, etc).
Name
sat
Type
number
Description
The sat number that it's is inscribed on.
Name
satributes
Type
string array
Description
The satributes for the inscription (e.g. UNCOMMON, PIZZA, PALINDROME... etc).
Name
metadata
Type
object (nullable)
Description
A JSON object with the inscription's metadata. The data can be nested.
Name
metaprotocol
Type
string (nullable)
Description
The inscription's specified metaprotocol (e.g. cbrc-20:deploy).
Name
parent_inscription_id
Type
string (nullable)
Description
The inscription's parent, inscribed through Provenance
Name
delegate_inscription_id
Type
string (nullable)
Description
The inscription's nominated delegate
Name
submodules
Type
string array (optional)
Description
If it's a recursive inscription, this will return a list of inscription IDs that are being used as modules to generate the recursive inscription.
Name
sats_name
Type
string (optional)
Description
The sats name (e.g. tristan.sats) registered through this inscription (if the inscription is identified as a sats name).
Name
brc20_action
Type
object (optional)
Description
A BRC-20 Action object (if the inscription has been verified as a BRC-20 action).

Inscription info

Retrieve the info for a specific inscription. You need to supply either an inscription ID (id) or an inscription number (number) as a query parameter.

Parameters

One of the following must be supplied:

Name
id
Type
string
Description
The inscription ID (e.g. b61b0172d95e266c18aea0c624db987e971a5d6d4ebc2aaed85da4642d635735i0)
Name
number
Type
integer
Description
The inscription number (e.g. 224530)

GET

/v1/inscription

curl -G https://api.ordiscan.com/v1/inscription/b61b0172d95e266c18aea0c624db987e971a5d6d4ebc2aaed85da4642d635735i0 \
  -H "Authorization: Bearer {token}"

{
  "data": {
    "inscription_id": "b61b0172d95e266c18aea0c624db987e971a5d6d4ebc2aaed85da4642d635735i0",
    "inscription_number": 348020,
    "content_type": "text/plain;charset=utf-8",
    "owner_address": "bc1pxaneaf3w4d27hl2y93fuft2xk6m4u3wc4rafevc6slgd7f5tq2dqyfgy06",
    "owner_output": "b61b0172d95e266c18aea0c624db987e971a5d6d4ebc2aaed85da4642d635735:0",
    "genesis_address": "bc1pxaneaf3w4d27hl2y93fuft2xk6m4u3wc4rafevc6slgd7f5tq2dqyfgy06",
    "genesis_output": "b61b0172d95e266c18aea0c624db987e971a5d6d4ebc2aaed85da4642d635735:0",
    "timestamp": "2023-03-08T04:16:31.000Z",
    "content_url": "https://ordiscan.com/content/b61b0172d95e266c18aea0c624db987e971a5d6d4ebc2aaed85da4642d635735i0",
    "brc20_action": {
      "tick": "ORDI",
      "action": "DEPLOY"
    }
  }
}

List of inscriptions

Retrieve a list of inscriptions based on different filters. The max number of inscriptions returned per request is 100.

Parameters

Name
address
Type
string (optional)
Description
A valid Bitcoin address. Specify this to only return inscriptions owned by this address.
Name
content_type
Type
string (optional)
Description
Filter the inscriptions by content type (e.g. text/plain, image/jpeg...). You can specify multiple content types by separating them with a comma (,).
Name
sort
Type
string (optional)
Description
Specify the sorting order for the returned inscriptions. Can be either:
- inscription_number_desc (default). Sorts by descending inscription number.
- inscription_number_asc. Sorts by ascending inscription number.
Name
afterNumber
Type
integer (optional)
Description
Only return inscriptions above a certain inscription number. Useful for pagination.
Name
beforeNumber
Type
integer (optional)
Description
Only return inscriptions below a certain inscription number. Useful for pagination.

GET

/v1/inscriptions

curl -G https://api.ordiscan.com/v1/inscriptions \
  -H "Authorization: Bearer {token}" \
  -d address="112AmK5SB2uT7miUTqjLrcRJB7myLBM7xu"

{
  "data": [
    {
      "inscription_id": "1eabfab072b44f520bbc919abd8aba51dbebf5758c759e4572b7e1ad356fe647i0",
      "inscription_number": 1523361,
      "content_type": "text/plain;charset=utf-8",
      "owner_address": "112AmK5SB2uT7miUTqjLrcRJB7myLBM7xu",
      "owner_output": "71c28a89a7898f3c667f6f68022d263eb96afa283d6ed4cb900bd204638d7883:0",
      "timestamp": "2023-04-23T21:48:00.000Z",
      "content_url": "https://ordiscan.com/content/1eabfab072b44f520bbc919abd8aba51dbebf5758c759e4572b7e1ad356fe647i0"
    }
  ]
}

Activity

Properties

Name
txid
Type
string
Description
The TXID (Transaction ID) of the transaction
Name
type
Type
string
Description
The type of activity. Can be one of the following:
- SEND: the address sent an inscription to another address
- RECEIVE: the address received an inscription from another address
- INSCRIBE: the address created (and received) a new inscription
Name
inscription_id
Type
string
Description
Unique identifier for the inscription.
Name
counterpart_address
Type
string
Description
The Bitcoin address of the counterpart (if the activity is a SEND or RECEIVE)
Name
spent_as_fee
Type
boolean
Description
Whether the inscription was spent as a fee (if the activity is a SEND)
Name
confirmed
Type
boolean
Description
Whether the event has been confirmed or not yet (i.e. included in a block)
Name
timestamp
Type
string
Description
A datetime string for when the event occured

Address activity

Retrieve all Ordinals-related activity for a specific Bitcoin address. Limited to 10 events per page.

Parameters

Name
address
Type
string
Description
A valid Bitcoin address
Name
page
Type
number (optional)
Description
Used to retrieve the next page of activity (e.g. ?page=2)

GET

/v1/address/{bitcoin-address}/activity

curl -G https://api.ordiscan.com/v1/address/112AmK5SB2uT7miUTqjLrcRJB7myLBM7xu/activity \
  -H "Authorization: Bearer {token}"

{
  "data": [
    {
      "txid": "71c28a89a7898f3c667f6f68022d263eb96afa283d6ed4cb900bd204638d7883",
      "type": "RECEIVE",
      "inscription_id": "1eabfab072b44f520bbc919abd8aba51dbebf5758c759e4572b7e1ad356fe647i0",
      "counterpart_address": "bc1qmjru4ce5xuma66lsmw2pv38wv9nscq9nxmwkv9",
      "spent_as_fee": false,
      "confirmed": true,
      "timestamp": "2023-04-23T21:48:00.000Z"
    }
  ]
}

Rare sats

Ordiscan indexes a wide range of rare sat categories. You can read more about each satribute on the Rare sats page.

Available satributes:

UNCOMMON
RARE
EPIC
LEGENDARY
MYTHIC
BLACK_UNCOMMON
BLACK_RARE
BLACK_EPIC
BLACK_LEGENDARY
BLACK_MYTHIC
BLOCK_9
BLOCK_78
NAKAMOTO
FIRST_TX
VINTAGE
PIZZA
HITMAN
PALINDROME
ALPHA
OMEGA

Rare sats for address

Retrieve all rare sats for a specific Bitcoin address. If the address has no rare sats, it will return an empty array.

Parameters

Name
address
Type
string
Description
A valid Bitcoin address

GET

/v1/address/{bitcoin-address}/rare-sats

curl -G https://api.ordiscan.com/v1/address/bc1pxaneaf3w4d27hl2y93fuft2xk6m4u3wc4rafevc6slgd7f5tq2dqyfgy06/rare-sats \
  -H "Authorization: Bearer {token}"

{
  "data": [
    {
	  "satributes": [
	    "UNCOMMON",
	    "ALPHA"
	  ],
	  "ranges": [
	    [
		  1964333750000000,
		  1964333750000001
		],
	  ]
	},
    {
	  "satributes": [
		"PIZZA"
	  ],
	  "ranges": [
		[
          120485000000000,
          120485000001000,
		]
	  ]
	},
  ]
}

Sat ranges for UTXO

Get all the sat ranges for a specific UTXO, regardless of whether they contain any rare sats or not.

Parameters

Name
utxo
Type
string
Description
A valid Bitcoin UTXO (e.g. 3d57f76284e17370f1ce45e75f68b5960906c4117951607f20ddd19f85c15706:0)

GET

/v1/utxo/{utxo}/sat-ranges

curl -G https://api.ordiscan.com/v1/utxo/3d57f76284e17370f1ce45e75f68b5960906c4117951607f20ddd19f85c15706:0/sat-ranges \
  -H "Authorization: Bearer {token}"

{
  "data": [
    [
      740078609838558,
      740078609848558
    ]
  ]
}

BRC-20

BRC-20 is a metaprotocol on top of inscriptions. It's an account-based system where balances are tied to specific Bitcoin addresses.

Properties

Name
tick
Type
string
Description
The unique 4-character tick of the BRC-20 token.
Name
max_supply
Type
number
Description
The max supply available to mint.
Name
minted
Type
number
Description
The number of tokens minted so far.
Name
price
Type
string | null
Description
The current market price for the token in USD. This will only be available for the most well-known tokens, otherwise it returns null.

BRC-20 token info

Get info about a specific BRC-20 token.

Parameters

Name
tick
Type
string
Description
The unique tick of the token. Can be either uppercase or lowercase.

GET

/v1/brc20/{tick}

curl -G https://api.ordiscan.com/v1/brc20/ordi \
  -H "Authorization: Bearer {token}"

{
  "data": {
    "tick": "ORDI",
    "minted": 21000000,
    "maxSupply": 21000000,
    "price": 76.44
  }
}

BRC-20 balances

Get all BRC-20 balances for a Bitcoin address.

Parameters

Name
address
Type
string
Description
A valid Bitcoin address

GET

/v1/address/{bitcoin-address}/brc20

curl -G https://api.ordiscan.com/v1/address/bc1pxaneaf3w4d27hl2y93fuft2xk6m4u3wc4rafevc6slgd7f5tq2dqyfgy06/brc20 \
  -H "Authorization: Bearer {token}"

{
  "data": [
    {
      "tick": "ORDI",
      "balance": 150
	},
    {
      "tick": "SATS",
      "balance": 100000000
	}
  ]
}

Runes

Properties

Name
id
Type
string
Description
The unique ID for the Rune (example: 840000:1)
Name
name
Type
string
Description
The unique name of the rune, without spacers (example: UNCOMMONGOODS)
Name
formatted_name
Type
string
Description
The formatted name of the rune, with spacers (example: UNCOMMON•GOODS)
Name
number
Type
number
Description
The rune's unique sequential number.
Name
inscription_id
Type
string | null
Description
The parent inscription ID of the rune (if any). This usually acts as the rune's logo.
Name
decimals
Type
number
Description
The number of decimals supported.
Name
symbol
Type
string
Description
The rune's symbol.
Name
etching_txid
Type
string | null
Description
The ID of the bitcoin transaction that etched (created) the rune.
Name
timestamp_unix
Type
string | null
Description
The unix timestamp of the etching transaction. Returns null for the very first hard-coded rune (UNCOMMON•GOODS).
Name
premined_supply
Type
string
Description
The number of premined runes.
Name
current_supply
Type
string
Description
The current supply for this rune (includes the premine).
Name
current_mint_count
Type
number
Description
The current number of mint transactions for this rune.
Name
amount_per_mint
Type
string | null
Description
The number of runes created by 1 mint transaction. returns null if the rune doesn't support minting.
Name
mint_count_cap
Type
string | null
Description
The maximum number of mint transactions for the rune.
Name
mint_start_block
Type
number | null
Description
If set, the rune cannot be minted before this block.
Name
mint_end_block
Type
number | null
Description
If set, the rune cannot be minted after this block.

Rune info

Get the info for a rune.

Parameters

Name
name
Type
string
Description
The unique name of the rune (without spacers)

GET

/v1/rune/{name}

curl -G https://api.ordiscan.com/v1/rune/UNCOMMONGOODS \
  -H "Authorization: Bearer {token}"

{
  "data": {
    "id": "1:0",
    "name": "UNCOMMONGOODS",
    "formatted_name": "UNCOMMON•GOODS",
    "spacers": 128,
    "number": 0,
    "inscription_id": null,
    "decimals": 0,
    "mint_count_cap": "340282366920938463463374607431768211455",
    "symbol": "⧉",
    "etching_txid": null,
    "amount_per_mint": "1",
    "timestamp_unix": null,
    "premined_amount": "0",
    "mint_start_block": 840000,
    "mint_end_block": 1050000
  }
}

Rune balances

Get all rune balances for a Bitcoin address. The returned balances use the rune's smallest denomination, and therefore never have decimals.

Parameters

Name
address
Type
string
Description
A valid Bitcoin address

GET

/v1/address/{bitcoin-address}/runes

curl -G https://api.ordiscan.com/v1/address/bc1pxaneaf3w4d27hl2y93fuft2xk6m4u3wc4rafevc6slgd7f5tq2dqyfgy06/runes \
  -H "Authorization: Bearer {token}"

{
  "data": [
    {
      "name": "UNCOMMONGOODS",
      "balance": "10"
    },
    {
      "name": "RSICGENESISRUNE",
      "balance": "100000"
    },
    {
      "name": "DOGGOTOTHEMOON",
      "balance": "300000"
    },
  ]
}

Rune market info

Get the latest price and market cap for a rune.

Parameters

Name
name
Type
string
Description
The unique name of the rune (without spacers)

GET

/v1/rune/{name}/market

curl -G https://api.ordiscan.com/v1/rune/DOGGOTOTHEMOON/market \
  -H "Authorization: Bearer {token}"

{
{
  "data": {
    "price_in_sats": 4.15,
    "price_in_usd": 0.002529,
    "market_cap_in_btc": 4150,
    "market_cap_in_usd": 252851200
  }
}

Rune name unlock

Check when a specific rune name becomes available to etch.

Status can be:

ETCHED (name already taken)
AVAILABLE (name can be etched)
LOCKED (name hasn't been unlocked yet)
RESERVED (name is too long and can only be assigned randomly)

Parameters

Name
name
Type
string
Description
The desired name of the rune (without spacers)

GET

/v1/rune-name/{name}

curl -G https://api.ordiscan.com/v1/rune-name/HELLO \
  -H "Authorization: Bearer {token}"

{
  "data": {
    "name": "HELLO",
    "status": "LOCKED",
    "unlock_block_height": 975173,
    "unlock_block_timestamp": "2026-11-14T23:15:07.000Z"
  }
}