ordinalsbot.com API Documentation
Create and Track ordinal inscriptions programmatically, pay with Lightning or onchain BTC.
Instructions on how to use ordinalsbot.com API to generate inscription orders from anywhere, pay with Lightning or onchain Bitcoin and receive the inscriptions to the provided address.
Contact
OrdinalsBot Discord: https://discord.gg/3hwsTRhtp3
Twitter: https://twitter.com/ordinalsbot
API info
API root is at: https://ordinalsbot.com/api
You can use https://ordinalsbot.com/api/status to check for API status and availability.
API root is currently in the process of being migrated to https://api2.ordinalsbot.com. Please double check API root for a particular endpoint.
This service takes some files as input, inscribes them on the bitcoin blockchain as explained on https://docs.ordinals.com and sends the inscribed UTXO to the provided bitcoin address.
No guarantees are made on the quality or speed of the inscription.
Signet
You can use our signet instance for testing the API.
Signet API root is at https://signet.ordinalsbot.com/api and Web UI is at https://signet.ordinalsbot.com
https://signet.ordinalsbot.com/api/status to check for signet API status and availability.
You can download a signet wallet at https://github.com/nbd-wtf/obw/releases and get signet coins from faucets like https://signet.bc-2.jp.
All endpoints except text and image hash search will work on the signet instance. Just replace the API root with signet endpoint.
Getting Prices
Use this endpoint to check the price (in satoshis) that user will need to pay to use services offered by this API.
Get Inscription Price (in satoshis)
GET https://ordinalsbot.com/api/price
This endpoint will calculate all fees related to the operation and return the total as well as the breakdown.
Query Parameters
fee*
Number
Miner fee that will be paid while inscribing the ordinal in sats/byte. (default=2 sats/byte)
count
Number
Number of files to be inscribed (default=1)
size*
Number
Total size of all files to be inscribed in bytes
rareSats
String
Inscribe on a rare, exotic, early sat. Options: 2009 | 2010 | 2011 | block78 | pizza | uncommon | random
(default=random)
{
"status": "ok",
"chainFee": 9458, // chain fee that will be paid to miners
"baseFee": 100000, // base service fee taken by ordinalsbot.com
"serviceFee": 100945, // total service fee taken by ordinalsbot.com
"totalFee": 110403 // total amount to be paid by the user
}Creating an Inscription Order
Use this endpoint to create an inscription order that will be processed once the related invoice is paid.
There's currently a limit of 10000 files per order.
Make sure images are optimized size (preferably converted to .webp) and uploaded to ordinalsbot bucket in an accessible location.
if you choose to send file contents as base64 dataURL instead of url, there's a limit of 50MB per API call.
Create Order
POST https://api2.ordinalsbot.com/order
Remember to include headers with your POST request:
headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' }
Request Body
files*
Array
An array of objects that includes:
name:string; => name of the file including extension.
size:number; => size of the file in bytes
url:string; => publicly accessible image URL
Note: you can send base64 encoded text/image/video data in a parameter called dataURL instead of url
fee
Number
Miner fee that will be paid while inscribing the ordinals in sats/byte. (default=2 sats/byte)
referral
String
referral code to earn up to %15 of the order service fee.
receiveAddress*
String|Array
A single Bitcoin address to receive the inscriptions for the whole order OR An array of strings of Bitcoin addresses to receive each corresponding item from files array.
lowPostage
Boolean
Inscribe file with minimum postage (padding) 546 sats instead of the standard 10,000 sats.
(default=false)
rareSats
String
Inscribe on a rare, exotic or early sat. Options: 2009 | 2010 | 2011 | block78 | pizza | uncommon | random
Check /inventory endpoint for all available options and their current availability.
webhookUrl
String
webhook url to receive a POST payload for order updates with below object: {
id: xxx, => orderId index: 0, => index of file in the original order request file array file: {...} => file object for the update tx: {reveal, inscription, commit} => inscription related transaction data
}
additionalFee
Number
Amount of satoshis to charge extra for this order that will be added to "referral" account.
Needs to be used together with "referral"
{
status: 'ok',
..., // input parameters
charge: {
...
"id": "815xxx-xxx-xxx-xxx79",
"address": "3P...Vu",
"amount": 1218725,
"lightning_invoice": {
"expires_at": 1675786558,
"payreq": "lnbc1218...7qz9v"
},
"created_at": 1677176476,
},
chainFee: 718725 // in satoshis
serviceFee: 100000, // in satoshis
orderType: 'bulk',
createdAt: 1675785959855, // timestamp in ms,
}Supported file extensions may change. If you include any unsupported files order creation will fail.
Currently Supported files:
'apng', 'flac', 'gif', 'html', 'jpg','jpeg', 'mp3', 'pdf', 'png', 'svg', 'txt', 'wav', 'webm', 'webp', 'mp4', 'stl', 'glb', 'avif', 'yaml' , 'yml', 'asc', 'json', 'js', 'css'
Getting Order Status
Use this endpoint to check the status of an order
Get Order Status
GET https://api2.ordinalsbot.com/order
Check an inscription order status.
Query Parameters
id*
String
Order ID returned by the `/bulkorder` endpoint
{
status: 'ok',
paid: true, // order payment successfully received
underpaid: true, // order is underpaid => user needs to complete the payment.
expired: true, // order payment is not received in the allocated time,
tx: {
"commit": "edc...be9",
"fees": 157840,
"inscription": "dff...5i0",
"reveal": "dff...0c5"
}, // inscription data as returned by ord wallet
sent: '4axxxdeadbeef', // order is inscribed and sent to the provided address
}Create a Collection for On-Demand Inscription
Use this endpoint to create a collection that other users will be able to create orders on and inscribe on demand.
All collections must be approved by the ordinalsbot.com team before they go live.
Collections with over 1000 items need to be manually uploaded.
Get in touch with us on Discord.
Create Collection
POST https://ordinalsbot.com/api/collectioncreate
Request Body
files
Object
An array of objects that includes:
name:string; => name of the file including extension.
size:number; => size of the file in bytes
url:string; => publicly accessible image URL
You can also provide files manually after contacting us.
fee
Number
Miner fee that will be paid while inscribing the ordinals in sats/byte. (default=2 sats/byte)
receiveAddress
String
Bitcoin address to receive payouts from inscriptions
id*
String
URL safe unique collection slug.
Will be used as mint URL.
name*
String
Collection Display Name
description*
String
Collection description
creator*
String
Collection creator
price*
Number
Inscription price per file (for collection creator)
set to 0 for free mints
serviceFee
Number
Inscription service fee per file taken by ordinalsbot.com
min: 27000 (sats)
totalCount*
Number
Max supply of the collection.
{
status: 'ok',
..., // input parameters
createdAt: 1675785959855, // timestamp in ms,
}Create Collection Inscription Order
Use this endpoint to create an inscription order that will inscribe a file from an existing collection.
Create Collection Order
POST https://ordinalsbot.com/api/collectionorder
Request Body
receiveAddress
String
Bitcoin address to receive the inscriptions for the whole order
collection*
Object
Object including
id: Collection slug to be inscribed
count: number of inscriptions being ordered.
rareSats (optional): 2009 | 2010 | 2011 | block78 | pizza | uncommon | random
Check /inventory endpoint for all available options and their current availability.
{
status: 'ok',
..., // input parameters
charge: {
...
"id": "815xxx-xxx-xxx-xxx79",
"address": "3P...Vu",
"amount": 1218725,
"lightning_invoice": {
"expires_at": 1675786558,
"payreq": "lnbc1218...7qz9v"
},
"created_at": 1677176476,
},
chainFee: 718725 // in satoshis
serviceFee: 100000, // in satoshis
orderType: 'bulk',
createdAt: 1675785959855, // timestamp in ms,
}Create Text Inscription Order
Use this endpoint to create an inscription order that will inscribe some text string.
Create Text Order
POST https://ordinalsbot.com/api/textorder
Request Body
texts*
Array
An array of strings to be inscribed
fee
Number
Miner fee that will be paid while inscribing the ordinals in sats/byte. (default=2 sats/byte)
referral
String
referral code to earn up to %15 of the order service fee.
receiveAddress*
String
Bitcoin address to receive the inscriptions for the whole order
{
status: 'ok',
..., // input parameters
charge: {
...
"id": "815xxx-xxx-xxx-xxx79",
"address": "3P...Vu",
"amount": 1218725,
"lightning_invoice": {
"expires_at": 1675786558,
"payreq": "lnbc1218...7qz9v"
},
"created_at": 1677176476,
},
chainFee: 718725 // in satoshis
serviceFee: 100000, // in satoshis
orderType: 'bulk',
createdAt: 1675785959855, // timestamp in ms,
}Search Existing Text Inscriptions
Use this endpoint to check if a certain text string was used in an inscription before.
Search for Text
GET https://api2.ordinalsbot.com/search
Check for previous occurrences of a text in inscriptions. Results array will be sorted by ascending block height.
Query Parameters
text*
String
Text string to search for e.g. zzz.sats or "satoshi"
{
"status":"ok",
"results":
[
{
"txid":"e0...7d",
"inputindex":"0",
"inscriptionid":"e05...di0",
"blockheight":"778211", // use blockheight as timestamp
"contenttypestr":"text/plain;charset=utf-8",
"content":"7b0...7d",
"contentstr":"{\n \"p\": \"sns\",\n \"op\": \"reg\",\n \"name\": zzz.sats\"\n}",
"contenthash":"7237...468",
"contentlength":"58",
"createdat":"2023-03-08T20:58:17.950Z" // this is when record is parsed - not the block timestamp
},
...
]
}Search Existing Image Inscriptions
Use this endpoint to check if a certain image was inscribed before.
const base64encodedimage = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAoElEQVR42u2VMQ6AMAhFe0fT1d3V3cv0ojUxaoBSBEo3Sf7S6n+UIqb0R2BUoHjjnPOrSBAyphqFiOajEJW5F9KrdyMvBL10lK0r+qwJ8GVOIVoAm/26L5eg8bNmPQWbfb1rzq3B+3ADaPZwzQJoukZ7B1qICkD3wgHTTzAVwO1ZOwlBep3DQc1tqimR1Vz8FqSB55qmEmD0fyACmBEuxglnHBu4i1egeQAAAABJRU5ErkJggg=='
const buff = Buffer.from(base64encodedimage.split(";base64,")[1], 'base64');
const imageHash = bitcoin.crypto.sha256(buff).toString('hex')Search for Image
GET https://api2.ordinalsbot.com/search
Check for previous occurrences of an image in inscriptions. Results array will be sorted by ascending block height.
Query Parameters
hash*
String
sha256 hash of an image buffer in hex
{
"status":"ok",
"results":
[
{
"txid":"ea0d...a8",
"inputindex":"0",
"inscriptionid":"ea0d....8i0",
"blockheight":"775528", // use blockheight as timestamp
"contenttypestr":"image/png",
"contenthash":"59edca9...a9ca4c80d",
"contentlength":"217",
"createdat":"2023-03-08T16:30:38.690Z" // this is when record is parsed - not the block timestamp
},
...
]
}Check Rare Sats Inventory
Use this endpoint to check any rare, special, vintage sats available to be used in individual or collection inscriptions.
Check Rare Sats Inventory
GET https://ordinalsbot.com/api/inventory
Check for available special sats that are available to be inscribed on. This endpoint will return their available count, price and max file size that can be handled.
Each property can be used as input when creating inscription orders, for instance: rareSats: block9
{
"2009": {
"amount": 24417855,
"baseFee": 50000,
"count": 33,
"maxSize": 4812114,
"minSize": 526
},
"2010": {
"amount": 10215796,
"baseFee": 30000,
"count": 130,
"maxSize": 616822,
"minSize": 516
},
"2011": {
"amount": 18998180,
"baseFee": 20000,
"count": 189,
"maxSize": 998200,
"minSize": 385
},
"block490": {
"amount": 0,
"baseFee": 25000,
"count": 0,
"maxSize": 0,
"minSize": 100000000
},
"block78": {
"amount": 6280406,
"baseFee": 25000,
"count": 1,
"maxSize": 1000000,
"minSize": 5502
},
"block9": {
"amount": 5010920,
"baseFee": 25000,
"count": 14,
"maxSize": 1000000,
"minSize": 546
},
"block940": {
"amount": 1402536,
"baseFee": 25000,
"count": 1,
"maxSize": 695417,
"minSize": 11702
},
"btcmachines_glam": {
"amount": 8261264,
"baseFee": 178787,
"count": 3,
"maxSize": 872758,
"minSize": 3780
},
"pizza": {
"amount": 5994604,
"baseFee": 25000,
"count": 1,
"maxSize": 1000000,
"minSize": 49996
},
"rare_1": {
"amount": 125087769,
"baseFee": 3000000,
"count": 15,
"maxSize": 5000000,
"minSize": 9500
},
"updatedAt": 1690389598311
}Getting Referral Earnings
Remember you can always earn referral commissions without using the API.
Just share your referral link https://ordinalsbot.com/?ref=your-referral-code with your community, visitors or followers and you'll automatically earn referral commissions from the inscriptions they make.
Use this endpoint to check earnings for your referrals code
Get Referral Status
GET https://ordinalsbot.com/api/referrals
Check referral earning status.
Your referral earning is calculated as
paidCount * serviceFee profit * 0.15
(e.g. 100 * 15000 (sats) * %15 commission)
Query Parameters
referral*
String
Your referral code
address*
String
Your bitcoin address that you've set for payouts
{
"address":"bc1qxxx",
"orderCount":962, // how many orders were created with your reflink
"paidCount":305 // how many paid orders were processed.
}Saving Referral Code
Use this endpoint to set a unique referral code for yourself.
Set Referral Code and Payout Address
POST https://ordinalsbot.com/api/referrals
Use this endpoint to set your referral code and payout address. Your address allows you to query your referral earnings.
Request Body
referral*
String
Your unique referral code
address*
String
Your bitcoin address that you want to receive payouts to.
{
"status":"ok" // your information is saved.
}Last updated