> ## Documentation Index > Fetch the complete documentation index at: https://docs.oceanx.trade/llms.txt > Use this file to discover all available pages before exploring further. # Read observed top traders > Ranks wallets by observed buy plus sell USD volume descending, using an already cached native execution view. PnL is explicitly partial execution-only accounting, not transfer-aware wallet PnL; no claim of canonical current holdings is made. all means retained built history. Source cursors pin the selected window and expire after 30 seconds; correction revisions invalidate them. Source observedAtMs and history coverage remain visible even when retained history is old. Solana only. Requires md.read; one shared REST bucket request per call, including coalesced reads. Cache-Control: no-store. Unknown amounts remain null; exact monetary strings are never synthesized from floats. No RPC, vendor fallback, history build, background refresh, or per-result snapshot fetch. Unknown/repeated parameters and URLs over 8 KiB are rejected. ## OpenAPI ````yaml https://www.oceanx.trade/api/v1/openapi.json get /api/v1/tokens/{chain}/{address}/top-traders openapi: 3.1.0 info: title: OceanX Developer API version: 1.0.0 description: >- Public API for the OceanX trading platform. Currently in beta and free to use while in beta. This spec covers the **spot quote** domain. The wallet **tracker** and **perps** domains are documented at https://docs.oceanx.trade/api/overview and are not yet described here. contact: url: https://docs.oceanx.trade termsOfService: https://www.oceanx.trade/legal/terms license: name: Proprietary url: https://www.oceanx.trade/legal/terms servers: - url: https://www.oceanx.trade description: Production security: - bearerAuth: [] tags: - name: Router description: >- Read-only Raptor route quotes and public Solana transaction status. Build and execution remain separately gated. - name: Market Data description: Read-only OceanX market context sourced and cached by VM producers. - name: Spot description: >- Executable Solana swap quotes off OceanX's own router, and the exit checker that reports whether a whole position can be sold. - name: Callouts description: >- Public token callouts — user-posted token calls with live click/volume attribution stats. Read-only. - name: Copy Trading description: Key-owner follow, fill and PnL reads; no execution authority. - name: Price Alerts description: Key-owner alert management through the existing evaluator; no webhooks. paths: /api/v1/tokens/{chain}/{address}/top-traders: get: tags: - Market Data summary: Read observed top traders description: >- Ranks wallets by observed buy plus sell USD volume descending, using an already cached native execution view. PnL is explicitly partial execution-only accounting, not transfer-aware wallet PnL; no claim of canonical current holdings is made. all means retained built history. Source cursors pin the selected window and expire after 30 seconds; correction revisions invalidate them. Source observedAtMs and history coverage remain visible even when retained history is old. Solana only. Requires md.read; one shared REST bucket request per call, including coalesced reads. Cache-Control: no-store. Unknown amounts remain null; exact monetary strings are never synthesized from floats. No RPC, vendor fallback, history build, background refresh, or per-result snapshot fetch. Unknown/repeated parameters and URLs over 8 KiB are rejected. operationId: getTokenTopTraders parameters: - name: chain in: path required: true schema: type: string enum: - solana - name: address in: path required: true schema: type: string description: Valid base58 Solana mint. - name: window in: query schema: type: string enum: - 1h - 24h - all default: 24h - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 25 - name: cursor in: query schema: type: string minLength: 1 maxLength: 512 description: >- Opaque source cursor. Repeat all selectors. Changed/expired views return 409; restart from the first page. responses: '200': description: Source observations with explicit coverage and pagination. headers: X-RateLimit-Limit: schema: type: integer description: Requests allowed per window. X-RateLimit-Remaining: schema: type: integer description: Requests left. X-RateLimit-Reset: schema: type: integer description: Unix seconds when the window resets. X-Request-Id: schema: type: string content: application/json: schema: $ref: '#/components/schemas/ResearchTradersPage' '400': description: >- invalid_request, unsupported_chain, invalid_address, invalid_limit, invalid_query, invalid_window, or invalid_cursor. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing, malformed or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: The key is valid but lacks the required scope. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- cursor_expired_or_changed: restart pagination after expiry, eviction, correction, or selector changes. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- rate_limited (key REST bucket) or source_busy (bounded native reader capacity). Honour Retry-After. content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-RateLimit-Limit: schema: type: integer description: Requests allowed per window. X-RateLimit-Remaining: schema: type: integer description: Requests left. X-RateLimit-Reset: schema: type: integer description: Unix seconds when the window resets. Retry-After: schema: type: integer '500': description: 'internal_error: existing key-verification dependency failed.' content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: >- data_unavailable (cold, stale, malformed, oversized, or failed source) or rate_limit_unavailable. Never a fabricated empty success. content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: ResearchTradersPage: type: object required: - data - pagination - meta properties: data: type: array maxItems: 100 items: type: object required: - wallet - rank - boughtTokens - soldTokens - boughtUsd - soldUsd - buys - sells - lastTradeAtMs - realizedPnl properties: wallet: type: string rank: type: - integer - 'null' minimum: 0 boughtTokens: type: - string - 'null' description: >- Exact source decimal string; float-only or unknown source values remain null. soldTokens: type: - string - 'null' description: >- Exact source decimal string; float-only or unknown source values remain null. boughtUsd: type: - string - 'null' description: >- Exact source decimal string; float-only or unknown source values remain null. soldUsd: type: - string - 'null' description: >- Exact source decimal string; float-only or unknown source values remain null. buys: type: - integer - 'null' minimum: 0 sells: type: - integer - 'null' minimum: 0 lastTradeAtMs: type: - integer - 'null' minimum: 0 description: >- Unix milliseconds from the source, never refreshed by retrieval. realizedPnl: type: object required: - value - status - reason - observedAtMs properties: value: oneOf: - type: object required: - usd - native - roiPct properties: usd: type: string native: type: - string - 'null' roiPct: type: - string - 'null' - type: 'null' status: type: string enum: - partial - unavailable reason: type: string const: observed_swaps_only_not_transfer_aware observedAtMs: type: - integer - 'null' minimum: 0 description: >- Unix milliseconds from the source, never refreshed by retrieval. pagination: type: object required: - total - hasMore - nextCursor properties: total: type: - integer - 'null' minimum: 0 description: >- Matching indexed rows, not whole-chain population. Null when membership is incomplete. hasMore: type: - boolean - 'null' description: Null when membership is incomplete; not proof of exhaustion. nextCursor: type: - string - 'null' description: >- Repeat all selectors with this opaque cursor. Null for exhausted or partial results; check hasMore and coverage. meta: type: object required: - requestId - methodVersion - chain - observedAtMs - address - window - ranking - source - status - coverage properties: requestId: type: string methodVersion: type: string const: public-research-v1 chain: const: solana type: string observedAtMs: type: - integer - 'null' minimum: 0 description: Unix milliseconds from the source, never refreshed by retrieval. address: type: string window: type: string enum: - 1h - 24h - all ranking: type: string const: observed_volume_desc source: type: string const: native_execution_view status: type: string const: partial coverage: type: object required: - basis - transferAware - windowFromMs - windowToMs - coveredFromMs - historyComplete properties: basis: type: string const: observed_swaps_only transferAware: type: boolean const: false windowFromMs: type: - integer - 'null' minimum: 0 description: >- Unix milliseconds from the source, never refreshed by retrieval. windowToMs: type: - integer - 'null' minimum: 0 description: >- Unix milliseconds from the source, never refreshed by retrieval. coveredFromMs: type: - integer - 'null' minimum: 0 description: >- Unix milliseconds from the source, never refreshed by retrieval. historyComplete: type: - boolean - 'null' Error: type: object required: - error properties: requestId: type: string description: Request identifier on new token endpoints. error: type: object required: - code - message properties: code: type: string description: Stable machine-readable code. Branch on this, not the message. example: no_route message: type: string description: Human-readable detail. May change. securitySchemes: bearerAuth: type: http scheme: bearer description: >- An OceanX API key, created in the app under Settings → Developer API. Send it as `Authorization: Bearer ox_live_…`. Required scopes are operation-specific: market reads use md.read, tracker uses tracker.read, copy reads use copy.read, and alert operations use alerts.read or alerts.write. New scopes require explicit selection and grant no trading authority. Existing perps operations retain their documented scopes. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.