Create a Managed Inscription Order

Managed inscriptions are custodial and requires you to wait 1 confirmation for payment transaction. However you can pay with any wallet and use our inventory of special sats to inscribe on.

Use this endpoint to create a "managed" inscription order that will be processed once the related invoice is paid.

Managed Inscription vs Direct Inscriptions

TypeNon-CustodialRare SatsFeesSpeed

No

OrdinalsBot Inventory

Higher due to multiple transactions

Requires 2 confirmations to complete including payment

Yes

User's own inventory

Cheaper thanks to chained transactions

Payment and inscription can complete in 1 block

  • There's currently a limit of 10000 files per order.

  • If you choose to send file contents as base64 or text encoded dataURL instead of url (and metadataUrl), there's a limit of 50MB per API call.

  • Currently only internally hosted URLs are supported so if you're dynamically generating files, send them as dataURL which will automatically be uploaded to OrdinalsBot buckets.

  • The /order endpoint has a rate limit of maximum of 2 requests every 10 seconds.

POST a new inscription order

Create Order

POST https://api.ordinalsbot.com/order

Remember to include headers with your POST request:

headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' }

Request Body

NameTypeDescription

files*

Array

An array of objects that includes:

Mandatory

name:string; => name of the file including extension.

size:number; => size of the file in bytes

url:string; => file URL hosted on OrdinalsBot buckets

Optional

metadataUrl:string; => metadata json file URL hosted on OrdinalsBot buckets

metadataSize:number; => size of the metadata file in bytes

metaprotocol:string; => Metaprotocol field to be included in the inscription data

Note: you can send any dataURL text/json/image/video data in a parameter called dataURL instead of url for files

metadataDataURL instead of metadataUrl for metadata json files "files" OR "delegates" array is mandatory

delegates*

Array

An array of objects that includes:

Mandatory

delegateId:string; => inscription ID of the delegate that will be inscribed.

Optional

metadataUrl:string; => metadata json file URL hosted on OrdinalsBot buckets

metadataSize:number; => size of the metadata file in bytes

metaprotocol:string; => Metaprotocol field to be included in the inscription data

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.

fee

Number

Miner fee that will be paid while inscribing the ordinals in sats/byte.

(default=2 sats/byte)

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: block9 | block78 | pizza | uncommon | black | vintage | random

Check /inventory endpoint for all available options and their current availability.

referral

String

Referral code to earn up to %15 of the order base fee.

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" parameter.

Note: additionalFee is added PER FILE!

webhookUrl

String

webhook url to receive a POST payload for order updates.

timeout

Number

Order timeout in minutes. Must be a multiple of 10.

Generated payment invoice will be valid for this duration only. Payments that are sent after this will not be processed.

(default=4320)

compress

Boolean

Enable brotli compression for all of the files in the order.

(default=false)

parent

Object

The parent parent/child orders

Mandatory

inscriptionId: string -> the inscription ID of the parent

returnAddress: string -> the address to send the parent inscription back once the order has been inscribed

After the order is paid, the deposit address for the parent will appear under the parent object in a new field depositAddress. See parent-child workflow below for more details.

batchMode

String

Use batch inscription for this order.

Options:

separate-outputs: inscribe on separate postage-sized outputs

shared-output: inscribe on a single output separated by postage

{
    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,
    },
    paylink: {
        "id": "66xxx16", // visit https://app.hel.io/pay/66xxx16 to pay
    },
    chainFee: 718725 // in satoshis
    serviceFee: 9000, // 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', 'gz'

// Here's a sample payload you can POST to create an order with metadata
{
    "files": [
        {
            "size": 10,
            "type": "plain/text",
            "name": "my-text-inscription-file.txt",
            "dataURL": "data:plain/text;base64,dGVzdCBvcmRlcg==",
            "metadataUrl": "https://ordinalsbot-prod.s3.us-east-2.amazonaws.com/ab5016de-a19c-4e96-bd74-b5767d4b27ad_test-metadata-1.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAQICQJQRPF36N3RK2%2F20231121%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20231121T183823Z&X-Amz-Expires=60480&X-Amz-Signature=ec514073843f400b9244fb6a1c4a5aa39fc13f3e8b50956dec4706e9c6ca5bb5&X-Amz-SignedHeaders=host&x-id=GetObject",
            "metadataSize": 113,
        }
    ],
    "lowPostage": true,
    "receiveAddress": "",
    "fee": "11"
}

Parent-child workflow:

  1. Create an regular inscription order but add a parent field

  2. In the parent you should pass the parent inscription ID inscriptionId and returnAddress

  3. Once the order is created and a payment is confirmed a depositAddress will appear in the parent object, you should send the parent there

  4. Once the parent is confirmed the order will start inscribing

  5. Once done inscribing the parent will be returned to the returnAddress specified at order creation

POST to update order receive address

Update order address

POST https://api.ordinalsbot.com/address

If an order is placed with a receive address set, this endpoint can be called to update the receive address after the order has been placed.

Request Body

NameTypeDescription

orderId*

String

The ID of the order to update

address*

String

The receive address

{
    status: 'ok'
}

DELETE to cancel an order

Cancel an order

DELETE https://api.ordinalsbot.com/order

An order can be canceled before the payment is received.

Query Parameters

NameTypeDescription

id*

String

Order ID to be cancelled.

{
    status: 'ok'
}

Last updated