LogoLogo
Back to AppHelp Center
  • Getting Started
    • Welcome
  • OrdinalsBot API
    • Overview
    • Libraries
    • Template-App
    • Signet
    • Testnet
    • Fractal
    • Getting Prices
      • Getting Prices (Legacy)
    • Create a Direct Inscription Order
    • Create a Managed Inscription Order
    • Get Order Status
    • Create a Collection
    • Create a Collection Order
    • Create Text Inscription Order
    • Search Inscriptions
    • Check Rare Sats Inventory
    • Referral Scheme
    • Transaction Accelerator
    • Burning Assets
    • Webhooks
    • Order States
    • Order Types
  • Runes
    • Etch
    • Mint
    • Direct Mint
      • 1. Generate Direct Mint PSBT
      • 2. Direct Rune Mint Process PSBT
    • Launchpad
      • Create
      • Mint
      • Get Launchpad
    • Airdrop
  • Token Pay
    • What is TokenPay?
    • API Docs
      • API reference
        • Order
        • Create payment psbt
        • Create burn rune psbt
        • Validate burn rune tx
        • Create burn inscription psbt
        • Utils
          • Checktx
          • Submittx
          • Finalize psbt
        • User
          • Withdrawal
          • Order
            • Rune
          • Account
            • Withdraw
            • Balance
      • Specification
  • Marketplace
    • User Guide: Pre-Inscribed Launchpad API
    • API Docs
    • Editions Launchpad
  • Launchpad API
    • Create Marketplace
    • Create a new Launchpad
    • Retrieve Launch PSBT
    • Confirm Launch
    • Check Allocation
    • Check for Padding Outputs
    • Setup Padding Outputs
    • Create buy offer
    • Confirm buy offer
    • Get Launch Info
  • Sat Scanner API
    • Find Special Ranges
    • Find Special Ranges UTXO
    • Supported Satributes
  • Sat Extractor
    • Extract
  • BRC20 / BRC2.0PROG
    • OPI API
    • Bitcoin Remix
  • SNS API
    • SNS API
  • Mempool API
    • Mempool API
  • TAP PROTOCOL
    • Tap Reader API
  • UTXO
    • Split
  • User Guide
    • Inscribe your first Ordinal
    • Receiving Payments
  • Knowledge Base
    • Ordinals
      • What is an Ordinal?
      • Satoshi Rarity
      • What are BRC-20 Tokens?
      • Image Optimisation
      • Pixel Art
    • Bitcoin
      • Unspent Transaction Output (UTXO)
  • Official Links
    • Twitter
    • Discord
Powered by GitBook
On this page
  • POST a new inscription order
  • Create Order
  • Example of parent/child order with a delegate
  • Pay Order with Special Sats
  • Create Special Sat Payment PSBT
  • Pay for Parent Child Direct inscribe order
  • Create PSBT to pay for Parent Child order
  • Order States
  1. OrdinalsBot API

Create a Direct Inscription Order

Ordinalsbot supports simplified inscriptions that avoid the need to do additional commit transaction, thus reducing the cost of inscription.

PreviousGetting Prices (Legacy)NextCreate a Managed Inscription Order

Last updated 11 days ago

Use this endpoint to create a direct inscription order that will be processed once the deposit address is funded.

  • 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, 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 which will automatically be uploaded to OrdinalsBot buckets. (e.g. needs to be base64 and in this format `data:plain/text;base64,dGVzdCBvcmRlcg==`)

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

  • There is a slight delay between the time the order is created and the charge address appears. You will need to poll the order after it is created to see the charge address. See

  • The deposit address for parent inscriptions will appear on the depositAddress field for each parent object, after which the order enters into a waiting-parent state. Make sure to send parents first, before paying the charge

  • When paying for an order with multiple parent inscriptions make sure to craft a transaction such that you send the parents first, to the depositAddress of the parent array and send the charge payment last. You can do this all in a single transaction.

POST a new inscription order

Create Order

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

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

see below for sample payload.

delegates

Array

An array of objects that includes: Mandatory delegateId: string; => the delegate inscription id 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

receiveAddress*

String

A single Bitcoin address to receive the inscriptions for the whole order

parents

Array

