In the rapidly evolving world of Web3, accessing accurate and real-time wallet asset data is essential for developers, traders, and blockchain analysts. The Runes API and Market API offered by OKX provide powerful tools to retrieve detailed information about digital assets held in blockchain wallets—especially for emerging token standards like Runes on Bitcoin. This guide walks you through how to efficiently use the Get Wallet Assets endpoint to fetch comprehensive asset details from specific wallet addresses.
Whether you're building a decentralized application (dApp), analyzing market trends, or managing multi-wallet portfolios, understanding how to interact with these Web3 APIs gives you a competitive edge in today’s data-driven crypto ecosystem.
Understanding the Get Wallet Assets Endpoint
The GET /api/v5/mktplace/nft/runes/get-owned-assets endpoint allows developers to query all Runes assets owned by one or more specified wallet addresses. Runes are a new type of fungible token protocol built on Bitcoin, designed for simplicity and efficiency in token creation and transfer.
This API call returns granular data about each asset, including ownership details, transaction metadata, pricing information, and listing status—making it ideal for integration into marketplaces, portfolio trackers, and analytics platforms.
Key Features of the Endpoint
- Supports multiple wallet address queries in a single request (up to 20).
- Provides both UTXO-level and token-level data.
- Includes pricing in BTC, USD, and satoshis for listed assets.
- Delivers metadata such as icons, names, and ticker symbols.
- Enables pagination via cursor-based navigation.
These features make the endpoint not only robust but also scalable for high-performance applications.
Request Details
To retrieve wallet assets, send a GET request to the following URL:
https://web3.okx.com/api/v5/mktplace/nft/runes/get-owned-assetsRequired and Optional Parameters
| Field | Type | Required | Description |
|---|---|---|---|
runesId | String | Yes | Unique identifier of the token |
walletAddresses | String | Yes | Comma-separated list of wallet addresses (max 20) |
cursor | String | No | Cursor for pagination (maximum 1,000) |
limit | Integer | No | Number of records per page (default: 10, max: 100) |
🔍 Tip: Use the cursor parameter to handle large datasets efficiently. It enables sequential fetching without duplication, ensuring smooth performance even when scanning multiple wallets.Example Request
GET /api/v5/mktplace/nft/runes/get-owned-assets?runesId=12345&walletAddresses=bc1qabc...,bc1qxyz...&limit=20
Host: web3.okx.comThis request fetches up to 20 assets associated with two Bitcoin addresses under the specified Runes ID.
Response Structure Explained
The API returns a JSON array of asset objects containing rich metadata. Below is a breakdown of key response fields:
assetId: Internal database identifier (no external significance).tickerType: Token standard type (4indicates Runes).ticker,name,symbol: Human-readable identifiers for the token.tickerId,inscriptionNum: Unique identifiers tied to blockchain records.ownerAddress: The wallet currently holding the asset.amount: Quantity of Runes held within the UTXO.chain: Blockchain network (e.g., Bitcoin mainnet).utxoTxHash,utxoVout,utxoValue: UTXO-specific transaction data.txHash: Transaction hash where ownership was confirmed.tickerIcon: URL to the token's icon image.status: Listing status (0: not listed,1: listed,2: pending).listTime,orderId: Timestamp and ID if the asset is on sale.confirmations: Number of blockchain confirmations.Pricing Data:
price: BTC priceusdPrice: USD valuesatPrice: Price in satoshis
unavailable: Flag indicating complex UTXO conditions (e.g., multiple Atomicals or protocol assets in one UTXO).
This depth of detail supports advanced use cases such as real-time price tracking, fraud detection, and cross-protocol analysis.
👉 Access real-time blockchain data with an API built for speed, accuracy, and scalability.
Practical Use Cases
1. Portfolio Dashboard Development
Developers can integrate this API into personal finance dashboards that display Runes holdings across multiple wallets. By combining balance data with live pricing (usdPrice, price), users gain instant visibility into their portfolio value.
2. NFT & Runes Marketplace Monitoring
Marketplaces can use the status and orderId fields to monitor listed assets and verify order validity. The inclusion of listTime helps enforce time-based rules or detect stale listings.
3. On-Chain Analytics Tools
Analysts can leverage UTXO-level data (utxoTxHash, confirmations) to trace asset provenance and assess liquidity risks. High confirmation counts indicate secure holdings, while low values may signal recent transfers needing verification.
4. Arbitrage and Trading Bots
With access to both market price and listing status, trading bots can identify mispriced Runes across platforms and execute arbitrage strategies—especially valuable during volatile market conditions.
Frequently Asked Questions
Q: Can I query more than 20 wallet addresses at once?
A: No, the API limits requests to 20 addresses per call. For larger datasets, consider batching requests using automation scripts or server-side logic.
Q: What does "unavailable = 1 or 2" mean in the response?
A: These flags indicate complex UTXO scenarios:
1: Multiple Atomicals assets exist in the same UTXO2: Multiple protocol assets (e.g., Runes + BRC-20) are bundled
Such cases may require special handling during transfers or listings.
Q: Is there rate limiting on this API?
A: Yes, to ensure service stability, OKX applies fair usage policies. Check official documentation for exact limits or consider using WebSocket streams for high-frequency needs.
Q: How often is pricing data updated?
A: Prices (usdPrice, price) are refreshed in near real-time based on active market listings. However, unlisted assets may show null or outdated values.
Q: Can I get historical ownership data?
A: This endpoint only returns current ownership. For historical tracking, combine it with blockchain explorers or use OKX’s chain indexing APIs.
Q: Does this support testnet or only mainnet?
A: Currently, the API operates on Bitcoin mainnet only. Testnet support may be available through sandbox environments—check developer resources for details.
Why Choose OKX Web3 APIs?
OKX's Web3 API suite stands out for its reliability, low latency, and deep integration with emerging protocols like Runes. With comprehensive endpoints covering wallet services, market data, and NFT operations, it serves as a full-stack solution for modern blockchain development.
Moreover, its clean authentication model and consistent response formats reduce integration time—letting you focus on innovation rather than infrastructure.
👉 Start building smarter dApps with a trusted Web3 API platform trusted by developers worldwide.
Final Thoughts
As Bitcoin-based tokens like Runes gain traction, having immediate access to wallet-level asset data becomes crucial. The Get Wallet Assets endpoint empowers developers with precise, structured insights into Runes ownership and market activity.
By leveraging this API effectively—and integrating it into broader Web3 applications—you unlock new possibilities in decentralized finance, digital collectibles, and blockchain analytics.
Stay ahead of the curve by harnessing real-time data from one of the most advanced Web3 platforms available today.