unisat-dev-docs

Inscribe API

Legacy V2 inscription API. GET /v2/inscribe/order/summary remains supported; all other V2 inscription endpoints are deprecated and new integrations must use the Inscribe API V5 endpoints under /inscribe-v5. See open-api/inscribe-v5-migration.md.

👉 View Swagger UI


📑 Table of Contents

Route Summary
GET /v2/inscribe/order/summary Summarize inscription order counts
GET /v2/inscribe/order/list List inscription orders with status details
GET /v2/inscribe/order/(orderId) Get one inscription order state
POST /v2/inscribe/order/create Create generic inscription payment order
POST /v2/inscribe/order/create/brc20-deploy Create deprecated BRC-20 deploy inscription order
POST /v2/inscribe/order/create/brc20-mint Create deprecated BRC-20 mint inscription order
POST /v2/inscribe/order/create/brc20-transfer Create deprecated BRC-20 transfer inscription order
POST /v2/inscribe/order/request-commit Prepare inscription commit PSBT
POST /v2/inscribe/order/sign-commit Submit signed inscription commit PSBT
POST /v2/inscribe/order/sign-reveal Submit signed inscription reveal PSBT
POST /v2/inscribe/order/create/brc20-5byte-mint Create deprecated BRC-20 5-byte mint order
POST /v2/inscribe/order/request-commit/brc20-5byte-mint Prepare deprecated 5-byte commit PSBT
POST /v2/inscribe/order/sign-commit/brc20-5byte-mint Submit deprecated signed 5-byte commit
POST /v2/inscribe/order/sign-reveal/brc20-5byte-mint Submit deprecated signed 5-byte reveal
POST /v2/inscribe/order/create/runes-etch Create Runes etch inscription order
POST /v2/inscribe/order/create/runes-mint Create Runes mint inscription order
POST /v2/inscribe/order/(orderId)/refund Submit inscription order refund
POST /v2/inscribe/order/(orderId)/refund-estimate Estimate inscription refund amount

Inscribe

Summarize inscription order counts

Method: GET
Path: /v2/inscribe/order/summary
Swagger Link: View in Swagger UI

Description

Returns orderCount totals by status for the current API key, including pending, inscribing, minted, closed, and refunded buckets. Use it for dashboard totals and reconcile the counts before drilling into order lists; it never creates payment state or broadcasts transactions.

Response (200)

Successful operation

Response (401)

Invalid API Key


List inscription orders with status details

Method: GET
Path: /v2/inscribe/order/list
Swagger Link: View in Swagger UI

Description

Returns paginated inscription orders, including orderId, status, payment amounts, receiveAddress, fee fields, counts, and optional file details. Use it to monitor order progress or reconcile payments; check status, paidAmount, amount, and files before taking follow-up signing or refund actions.

Parameters

Response (200)

Successful operation

Response (401)

Invalid API Key

Notes


Get one inscription order state

Method: GET
Path: /v2/inscribe/order/{orderId}
Swagger Link: View in Swagger UI

Description

Returns a single order with status, payAddress, receiveAddress, paidAmount, required amount, fee breakdown, inscription counts, file statuses, and refund fields. Poll it before payment, commit signing, reveal signing, or refund decisions; verify status and amount fields because this endpoint is read-only.

Parameters

Response (200)

Successful operation

Response (401)

Invalid API Key

Notes

enum OrderStatus {
  // when create order
  pending = "pending",

  // pay not enough, need pay more
  payment_notenough = "payment_notenough",

  // pay over, need choose continue or refund
  payment_overpay = "payment_overpay",

  // there is an inscription in payment transaction, need refund
  payment_withinscription = "payment_withinscription",

  // in some case, payment transaction need be confirmed
  payment_waitconfirmed = "payment_waitconfirmed",

  // payment success
  payment_success = "payment_success",

  // ready to inscribe
  ready = "ready",
  inscribing = "inscribing",
  minted = "minted",
  closed = "closed",
  refunded = "refunded",
  cancel = "cancel",
}

