> ## 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 cached token identity and market facts

> Requires md.read and consumes the existing REST key limiter. Solana only; unsupported chains return 400 unsupported_chain. Unknown/repeated query parameters and URLs over 8 KiB are rejected. Responses use Cache-Control: no-store. No paid enrichment is started. Market amounts require exact source strings; current float-only snapshot fields remain null. Window buy/sell/economic-volume fields remain unavailable until qualified, rather than relabeling execution-leg statistics. Field observations retain source clocks; retrieval does not renew freshness.



## OpenAPI

````yaml https://www.oceanx.trade/api/v1/openapi.json get /api/v1/tokens/{chain}/{address}
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}:
    get:
      tags:
        - Market Data
      summary: Read cached token identity and market facts
      description: >-
        Requires md.read and consumes the existing REST key limiter. Solana
        only; unsupported chains return 400 unsupported_chain. Unknown/repeated
        query parameters and URLs over 8 KiB are rejected. Responses use
        Cache-Control: no-store. No paid enrichment is started. Market amounts
        require exact source strings; current float-only snapshot fields remain
        null. Window buy/sell/economic-volume fields remain unavailable until
        qualified, rather than relabeling execution-leg statistics. Field
        observations retain source clocks; retrieval does not renew freshness.
      operationId: getTokenSummary
      parameters:
        - name: chain
          in: path
          required: true
          schema:
            type: string
            enum:
              - solana
        - name: address
          in: path
          required: true
          schema:
            type: string
            pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
        - name: include
          in: query
          schema:
            type: string
            enum:
              - risk
      responses:
        '200':
          description: Cached native observations. Null fields are unavailable, not zero.
          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:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/TokenSummary'
                  meta:
                    $ref: '#/components/schemas/TokenResponseMeta'
        '400':
          description: Failed validation before reaching the engine.
          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'
        '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: >-
            The routing engine or rate-limit storage is unavailable. Retry with
            backoff; no upstream work was admitted when the limiter failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    TokenSummary:
      type: object
      required:
        - chain
        - address
        - name
        - symbol
        - decimals
        - supply
        - supplyType
        - firstObservedAtMs
        - createdAtMs
        - imageUrl
        - imageStatus
        - website
        - socialLinks
        - launchpad
        - dex
        - poolAddress
        - stage
        - bondingProgressPct
        - priceUsd
        - priceNative
        - marketCapUsd
        - fdvUsd
        - liquidityUsd
        - holders
        - windows
        - fieldMeta
      properties:
        chain:
          const: solana
          type: string
        address:
          type: string
        name:
          type:
            - string
            - 'null'
        symbol:
          type:
            - string
            - 'null'
        decimals:
          type:
            - integer
            - 'null'
          minimum: 0
        supply:
          type:
            - string
            - 'null'
          pattern: ^(0|[1-9]\d*)(\.\d+)?$
          description: >-
            Exact source decimal string; null when the source only has a
            floating-point approximation or no fact.
        supplyType:
          type:
            - string
            - 'null'
        firstObservedAtMs:
          type:
            - integer
            - 'null'
          minimum: 0
        createdAtMs:
          type:
            - integer
            - 'null'
          minimum: 0
        imageUrl:
          type:
            - string
            - 'null'
        imageStatus:
          type: string
          enum:
            - resolved
            - unavailable
        website:
          type:
            - string
            - 'null'
        socialLinks:
          type: object
          required:
            - twitter
            - telegram
          properties:
            twitter:
              type:
                - string
                - 'null'
            telegram:
              type:
                - string
                - 'null'
        launchpad:
          type:
            - string
            - 'null'
        dex:
          type:
            - string
            - 'null'
        poolAddress:
          type:
            - string
            - 'null'
        stage:
          type:
            - string
            - 'null'
        bondingProgressPct:
          type:
            - string
            - 'null'
          pattern: ^(0|[1-9]\d*)(\.\d+)?$
          description: >-
            Exact source decimal string; null when the source only has a
            floating-point approximation or no fact.
        priceUsd:
          type:
            - string
            - 'null'
          pattern: ^(0|[1-9]\d*)(\.\d+)?$
          description: >-
            Exact source decimal string; null when the source only has a
            floating-point approximation or no fact.
        priceNative:
          type:
            - string
            - 'null'
          pattern: ^(0|[1-9]\d*)(\.\d+)?$
          description: >-
            Exact source decimal string; null when the source only has a
            floating-point approximation or no fact.
        marketCapUsd:
          type:
            - string
            - 'null'
          pattern: ^(0|[1-9]\d*)(\.\d+)?$
          description: >-
            Exact source decimal string; null when the source only has a
            floating-point approximation or no fact.
        fdvUsd:
          type:
            - string
            - 'null'
          pattern: ^(0|[1-9]\d*)(\.\d+)?$
          description: >-
            Exact source decimal string; null when the source only has a
            floating-point approximation or no fact.
        liquidityUsd:
          type:
            - string
            - 'null'
          pattern: ^(0|[1-9]\d*)(\.\d+)?$
          description: >-
            Exact source decimal string; null when the source only has a
            floating-point approximation or no fact.
        holders:
          type:
            - integer
            - 'null'
          minimum: 0
        windows:
          type: object
          required:
            - 5m
            - 1h
            - 6h
            - 24h
          additionalProperties:
            type: object
            required:
              - buys
              - sells
              - economicVolumeUsd
              - observation
            properties:
              buys:
                type:
                  - integer
                  - 'null'
                minimum: 0
              sells:
                type:
                  - integer
                  - 'null'
                minimum: 0
              economicVolumeUsd:
                type:
                  - string
                  - 'null'
                pattern: ^(0|[1-9]\d*)(\.\d+)?$
                description: >-
                  Exact source decimal string; null when the source only has a
                  floating-point approximation or no fact.
              observation:
                $ref: '#/components/schemas/TokenObservation'
        fieldMeta:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/TokenObservation'
        risk:
          $ref: '#/components/schemas/TokenRisk'
    TokenResponseMeta:
      type: object
      required:
        - requestId
        - methodVersion
        - chain
      properties:
        requestId:
          type: string
          format: uuid
        methodVersion:
          type: string
        chain:
          const: solana
          type: string
    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.
    TokenObservation:
      type: object
      required:
        - status
        - observedAtMs
        - staleAfterMs
        - source
        - methodVersion
        - coverage
      properties:
        status:
          type: string
          enum:
            - known
            - partial
            - stale
            - unavailable
        observedAtMs:
          type:
            - integer
            - 'null'
          minimum: 0
        staleAfterMs:
          type:
            - integer
            - 'null'
          minimum: 0
        source:
          type: string
        methodVersion:
          type: string
        coverage:
          type: object
          required:
            - reason
            - complete
          properties:
            reason:
              type: string
            complete:
              type: boolean
    TokenRisk:
      type: object
      required:
        - chain
        - address
        - modelVersion
        - facts
        - tags
      properties:
        chain:
          const: solana
          type: string
        address:
          type: string
        modelVersion:
          type: string
          const: public-risk-v1
        facts:
          type: object
          additionalProperties:
            type:
              - boolean
              - 'null'
        tags:
          type: array
          maxItems: 10
          items:
            allOf:
              - $ref: '#/components/schemas/TokenObservation'
              - type: object
                required:
                  - code
                  - state
                  - severity
                  - value
                  - unit
                properties:
                  code:
                    type: string
                    enum:
                      - mint_authority_active
                      - freeze_authority_active
                      - concentrated_top10
                      - developer_holding
                      - developer_sold_all
                      - sniper_holding
                      - insider_holding
                      - bundled_holding
                      - suspected_wash_volume
                      - lp_not_burned
                  state:
                    type: string
                    enum:
                      - present
                      - absent
                      - unknown
                  severity:
                    type: string
                    enum:
                      - warning
                      - info
                  value:
                    type:
                      - boolean
                      - 'null'
                  unit:
                    type:
                      - string
                      - 'null'
  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.