Submitting a listing, or making an order, is a fundamental process for any user looking to sell a Runes inscription on a digital marketplace. This action allows holders to offer their digital assets for sale at a specified price, making them available to potential buyers within the ecosystem.
This guide provides a comprehensive overview of the technical process involved in submitting a single Runes inscription listing via a dedicated API endpoint. Before initiating a listing, it is crucial to verify your holdings. You can do this by first calling the appropriate endpoint to fetch your wallet's assets, which will return a list of all Runes inscriptions held by a specific wallet address.
Understanding the Make Order Endpoint
The primary function of the 'make order' API is to facilitate the listing of a Runes-based digital asset for sale. It requires specific details about the asset, the seller's wallet, and the proposed sale terms to construct and submit the transaction to the marketplace.
Key Request Parameters
To successfully submit a listing, you must provide the following parameters in your API request:
- runesId: The unique identifier of the Runes token you wish to list (e.g.,
840000:3). - walletAddress: The blockchain address of the wallet that currently holds the specified
runesId. - utxo: The Unspent Transaction Output where the Runes token resides. This must be formatted as
txHash:vout(e.g.,d578a0967605257f75be625cbdc2506f2a52f9135f56f302badab6a3da54e0d4:0). - unitPrice: The listing price per unit of the token, denominated in satoshis.
- totalPrice: The total listing price for the inscription, denominated in BTC.
- psbt: A Partially Signed Bitcoin Transaction (PSBT) that has been signed. The API currently only accepts a base64-encoded PSBT. Crucially, the UTXO containing the inscription must be placed at input index=1, and the recipient address and amount must be placed at output index=1.
API Request Details
- HTTP Method: POST
- Request URL:
https://web3.okx.com/api/v5/mktplace/nft/runes/make-order
Interpreting the Response
The API's response will indicate whether your listing submission was successful or not. The response body contains several key fields:
- code: An integer status code. A value of
0indicates success. Any other value signifies a failure, and the reason should be investigated. - data: An object containing the main response data. The structure of this object can be inferred from the provided response examples in the full documentation.
- msg: A string message providing additional context, particularly useful for debugging when the
codeis not0.
Best Practices for Listing Runes Inscriptions
Successfully navigating the marketplace involves more than just the technical API call. Adhering to best practices can increase your chances of a successful sale.
- Accurate Pricing: Research the current market value of similar Runes inscriptions. Setting a competitive
unitPriceandtotalPriceis essential for attracting buyers. - Wallet Management: Ensure the
walletAddressyou specify is secure and that you have control over the private keys. Double-check that it indeed holds the asset you are trying to list. - UTXO Verification: Providing the correct
utxois critical. An incorrect or spent UTXO will cause the transaction to fail. - PSBT Construction: Pay close attention to the requirements for constructing and signing the PSBT. Incorrectly formatting the inputs and outputs is a common source of errors.
For developers and advanced users looking to streamline this process, it is highly recommended to explore more strategies for building robust and automated marketplace integration tools.
Frequently Asked Questions
What is the difference between unitPrice and totalPrice?
The unitPrice is the price per single unit of the Runes token, measured in satoshis. The totalPrice is the final sale price for the entire inscription listing, denominated in Bitcoin (BTC). For assets with a balance of 1, these values will often be equivalent when converted.
Why do I need to provide a UTXO?
The UTXO (Unspent Transaction Output) is a fundamental concept in Bitcoin-based protocols. It specifies the exact location on the blockchain where your Runes token is currently held. The marketplace uses this information to construct the transaction that transfers ownership upon a successful sale.
What happens if my PSBT is formatted incorrectly?
If the PSBT is not base64-encoded, or if the required UTXO and recipient details are not in the mandated input/output index positions (index=1), the API request will be rejected. You will receive a non-zero code and a msg describing the error, and the listing will not be submitted.
How can I check the status of my listing after it's submitted?
A successful API response typically returns a data object containing details about the new listing. You would then use other marketplace API endpoints, such as one for querying order status, to track its progress and see if it gets filled by a buyer.
Is there a fee for listing an inscription?
Marketplaces often charge fees for facilitating trades. The specific fee structure (e.g., a flat fee or a percentage of the sale price) is usually detailed in the marketplace's general documentation and not within the specific API call parameters described here.
Can I cancel a listing after it has been submitted?
Yes, most marketplaces provide a method to cancel active listings. This is typically done through a separate "cancel order" API endpoint, which would require the order ID or another unique identifier for the listing you wish to remove.