Integrating digital assets like Bitcoin-based NFTs and BRC-20 tokens into major trading platforms is a crucial step for developers and Web3 projects aiming for broader market exposure. OKX, one of the leading Web3 ecosystems, offers a robust Marketplace API that enables seamless listing submissions for Ordinals, BRC-20 tokens, and BTC NFTs. This guide walks you through the technical workflow, required parameters, and best practices for submitting listings using the OKX WaaS (Wallet-as-a-Service) Web3 API.
Whether you're building a decentralized marketplace, managing an Ordinals collection, or launching a BRC-20 token, understanding how to interact with the OKX Ordinals API ensures your assets reach active buyers efficiently.
How to Submit an Ordinal Listing on OKX
To list an ordinal inscription—whether it's a BRC-20 token or a BTC-native NFT—you must use the designated endpoint provided by OKX’s Web3 API infrastructure. The process revolves around constructing a valid PSBT (Partially Signed Bitcoin Transaction) and submitting it with essential metadata via a secure POST request.
👉 Discover how to generate PSBTs and list your inscriptions in minutes.
API Endpoint
POST https://web3.okx.com/api/v5/mktplace/nft/ordinals/okx/make-ordersThis endpoint accepts structured JSON payloads containing all necessary details about the asset being listed, including pricing, ownership proof (via PSBT), and inscription identifiers.
Required Request Parameters
To ensure your listing is processed successfully, include the following parameters in your request body. Each field plays a specific role in validating and publishing your listing.
| Parameter | Type | Required | Description |
|---|---|---|---|
nftId | String | Yes | Unique identifier for the ordinal NFT being listed |
inscriptionId | String | Yes | The unique ID of the Bitcoin inscription |
orderType | Integer | Yes | Set to 2 to indicate this is a listing (ask order) |
unitPrice | BigDecimal | Yes | Price per unit in satoshis. For NFTs, this is the total price |
isBrc20 | Boolean | No | true if listing a BRC-20 token; false for BTC NFTs. Defaults to true |
psbt | String | Yes | Base64-encoded PSBT proving control over the UTXO containing the inscription |
totalPrice | BigDecimal | Yes | Total listing price in satoshis |
🔍 Note: You can retrieve the required UTXO data for your inscription using the Query UTXO interface provided by OKX. This step is essential for generating a valid PSBT.
Understanding PSBT Requirements
A Partially Signed Bitcoin Transaction (PSBT) serves as cryptographic proof that you control the wallet holding the inscription. Since Ordinals are inscribed directly onto Bitcoin UTXOs, transferring or listing them requires interaction at the transaction level.
The PSBT must:
- Be base64-encoded
- Include input from the UTXO containing the inscription
- Not be fully signed—only partially signed so OKX can complete and broadcast it
Failure to provide a correct PSBT will result in a rejected listing. Developers should test their PSBT generation logic in a sandbox environment before going live.
Response Structure
After submitting your request, OKX returns a JSON response indicating whether the operation was successful.
Response Parameters
| Parameter | Type | Description |
|---|---|---|
nftId | String | The unique NFT ID associated with the listing request |
success | Boolean | Returns true if the listing was accepted, false otherwise |
errorMsg | String | Detailed error message if the submission failed |
Example Success Response
{
"nftId": "abc123-inscription-hash",
"success": true,
"errorMsg": null
}Example Error Response
{
"nftId": "abc123-inscription-hash",
"success": false,
"errorMsg": "Invalid PSBT: Input does not match inscription UTXO"
}Monitoring errorMsg is critical during development to debug issues related to formatting, authentication, or transaction validity.
Step-by-Step Workflow for Developers
- Identify the Inscription
Locate theinscriptionIdand correspondingnftIdfrom your wallet or indexer. - Fetch UTXO Data
Use the OKX UTXO Query API to get transaction output details. - Construct PSBT
Create a partially signed transaction spending the UTXO, ensuring inputs reference the correct inscription. - Encode PSBT in Base64
Convert the raw PSBT bytes into a base64 string for transmission. - Build JSON Payload
Assemble all required parameters, including pricing and asset type. - Send POST Request
Submit to the/make-ordersendpoint with proper headers (authentication handled separately via WaaS). - Handle Response
Checksuccessflag and log errors for troubleshooting.
👉 Learn how top builders automate listings with OKX APIs.
Common Use Cases
- NFT Marketplaces: Allow users to list their Ordinals directly from your platform.
- BRC-20 Launchpads: Enable creators to set prices and list tokens immediately after minting.
- Wallet Integrations: Add "List on OKX" functionality inside non-custodial wallets.
- Automated Pricing Bots: Update listings dynamically based on market conditions.
These integrations enhance liquidity and user experience across the Bitcoin ecosystem.
Frequently Asked Questions (FAQ)
Q: Can I list both BRC-20 tokens and BTC NFTs using this API?
A: Yes. By setting the isBrc20 parameter to true or false, you can list either BRC-20 tokens or BTC-based NFTs respectively.
Q: What happens if my PSBT is invalid?
A: The API will reject the request and return an error message explaining the issue—common causes include incorrect UTXO references or malformed transactions.
Q: Is there a fee for listing?
A: Listing itself is free, but blockchain transaction fees apply when the sale is executed and the PSBT is finalized and broadcasted.
Q: Do I need KYC or approval to use this API?
A: Access depends on your integration method through OKX WaaS. Most developer tools require registration and API key authentication, but no individual KYC is needed solely for listing submission.
Q: How long does it take for a listing to appear on OKX?
A: Listings typically appear within seconds after successful submission, assuming all data is valid and network conditions are normal.
Q: Can I cancel or update my listing?
A: This API is for creating listings only. Cancellation or price updates require separate endpoints or manual action via the OKX interface.
Core Keywords for SEO
- Ordinals API
- BRC-20 listing
- BTC NFT marketplace
- OKX Web3 API
- Submit listing OKX
- PSBT for Ordinals
- WaaS API documentation
- Bitcoin inscription listing
These keywords reflect high-intent search queries from developers and project teams building on Bitcoin’s emerging digital asset layers.
By mastering the OKX listing submission API, developers unlock direct access to one of the most active markets for Bitcoin-native assets. With clear parameter requirements, strong documentation support, and integration-ready design, this toolset empowers builders to bring innovation directly to users.
👉 Start building today—connect your app to OKX’s Web3 ecosystem.
Ensure your backend systems are equipped to handle PSBT generation, error handling, and real-time status checks. As demand for BRC-20 tokens and Ordinal NFTs continues to grow, early integration offers significant first-mover advantages in visibility and user engagement.