Query Wallet Accounts with OKX Web3 API

Managing digital asset accounts efficiently is crucial for developers building on blockchain infrastructure. Whether you're integrating wallet functionality into a decentralized application (dApp) or managing multiple user accounts at scale, having reliable access to account data is essential. The OKX Web3 API offers a powerful and secure way to query wallet accounts under your project, enabling seamless wallet account management, Web3 integration, and scalable wallet-as-a-service solutions.

This guide walks you through the account query endpoint, including request structure, parameters, response format, and practical usage examples — all optimized for developers seeking robust, production-ready API interactions in 2025.

Understanding the Query Accounts Endpoint

The /wallet/account/accounts endpoint allows you to retrieve a list of all accounts created under your project. This includes both wallet accounts (where private keys are managed) and observation-only accounts (used for monitoring external addresses without control). It's an essential tool for platforms requiring real-time visibility into user or system-generated wallets.

This API call uses a simple GET request and supports pagination via cursor-based navigation, ensuring efficient handling of large datasets without performance degradation.

👉 Discover how OKX Web3 API simplifies blockchain integration for your dApp

Request Details

Endpoint

GET https://web3.okx.com/api/v5/wallet/account/accounts

This HTTPS endpoint is part of the OKX Wallet-as-a-Service suite, designed for high availability and low-latency responses. All requests must be authenticated using your project credentials.

Authentication Headers

To access this endpoint, include the following headers:

• OK-ACCESS-PROJECT: Your unique project ID
• OK-ACCESS-KEY: API key assigned to your application
• OK-ACCESS-SIGN: Signature generated from the request content
• OK-ACCESS-PASSPHRASE: Passphrase set during API key creation
• OK-ACCESS-TIMESTAMP: ISO 8601 formatted timestamp (e.g., 2025-04-05T10:20:30.123Z)

These headers ensure secure, identity-verified access to your account data.

Optional Request Parameters

You can fine-tune the response using optional query parameters:

Using limit helps control payload size, while cursor enables smooth navigation across paginated results. For example, setting limit=100 retrieves up to 100 accounts in one call, reducing round trips.

Response Structure

A successful request returns a JSON object with the following structure:

The cursor field is key for pagination — use its value in subsequent requests as the cursor parameter to fetch the next batch.

Practical Usage Example

Here’s a complete curl command demonstrating how to call this endpoint:

curl --location --request GET 'https://web3.okx.com/api/v5/wallet/account/accounts?limit=50' \
--header 'Content-Type: application/json' \
--header 'OK-ACCESS-PROJECT: 86af********d1bc' \
--header 'OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418' \
--header 'OK-ACCESS-SIGN: leaV********3uw=' \
--header 'OK-ACCESS-PASSPHRASE: 1****6' \
--header 'OK-ACCESS-TIMESTAMP: 2025-04-05T12:21:41.274Z'

This returns up to 50 accounts starting from the first page. If more records exist, the response includes a cursor value like "50" — use it in the next request to continue fetching.

Interpreting the Response

Below is a sample successful response:

{
  "code": "0",
  "data": [
    {
      "cursor": "50",
      "accounts": [
        {
          "accountId": "0xdf54b6c6195ea4d948d03bfd818d365cf175cfc2",
          "accountType": "0"
        },
        {
          "accountId": "0x04ad62387d1f1c7034087bbe4d16163d06fae42d",
          "accountType": "1"
        }
      ]
    }
  ],
  "msg": "success"
}

In this example:

• Two accounts are returned.
• The first is a wallet account (accountType: "0"), likely controlled by your system.
• The second is an observation account (accountType: "1"), possibly added to track external transactions.
• The cursor value "50" indicates that the next page begins at record 51.

Developers can parse this data to display account lists, sync with internal databases, or trigger downstream processes like balance checks or transaction monitoring.

👉 Explore advanced wallet management tools built for Web3 developers

Key Use Cases

1. User Dashboard Integration

Display all user-associated wallets in a unified interface, allowing users to view and manage their digital asset holdings securely.

2. Multi-Account Monitoring

Track hundreds or thousands of addresses across chains with observation accounts, ideal for custodial services or analytics platforms.

3. Audit & Compliance Logging

Maintain logs of all created accounts for regulatory reporting and internal audits.

4. Automated Account Discovery

Integrate with backend systems to automatically detect new accounts and apply policies (e.g., tagging, risk scoring).

Frequently Asked Questions

Q: What is the difference between a wallet account and an observation account?
A: A wallet account (accountType: "0") is one where private keys are generated and stored (if applicable), allowing transaction signing. An observation account (accountType: "1") only monitors on-chain activity without private key access — useful for tracking third-party addresses.

Q: How do I paginate through large numbers of accounts?
A: Use the cursor value from each response in the next request’s cursor parameter. Combine with limit (up to 100) to optimize performance.

Q: Is there a rate limit on this API endpoint?
A: Yes, standard rate limits apply based on your project tier. Refer to OKX documentation for specific thresholds, typically measured in requests per second.

Q: Can I filter accounts by type or chain?
A: Currently, filtering by type isn’t supported directly in this endpoint. You’ll need to filter results client-side. Chain-level queries depend on project configuration and supported networks.

Q: How secure is this API for production use?
A: The OKX Web3 API employs industry-standard security practices, including HMAC authentication, encrypted communication (TLS), and scoped API keys. Always store credentials securely and avoid exposing them in client-side code.

Final Thoughts

Efficient wallet account management lies at the heart of modern Web3 applications. With the OKX Wallet-as-a-Service API, developers gain instant access to scalable, secure tools for querying and managing blockchain identities.

Whether you're building a DeFi platform, NFT marketplace, or institutional custody solution, mastering this endpoint empowers you to deliver smooth, data-driven experiences — all while maintaining full control and visibility over your ecosystem of accounts.

👉 Start building smarter Web3 applications today with OKX’s developer-first tools