Create Listing with Runes API – WaaS Web3 Documentation

Integrating blockchain-powered digital assets into modern marketplaces requires reliable, developer-friendly tools. The Runes API by OKX enables developers and creators to seamlessly list Runes inscriptions on a global marketplace, leveraging Bitcoin’s growing ecosystem of tokenized assets. This guide walks you through the listing process, required parameters, and best practices for using the Runes API within the broader Marketplace API suite of WaaS (Wallet as a Service) Web3 solutions.

Whether you're building a decentralized application, managing digital collectibles, or automating asset listings, understanding how to correctly structure your API calls is crucial for success.

How to List a Runes Inscription

To list a single Runes inscription on the OKX platform, use the dedicated endpoint designed for secure and efficient marketplace integration.

Before initiating a listing request, it's recommended to first retrieve your wallet’s asset holdings using the Get Wallet Assets method. This allows you to identify which Runes tokens are available for listing and confirm ownership via UTXO data.

👉 Discover how to automate Runes listings with powerful Web3 tools.

Request Endpoint

Use the following POST request to submit your listing:

POST https://web3.okx.com/api/v5/mktplace/nft/runes/make-order

This endpoint accepts structured JSON payloads containing all necessary details about the inscription, pricing, and transaction proof.

Required Request Parameters

Each listing must include precise information to validate ownership and set pricing terms. Below are the mandatory fields:

• runesId (String, Required)
  The unique identifier for the Runes token (e.g., 840000:3).
• walletAddress (String, Required)
  The blockchain address that currently holds the specified Runes inscription.
• utxo (String, Required)
  The unspent transaction output where the token resides. Format: txHash:vout
  Example: d578a0967605257f75be625cbdc2506f2a52f9135f56f302badab6a3da54e0d4:0
• unitPrice (BigDecimal, Required)
  The price per unit of the inscription, denominated in Satoshis.
• totalPrice (BigDecimal, Required)
  The total listing price in BTC. Ensure this aligns with the unit price and quantity.

• psbt (String, Required)
  A signed Partially Signed Bitcoin Transaction (PSBT), provided in base64 encoding.
  Important:

  • The UTXO containing the inscription must be placed at input index 1.
  • The corresponding output at index 1 must contain the receiving address and correct amount.

Ensuring accurate PSBT formatting is essential—malformed transactions will result in failed listings.

Understanding the Response Structure

After submitting your request, the API returns a standardized JSON response.

Response Parameters

• code (Integer)
  Indicates the result status:

  • 0 = Success
  • Any other value = Failure
• data (Object)
  Contains the detailed response body upon success. Specific fields depend on the operation outcome.
• msg (String)
  A human-readable message explaining the result, especially useful when an error occurs (code ≠ 0).

A successful response confirms that your Runes inscription has been submitted for listing and is being processed by the marketplace engine.

👉 Learn how to generate compliant PSBTs for Runes listings.

Practical Use Case: Automating Bulk Listings

Imagine managing a collection of 100+ Runes inscriptions across multiple wallets. Manually listing each one would be time-consuming and error-prone. By integrating the Runes API into a custom script or backend service, developers can:

• Fetch available inscriptions via get wallet assets
• Validate UTXO states
• Generate properly formatted PSBTs
• Submit batched listing requests programmatically

This automation not only increases efficiency but also ensures consistency in pricing and transaction structure.

For example:

{
  "runesId": "840000:3",
  "walletAddress": "bc1qabc...xyz",
  "utxo": "d578a096...e0d4:0",
  "unitPrice": 10000,
  "totalPrice": 0.0001,
  "psbt": "cHNidP8..."
}

Such JSON payloads can be dynamically generated based on real-time inventory data.

Common Errors and Troubleshooting

Even with correct syntax, issues may arise during listing attempts. Here are frequent causes:

• Invalid PSBT: Ensure the UTXO is at input index 1 and output matches.
• Insufficient balance: The wallet must cover network fees.
• Incorrect runesId: Double-check token ID format.
• Expired UTXO: UTXOs can become invalid if spent in another transaction.

Always verify asset status before submission and handle non-zero code responses gracefully in your application logic.

Security Best Practices

When working with private keys and PSBTs:

• Sign transactions off-chain using secure environments.
• Never expose private keys in logs or client-side code.
• Use hardware wallets or secure enclaves when possible.
• Validate all inputs before constructing PSBTs.

These steps reduce the risk of fund loss or unauthorized access.

Frequently Asked Questions

Q: Can I list multiple Runes inscriptions in one request?
A: No. Each API call supports only a single inscription listing. For bulk operations, send multiple requests sequentially or in parallel with proper rate-limit handling.

Q: What happens if my PSBT is incorrectly formatted?
A: The API will reject the request with a non-zero code and an explanatory msg. Always test PSBT generation with small-value inscriptions first.

Q: Is there a fee for listing Runes on OKX?
A: Listing itself is typically free, but blockchain transaction fees apply when the sale settles. These are deducted from the final payout.

Q: How long does it take for a listing to go live?
A: Once the PSBT is validated and accepted, listings appear almost instantly—usually within seconds.

Q: Can I cancel or edit a listing after submission?
A: Yes, through separate API endpoints designed for updating or removing active listings. Check the full documentation for cancel-order and update-order methods.

Q: Do I need KYC verification to list Runes?
A: Depending on jurisdiction and volume, identity verification may be required. Integrate compliance checks early in your user flow to avoid disruptions.

👉 Access advanced Web3 APIs for seamless blockchain integration.

Final Thoughts

The Runes API is a powerful tool for developers looking to participate in the emerging Bitcoin-native token economy. With precise control over pricing, ownership verification via UTXO, and support for secure PSBT-based transactions, it offers both flexibility and reliability.

By combining this with other features in the Marketplace API suite under WaaS Web3, you can build robust applications that manage digital assets at scale—whether for NFT platforms, gaming ecosystems, or decentralized marketplaces.

Core keywords naturally integrated throughout: Runes API, Marketplace API, WaaS, Web3 API, list Runes inscription, PSBT, wallet assets, OKX platform

Ensure your integration follows best practices in security, validation, and user experience to maximize adoption and trust.