Array of parent objects that will become parents to the inscriptions Mandatory inscriptionId: string; => the inscription id of the parent returnAddress: string; => where to return this parent inscription value: number; => amount of sats in the parent inscription utxo

fee

Number

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

(default=2 sats/byte)

postage

Number

Set custom postage for the order's asset: minimum 330 sats, maximum 10,000 sats.

(default=546)

allowedSatributes

Array

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.

inscriptionIdPrefix

string

We will grind an inscription id prefix if this option is specified. All inscriptions in the order will have this prefix. Maximum: 4 hex characters i.e. "b1fd"

burnAfterInscribe

Boolean

⚠️ If set to true, the "receiveAddress" will be ignored and inscription will be sent to p2a anchor address and then burned by sending it to OP_RETURN "BRC20PROG".

uncurseIt

Boolean

Will make the inscription envelope is valid as per rules before jubilee to make the resulting inscription output not "cursed" hence, "not vindicated" (aka "blessed")

webhookUrl

String

webhook url to receive a POST payload for order updates.

{
    status: 'ok',
    id: 'c411ca33-53dd-4d4f-b959-6c6dffcc88e5',
    ..., // input parameters
    charge: {
        // The payment address will appear with a short delay
        // Do a GET /order?id={id} to get the charge address
        amount: 1218725
    },
    chainFee: 718725 // in satoshis
    serviceFee: 2000, // in satoshis
    orderType: 'direct',
    createdAt: 1675785959855, // timestamp in ms,
}
{
    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', '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==",
            "metadataDataURL": "data:application/json;base64,ewogICAgImluc2NyaWJlZF9ieSI6ICJPcmRpbmFsc0JvdCIKfQ==",
            "metadataSize": 37
        }
    ],
    "postage": 546,
    "receiveAddress": "",
    "fee": "11"
}

Example of parent/child order with a delegate

Inscription properties:

  • one delegate inscription of 0426b1e763be8f7b6cff7bc05640534f506d174dc6f14b57ce146bc37a553b06i0

  • three parents

  • chosen prefix "00"

  • the three parents are sent first

  • the charge payment is sent last

// here is a sample playload you can post to create an order for a single delegate 
// inscription with three parents
{
    "delegates": [
        {
            "delegateId": "0426b1e763be8f7b6cff7bc05640534f506d174dc6f14b57ce146bc37a553b06i0"
        }
    ],
    "parents": [
        {
            "inscriptionId": "b951105d1e91a48a6d2aa2f8d3531314e6a7c7a16d7ffd78d3dd1feaaa2e4ffci0",
            "returnAddress": "bc1pgnwmg7wplc09cm9fctgmgalu7l4synjh7khwzre9qlcvg5xy0k5qz9mwe3"
        },
        {
            "inscriptionId": "b951105d1e91a48a6d2aa2f8d3531314e6a7c7a16d7ffd78d3dd1feaaa2e4ffci1",
            "returnAddress": "bc1pgnwmg7wplc09cm9fctgmgalu7l4synjh7khwzre9qlcvg5xy0k5qz9mwe3"
        },
        {
            "inscriptionId": "b951105d1e91a48a6d2aa2f8d3531314e6a7c7a16d7ffd78d3dd1feaaa2e4ffci2",
            "returnAddress": "bc1pgnwmg7wplc09cm9fctgmgalu7l4synjh7khwzre9qlcvg5xy0k5qz9mwe3"
        }
    ],
    "inscriptionIdPrefix": "00",
    "postage": 546,
    "receiveAddress": "bc1pgnwmg7wplc09cm9fctgmgalu7l4synjh7khwzre9qlcvg5xy0k5qz9mwe3",
    "fee": 15
}

Pay Order with Special Sats

Use this endpoint to create a PSBT from user's wallet, that would pay a direct inscription deposit address created above with POST a new inscription ordersuch that the resulting inscription will sit on the special sat from user's own wallet.

Make sure to carefully review any transactions you are signing in order to avoid unexpected consequences. Most wallets show the inputs & outputs of a PSBT before you sign them.

Create Special Sat Payment PSBT

POST https://api.ordinalsbot.com/create-special-sats-psbt