enum InscriptionStatus {
  pending = "pending",
  unconfirmed = "unconfirmed",
  confirmed = "confirmed",
}

Create generic inscription payment order

Method: POST
Path: /v2/inscribe/order/create
Swagger Link: View in Swagger UI

Description

Creates an inscription order for arbitrary files and returns orderId, payAddress, required amount, receiveAddress, fee breakdown, and order/file status. Confirm receiveAddress, file data, outputValue, feeRate, dev fee fields, and expected payment amount before calling because it starts payable order state.

Request Body

Content-Type: application/json (required)

Response (200)

Successful operation

Response (401)

Invalid API Key


Create deprecated BRC-20 deploy inscription order

Method: POST
Path: /v2/inscribe/order/create/brc20-deploy
Swagger Link: View in Swagger UI

Description

Creates a payable inscription order for legacy BRC-20 deploy content and returns orderId, payAddress, amount, receiveAddress, fee fields, and status. Confirm ticker, max, limit, receiveAddress, feeRate, outputValue, and payment amount before use; prefer newer workflows when available.

Request Body

Content-Type: application/json (required)

Response (200)

Successful operation

Response (401)

Invalid API Key


Create deprecated BRC-20 mint inscription order

Method: POST
Path: /v2/inscribe/order/create/brc20-mint
Swagger Link: View in Swagger UI

Description

Creates a payable inscription order for legacy BRC-20 mint content and returns orderId, payAddress, amount, receiveAddress, fee fields, and status. Confirm ticker, mint amount, count, receiveAddress, feeRate, outputValue, and total payment before use; prefer newer workflows when available.

Request Body

Content-Type: application/json (required)

Response (200)

Successful operation

Response (401)

Invalid API Key


Create deprecated BRC-20 transfer inscription order

Method: POST
Path: /v2/inscribe/order/create/brc20-transfer
Swagger Link: View in Swagger UI

Description

Creates a payable inscription order for legacy BRC-20 transfer content and returns orderId, payAddress, amount, receiveAddress, fee fields, and status. Confirm ticker, transfer amount, receiveAddress, feeRate, outputValue, and payment amount before use; prefer newer workflows when available.

Request Body

Content-Type: application/json (required)

Response (200)

Successful operation

Response (401)

Invalid API Key


Prepare inscription commit PSBT

Method: POST
Path: /v2/inscribe/order/request-commit
Swagger Link: View in Swagger UI

Description

Returns commit transaction PSBT hex and inputsToSign for a paid inscription order. Confirm orderId, payerAddress, payerPubkey, payment status, and signing indexes before signing; this prepares spend material but later sign endpoints advance the on-chain workflow.

Request Body

Content-Type: application/json (required)

Response (200)

Successful operation

Response (401)

Invalid API Key


Submit signed inscription commit PSBT

Method: POST
Path: /v2/inscribe/order/sign-commit
Swagger Link: View in Swagger UI

Description

Submits the signed commit PSBT for an inscription order and returns next-step PSBT/signing material when accepted. Verify orderId, PSBT content, payer inputs, payment amount, and fee assumptions before calling because it advances the transaction workflow.

Request Body

Content-Type: application/json (required)

Response (200)

Successful operation

Response (401)

Invalid API Key


Submit signed inscription reveal PSBT

Method: POST
Path: /v2/inscribe/order/sign-reveal
Swagger Link: View in Swagger UI

Description

Submits the signed reveal PSBT and returns the resulting inscriptionId when the reveal is accepted. Verify orderId, PSBT content, receiveAddress, file payload, and fees before calling because this can finalize inscription creation on-chain.

Request Body

Content-Type: application/json (required)

Response (200)

Successful operation

Response (401)

Invalid API Key


Create deprecated BRC-20 5-byte mint order

Method: POST
Path: /v2/inscribe/order/create/brc20-5byte-mint
Swagger Link: View in Swagger UI

