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
dataURLwhich will automatically be uploaded to OrdinalsBot buckets. (e.g. needs to be base64 and in this format `data:plain/text;base64,dGVzdCBvcmRlcg==`)The
/inscribeendpoint 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
depositAddressfield for each parent object, after which the order enters into awaiting-parentstate. Make sure to send parents first, before paying the chargeWhen paying for an order with multiple parent inscriptions make sure to craft a transaction such that you send the parents first, to the
depositAddressof the parent array and send the charge payment last. You can do this all in a single transaction.
POST a new inscription order
POST a new inscription orderCreate 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
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
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"
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 valid as per rules before jubilee to make the resulting inscription output not "cursed" hence, "not vindicated" (aka "blessed")
Refer to ordinals docs for details.
NOTE: Some BRC20 indexers are strict about this and some are not...
webhookUrl
String
webhook url to receive a POST payload for order updates.
Refer to Webhooks for format of the webhook payload
{
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,
}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"
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",
"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
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
{
// 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
]
}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
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
]
}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.Last updated