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

·

Creating an ordinals listing on the OKX platform has never been easier. Whether you're new to Bitcoin-based NFTs or a seasoned Web3 developer, this step-by-step guide will walk you through the entire process of listing your inscriptions using the OKX WaaS (Wallet-as-a-Service) Web3 APIs. From retrieving valid inscription data to submitting your final listing, we’ll cover every technical detail with clarity and precision.

This tutorial is ideal for developers integrating ordinals functionality into decentralized applications, marketplaces, or digital asset management tools. By leveraging the Ordinals API and Marketplace API, you can automate and streamline the listing process securely and efficiently.

Step 1: Retrieve Valid Inscription Data

Before listing any ordinal, you must first identify a valid Bitcoin inscription (NFT) that is eligible for sale. This requires querying the OKX API to retrieve active inscriptions associated with your wallet or target address.

To get started:

  1. Set up request headers
    Ensure your authentication tokens and content-type headers (e.g., Content-Type: application/json, Authorization: Bearer <token>) are correctly configured.
  2. Make the API call
    Use the Retrieve Valid Inscriptions endpoint to fetch available inscriptions. The response includes critical metadata such as inscriptionId, contentType, genesisAddress, and satPoint.

👉 Generate highly click-attractive anchor text here based on article context and anchor link characteristics; no brand names other than 'OKX' may appear here.

Pro Tip: Filter results by status (unlisted, listed) to avoid duplicate submissions. Only unlisted inscriptions should be processed for new listings.

This data forms the foundation of your listing—without a valid inscriptionId, subsequent steps cannot proceed.

Step 2: Fetch UTXO Information for the Inscription

Each Bitcoin inscription is tied to a specific Unspent Transaction Output (UTXO). To construct a valid transaction for listing, you need accurate UTXO details including txid, vout, and value.

Here’s how:

  1. Construct a new API request
    Use the inscriptionId obtained in Step 1 to query the UTXO via the Query UTXO endpoint.

  2. Parse the response
    You'll receive structured data like:

    {
  "txid": "abc123...",
  "vout": 0,
  "value": 546,
  "scriptPubKey": "76a914..."
}

This UTXO information is essential for building the Partially Signed Bitcoin Transaction (PSBT) in the next phase.

🔑 Why It Matters: A mismatched UTXO will invalidate the PSBT and cause transaction failure. Always verify that the UTXO corresponds exactly to the inscription being listed.

Step 3: Generate and Sign the PSBT with Listing Price

Now comes the core transaction-building phase: creating a PSBT that encodes your desired listing price and prepares it for signing.

Key Requirements:

Process Overview:

  1. Prepare PSBT Message
    Define inputs (from UTXO), outputs (recipient address + marketplace fee), and embed metadata indicating the intent to list. Include:

    • unitPrice (in satoshis)
    • totalPrice
    • inscriptionId

  2. Use Wallet SDK for Signing
    Leverage tools like the OKX Bitcoin Wallet SDK to generate and sign the PSBT securely. Example snippet:

    const psbt = new BitcoinPSBT();
psbt.addInput({ hash: utxo.txid, index: utxo.vout });
// Add outputs and custom listing logic
const signedPsbt = await wallet.signPsbt(psbt);

👉 Generate highly click-attractive anchor text here based on article context and anchor link characteristics; no brand names other than 'OKX' may appear here.

⚠️ Important Note: For BRC-20 tokens, calculate unitPrice = totalPrice / number of inscriptions. For BTC NFTs (single units), unitPrice equals totalPrice.

Once signed, the PSBT is ready for submission to the marketplace.

Step 4: Submit Your Ordinals Listing to OKX

With all prerequisites complete, it’s time to finalize and publish your listing on the OKX platform.

Submission Steps:

  1. Configure Endpoint & Headers
    Target the official listing submission endpoint with proper authorization headers and body parameters:

    {
  "inscriptionId": "abc123i0",
  "psbt": "psbt-base64-string",
  "unitPrice": 200,
  "totalPrice": 10000
}

  2. Send POST Request
    Execute the request. On success, you’ll receive a confirmation response:

    {
  "success": true,
  "listingId": "list_789xyz",
  "message": "Inscription listed successfully"
}

Your ordinal is now live on the marketplace—visible to global buyers and ready for trade.

Frequently Asked Questions (FAQ)

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

The inscription ID uniquely identifies a Bitcoin-native NFT on-chain. It follows the format {txid}i{index} and is required at every stage—from fetching UTXO to submitting listings.

Q2: Can I update my listing price after publishing?

Yes, but only downward adjustments are allowed directly. Lowering the price reuses the same process with updated values. Raising requires delisting first, then relisting at a higher price.

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

The system enforces a minimum value of 0.00001 BTC (1,000 satoshis) for all transactions involving ordinals. Ensure both totalPrice and output values meet this threshold.

Q4: Is there a difference between BTC NFTs and BRC-20 listings?

Yes. BTC NFTs represent single digital artifacts—so unitPrice = totalPrice. BRC-20 tokens are fungible across multiple inscriptions, so unitPrice = totalPrice / quantity.

Q5: Do I need to manually broadcast the transaction?

No. Once submitted via the OKX API, the platform handles transaction broadcasting to the Bitcoin network upon buyer purchase or manual delisting.

Q6: How secure is this process?

Security is enforced through signed PSBTs, authenticated API access, and backend validation. Never expose private keys—signing should occur client-side using trusted SDKs.

Final Thoughts

By following this guide, developers can seamlessly integrate ordinals listing capabilities into their applications using OKX's robust Web3 API suite. With clear endpoints for retrieving inscriptions, managing UTXOs, generating PSBTs, and publishing listings, automation becomes not just possible—but efficient and reliable.

Whether you're building a marketplace aggregator, a collector dashboard, or a minting tool, understanding these core workflows empowers you to deliver real value in the evolving Bitcoin ecosystem.

👉 Generate highly click-attractive anchor text here based on article context and anchor link characteristics; no brand names other than 'OKX' may appear here.

Core Keywords:

These keywords have been naturally integrated throughout the article to enhance search visibility while maintaining readability and technical accuracy.