Create a PSBT that would generate a inscription on the special sat provided, fees and postage comes out of a common sat output. Below is an example of creating the PSBT and singing it using XVerse wallet:

/**
 * Create a PSBT for signing the transaction by calling the /create-special-sats-psbt API.
 * This returns a base64-encoded PSBT, PSBT Hex, sender ordinal, and payment inputs that need to be signed.
 */
const {
  psbtBase64,
  paymentInputIndices,
  ordinalInputIndices,
  psbtHex
} = await axios({
  method: "post",
  url: "https://api.ordinalsbot.com/create-special-sats-psbt",
  data: {
    chargeAmount, // The amount of sats to be pay
    fundingAddress, // The address to which the user will send bitcoin funds.
    specialSatsOutput, // The special sats output selected for inscription by user. (e.g xxxxxx:0)
    paymentAddress, // The user's payment address.
    paymentPublicKey, // The user's payment address' public key..
    ordinalAddress, // The user's ordinal address.
    ordinalPublicKey, // The user's ordinal address public key.
    feeRate, // The fee rate selected by the user in sats/vB.
  },
});

// prepare the inputs for XVerse wallet to sign
const inputsToSign = [
  {
    address: ordinalsAddress,
    signingIndexes: ordinalInputIndices,
  },
  {
    address: paymentAddress,
    signingIndexes: paymentInputIndices,
  },
];

// When using XVerse Wallet
// Create the payload for signing the transaction
const payload = {
  network: { type: "Mainnet" },
  message: "Sign Transaction",
  psbtBase64: psbtBase64, // PSBT returned by the API call
  broadcast: true,
  inputsToSign: inputsToSign,
};

// Make signing request to wallet, this will prompt the user to sign
await signTransaction({
  payload,
  onFinish: async (response) => {
    try {
      console.log({ response });
      console.log(`Payment successful: ${response?.txId}`);
    } catch (saveError) {
      console.error("Error Payment:", saveError);
    }
  },
  onCancel: () => console.log("Payment canceled"),
});

Request Body

Name
Type
Description

chargeAmount*

Number

Total amount to be sent to fundingAddress as fees and postage.

fundingAddress*

String

paymentAddress*

String

Bitcoin payment address where common sats for fees and postage will be paid from.

paymentPublicKey*

String

Bitcoin payment public key where where common sats for fees and postage will be paid from.

ordinalAddress*

String

The ordinal address which is a taproot address for inscriptions, runes or BRC20.

ordinalPublicKey*

String

The public key for the ordinals address which is a taproot address for inscriptions, runes or BRC20.

specialSatsOutput*

String

UTXO that contains the special/rare sat that will inscribed on. This should be in txid:vout format for example: bab2074844dbf62264e2bcf4298ee90d135973e2fe43ae7e33923e7e0c2d1884:0

feeRate*

Number

Target Fee rate that should be used in sats/vB

{
    // PSBT to be signed and published by user's wallet
    "psbtBase64": "cHNi...AAAAA",
    // same PSBT in hex format (for leather wallet)
    "psbtHex": "70736274ff01...47dc200000000",
    // Payment inputs to sign with the payment address
    "paymentInputIndices": [
        1
    ]
    // Ordinal inputs to sign with the ordinal address
    "ordinalInputIndices": [
        0
    ]
}
{
    status: 'error', 
    error: 'error reason'
}
{
    status: 'error',
    reason: 'unable to check data'
}

Pay for Parent Child Direct inscribe order

Use this endpoint to create a PSBT from user's wallet, that would pay a direct inscription order for multi parent direct inscribe order. This transaction will pay the charge in btc and also transfer the multiple parents:

Make sure to carefully review any transactions you are signing in order to avoid unexpected consequences. Most wallets show the inputs & outputs of a PSBT before you sign them.

Create PSBT to pay for Parent Child order

POST https://api.ordinalsbot.com/create-parent-child-psbt

Name
Type
Description

orderId*

String

The ID of the parent child order. The PSBT will be created to pay the bitcoin fee as well as to transfer the parent inscriptions for this order

paymentAddress*

String

Bitcoin payment address where common sats for fees and postage will be paid from.

paymentPublicKey*

String

