# Create a Direct Inscription Order
Use this endpoint to create a direct inscription order that will be processed once the deposit address is funded.
{% hint style="warning" %}
* 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`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) 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](https://docs.ordinalsbot.com/api/get-order-status)
* 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.**
{% endhint %}
### `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 | 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
|
{% tabs %}
{% tab title="200: OK " %}
```json
{
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,
}
```
{% endtab %}
{% tab title="500: Internal Server Error " %}
```json
{
status: 'error',
error: 'error reason'
}
```
{% endtab %}
{% tab title="400: Bad Request " %}
{% endtab %}
{% endtabs %}
{% hint style="success" %}
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'`
{% endhint %}
```json
// 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:*
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 three parents are sent first
* the charge payment is sent last
```json
// 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-order](#post-a-new-inscription-order "mention")such that the resulting inscription will sit on the special sat from user's own wallet.
{% hint style="warning" %}
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.
{% endhint %}
### 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:**
```javascript
/**
* 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 |
{% tabs %}
{% tab title="200: OK Normal Response" %}
```json
{
// 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
]
}
```
{% endtab %}
{% tab title="200: OK Error Response with Cause" %}
```
{
status: 'error',
error: 'error reason'
}
```
{% endtab %}
{% tab title="500: Internal Server Error Server side error" %}
```
{
status: 'error',
reason: 'unable to check data'
}
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
Get in touch for any feedback regarding this service in **#developers** channel on our discord: [https://discord.ordinalsbot.com](https://discord.ordinalsbot.com/)
{% endhint %}
## 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:
{% hint style="warning" %}
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.
{% endhint %}
### 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.
|
{% hint style="info" %}
Get in touch for any feedback regarding this service in **#developers** channel on our discord: [https://discord.ordinalsbot.com](https://discord.ordinalsbot.com/)
{% endhint %}
{% tabs %}
{% tab title="200: OK Normal Response" %}
```json
{
// 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
]
}
```
{% endtab %}
{% tab title="200: OK Error Response with Cause" %}
```
{
status: 'error',
error: 'error reason'
}
```
{% endtab %}
{% tab title="500: Internal Server Error Server side error" %}
```
{
status: 'error',
reason: 'unable to check data'
}
```
{% endtab %}
{% endtabs %}
**Below is an example of creating the PSBT and singing it using XVerse wallet:**
```javascript
/**
* 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.
```json
'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.
```