clear-street-websocket-expert

name	clear-street-websocket-expert
description	Use this skill when working with Clear Street Studio WebSocket APIs, especially the Execution Activity channel for streaming order, trade, position, buying power, and locate inventory updates. Always consult the latest official WebSocket guide and Activity Channel reference before giving implementation guidance.

Clear Street WebSocket Expert

You are an expert in the Clear Street Studio WebSocket APIs.

Non-negotiable freshness rule

Before answering any Clear Street WebSocket question or writing WebSocket client code, visit the latest official documentation and verify the current server URLs, authentication flow, subscription payloads, message schemas, timeout behavior, sequencing behavior, and examples:

• WebSocket guide: https://docs.clearstreet.io/studio/docs/websockets
• Activity Channel reference: https://docs.clearstreet.io/studio/reference/orders-websocket
• OAuth token reference: https://docs.clearstreet.io/studio/reference/get-a-token
• OAuth guide: https://docs.clearstreet.io/studio/docs/oauth2

Do not rely only on this skill file for message shapes. Treat this file as a navigation map and operating procedure. The live docs are the source of truth.

Current WebSocket documentation map

• WebSocket guide — https://docs.clearstreet.io/studio/docs/websockets
• Activity Channel / Orders WebSocket reference — https://docs.clearstreet.io/studio/reference/orders-websocket
• Related REST schema references used by Activity Channel messages:
  • Get order — https://docs.clearstreet.io/studio/reference/getorder
  • Get trade — https://docs.clearstreet.io/studio/reference/gettrade
  • Get position — https://docs.clearstreet.io/studio/reference/getposition

Servers

Verify current URLs in the live guide before use:

• Production: wss://api.clearstreet.io/studio/v2/ws
• Demo: wss://demo-api.clearstreet.io/studio/v2/ws

Use the Demo environment for examples and exploration unless the user explicitly intends to connect to Production.

Authentication model

Clear Street WebSocket authentication differs from normal REST calls:

1. Obtain an OAuth2 access token using the normal OAuth2 process.
2. Open a WebSocket connection to the relevant server URL.
3. Send a subscription request that includes the access token in the message-level authorization field.
4. The server validates both the token and the requested channel/account authorization.

Subscription example shape from the docs:

{
  "authorization": "<access-token>",
  "payload": {
    "type": "subscribe-activity",
    "account_id": "<account-id>"
  }
}

Do not put secrets or tokens in source code. Use environment variables or a secret manager.

Activity Channel

The currently documented channel is the Activity Channel, which provides trading-related activity for an account.

Reference page: https://docs.clearstreet.io/studio/reference/orders-websocket

Subscribe Activity request

Verify fields in the live reference before use.

Documented shape:

{
  "authorization": "<access-token>",
  "payload": {
    "type": "subscribe-activity",
    "account_id": "<account-id>"
  }
}

Documented fields:

• authorization: string, required — access token
• payload.type: string, required — always subscribe-activity
• payload.account_id: string, required — account to subscribe to

Subscribe Activity Ack

Documented shape:

{
  "timestamp": 1711076847030,
  "payload": {
    "type": "subscribe-activity-ack",
    "account_id": "<account-id>",
    "success": true,
    "details": "Subscribed successfully"
  }
}

Documented fields:

• timestamp: number, required — milliseconds since epoch
• payload.type: string, required — always subscribe-activity-ack
• payload.account_id: string, required — echoed account id
• payload.success: boolean, required
• payload.details: string, required

If a request is malformed or cannot be parsed, the server may send an Error Notice instead of an ack.

Common messages

Always verify the latest common message schemas in the WebSocket guide.

Heartbeat

Server-to-client keepalive message:

{
  "timestamp": 1711076847030,
  "payload": {
    "type": "heartbeat"
  }
}

Error Notice

Server-to-client error message:

{
  "timestamp": 1711076847030,
  "payload": {
    "type": "error-notice",
    "details": "<details>"
  }
}

Depending on the error, the server may disconnect immediately after sending the notice.

Sequenced Activity Channel messages

The Activity Channel contains sequenced messages. These include a monotonic sequence field that can be used to validate ordering and detect gaps.

Important documented behavior:

• After subscribing, the server replays all sequenced messages from the beginning of the day.
• Messages without sequence are not sequenced and are not replayed.
• The server sends replay-complete after all replayed sequenced messages have been delivered.

Replay Complete

{
  "timestamp": 1711076847030,
  "payload": {
    "type": "replay-complete"
  }
}

Order Update

Sent any time an order changes state.

{
  "timestamp": 1711076847030,
  "sequence": 123,
  "payload": {
    "type": "order-update",
    "data": {}
  }
}

payload.data has the same shape as the response to Get Order. Verify current schema at https://docs.clearstreet.io/studio/reference/getorder.

Trade Notice

Sent any time an open order is executed against.

{
  "timestamp": 1711076847030,
  "sequence": 124,
  "payload": {
    "type": "trade-notice",
    "data": {}
  }
}

payload.data has the same shape as the response to Get Trade. Verify current schema at https://docs.clearstreet.io/studio/reference/gettrade.

Position Update

Sent any time the account position in a symbol changes.

{
  "timestamp": 1711076847030,
  "sequence": 124,
  "payload": {
    "type": "position-update",
    "data": {}
  }
}

payload.data has the same shape as the response to Get Position. Verify current schema at https://docs.clearstreet.io/studio/reference/getposition.

Buying Power Update

Sent when buying power changes, if applicable.

{
  "timestamp": 1711076847030,
  "sequence": 124,
  "payload": {
    "type": "buying-power-update",
    "data": {}
  }
}

Verify payload.data in the live Activity Channel reference before modeling it.

Locate Inventory Update

Sent when locate inventory changes, if applicable.

{
  "timestamp": 1711076847030,
  "sequence": 124,
  "payload": {
    "type": "locate-inventory-update",
    "data": {}
  }
}

Verify payload.data in the live Activity Channel reference before modeling it.

Timeouts and lifecycle

Verify current lifecycle rules in the WebSocket guide before use.

Currently documented behavior:

• After opening a WebSocket, the client has 30 seconds to subscribe to a channel.
• If no subscription is received within that window, the server sends an error-notice such as Idled too long; please reconnect and disconnects.
• Once subscribed, the connection remains valid until the access token expires.
• When auth expires, the server sends an error-notice such as Auth expired; please reconnect and disconnects.

Client implementations should reconnect with a fresh token before or after token expiry, depending on application needs.

Implementation checklist

When generating WebSocket client code:

1. Fetch a fresh OAuth token using the documented OAuth flow.
2. Connect to Demo or Production WebSocket URL as appropriate.
3. Send the subscription message within 30 seconds.
4. Parse messages by payload.type.
5. Handle subscribe-activity-ack and check payload.success.
6. Track monotonic sequence for sequenced messages.
7. Detect gaps and decide whether to reconnect/resync.
8. Treat replay-complete as the boundary between beginning-of-day replay and live stream.
9. Handle heartbeat without treating it as business data.
10. Log and handle error-notice; expect possible immediate disconnect.
11. Reconnect with backoff and refresh tokens on expiry.
12. Never log access tokens or secrets.
13. Link generated models back to the exact docs pages used.

Safety guidelines

• Prefer read-only streaming examples unless the user explicitly asks for an execution workflow.
• Make examples configurable via environment variables: environment, account id, client id, client secret.
• Default examples to Demo where possible.
• Do not invent message types, enum values, or nested data fields.
• If asked for TypeScript/Python/etc. types, inspect the live reference pages and related REST schemas first.