This guide explains how to use the API endpoint to retrieve valid inscription data associated with a specific Web3 wallet address. The process involves querying the Ordinals and NFT marketplace API to obtain detailed information about inscriptions, including their unique identifiers, associated tickers, and quantities.
Understanding how to efficiently gather this data is essential for developers, traders, and analysts working within the Bitcoin NFT and BRC-20 ecosystem. The provided API offers a structured way to access this on-chain information programmatically.
API Request Details
To retrieve valid inscriptions, you must send a POST request to the designated API endpoint with the required parameters.
Endpoint
The request should be sent to the following address:https://web3.okx.com/api/v5/mktplace/nft/ordinals/get-valid-inscriptions
Required Parameters
Your request must include the following parameters to be processed successfully:
- slug: A string representing the unique identifier of the NFT collection you are querying.
- walletAddress: A string containing the specific wallet address for which you want to retrieve valid inscription data.
- limit: A string defining the maximum number of collections to return in the response. The default value is
10, and the maximum allowed value is100.
Optional Parameters
You can customize your query further with these optional parameters:
- cursor: A string used for pagination. Include the cursor value from a previous response to retrieve the next page of results.
sort: A string to define the order of the results. Available options include:
listing_time_desc: Sort by order creation time, descending (newest first).listing_time_asc: Sort by order creation time, ascending (oldest first).price_desc: Sort by order price, from high to low.price_asc: Sort by order price, from low to high.unitprice_desc: Sort by order unit price, from low to high.unitprice_asc: Sort by order unit price, from high to low.
- isBrc20: A boolean value. Set to
trueto retrieve BRC-20 token listings orfalsefor BTC NFT listings. The default value istrue.
Understanding the API Response
A successful API call returns an array of objects, each containing detailed information about a valid inscription linked to the provided wallet address.
Response Parameters
Each object in the response array contains the following fields:
- inscriptionId: The unique identifier of the inscription.
- nftId: The unique NFT ID associated with this specific inscription.
- ticker: The ticker symbol of the related BRC-20 token (e.g., ORDI, SATS).
- tickerId: The unique identifier for the ticker.
- amount: The quantity or number of inscriptions included in the order.
- cursor: A pagination token. Use this value in a subsequent request to retrieve the next page of results.
Practical Use Cases and Implementation
Implementing this API call allows you to build applications that require real-time insight into a wallet's Ordinals holdings. Common use cases include portfolio trackers, marketplace inventory checks, and analytical dashboards.
Developers can integrate this functionality into their platforms to provide users with a seamless way to view their digital assets. The pagination feature ensures that even wallets with large numbers of inscriptions can be queried efficiently without overloading the system or the response.
When building your request, ensure that all required parameters are correctly formatted to avoid errors. The walletAddress must be a valid address, and the slug must correspond exactly to the intended collection. 👉 Explore more strategies for API integration
Frequently Asked Questions
What is the purpose of the 'slug' parameter?
The 'slug' is a unique identifier for an NFT collection on the marketplace. It ensures that the API retrieves inscriptions from the specific collection you are interested in, rather than from all collections associated with a wallet.
How does pagination work with this API?
Pagination is handled through the cursor parameter. The initial response will include a cursor value if more data is available. To get the next set of results, simply include this cursor value in your next identical API request.
Can I filter results to show only NFTs or only BRC-20 tokens?
Yes, you can. Use the isBrc20 parameter. Set it to false to retrieve only Bitcoin NFT listings, or leave it as the default true to retrieve BRC-20 token listings.
What is the difference between 'price' and 'unitprice' in sorting?
'Price' refers to the total price of the entire order or listing. 'Unitprice' refers to the price per individual unit or token within that order, which is crucial for fractionalized assets or bulk listings.
Is there a rate limit for making API requests?
While the specific rate limits are not detailed in this endpoint's documentation, it is a standard practice to implement sensible throttling in your application to avoid being blocked by the API server.
What should I do if I receive an empty response?
An empty array typically means that no valid inscriptions were found for the given wallet address and collection slug combination. Double-check the wallet address and slug for accuracy, and ensure the wallet holds assets from that collection.