Trade Actions (WebSocket)

Alpha Version

The Ostium Builder Service is in Alpha. API endpoints, specifications, and builder URLs may change without notice. Use with caution in production environments.

Endpoint

ws(s)://<host>/v1/exchange/ws

Request Envelope

Send a JSON message with action, headers, and payload.

Field	Type	Required	Description
`id`	`string`	No	Client-provided ID for correlation.
`action`	`string`	Yes	`open`, `close`, `cancel`, `modify`, `margin`, `health`.
`headers`	`object`	Cond.	Header map. Required for all actions except `health`.
`payload`	`object`	Cond.	Request body for the action. Required for all actions except `health`.

Headers Map

Field	Type	Required	Description
`X-Trader-Address`	`string`	Yes	Trader wallet address.
`X-API-Key`	`string`	No	Delegated mode (delegate wallet must be verified).

Example

{
  "id": "client-1",
  "action": "open",
  "headers": {
    "X-Trader-Address": "0x...",
    "X-API-Key": "optional"
  },
  "payload": {
    "open": {"a":0,"b":true,"p":"42500","s":"100","l":"10","t":"market"}
  }
}

Response Envelope

Field	Type	Required	Description
`id`	`string`	No	Echoes the request `id` if provided.
`ok`	`boolean`	Yes	`true` on success, `false` on error.
`data`	`object`	Cond.	Success payload (unsigned txs or delegated tx hash).
`error`	`object`	Cond.	Error payload when `ok` is `false`.

Success Data (unsigned)

{ "transactions": [ { "to": "0x...", "data": "0x...", "value": "0", "from": "0x..." } ] }

Success Data (delegated)

{ "txHash": "0x...", "smartAccountAddress": "0x..." }

Error Envelope

Field	Type	Required	Description
`message`	`string`	Yes	Human-readable error message.
`code`	`number`	Yes	HTTP-style status code.
`errorCode`	`string`	Yes	Machine-readable error code.

Example:

{
  "id": "client-1",
  "ok": false,
  "error": { "message": "Invalid JSON payload", "code": 400, "errorCode": "INVALID_REQUEST" }
}

Delegated Mode

When X-API-Key is present:

The delegate wallet must be verified or the response is 401.
Only one action is allowed per message (one open, one close, or one cancel).

Rate Limits

Trade action WebSocket connections are limited to 100 messages per minute per connection.