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:
curl -G https://api.ordiscan.com/v1/inscription/b61b0172d95e266c18aea0c624db987e971a5d6d4ebc2aaed85da4642d635735i0 \
-H "Authorization: Bearer {token}"
Pricing Plans:
Free
$0
/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
)
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.
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 addressRECEIVE
: the address received an inscription from another addressINSCRIBE
: 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
orRECEIVE
)
- 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
)
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
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
)
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.
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
curl -G https://api.ordiscan.com/v1/address/bc1pxaneaf3w4d27hl2y93fuft2xk6m4u3wc4rafevc6slgd7f5tq2dqyfgy06/brc20 \
-H "Authorization: Bearer {token}"
{
"data": [
{
"tick": "ORDI",
"balance": 150
},
{
"tick": "SATS",
"balance": 100000000
}
]
}