Bitcoin payment public key where where common sats for fees and postage will be paid from.

ordinalAddress*

String

Address for holding ordinals which is usually a taproot address for inscriptions, runes and BRC20.

ordinalPublicKey*

String

The public key for the ordinals address which is a taproot address for inscriptions, runes or BRC20.

feeRate*

Number

Target Fee rate that should be used in sats/vB

specialSatsOutput

String

(Optional) Special sat utxo you want to use for the inscription itself.

This utxo will be placed after parents, before any fee utxo pulled from your payment address.

{
    // PSBT to be signed and published by user's wallet
    "psbtBase64": "cHNi...AAAAA",
    // same PSBT in hex format (for leather wallet)
    "psbtHex": "70736274ff01...47dc200000000",
    // Payment inputs to sign with the payment address
    "paymentInputIndices": [
        1
    ]
    // Ordinal inputs to sign with the ordinal address
    "ordinalInputIndices": [
        0
    ]
}
{
    status: 'error', 
    error: 'error reason'
}
{
    status: 'error',
    reason: 'unable to check data'
}

Below is an example of creating the PSBT and singing it using XVerse wallet:

/**
 * Create a PSBT for signing the transaction by calling /create-parent-child-psbt
 * API.
 * This returns a base64-encoded PSBT, PSBT Hex, sender ordinal, and 
 * payment and ordinal inputs that need to be signed.
 */
const {
  psbtBase64,
  paymentInputIndices,
  ordinalInputIndices,
  psbtHex
} = await axios({
  method: "post",
  url: "https://api.ordinalsbot.com/create-parent-child-psbt",
  data: {
    orderId, // The ID of the order for which to create the PSBT.
    paymentAddress, // The user's payment address.
    paymentPublicKey, // The user's payment address public key.
    ordinalAddress, // The user's ordinal address.
    ordinalPublicKey, // The user's ordinal address public key.
    feeRate, // The fee rate selected by the user in sats/vB.
  },
});

// input to sign
const inputsToSign = [
  {
    address: ordinalsAddress,
    signingIndexes: ordinalInputIndices,
  },
  {
    address: paymentAddress,
    signingIndexes: paymentInputIndices,
  },
];

// When using XVerse Wallet
// Create the payload for signing the transaction
const payload = {
  network: { type: "Mainnet" },
  message: "Sign Transaction",
  psbtBase64: psbtBase64, // PSBT returned by the API
  broadcast: true,
  inputsToSign: inputsToSign,
};

// Make signing request
await signTransaction({
  payload,
  onFinish: async (response) => {
    try {
      console.log({ response });
      console.log(`Payment successful: ${response?.txId}`);
    } catch (saveError) {
      console.error("Error Payment:", saveError);
    }
  },
  onCancel: () => console.log("Payment canceled"),
});

Order States

Direct inscription orders go through below states, note that some of them are optional.

'prep' // commit address is being generated
'waiting-parent' // optional - order is waiting for the parent inscription to hit the wallet
'waiting-payment' // order is waiting for a payment to be detected
'mempool' // payment tx is seen and reveal tx is broadcasted into the mempool
'completed' // reveal tx received 1 confirmation, order is finalized.

Array of satributes that this inscription will be allowed to be inscribed on. List of supported satributes are available at

Refer to for details.

Refer to for format of the webhook payload

Result:

When depositAddress becomes available on each parent object and address under the charge object you can exectute sending of the parents and paying the charge in a single transaction. The only requirement is that you send the parents before you send the charge. Here is an example of a funding transaction to an order of this type:

The address to which the PSBT will send funds. Note: This address would come from

Get in touch for any feedback regarding this service in #developers channel on our discord:

Get in touch for any feedback regarding this service in #developers channel on our discord:

dataURL
/order
https://ordinals.com/inscription/00ee0087bb02437ed3eab12089442f24fd367fe827989372871e196e6bcec218i0
https://mempool.space/tx/165987ba58ddfea7d8b4d0adfbc89b271bd01b7bcd911e2eb2ed5e431e3ad4a2
https://discord.ordinalsbot.com
https://discord.ordinalsbot.com
Supported Satributes
Webhooks
Create a Direct Inscription Order
ordinals docs