> For the complete documentation index, see [llms.txt](https://lambdaplex-labs.gitbook.io/lambdaplex/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lambdaplex-labs.gitbook.io/lambdaplex/for-developers/api/asyncapi-spec.md). # AsyncAPI spec ## Lambdaplex WebSocket API 0.1.0 documentation * Default content type: [application/json](https://www.iana.org/assignments/media-types/application/json) Single-connection WebSocket that merges control messages (subscribe etc.) for public market data streams with optional session authentication via Ed25519 keys to unlock user data streams ### Rate Limits * `ws_handshake`: Connection rate per IP * `ws_msg`: Message rate per connection * `ws_sub`: Subscription rate per connection * `ws_auth`: Session logon rate (per IP + per API key) ### Table of Contents * Servers * lambdaplex-ws * Operations * PUB / * SUB / ### Servers #### `lambdaplex-ws` Server * URL: `wss://api.lambdaplex.io/api/v1/ws` * Protocol: `wss` Single endpoint for public and authenticated data streams ### Operations #### PUB `/` Operation *Client-to-server control messages* JSON request/response and public+private streams in a unified connection Accepts **one of** the following messages: **Message `SubscribeReqMsg`** * Content type: [application/json](https://www.iana.org/assignments/media-types/application/json) * Correlation ID: `$message.payload#/id` Correlates requests and responses via payload.id **Payload** | Name | Type | Description | Value | Constraints | Notes | | -------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ----------- | --------------------------------------------------- | | (root) | object | - | - | - | **additional properties are allowed** | | id | oneOf | Request/response correlation id | - | - | **required**, **additional properties are allowed** | | id.0 (oneOf item) | string | - | - | - | - | | id.1 (oneOf item) | integer | - | - | - | - | | method | string | - | const (`"subscribe"`) | - | **required** | | params | array\ | - | - | non-empty | **required** | | params (single item) | string | Stream name; either a market data stream (currently only depth diffs): - `@depth` - `@trade` Or a user data stream (requires session authentication): - `userData` | - | - | - | > Examples of payload *(generated)* ```json { "id": "string", "method": "subscribe", "params": [ "string" ] } ``` **Message `UnsubscribeReqMsg`** * Content type: [application/json](https://www.iana.org/assignments/media-types/application/json) * Correlation ID: `$message.payload#/id` Correlates requests and responses via payload.id **Payload** | Name | Type | Description | Value | Constraints | Notes | | -------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ----------- | --------------------------------------------------- | | (root) | object | - | - | - | **additional properties are allowed** | | id | oneOf | Request/response correlation id | - | - | **required**, **additional properties are allowed** | | id.0 (oneOf item) | string | - | - | - | - | | id.1 (oneOf item) | integer | - | - | - | - | | method | string | - | const (`"unsubscribe"`) | - | **required** | | params | array\ | - | - | non-empty | **required** | | params (single item) | string | Stream name; either a market data stream (currently only depth diffs): - `@depth` - `@trade` Or a user data stream (requires session authentication): - `userData` | - | - | - | > Examples of payload *(generated)* ```json { "id": "string", "method": "unsubscribe", "params": [ "string" ] } ``` **Message `SessionLogonReqMsg`** * Content type: [application/json](https://www.iana.org/assignments/media-types/application/json) * Correlation ID: `$message.payload#/id` Correlates requests and responses via payload.id **Payload** | Name | Type | Description | Value | Constraints | Notes | | ----------------- | ------- | --------------------------------------------------------------------- | ------------------------- | ----------- | --------------------------------------------------- | | (root) | object | - | - | - | **additional properties are allowed** | | id | oneOf | Request/response correlation id | - | - | **required**, **additional properties are allowed** | | id.0 (oneOf item) | string | - | - | - | - | | id.1 (oneOf item) | integer | - | - | - | - | | method | string | - | const (`"session.logon"`) | - | **required** | | params | object | - | - | - | **required**, **additional properties are allowed** | | params.apiKey | string | - | - | - | **required** | | params.timestamp | integer | - | - | - | **required** | | params.recvWindow | number | ms; up to 3 decimal places; max 60000 | - | - | - | | params.signature | string | Base64 Ed25519 signature over the alphabetically sorted param string. | - | - | **required** | > Examples of payload *(generated)* ```json { "id": "string", "method": "session.logon", "params": { "apiKey": "string", "timestamp": 0, "recvWindow": 0, "signature": "string" } } ``` **Message `SessionLogoutReqMsg`** * Content type: [application/json](https://www.iana.org/assignments/media-types/application/json) * Correlation ID: `$message.payload#/id` Correlates requests and responses via payload.id **Payload** | Name | Type | Description | Value | Constraints | Notes | | ----------------- | ------- | ------------------------------- | -------------------------- | ----------- | --------------------------------------------------- | | (root) | object | - | - | - | **additional properties are allowed** | | id | oneOf | Request/response correlation id | - | - | **required**, **additional properties are allowed** | | id.0 (oneOf item) | string | - | - | - | - | | id.1 (oneOf item) | integer | - | - | - | - | | method | string | - | const (`"session.logout"`) | - | **required** | > Examples of payload *(generated)* ```json { "id": "string", "method": "session.logout" } ``` **Message `SessionSubscribeReqMsg`** * Content type: [application/json](https://www.iana.org/assignments/media-types/application/json) * Correlation ID: `$message.payload#/id` Correlates requests and responses via payload.id **Payload** | Name | Type | Description | Value | Constraints | Notes | | ----------------- | ------- | ------------------------------- | ----------------------------- | ----------- | --------------------------------------------------- | | (root) | object | - | - | - | **additional properties are allowed** | | id | oneOf | Request/response correlation id | - | - | **required**, **additional properties are allowed** | | id.0 (oneOf item) | string | - | - | - | - | | id.1 (oneOf item) | integer | - | - | - | - | | method | string | - | const (`"session.subscribe"`) | - | **required** | > Examples of payload *(generated)* ```json { "id": "string", "method": "session.subscribe" } ``` **Message `SessionUnsubscribeReqMsg`** * Content type: [application/json](https://www.iana.org/assignments/media-types/application/json) * Correlation ID: `$message.payload#/id` Correlates requests and responses via payload.id **Payload** | Name | Type | Description | Value | Constraints | Notes | | ----------------- | ------- | ------------------------------- | ------------------------------- | ----------- | --------------------------------------------------- | | (root) | object | - | - | - | **additional properties are allowed** | | id | oneOf | Request/response correlation id | - | - | **required**, **additional properties are allowed** | | id.0 (oneOf item) | string | - | - | - | - | | id.1 (oneOf item) | integer | - | - | - | - | | method | string | - | const (`"session.unsubscribe"`) | - | **required** | > Examples of payload *(generated)* ```json { "id": "string", "method": "session.unsubscribe" } ``` **Message `ListSubsReqMsg`** * Content type: [application/json](https://www.iana.org/assignments/media-types/application/json) * Correlation ID: `$message.payload#/id` Correlates requests and responses via payload.id **Payload** | Name | Type | Description | Value | Constraints | Notes | | ----------------- | ------- | ------------------------------- | ------------------------- | ----------- | --------------------------------------------------- | | (root) | object | - | - | - | **additional properties are allowed** | | id | oneOf | Request/response correlation id | - | - | **required**, **additional properties are allowed** | | id.0 (oneOf item) | string | - | - | - | - | | id.1 (oneOf item) | integer | - | - | - | - | | method | string | - | const (`"subscriptions"`) | - | **required** | > Examples of payload *(generated)* ```json { "id": "string", "method": "subscriptions" } ``` #### SUB `/` Operation *Server-to-client responses to requests and events* JSON request/response and public+private streams in a unified connection Accepts **one of** the following messages: **Message `SuccessResMsg`** * Content type: [application/json](https://www.iana.org/assignments/media-types/application/json) * Correlation ID: `$message.payload#/id` Correlates requests and responses via payload.id A successful acknowledgment with no further result data **Payload** | Name | Type | Description | Value | Constraints | Notes | | ----------------- | ------- | ------------------------------- | --------------- | ----------- | --------------------------------------------------- | | (root) | object | - | - | - | **additional properties are allowed** | | id | oneOf | Request/response correlation id | - | - | **required**, **additional properties are allowed** | | id.0 (oneOf item) | string | - | - | - | - | | id.1 (oneOf item) | integer | - | - | - | - | | status | integer | - | allowed (`200`) | - | **required** | | result | null | - | - | - | **required** | > Examples of payload *(generated)* ```json { "id": "string", "status": 200, "result": null } ``` **Message `ErrorResMsg`** * Content type: [application/json](https://www.iana.org/assignments/media-types/application/json) * Correlation ID: `$message.payload#/id` Correlates requests and responses via payload.id An error acknowledgment with details in the `error` field **Payload** | Name | Type | Description | Value | Constraints | Notes | | ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------- | --------------------------------------------------- | | (root) | object | - | - | - | **additional properties are allowed** | | id | oneOf | Request/response correlation id | - | - | **required**, **additional properties are allowed** | | id.0 (oneOf item) | string | - | - | - | - | | id.1 (oneOf item) | integer | - | - | - | - | | status | integer | HTTP-style status code indicating the result of the request: **2xx - Success:** - `200` - Successful response **4xx - Client Errors (issue on your side):** - `400` - Request failed, check `error` field for reason - `401` - Authentication failed or not logged in - `403` - Blocked by Web Application Firewall - `404` - Unknown method or resource - `409` - Partial success/failure, check `error` field for details - `418` - Auto-banned for repeated rate limit violations - `429` - Rate limit exceeded, slow down requests **5xx - Server Errors (issue on server side):** - `500` - Internal error **Important:** 500 responses have unknown execution status. The request may have succeeded. Use query methods to confirm status and consider establishing a new WebSocket connection. | allowed (`200`, `400`, `401`, `403`, `404`, `409`, `418`, `429`, `500`) | - | **required** | | error | object | Error object | - | - | **required**, **additional properties are allowed** | | error.msg | string | - | - | - | **required** | > Examples of payload *(generated)* ```json { "id": "string", "status": 200, "error": { "msg": "string" } } ``` **Message `ListSubsResMsg`** * Content type: [application/json](https://www.iana.org/assignments/media-types/application/json) * Correlation ID: `$message.payload#/id` Correlates requests and responses via payload.id **Payload** | Name | Type | Description | Value | Constraints | Notes | | -------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ----------- | --------------------------------------------------- | | (root) | object | - | - | - | **additional properties are allowed** | | result | array\ | - | - | - | **required** | | result (single item) | string | Stream name; either a market data stream (currently only depth diffs): - `@depth` - `@trade` Or a user data stream (requires session authentication): - `userData` | - | - | - | | id | oneOf | Request/response correlation id | - | - | **required**, **additional properties are allowed** | | id.0 (oneOf item) | string | - | - | - | - | | id.1 (oneOf item) | integer | - | - | - | - | > Examples of payload *(generated)* ```json { "result": [ "string" ], "id": "string" } ``` **Message `DepthDiffEventMsg`** * Content type: [application/json](https://www.iana.org/assignments/media-types/application/json) **Payload** | Name | Type | Description | Value | Constraints | Notes | | --------------- | ------------------------------------------------- | --------------------------------------------------------------------------- | ----------------------- | ----------- | ------------------------------------- | | (root) | object | - | - | - | **additional properties are allowed** | | e | string | - | const (`"depthUpdate"`) | - | **required** | | E | integer | Source event time (ms); identical across sessions for the same market event | - | - | **required** | | s | string | Symbol | - | - | **required** | | U | integer | First depth update id | - | - | **required** | | u | integer | Last depth update id | - | - | **required** | | b | array\>> | Bid updates | - | - | **required** | | b (single item) | tuple\> | \[price, quantity] as strings to preserve precision | - | 2 items | **additional items are allowed** | | b.0 (index) | string | - | - | - | - | | b.1 (index) | string | - | - | - | - | | a | array\>> | Ask updates | - | - | **required** | | a (single item) | tuple\> | \[price, quantity] as strings to preserve precision | - | 2 items | **additional items are allowed** | | a.0 (index) | string | - | - | - | - | | a.1 (index) | string | - | - | - | - | > Examples of payload ```json { "e": "depthUpdate", "E": 1672515782136, "s": "PLEX-HBAR", "U": 157, "u": 160, "b": [ [ "0.0024", "10" ] ], "a": [ [ "0.0026", "100" ] ] } ``` **Message `TradeEventMsg`** * Content type: [application/json](https://www.iana.org/assignments/media-types/application/json) Public trade event for a given symbol **Payload** | Name | Type | Description | Value | Constraints | Notes | | ------ | ------- | ------------------------------------------------------------------------------------ | ----------------- | ----------- | ------------------------------------- | | (root) | object | - | - | - | **additional properties are allowed** | | e | string | - | const (`"trade"`) | - | **required** | | E | integer | Event time (ms), when the event was emitted | - | - | **required** | | s | string | Trading instrument symbol, e.g. "PLEX-HBAR" | - | - | **required** | | t | integer | Monotonic trade cursor id | - | - | **required** | | p | string | Trade price as a string to preserve precision | - | - | **required** | | q | string | Base asset quantity as a string to preserve precision | - | - | **required** | | T | integer | Trade time (ms), taken from the underlying domain event | - | - | **required** | | m | boolean | Whether this trade is marked as maker-side. true -> maker trade false -> taker trade | - | - | **required** | > Examples of payload ```json { "e": "trade", "E": 1672515782136, "s": "PLEX-HBAR", "t": 123456, "p": "0.0025", "q": "42.0", "T": 1672515782000, "m": true } ``` **Message `BalanceChangeEventMsg`** * Content type: [application/json](https://www.iana.org/assignments/media-types/application/json) Sent any time the authenticated account's balances change, including locked amount **Payload** | Name | Type | Description | Value | Constraints | Notes | | ------ | -------------- | ----------- | ------------------------- | ----------- | ------------------------------------- | | (root) | object | - | - | - | **additional properties are allowed** | | e | string | - | const (`"balanceChange"`) | - | **required** | | u | integer | - | - | - | **required** | | E | integer | - | - | - | **required** | | B | array\ | - | - | - | **required** | | B.a | string | - | - | - | **required** | | B.f | string | - | - | - | **required** | | B.l | string | - | - | - | **required** | > Examples of payload *(generated)* ```json { "e": "balanceChange", "u": 0, "E": 0, "B": [ { "a": "string", "f": "string", "l": "string" } ] } ``` **Message `OrderUpdateEventMsg`** * Content type: [application/json](https://www.iana.org/assignments/media-types/application/json) **Payload** | Name | Type | Description | Value | Constraints | Notes | | ------ | --------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------- | | (root) | object | - | - | - | **additional properties are allowed** | | e | string | - | const (`"orderUpdate"`) | - | **required** | | E | integer | - | - | - | **required** | | s | string | - | - | - | **required** | | c | string | - | - | - | **required** | | S | string | - | - | - | **required** | | o | string | Type of order | allowed (`"LIMIT"`, `"MARKET"`, `"STOP_LIMIT"`, `"STOP_MARKET"`) | - | **required** | | f | string \| null | GTC for limit-like orders; null for market-family orders | - | - | **required** | | q | string | - | - | - | **required** | | p | string | - | - | - | **required** | | P | string \| null | - | - | - | **required** | | C | string \| null | - | - | - | **required** | | x | string | An action taken on an order | allowed (`"ACCEPT"`, `"CANCEL"`, `"TRADE"`, `"REJECT"`, `"EXPIRE"`) | - | **required** | | X | string | Current status of an order | allowed (`"OPEN"`, `"CANCELED"`, `"FILLED"`, `"PARTIALLY_FILLED"`, `"EXPIRED"`, `"FAILED"`, `"ACTIVE"`) | - | **required** | | r | string | An action taken on the order | allowed (`"NONE"`, `"BAD_PRICE"`, `"INSUFFICIENT_BALANCE"`, `"STOP_PRICE_WOULD_TRIGGER_IMMEDIATELY"`) | - | **required** | | i | string | - | - | - | **required** | | l | string | - | - | - | **required** | | z | string | - | - | - | **required** | | L | string \| null | - | - | - | **required** | | n | string \| null | - | - | - | **required** | | N | string \| null | - | - | - | **required** | | T | integer | - | - | - | **required** | | t | integer \| null | Matches `cursorId` in `/api/v1/myTrades` for this fill. | - | - | **required** | | I | integer | Globally unique persisted domain event ID for this order update. | - | - | **required** | | w | boolean | - | - | - | **required** | | m | boolean \| null | - | - | - | **required** | | O | integer | - | - | - | **required** | | Z | string | - | - | - | **required** | | Y | string \| null | - | - | - | **required** | | W | integer \| null | - | - | - | **required** | > Examples of payload *(generated)* ```json { "e": "orderUpdate", "E": 0, "s": "string", "c": "string", "S": "string", "o": "LIMIT", "f": "string", "q": "string", "p": "string", "P": "string", "C": "string", "x": "ACCEPT", "X": "OPEN", "r": "NONE", "i": "string", "l": "string", "z": "string", "L": "string", "n": "string", "N": "string", "T": 0, "t": 0, "I": 0, "w": true, "m": true, "O": 0, "Z": "string", "Y": "string", "W": 0 } ```