Description

Creates a payable inscription order for legacy BRC-20 5-byte mint content and returns orderId, payAddress, amount, receiveAddress, fee fields, and status. Confirm deployer address/pubkey, ticker, mint amount, receiveAddress, feeRate, outputValue, and payment amount before use; prefer newer workflows when available.

Request Body

Content-Type: application/json (required)

Response (200)

Successful operation

Response (401)

Invalid API Key


Prepare deprecated 5-byte commit PSBT

Method: POST
Path: /v2/inscribe/order/request-commit/brc20-5byte-mint
Swagger Link: View in Swagger UI

Description

Returns commit PSBT hex and inputsToSign for a paid legacy BRC-20 5-byte mint order. Confirm orderId, payerAddress, payerPubkey, payment status, and signing indexes before signing; deprecated endpoint kept for compatibility.

Request Body

Content-Type: application/json (required)

Response (200)

Successful operation

Response (401)

Invalid API Key


Submit deprecated signed 5-byte commit

Method: POST
Path: /v2/inscribe/order/sign-commit/brc20-5byte-mint
Swagger Link: View in Swagger UI

Description

Submits the signed commit PSBT for a legacy BRC-20 5-byte mint order and returns next-step PSBT/signing material when accepted. Verify orderId, PSBT content, payer inputs, payment amount, and fees before calling; deprecated endpoint kept for compatibility.

Request Body

Content-Type: application/json (required)

Response (200)

Successful operation

Response (401)

Invalid API Key


Submit deprecated signed 5-byte reveal

Method: POST
Path: /v2/inscribe/order/sign-reveal/brc20-5byte-mint
Swagger Link: View in Swagger UI

Description

Submits the signed reveal PSBT for a legacy BRC-20 5-byte mint order and returns inscriptionId when accepted. Verify orderId, PSBT content, receiveAddress, inscription payload, and fees before calling; deprecated endpoint kept for compatibility.

Request Body

Content-Type: application/json (required)

Response (200)

Successful operation

Response (401)

Invalid API Key


Create Runes etch inscription order

Method: POST
Path: /v2/inscribe/order/create/runes-etch
Swagger Link: View in Swagger UI

Description

Creates a payable inscription order for Runes etching and returns orderId, payAddress, amount, receiveAddress, fee fields, and status. Confirm rune name/symbol/divisibility, premine and terms, file payload, receiveAddress, feeRate, outputValue, and total payment before calling.

Request Body

Content-Type: application/json (required)

Response (200)

Successful operation

Response (401)

Invalid API Key


Create Runes mint inscription order

Method: POST
Path: /v2/inscribe/order/create/runes-mint
Swagger Link: View in Swagger UI

Description

Creates a payable inscription order for Runes minting and returns orderId, payAddress, amount, receiveAddress, fee fields, and status. Confirm runeid, count, receiveAddress, feeRate, outputValue, dev fee fields, and total payment before calling.

Request Body

Content-Type: application/json (required)

Response (200)

Successful operation

Response (401)

Invalid API Key


Submit inscription order refund

Method: POST
Path: /v2/inscribe/order/{orderId}/refund
Swagger Link: View in Swagger UI

Description

Requests a refund transaction for a paid inscription order and returns the refund txid when accepted. Verify orderId, order status, paidAmount, safe refund amount, refundFeeRate, and destination assumptions before calling because it can move funds.

Parameters

Request Body

Content-Type: application/json (required)

Response (200)

Successful operation

Response (401)

Invalid API Key


Estimate inscription refund amount

Method: POST
Path: /v2/inscribe/order/{orderId}/refund-estimate
Swagger Link: View in Swagger UI

Description

Returns paidAmount, refundTxSize, and safeRefundAmount for an inscription order refund check. Use it before refund submission to compare fee impact and recoverable value; it never creates, signs, or broadcasts the refund transaction.

Parameters

Response (200)

Successful operation

Response (401)

Invalid API Key