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).

Get 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"
    }
  }
}

Get 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"
    }
  ]
}

Address 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

Get 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

Get 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,
		]
	  ]
	},
  ]
}

Get 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.

Get 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
  }
}

Get 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
	}
  ]
}