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

Type	Non-Custodial	Rare Sats	Fees	Speed
Managed	No	OrdinalsBot Inventory	Higher due to multiple transactions	Requires 2 confirmations to complete including payment
Direct	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

Name	Type	Description
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. Refer to Webhooks for format of the webhook payload
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. Refrain from using too short timeout values and instead use Cancel an order (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

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

500: Internal Server Error

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

400: Bad Request

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

Name	Type	Description
orderId*	String	The ID of the order to update
address*	String	The receive address

200: OK Normal Response

{
    status: 'ok'
}

200: OK

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

500: Internal Server Error Server Side Error

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

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

Name	Type	Description
id*	String	Order ID to be cancelled.

200: OK Normal Response

{
    status: 'ok'
}

200: OK

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

500: Internal Server Error Server Side Error

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