> ## 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. # Perps WebSocket session > Mint a short-lived /perps/ws ticket. Subscribe after upgrade with op=subscribe and topics such as hl:BTC:mid, hl:BTC:book and hl:BTC:trades. Send client frames every 30 seconds; reconnect using a fresh ticket. This feed is market data, not private orders or positions. ## OpenAPI ````yaml https://www.oceanx.trade/api/v1/openapi.json get /api/v1/perps/realtime/session openapi: 3.1.0 info: title: OceanX Developer API version: 1.0.0 description: >- OceanX Developer API v1 (beta). Covers every public route and method: market data, charts, token/risk facts, wallet analytics, tracker, copy reads, alerts, owned account wallet/funding reads, spot quotes and perps. Scope and availability are operation-specific. Spot execution, copy execution, account withdrawals, developer webhooks and prediction trading are not public v1 capabilities. Perps order submission and collateral rebalance remain unavailable; their error contracts are explicit. Documentation: https://docs.oceanx.trade/api/overview. 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: Perps description: Cross-venue market data and explicit account-wallet execution limitations. - 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/perps/realtime/session: get: tags: - Perps summary: Perps WebSocket session description: >- Mint a short-lived /perps/ws ticket. Subscribe after upgrade with op=subscribe and topics such as hl:BTC:mid, hl:BTC:book and hl:BTC:trades. Send client frames every 30 seconds; reconnect using a fresh ticket. This feed is market data, not private orders or positions. operationId: getPerpsRealtimeSession parameters: - name: format in: query required: false description: Only json selects JSON; other values use MessagePack. schema: type: string enum: - json - msgpack default: msgpack responses: '200': description: Session and subscription/keepalive contract. 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/PerpsRealtimeSession' '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 (`insufficient_scope`), or its account no longer has product access (`product_access_revoked`). 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' '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: PerpsRealtimeSession: type: object required: - wsUrl - expiresInSeconds - subscribeContract - keepalive properties: wsUrl: type: string format: uri description: >- Short-lived WebSocket URL. Treat the embedded ticket as a credential. expiresInSeconds: type: integer subscribeContract: type: object required: - op - note - topicExample - wildcard properties: op: const: subscribe type: string note: type: string topicExample: type: array items: type: string wildcard: type: string keepalive: type: object required: - format - clientPingSeconds - serverPingSeconds - note properties: format: type: string enum: - json - msgpack clientPingSeconds: type: integer serverPingSeconds: type: integer note: 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. 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, alert operations use alerts.read or alerts.write, and owned wallet/funding reads require explicit account.read. 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.