> ## Documentation Index > Fetch the complete documentation index at: https://docs.hyperprop.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a trading stream token > Returns a short-lived token for the real-time trading stream of **all** your organization's trading accounts: every order, execution, position change, balance/equity update and rule violation, as it happens. New accounts are included automatically. The stream is read-only. It accepts no trading commands. **Connect** to the returned `url` with the token in the `Authorization` header: ```bash TOKEN=$(curl -s -X POST "https://api.hyperprop.com/platform/v1/organization/trading-accounts/stream-token" \ -H "X-API-Key: hp_live_your_key_here" | jq -r .data.token) websocat -H "Authorization: Bearer $TOKEN" wss://api.hyperprop.com/trade/org/stream ``` The first message is `{"type": "Welcome", "organization_id": ..., "expires_at": ...}`. Then each event arrives as one JSON message with a `type`: `OrderSubmitted`, `OrderFilled` (one per execution, with the `trade`), `OrderCancelled`, `PositionUpdate`, `AccountUpdate` (balance, equity, P&L, drawdown, status), `RuleViolation` and account `Notification`. Every event carries `account_id`. A `Heartbeat` arrives every 15 seconds. **Options (optional query parameters, combinable):** `snapshot=1` sends the current state of your accounts (`AccountSnapshot` messages, then `SnapshotComplete`) right after `Welcome`; `seq=1` numbers every message; `floors=1` adds `RiskLimitsUpdate` messages; `v=2` selects message format 2, where every message carries `schema` and `ts_ms` and every position carries `position_id` and `state_epoch`. Without them every message is exactly as described above. **Filter (optional):** add query parameters to the stream URL to receive only some of your accounts. Other accounts' events are dropped on the server and never reach your connection. - `account_types`: comma-separated `evaluation`, `sim_funded`, `competition`, for example `wss://api.hyperprop.com/trade/org/stream?account_types=sim_funded`. - `account_ids`: comma-separated account IDs, at most 100 per connection. With both, an account must match both. Every event type is filtered the same way, including position closes from liquidation, administrative closes and recoveries, and `RiskLimitsUpdate`. An invalid filter is refused with HTTP `400` (`INVALID_FILTER`). Without a filter you receive every account, as before. The filter is fixed for the connection; to change it, reconnect. On a filtered connection, `Welcome` includes the active `filter`, `snapshot=1` sends only the accounts in the filter (flat ones included), and you are told when an account's membership changes: - `{"type": "AccountJoined", "account_id": ..., "account_type": "sim_funded", "reason": "new_account" | "account_type_changed", "as_of": ..., "positions_status": "ok", ...}` when an account enters the filter (for example a newly created sim-funded account). It carries the account's current state with the same fields as one account in `AccountSnapshot`: `positions_version` and `positions` (an empty list means flat), with `risk_limits` when you use `floors=1` and `state_epoch` and `position_id` when you use `v=2`. If the state cannot be read at that moment, `positions_status` is `"unavailable"` and `positions` is `null`: read the account's positions before relying on its position state. - `{"type": "AccountLeft", "account_id": ..., "account_type": ..., "reason": "account_type_changed", "as_of": ...}` when an account's type no longer matches. No further events are sent for it. `AccountJoined` and `AccountLeft` are ordinary messages: with `seq=1` they are numbered with the others, and with `v=2` they carry `schema` and `ts_ms`. An account that fails or passes keeps its type, so its closing events still arrive. Filtered connections count toward the same connection limit. **Token lifetime:** 15 minutes. Before it expires, request a new token and send `{"action": "refresh", "token": ""}` on the open connection (reply `TokenRefreshed`). Otherwise the connection closes with code `4001` and you reconnect with a new token. A revoked API key can't get new tokens, so its connections end within one token lifetime. **Missed events:** the stream does not replay events. If your connection falls behind, you get `{"type": "StreamGap", "dropped_events": n}`. After a `StreamGap` or a reconnect, reconnect with `snapshot=1` or read current state with `GET /organization/trading-accounts/positions`; with `perAccountResults=true` it returns each account's position book with `stateEpoch` and `stateVersion` to reconcile with `PositionUpdate` (`v=2`). A client that stops reading is disconnected (code `4008`). **Limits:** 5 open connections per organization per server; more are refused with HTTP `429`. One connection carries all your accounts, so one or two are enough. Send `{"action": "ping"}` for a `Pong`. Requires **view** permission on traders. **Access:** read-only and full-access API keys. Dashboard members need view access to Traders & accounts. ## OpenAPI ````yaml https://api.hyperprop.com/platform/openapi.json post /v1/organization/trading-accounts/stream-token openapi: 3.0.0 info: title: Hyperprop Platform API version: 1.0.0 description: >- REST API for the Hyperprop Trading Platform — provision evaluation and funded trading accounts, manage traders and plans, react to account lifecycle events via signed webhooks, and reconcile billing. Built for prop firms integrating from their own backend. Authentication, quick start, error handling, idempotency, pagination, custom metadata, webhooks, and the MCP connector are documented at https://docs.hyperprop.com. x-logo: url: https://app.hyperprop.com/logo-icon.svg altText: Hyperprop href: https://hyperprop.com servers: - url: https://api.hyperprop.com/platform description: Production security: [] tags: - name: Trading accounts description: Create, update, and inspect trading accounts. - name: Traders description: Look up and update the traders in your organization. - name: Trading plans description: Define the plans you sell. - name: Trading rules description: Define how accounts are evaluated. - name: Instruments description: >- The contracts your organization's accounts can trade, with their specifications. - name: Lockouts description: Pause and resume trading on an account. - name: Payouts description: Check payout eligibility and record payouts. - name: Purchases description: Purchases recorded for your organization. - name: Time Machine description: Restore accounts to an earlier trading day or instant. - name: Mass credit description: >- Credit back losses across many accounts after an incident, as background jobs you can follow, pause, export and reverse. - name: Webhooks description: Register webhook endpoints and inspect deliveries. - name: Events description: Your organization's event history, to replay or audit what happened. - name: Real-time streams description: >- Live events and trading data over a WebSocket, for dashboards and CRMs that update as things happen. - name: Reconciliation description: Balances, end-of-day snapshots, and fills for reconciliation. - name: Analytics description: Organization performance, revenue and top traders. - name: Risk description: Firm profit and loss and plan economics. - name: Billing and invoices description: >- Your Hyperprop invoices, credits and billing details, with usage so far this month, billing cycles, forecasts and CSV exports. - name: Team and roles description: Manage dashboard access for your staff. - name: API keys description: >- Manage your organization's API keys: rotation, read-only keys and IP allowlists. - name: Logs and health description: >- API request logs, the audit log, integration health, and idempotency key recovery. - name: Organization profile description: Your organization's profile and logo. - name: Support description: Open and follow up on support tickets. - name: Partner access description: >- Read a trader's journal as an approved partner app, with the trader's own key. paths: /v1/organization/trading-accounts/stream-token: post: tags: - Real-time streams summary: Create a trading stream token description: >- Returns a short-lived token for the real-time trading stream of **all** your organization's trading accounts: every order, execution, position change, balance/equity update and rule violation, as it happens. New accounts are included automatically. The stream is read-only. It accepts no trading commands. **Connect** to the returned `url` with the token in the `Authorization` header: ```bash TOKEN=$(curl -s -X POST "https://api.hyperprop.com/platform/v1/organization/trading-accounts/stream-token" \ -H "X-API-Key: hp_live_your_key_here" | jq -r .data.token) websocat -H "Authorization: Bearer $TOKEN" wss://api.hyperprop.com/trade/org/stream ``` The first message is `{"type": "Welcome", "organization_id": ..., "expires_at": ...}`. Then each event arrives as one JSON message with a `type`: `OrderSubmitted`, `OrderFilled` (one per execution, with the `trade`), `OrderCancelled`, `PositionUpdate`, `AccountUpdate` (balance, equity, P&L, drawdown, status), `RuleViolation` and account `Notification`. Every event carries `account_id`. A `Heartbeat` arrives every 15 seconds. **Options (optional query parameters, combinable):** `snapshot=1` sends the current state of your accounts (`AccountSnapshot` messages, then `SnapshotComplete`) right after `Welcome`; `seq=1` numbers every message; `floors=1` adds `RiskLimitsUpdate` messages; `v=2` selects message format 2, where every message carries `schema` and `ts_ms` and every position carries `position_id` and `state_epoch`. Without them every message is exactly as described above. **Filter (optional):** add query parameters to the stream URL to receive only some of your accounts. Other accounts' events are dropped on the server and never reach your connection. - `account_types`: comma-separated `evaluation`, `sim_funded`, `competition`, for example `wss://api.hyperprop.com/trade/org/stream?account_types=sim_funded`. - `account_ids`: comma-separated account IDs, at most 100 per connection. With both, an account must match both. Every event type is filtered the same way, including position closes from liquidation, administrative closes and recoveries, and `RiskLimitsUpdate`. An invalid filter is refused with HTTP `400` (`INVALID_FILTER`). Without a filter you receive every account, as before. The filter is fixed for the connection; to change it, reconnect. On a filtered connection, `Welcome` includes the active `filter`, `snapshot=1` sends only the accounts in the filter (flat ones included), and you are told when an account's membership changes: - `{"type": "AccountJoined", "account_id": ..., "account_type": "sim_funded", "reason": "new_account" | "account_type_changed", "as_of": ..., "positions_status": "ok", ...}` when an account enters the filter (for example a newly created sim-funded account). It carries the account's current state with the same fields as one account in `AccountSnapshot`: `positions_version` and `positions` (an empty list means flat), with `risk_limits` when you use `floors=1` and `state_epoch` and `position_id` when you use `v=2`. If the state cannot be read at that moment, `positions_status` is `"unavailable"` and `positions` is `null`: read the account's positions before relying on its position state. - `{"type": "AccountLeft", "account_id": ..., "account_type": ..., "reason": "account_type_changed", "as_of": ...}` when an account's type no longer matches. No further events are sent for it. `AccountJoined` and `AccountLeft` are ordinary messages: with `seq=1` they are numbered with the others, and with `v=2` they carry `schema` and `ts_ms`. An account that fails or passes keeps its type, so its closing events still arrive. Filtered connections count toward the same connection limit. **Token lifetime:** 15 minutes. Before it expires, request a new token and send `{"action": "refresh", "token": ""}` on the open connection (reply `TokenRefreshed`). Otherwise the connection closes with code `4001` and you reconnect with a new token. A revoked API key can't get new tokens, so its connections end within one token lifetime. **Missed events:** the stream does not replay events. If your connection falls behind, you get `{"type": "StreamGap", "dropped_events": n}`. After a `StreamGap` or a reconnect, reconnect with `snapshot=1` or read current state with `GET /organization/trading-accounts/positions`; with `perAccountResults=true` it returns each account's position book with `stateEpoch` and `stateVersion` to reconcile with `PositionUpdate` (`v=2`). A client that stops reading is disconnected (code `4008`). **Limits:** 5 open connections per organization per server; more are refused with HTTP `429`. One connection carries all your accounts, so one or two are enough. Send `{"action": "ping"}` for a `Pong`. Requires **view** permission on traders. **Access:** read-only and full-access API keys. Dashboard members need view access to Traders & accounts. operationId: postV1OrganizationTradingaccountsStreamtoken parameters: - name: Idempotency-Key in: header required: false description: >- Optional. A value that identifies this operation on your side, at most 255 characters. A retry with the same key, method, path and body within 24 hours returns the original response (with `Idempotency-Replayed: true`) instead of repeating the change. The same key with a different body returns `409 IDEMPOTENCY_KEY_REUSED`; a retry while the first request is still running returns `409 IDEMPOTENCY_KEY_IN_PROGRESS`. Server errors (5xx) are not saved, so a retry runs again. example: crm-sync-8814-attempt-1 schema: type: string maxLength: 255 responses: '200': description: Stream token content: application/json: schema: $ref: '#/components/schemas/Model1258' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Model11' '403': description: This API key does not have admin permissions content: application/json: schema: $ref: '#/components/schemas/Model1259' '409': description: >- The `Idempotency-Key` was used with a different body (`IDEMPOTENCY_KEY_REUSED`), or a request with the same key is still running (`IDEMPOTENCY_KEY_IN_PROGRESS`) content: application/json: schema: type: object properties: success: type: boolean description: Always false on errors example: false statusCode: type: integer example: 409 error: type: string example: Conflict message: type: string example: >- This Idempotency-Key was already used with a different request body. Use a new key for a different request. code: type: string enum: - IDEMPOTENCY_KEY_REUSED - IDEMPOTENCY_KEY_IN_PROGRESS example: IDEMPOTENCY_KEY_REUSED description: >- Machine-readable error code — switch on this, not on message text '503': description: The trading stream is not available right now content: application/json: schema: $ref: '#/components/schemas/Model1260' security: - X-API-Key: [] components: schemas: Model1258: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/Model1257' Model11: type: object properties: success: type: boolean description: Always false on errors example: false statusCode: type: number example: 401 error: type: string example: Unauthorized message: type: string example: Authentication required code: type: string description: Machine-readable error code — switch on this, not on message text example: UNAUTHORIZED Model1259: type: object properties: success: type: boolean description: Always false on errors example: false statusCode: type: number example: 403 error: type: string example: Forbidden message: type: string example: This API key does not have admin permissions code: type: string description: Machine-readable error code — switch on this, not on message text example: INSUFFICIENT_PERMISSIONS Model1260: type: object properties: success: type: boolean description: Always false on errors example: false statusCode: type: number example: 503 error: type: string example: Error message: type: string example: The trading stream is not available right now code: type: string description: Machine-readable error code — switch on this, not on message text example: STREAM_UNAVAILABLE Model1257: type: object properties: token: type: string description: 'Send as `Authorization: Bearer ` when connecting' example: >- eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6Im9yZ19zdHJlYW0ifQ.c2lnbmF0dXJl expiresIn: type: integer description: Seconds until the token expires example: 900 expiresAt: type: string example: '2026-10-25T16:15:00.000Z' url: type: string description: WebSocket URL to connect to example: wss://api.hyperprop.com/trade/org/stream securitySchemes: X-API-Key: type: apiKey name: X-API-Key in: header description: >- Organization API key (`hp_live_...`), sent in the `X-API-Key` header. Create, rotate and restrict keys in the dashboard or with the API keys endpoints; an organization can have two active keys, so you can rotate without downtime. A **full-access** key can call every endpoint in this reference. A **read-only** key can call `GET` endpoints (and create a trading stream token); any other request returns `403 READ_ONLY_KEY`. A key with an IP allowlist returns `403 IP_NOT_ALLOWED` from any other address. Each endpoint lists which keys can call it under **Access**. ```` ## Related topics - [Create an API key](https://docs.hyperprop.com/platform-api/api-keys/create-an-api-key.md) - [Real-time trading stream](https://docs.hyperprop.com/guides/realtime-trading-stream.md) - [Create a partner session](https://docs.hyperprop.com/trade-api/account/create-a-partner-session.md) - [Authentication](https://docs.hyperprop.com/authentication.md) - [Create or update a copy trading config](https://docs.hyperprop.com/trade-api/copy-trading/create-or-update-a-copy-trading-config.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.