Create Order

Create an order

post

https://open-api.unisat.iohttps://open-api-s1.unisat.iohttps://open-api-testnet.unisat.io

/v2/inscribe/order/create

Create an order to inscribe something

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

receiveAddressstringOptional

Bitcoin address to receive the inscriptions

feeRatenumber · floatOptional

The fee rate of transaction

Example: 1

outputValueinteger · int32Optional

The balance of inscription

Example: 546

devAddressstringOptional

Developer address to receive extra fee

devFeeinteger · int32Optional

Extra fee to pay to developer's address

Responses

200

Successful operation

application/json

401

Invalid API Key

post

/v2/inscribe/order/create

HTTPcURLJavaScriptPython

POST /v2/inscribe/order/create HTTP/1.1
Host: open-api.unisat.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 227

{
  "receiveAddress": "text",
  "feeRate": 1,
  "outputValue": 546,
  "files": [
    {
      "filename": "1000.sats",
      "dataURL": "data:text/plain;charset=utf-8;base64,eyJwIjoic25zIiwib3AiOiJyZWciLCJuYW1lIjoiMTAwMDAuc2F0cyJ9"
    }
  ],
  "devAddress": "text",
  "devFee": 1
}

{
  "code": 1,
  "msg": "text",
  "data": {
    "orderId": "",
    "status": "pending",
    "payAddress": "",
    "receiveAddress": "",
    "amount": 3000,
    "paidAmount": 1,
    "outputValue": 1,
    "feeRate": 1,
    "minerFee": 1,
    "serviceFee": 1,
    "devFee": 1,
    "files": [
      {
        "filename": "10000.sats",
        "inscriptionId": "",
        "status": "pending"
      }
    ],
    "count": 1,
    "pendingCount": 1,
    "unconfirmedCount": 0,
    "confirmedCount": 0,
    "createTime": 1693439128100,
    "refundTxid": "",
    "refundAmount": 1,
    "refundFeeRate": 1
  }
}

FAQ

How to pay after create an order?

The order will start inscribing once the "payAddress" receives the "amount". For example, if an order requires 3000 satoshis, you have to send 3000 satoshis to payAddress. After that, the inscription will be inscribed.

How is the open-api order charged?

We charge a base service fee of 1999 for the first 25 inscriptions, along with an additional network service fee of 4.99%. We round down the final cost.

Are the orders on the open-api and the UniSat website interoperable?

No.

Open API and UniSat website inscribing service do not share data. This ensures the stability of the Open API interface and prevents it from being affected by frequent changes to website inscribing service. For similar reasons, the orders on open-api do not enjoy discounts from the OG card or .unisat domain.

How many files can I submit for each order?

An order supports a maximum of 2000 files, with each file having a maximum size of 390 KB

How to estimate fee before create an order?

const address = ''; // the receiver address
const inscriptionBalance = 546; // the balance in each inscription
const fileCount = 1000; // the fileCount
const fileSize = 1000; // the total size of all files
const contentTypeSize = 100; // the size of contentType
const feeRate = 10; // the feeRate
const feeFileSize = 100; // the total size of first 25 files
const feeFileCount = 25 // do not change this
const devFee = 1000; // the fee for developer

const balance = inscriptionBalance * fileCount;

let addrSize = 25+1; // p2pkh
if(address.indexOf('bc1q')==0 || address.indexOf('tb1q')==0){
    addrSize = 22+1;
}else if(address.indexOf('bc1p')==0 || address.indexOf('tb1p')==0){
    addrSize = 34+1;
}else if(address.indexOf('2')==0 || address.indexOf('3')==0){
    addrSize = 23+1;
}

const baseSize = 88;
let networkSats = Math.ceil(((fileSize+contentTypeSize) / 4 + ( baseSize+8+addrSize+8+23)) * feeRate);
if(fileCount>1){
    networkSats = Math.ceil(((fileSize+contentTypeSize) / 4 + (baseSize+8+addrSize+(35+8)*(fileCount-1)+ 8+23 +(baseSize+8+addrSize+0.5)*(fileCount-1) )) * feeRate);
}
let networkSatsByFeeCount = Math.ceil(((feeFileSize+contentTypeSize) / 4 + ( baseSize+8+addrSize+8+23)) * feeRate);
if(fileCount>1){
    networkSatsByFeeCount = Math.ceil(((( feeFileSize)+contentTypeSize*(feeFileCount/fileCount)) / 4 + (baseSize+8+addrSize+(35+8)*(fileCount-1)+ 8+23 +(baseSize+8+addrSize+0.5)*Math.min(fileCount-1,feeFileCount-1) )) * feeRate);
}

const baseFee = 1999 * Math.min(fileCount, feeFileCount); // 1999 base fee for top 25 files
const floatFee = Math.ceil(networkSatsByFeeCount * 0.0499); // 4.99% extra miner fee for top 25 transations
const serviceFee = Math.floor(baseFee + floatFee);

const total = balance + networkSats + serviceFee; 
const truncatedTotal = Math.floor((total) / 1000) * 1000; // truncate
const amount = truncatedTotal + devFee; // add devFee at the end

console.log("The final amount need to pay: ",amount)