# ordinalsbot.com API Documentation Instructions on how to use [ordinalsbot.com](https://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: Twitter: ### API info API root is at: You can use to check for API status and availability. API root is currently in the process of being migrated to . Please double check API root for a particular endpoint. {% hint style="warning" %} This service takes some files as input, inscribes them on the bitcoin blockchain as explained on [https://docs.ordinals.com](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. {% endhint %} ### Signet You can use our [signet](https://en.bitcoin.it/wiki/Signet) instance for testing the API. Signet API root is at and Web UI is at [https://signet.ordinalsbot.com](https://signet.ordinalsbot.com/api) [https://signet.ordinalsbot.com/api/status](https://ordinalsbot.com/api/status) to check for signet API status and availability. You can download a signet wallet at and get signet coins from faucets like [https://signet.bc-2.jp](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)

| {% tabs %} {% tab title="200: OK " %} ```javascript { "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 } ``` {% endtab %} {% endtabs %} ### Creating an Inscription Order Use this endpoint to create an inscription order that will be processed once the related invoice is paid. {% hint style="danger" %} 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. {% endhint %} ## 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"

| | | | | | | {% tabs %} {% tab title="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,
}
{% endtab %} {% tab title="500: Internal Server Error " %} ```javascript { status: 'error', error: 'error reason' } ``` {% endtab %} {% endtabs %} {% hint style="success" %} Supported file extensions may change. If you include any unsupported files order creation will fail. * Currently Supported files: ```javascript 'apng', 'flac', 'gif', 'html', 'jpg','jpeg', 'mp3', 'pdf', 'png', 'svg', 'txt', 'wav', 'webm', 'webp', 'mp4', 'stl', 'glb', 'avif', 'yaml' , 'yml', 'asc', 'json', 'js', 'css' ``` {% endhint %} ### 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 | {% tabs %} {% tab title="200: OK Normal Response" %} {% code overflow="wrap" %} ```javascript { 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 } ``` {% endcode %} {% endtab %} {% tab title="500: Internal Server Error Server side error" %} ```javascript { status: 'error', reason: 'unable to save data' } ``` {% endtab %} {% tab title="200: OK Error Response with Cause" %} ```javascript { status: 'error', error: 'error reason' } ``` {% endtab %} {% endtabs %} ### 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. {% hint style="success" %} 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](https://join.satoshibles.com). {% endhint %} ## 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. | {% tabs %} {% tab title="200: OK " %} {% code overflow="wrap" %} ```javascript { status: 'ok', ..., // input parameters createdAt: 1675785959855, // timestamp in ms, } ``` {% endcode %} {% endtab %} {% tab title="500: Internal Server Error " %} ```javascript { status: 'error', error: 'error reason' } ``` {% endtab %} {% endtabs %} ### 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.

| {% tabs %} {% tab title="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,
}
{% endtab %} {% tab title="500: Internal Server Error " %} ```javascript { status: 'error', error: 'error reason' } ``` {% endtab %} {% endtabs %} ### 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 | {% tabs %} {% tab title="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,
}
{% endtab %} {% tab title="500: Internal Server Error " %} ```javascript { status: 'error', error: 'error reason' } ``` {% endtab %} {% endtabs %} ### 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" | {% tabs %} {% tab title="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
        },
        ...
    ]
}
{% endtab %} {% tab title="500: Internal Server Error Server side error" %} ```javascript { status: 'error', reason: 'server error' } ``` {% endtab %} {% tab title="200: OK Error Response with Cause" %} ```javascript { status: 'error', error: 'error reason' } ``` {% endtab %} {% endtabs %} ### Search Existing Image Inscriptions Use this endpoint to check if a certain image was inscribed before. {% hint style="info" %} 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: {% endhint %} ```javascript 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 | {% tabs %} {% tab title="200: OK Normal Response" %} {% code overflow="wrap" %} ```javascript { "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 }, ... ] } ``` {% endcode %} {% endtab %} {% tab title="500: Internal Server Error Server side error" %} ```javascript { status: 'error', reason: 'server error' } ``` {% endtab %} {% tab title="200: OK Error Response with Cause" %} ```javascript { status: 'error', error: 'error reason' } ``` {% endtab %} {% endtabs %} ### 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` {% tabs %} {% tab title="200: OK Normal Response" %} {% code overflow="wrap" %} ```javascript { "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 } ``` {% endcode %} {% endtab %} {% tab title="500: Internal Server Error Server side error" %} ```javascript { status: 'error', reason: 'server error' } ``` {% endtab %} {% tab title="200: OK Error Response with Cause" %} ```javascript { status: 'error', error: 'error reason' } ``` {% endtab %} {% endtabs %} ### Getting Referral Earnings {% hint style="success" %} Remember you can always earn referral commissions without using the API. Just share your referral link with your community, visitors or followers and you'll automatically earn referral commissions from the inscriptions they make. {% endhint %} 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 | {% tabs %} {% tab title="200: OK Normal Response" %} {% code overflow="wrap" %} ```javascript { "address":"bc1qxxx", "orderCount":962, // how many orders were created with your reflink "paidCount":305 // how many paid orders were processed. } ``` {% endcode %} {% endtab %} {% tab title="500: Internal Server Error Server side error" %} ```javascript { status: 'error', reason: 'unable to check data' } ``` {% endtab %} {% tab title="200: OK Error Response with Cause" %} ```javascript { status: 'error', error: 'error reason' } ``` {% endtab %} {% endtabs %} ### 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. | {% tabs %} {% tab title="200: OK Normal Response" %} {% code overflow="wrap" %} ```javascript { "status":"ok" // your information is saved. } ``` {% endcode %} {% endtab %} {% tab title="500: Internal Server Error Server side error" %} ```javascript { status: 'error', reason: 'unable to set data' } ``` {% endtab %} {% tab title="200: OK Error Response with Cause" %} ```javascript { status: 'error', error: 'referral code already exists - pick another one' } ``` {% endtab %} {% endtabs %} {% hint style="info" %} Get in touch for any questions regarding referral setup on satoshibles discord: [https://join.satoshibles.com](https://join.satoshibles.com/) {% endhint %}