Quick Start: How to Create an Ordinals Listing Using the OKX Marketplace API

·

Creating a Bitcoin ordinals listing on a leading Web3 platform has never been easier. With the OKX Marketplace API, developers and digital asset creators can seamlessly list inscriptions, manage UTXO data, and submit transactions using programmable Bitcoin-native tools. This comprehensive guide walks you through each step of the process—from retrieving valid inscription data to successfully submitting your ordinals listing on OKX.

Whether you're building a Bitcoin NFT marketplace, managing digital collectibles, or integrating BRC-20 tokens into your application, understanding how to use the Ordinals API and WaaS (Wallet as a Service) Web3 APIs is essential. Let’s dive into the workflow with clarity, precision, and developer-friendly insights.

Step 1: Retrieve Valid Inscription Data

Before listing any ordinal inscription, you must first verify its existence and validity. The initial phase involves fetching accurate inscription data from the blockchain via OKX’s API.

👉 Discover how to connect to powerful Web3 tools for seamless ordinals management.

To begin:

  1. Set up the request headers
    Ensure proper authentication by including required headers such as Content-Type, OK-ACCESS-KEY, and other authorization parameters based on your WaaS credentials.
  2. Make the GET request
    Use the endpoint detailed in the Retrieve Valid Inscriptions documentation to fetch available inscriptions linked to your wallet or specified address.

The response will include critical details like:

This data confirms that the inscription is eligible for listing and provides foundational metadata needed for subsequent steps.

Pro Tip: Always validate inscription status before proceeding—attempting to list an already-sold or invalid inscription will result in transaction failure.

Step 2: Fetch UTXO Information

Each Bitcoin-based inscription is tied to a specific Unspent Transaction Output (UTXO). To construct a valid transaction for listing, you must retrieve the UTXO associated with your target inscription.

You’ll need:

Follow these actions:

  1. Construct the request
    Set up the header and body to query UTXO information using the Query UTXO endpoint.

  2. Extract key UTXO fields
    Upon successful retrieval, you should receive:

    • txid: The transaction ID containing the UTXO
    • vout: Output index
    • value: Amount in satoshis
    • scriptPubKey: Locking script for verification

This UTXO data is crucial for building the Partially Signed Bitcoin Transaction (PSBT) in the next step.

Step 3: Generate and Sign PSBT with Listing Price

Now comes the core transaction-building phase. You'll define your desired listing price and generate a PSBT that reflects this intent. This unsigned transaction will later be signed and broadcasted.

Key Considerations:

Implementation Steps:

  1. Create the PSBT message payload
    Include:

    • inscriptionId
    • listingPrice in satoshis
    • UTXO details (txid, vout)
    • Output address (usually your marketplace-controlled address)
  2. Use the OKX Wallet SDK
    Leverage the OKX JavaScript Wallet SDK, particularly the psbtSign.ts module, to assemble and partially sign the transaction.

Example snippet (conceptual):

const psbt = new BitcoinPsbt();
psbt.addInput({ hash: txid, index: vout, nonWitnessUtxo: Buffer.from(rawTx, 'hex') });
psbt.addOutput({ address: marketplaceAddress, value: listingPrice });

After generating the PSBT hex string, keep it ready for submission.

👉 Access advanced tools to streamline PSBT creation and signing workflows.

Step 4: Submit the Ordinals Listing

With all components prepared—the valid inscription, UTXO data, and signed PSBT—you’re now ready to submit your listing to the OKX marketplace.

Prepare Your Request:

  1. Set endpoint and headers
    Use the designated marketplace submission endpoint and include:

    • Authorization tokens
    • Content-type
    • Request ID (if required)

  2. Structure the payload
    Important parameters include:

    • inscriptionId
    • psbtHex: Full PSBT string
    • totalPrice: Total listing price in satoshis
    • unitPrice: Calculated per unit (especially relevant for BRC-20)

💡 Understanding unitPrice:

  • For BTC NFTs (Ordinals): Since each NFT is unique and indivisible (amount = 1), unitPrice = totalPrice.
  • For BRC-20 tokens: These are fungible and may represent multiple units. Here,
    unitPrice = totalPrice / number of inscribed tokens.

Example: If you're listing 50 inscriptions of a BRC-20 token for 10,000 sats total,
unitPrice = 10,000 / 50 = 200 sats.

  1. Send the POST request
    Submit the finalized payload to the listing endpoint.

Upon success, you’ll receive a confirmation response such as:

{
  "result": true,
  "listingId": "lstg_abc123xyz",
  "message": "Inscription listed successfully"
}

Your ordinals asset is now live on the marketplace.

Frequently Asked Questions (FAQ)

Q1: What is an inscription ID, and why do I need it?

An inscription ID uniquely identifies a Bitcoin ordinal inscription in the format {txid}i{index}. It's required to locate the asset on-chain and link it to UTXO and listing data during API calls.

Q2: Can I update my listing price after submission?

Yes, but only downward adjustments are allowed under certain conditions. The new price must still meet minimum thresholds (≥1,000 sats), and reducing prices too frequently may affect visibility.

Q3: Why did my PSBT request fail with “insufficient amount”?

This error occurs when the specified totalPrice is below 1,000 satoshis (0.00001 BTC). Always ensure your pricing complies with platform minimums.

Q4: Is there a difference between listing BTC NFTs vs BRC-20 tokens?

Yes. BTC NFTs are single-unit assets—so unitPrice equals totalPrice. BRC-20 listings involve divisible tokens, requiring proper calculation of unitPrice based on quantity.

Q5: Do I need to manually sign the PSBT?

While OKX’s Wallet SDK supports signing functionality, you must control private keys securely. Never expose them in frontend code or untrusted environments.

Q6: How long does it take for a listing to appear on the marketplace?

Listings typically go live within seconds after successful submission and blockchain confirmation. However, front-end visibility may depend on marketplace indexing speed.

Final Thoughts

Integrating with OKX’s Marketplace API and Ordinals API empowers developers to build scalable Web3 applications around Bitcoin-native assets. From retrieving inscription data to submitting fully formed listings, each step leverages secure, well-documented endpoints designed for reliability and performance.

By mastering UTXO handling, PSBT construction, and correct pricing logic—especially across BTC NFTs and BRC-20 tokens—you position yourself at the forefront of the evolving Bitcoin ecosystem.

👉 Start building today with robust Web3 infrastructure built for innovation.

Core Keywords:
Ordinals API, Marketplace API, WaaS Web3 API, Bitcoin NFT, BRC-20, PSBT, UTXO, inscription ID