Create a Direct Inscription Order

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

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 dataURL 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 /order

• 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)
lowPostage	Boolean	Inscribe file with minimum postage (padding) 546 sats instead of the standard 10,000 sats. (default=false)
allowedSatributes	Array	Array of satributes that this inscription will be allowed to be inscribed on. List of supported satributes are available at Supported Satributes
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"
webhookUrl	String	webhook url to receive a POST payload for order updates. Refer to Webhooks for format of the webhook payload

200: OK

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

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==",
            "metadataDataURL": "data:application/json;base64,ewogICAgImluc2NyaWJlZF9ieSI6ICJPcmRpbmFsc0JvdCIKfQ==",
            "metadataSize": 37
        }
    ],
    "lowPostage": true,
    "receiveAddress": "",
    "fee": "11"
}

Example of parent/child order with a delegate

Inscription properties:

• one delegate inscription of 0426b1e763be8f7b6cff7bc05640534f506d174dc6f14b57ce146bc37a553b06i0

• three parents

• chosen prefix "00"

Result: https://ordinals.com/inscription/00ee0087bb02437ed3eab12089442f24fd367fe827989372871e196e6bcec218i0

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: https://mempool.space/tx/165987ba58ddfea7d8b4d0adfbc89b271bd01b7bcd911e2eb2ed5e431e3ad4a2

• 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",
    "lowPostage": true,
    "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	The address to which the PSBT will send funds. Note: This address would come from Create a Direct Inscription 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	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

200: OK Normal Response

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

200: OK Error Response with Cause

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

500: Internal Server Error Server side error

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

Get in touch for any feedback regarding this service in #developers channel on our discord: https://discord.ordinalsbot.com

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.

Get in touch for any feedback regarding this service in #developers channel on our discord: https://discord.ordinalsbot.com

200: OK Normal Response

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

200: OK Error Response with Cause

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

500: Internal Server Error Server side error

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