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

Name	Type	Description
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)

200: OK

{
    "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

Name	Type	Description
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"

200: OK

{
    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,
}

500: Internal Server Error

{
    status: 'error',
    error: 'error reason'
}

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

Name	Type	Description
id*	String	Order ID returned by the `/bulkorder` endpoint

200: OK Normal Response

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

500: Internal Server Error Server side error

{
    status: 'error',
    reason: 'unable to save data'
}

200: OK Error Response with Cause

{
    status: 'error', 
    error: 'error reason'
}

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

Name	Type	Description
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.

200: OK

{
    status: 'ok',
    ..., // input parameters
    createdAt: 1675785959855, // timestamp in ms,
}

500: Internal Server Error

{
    status: 'error',
    error: 'error reason'
}

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

Name	Type	Description
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.

200: OK

{
    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,
}

500: Internal Server Error

{
    status: 'error',
    error: 'error reason'
}

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

Name	Type	Description
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

200: OK

{
    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,
}

500: Internal Server Error

{
    status: 'error',
    error: 'error reason'
}

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

Name	Type	Description
text*	String	Text string to search for e.g. zzz.sats or "satoshi"

200: OK Normal Response

{
    "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
        },
        ...
    ]
}

500: Internal Server Error Server side error

{
    status: 'error',
    reason: 'server error'
}

200: OK Error Response with Cause

{
    status: 'error', 
    error: 'error reason'
}

Search Existing Image Inscriptions

Use this endpoint to check if a certain image was inscribed before.

Image Search is done by hashing the image file and checking against previous inscriptions' hashes.

To use this endpoint you need to sha256 hash the image file content as below:

  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

Name	Type	Description
hash*	String	sha256 hash of an image buffer in hex

200: OK Normal Response

{
    "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
        },
        ...
    ]
}

500: Internal Server Error Server side error

{
    status: 'error',
    reason: 'server error'
}

200: OK Error Response with Cause

{
    status: 'error', 
    error: 'error reason'
}

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

200: OK Normal Response

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

500: Internal Server Error Server side error

{
    status: 'error',
    reason: 'server error'
}

200: OK Error Response with Cause

{
    status: 'error', 
    error: 'error reason'
}

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

Name	Type	Description
referral*	String	Your referral code
address*	String	Your bitcoin address that you've set for payouts

200: OK Normal Response

{
    "address":"bc1qxxx",
    "orderCount":962, // how many orders were created with your reflink
    "paidCount":305 // how many paid orders were processed.
}

500: Internal Server Error Server side error

{
    status: 'error',
    reason: 'unable to check data'
}

200: OK Error Response with Cause

{
    status: 'error', 
    error: 'error reason'
}

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

Name	Type	Description
referral*	String	Your unique referral code
address*	String	Your bitcoin address that you want to receive payouts to.

200: OK Normal Response

{
    "status":"ok" // your information is saved.
}

500: Internal Server Error Server side error

{
    status: 'error',
    reason: 'unable to set data'
}

200: OK Error Response with Cause

{
    status: 'error', 
    error: 'referral code already exists - pick another one'
}

Get in touch for any questions regarding referral setup on satoshibles discord: https://join.satoshibles.com