> ## 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 a retained Scout stage snapshot > Requires md.read and the existing 120/min REST key limiter before any backend read. Solana only. Maps new/latest and migrated/graduated using producer membership. At most 200 retained tokens; not an exhaustive listing. Initialized complete empty windows succeed; unavailable, legacy, corrupt or uninitialized windows fail 503. Nonempty partial windows retain partial coverage even if filters exclude every row. Unknown amounts and clocks are null, never zero. All filters and pagination run over an immutable backend version. Signed cursors bind chain, stage, every filter, sort, order and limit; repeat all selectors. The five-minute expiry and age evaluation time never slide. Sort ties use mint ascending and unknowns sort last in either direction. Backend retention expiry is not freshness. No vendor/enrichment/history work, retries or idle refresh. Cache-Control: no-store. Unknown/repeated selectors and URLs over 8 KiB fail 400. Before the snapshot backend is rolled, this route fails closed with 503. ## OpenAPI ````yaml https://www.oceanx.trade/api/v1/openapi.json get /api/v1/scout/{stage} 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/scout/{stage}: get: tags: - Market Data summary: Read a retained Scout stage snapshot description: >- Requires md.read and the existing 120/min REST key limiter before any backend read. Solana only. Maps new/latest and migrated/graduated using producer membership. At most 200 retained tokens; not an exhaustive listing. Initialized complete empty windows succeed; unavailable, legacy, corrupt or uninitialized windows fail 503. Nonempty partial windows retain partial coverage even if filters exclude every row. Unknown amounts and clocks are null, never zero. All filters and pagination run over an immutable backend version. Signed cursors bind chain, stage, every filter, sort, order and limit; repeat all selectors. The five-minute expiry and age evaluation time never slide. Sort ties use mint ascending and unknowns sort last in either direction. Backend retention expiry is not freshness. No vendor/enrichment/history work, retries or idle refresh. Cache-Control: no-store. Unknown/repeated selectors and URLs over 8 KiB fail 400. Before the snapshot backend is rolled, this route fails closed with 503. operationId: getScoutSnapshot parameters: - name: stage in: path required: true schema: type: string enum: - new - graduating - migrated - name: chain in: query schema: type: string enum: - solana default: solana - name: launchpad in: query schema: type: string pattern: ^[a-zA-Z0-9_.-]{1,64}$ description: Exact case-sensitive producer launchpad match; unknown excluded. - name: minLiquidityUsd in: query schema: type: string maxLength: 128 pattern: ^\d+(\.\d+)?$ description: >- Inclusive exact decimal threshold. Unknown liquidity is excluded, including when the minimum is zero. - name: maxAgeSeconds in: query schema: type: integer minimum: 1 maximum: 2592000 description: >- Inclusive age from producer-pinned first observation (createdAtMs), relative to selectionAtMs. Unknown/future creation observations are excluded. - name: sort in: query schema: type: string enum: - createdAt - volume5m - liquidityUsd default: createdAt - name: order in: query schema: type: string enum: - asc - desc default: desc - name: limit in: query schema: type: integer minimum: 1 maximum: 200 default: 50 - name: cursor in: query schema: type: string minLength: 1 maxLength: 2048 description: >- Opaque HMAC-signed five-minute pagination cursor. Tampering or changed selectors: 400; expiry or evicted version: 410. responses: '200': description: >- Qualified retained stage window; producer clocks and coverage preserved. 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. content: application/json: schema: $ref: '#/components/schemas/ScoutSnapshot' '400': description: invalid_request, invalid_cursor or cursor_mismatch; no backend read. 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. content: application/json: schema: $ref: '#/components/schemas/ScoutError' '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' '410': description: >- cursor_expired or snapshot_expired_or_evicted; restart from the first page. Includes unavailable coverage. 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. content: application/json: schema: $ref: '#/components/schemas/ScoutError' '429': description: Rate limited. Honour `Retry-After`. 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 description: Seconds to wait. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Existing API-key verification dependency failed. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: >- snapshot_unavailable with unavailable coverage for missing key configuration, unsupported/pre-roll backend, uninitialized/corrupt source, capacity or timeout. Shared limiter failure uses the existing Error envelope. content: application/json: schema: anyOf: - $ref: '#/components/schemas/ScoutError' - $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: ScoutSnapshot: type: object required: - data - meta properties: data: type: object required: - chain - stage - items properties: chain: const: solana stage: type: string enum: - new - graduating - migrated items: type: array maxItems: 200 items: $ref: '#/components/schemas/ScoutItem' meta: type: object required: - requestId - methodVersion - source - snapshotVersion - snapshotExpiresAtMs - observedAtMs - staleAfterMs - coverage - replayCursor - selectionAtMs - cursorExpiresAtMs - nextCursor - matchedCount - windowCount properties: requestId: type: string methodVersion: const: public-scout-v1 source: const: cache snapshotVersion: type: string pattern: ^[0-9a-f]{40}$ snapshotExpiresAtMs: type: integer description: >- Backend retention deadline only. Does not establish freshness or extend the cursor lease. observedAtMs: type: - integer - 'null' minimum: 1 maximum: 9007199254740991 description: >- Original stage-membership observation time. Current producer supplies null. staleAfterMs: type: - integer - 'null' minimum: 1 maximum: 9007199254740991 description: >- Producer freshness duration. Current producer supplies null; retrieval and retention do not substitute. coverage: $ref: '#/components/schemas/ScoutCoverage' replayCursor: type: 'null' description: Replay is not available in this slice. selectionAtMs: type: integer description: >- First page filter evaluation time, fixed through pagination; not a producer observation. cursorExpiresAtMs: type: integer description: selectionAtMs plus five minutes, unchanged on subsequent pages. nextCursor: type: - string - 'null' description: >- Opaque signed cursor; repeat all selectors. Null on the last page. matchedCount: type: integer minimum: 0 maximum: 200 windowCount: type: integer minimum: 0 maximum: 200 ScoutError: type: object required: - error - requestId properties: error: type: object required: - code - message properties: code: type: string message: type: string requestId: type: string meta: type: object required: - coverage properties: coverage: $ref: '#/components/schemas/ScoutCoverage' 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. ScoutItem: type: object required: - mint - name - symbol - createdAtMs - chainCreatedAtMs - stageEnteredAtMs - migratedAtMs - provisionalExpiresAtMs - launchpad - poolAddress - removalReason - provisional - priceUsd - marketCapUsd - liquidityUsd - volume5mUsd - bondingProgressPct - fieldUpdatedAt - riskSources - mcSource - curveSource - migrationEvent - provenance - amountCoverage properties: mint: type: string description: Case-sensitive Solana mint. name: type: - string - 'null' symbol: type: - string - 'null' createdAtMs: type: - integer - 'null' minimum: 1 maximum: 9007199254740991 description: Producer-pinned first observation; not chain creation time. chainCreatedAtMs: type: - integer - 'null' minimum: 1 maximum: 9007199254740991 stageEnteredAtMs: type: - integer - 'null' minimum: 1 maximum: 9007199254740991 migratedAtMs: type: - integer - 'null' minimum: 1 maximum: 9007199254740991 provisionalExpiresAtMs: type: - integer - 'null' minimum: 1 maximum: 9007199254740991 launchpad: type: - string - 'null' poolAddress: type: - string - 'null' removalReason: type: - string - 'null' provisional: type: - boolean - 'null' priceUsd: type: - string - 'null' maxLength: 128 pattern: ^-?\d+(\.\d+)?$ description: >- Exact producer decimal string, preserving scale; unknown or unqualified numeric source values remain null. marketCapUsd: type: - string - 'null' maxLength: 128 pattern: ^-?\d+(\.\d+)?$ description: >- Exact producer decimal string, preserving scale; unknown or unqualified numeric source values remain null. liquidityUsd: type: - string - 'null' maxLength: 128 pattern: ^-?\d+(\.\d+)?$ description: >- Exact producer decimal string, preserving scale; unknown or unqualified numeric source values remain null. volume5mUsd: type: - string - 'null' maxLength: 128 pattern: ^-?\d+(\.\d+)?$ description: >- Exact producer decimal string, preserving scale; unknown or unqualified numeric source values remain null. bondingProgressPct: type: - string - 'null' maxLength: 128 pattern: ^-?\d+(\.\d+)?$ description: >- Exact producer decimal string, preserving scale; unknown or unqualified numeric source values remain null. fieldUpdatedAt: description: Original producer field clocks, or null; not snapshot freshness. riskSources: description: Original producer risk provenance, or null; no safety guarantee. mcSource: type: - string - 'null' curveSource: type: - string - 'null' migrationEvent: description: Original producer transition metadata, or null. provenance: description: Original producer provenance, or null. amountCoverage: type: object required: - status - reason properties: status: type: string reason: type: - string - 'null' ScoutCoverage: type: object required: - status - reason - initialized - basis - complete description: >- Coverage of the retained stage window only, never global/history completeness. Unavailable responses have initialized=null because the adapter cannot establish initialization. properties: status: type: string enum: - complete - partial - unavailable reason: type: - string - 'null' initialized: type: - boolean - 'null' basis: const: retained_stage_window complete: type: boolean 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.