This documentation outlines how to use the Fractal Ordinals API to retrieve valid inscription data associated with a specific wallet address. This interface is essential for developers building applications that need to query and display detailed information about non-fungible tokens (NFTs) or BRC-20 token inscriptions on the blockchain.
Understanding the API Endpoint
The Fractal Ordinals API provides a straightforward POST method to fetch valid inscriptions. This is particularly useful for platforms that need to display a user's holdings, verify ownership, or analyze digital asset portfolios.
Request Address
To call this API, send a POST request to the following address:https://web3.okx.com/api/v5/mktplace/nft/fractal-ordinals/get-valid-inscriptions
Required Request Parameters
The request must include specific parameters to retrieve the correct data. The table below details each parameter:
| Parameter | Type | Required | Description |
|---|---|---|---|
| slug | String | Yes | The unique identifier (slug) of the collection. |
| walletAddress | String | Yes | The wallet address for which you are querying valid inscriptions. |
| limit | String | Yes | The maximum number of collections to return. Default is 10; maximum is 100. |
Optional Request Parameters
You can customize your query further with these optional parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| cursor | String | No | A pagination cursor for retrieving the next page of results. |
| sort | String | No | Defines the sorting order of the results. Options include: • listing_time_desc (default): Sort by order creation time, descending.• listing_time_asc: Sort by order update time, ascending.• price_desc: Sort by order price, high to low.• price_asc: Sort by order price, low to high.• unitprice_desc: Sort by order unit price, low to high.• unitprice_asc: Sort by order unit price, high to low. |
| isBrc20 | Boolean | No | Determines whether to retrieve Fractal NFT (false) or BRC-20 (true) listings. The default is true. |
Interpreting the API Response
A successful API call returns an array of objects, each containing detailed information about an ordinal inscription.
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| inscriptionId | String | The unique ID of the inscription. |
| nftId | String | The associated NFT ID for the inscription. |
| ticker | String | The ticker symbol of the BRC-20 token. |
| tickerId | String | The unique ID for the token ticker. |
| amount | String | The quantity of inscriptions included in the order. |
| cursor | String | A pagination token to be used in subsequent requests to retrieve the next page of data. |
Practical Use Cases and Implementation
This API is a powerful tool for developers creating marketplaces, portfolio trackers, or analytical dashboards. By providing a wallet address, you can instantly fetch a structured list of all valid inscriptions, complete with sorting and pagination for a smooth user experience.
👉 Explore more strategies for API integration
For instance, a marketplace could use this data to populate a user's profile page with their collectibles. A financial app could use the amount and ticker fields to calculate the total value of a user's BRC-20 holdings. The key is to handle the pagination correctly using the cursor parameter to ensure all data is retrieved for wallets with large numbers of inscriptions.
Frequently Asked Questions
What is the main purpose of the Fractal Ordinals API?
This API is designed to query and retrieve a list of valid digital inscriptions, such as NFTs or BRC-20 tokens, that are associated with a specific blockchain wallet address. It provides essential data for building applications that display or analyze a user's on-chain assets.
How does pagination work with this API?
The API uses a cursor-based pagination system. If the response contains a cursor field, it means there are more results available. To get the next page of data, you simply include this cursor value in the cursor parameter of your subsequent API request.
What is the difference between retrieving NFTs and BRC-20 tokens?
You control this with the isBrc20 parameter. Setting it to true (the default) will return BRC-20 token listings. Setting it to false will return listings for Fractal NFTs instead.
What does the 'slug' parameter refer to?
The slug is a unique, human-readable identifier for a specific collection of digital assets. It is used to filter the results so that you only retrieve inscriptions belonging to that particular collection.
Is there a limit to how many records I can request at once?
Yes, the limit parameter controls the page size. The default value is 10 items per request, and the maximum allowable value is 100 items per request. For larger datasets, you must use pagination.
How can I ensure I get the most recently listed items first?
Use the sort parameter and set its value to listing_time_desc. This will sort the results in descending order based on the order creation time, placing the newest listings at the top of the response.