Trading API

Address

wss://stream-hk.osl.com/ws/v5/trade

wss://stream-hk.oslsandbox.com/ws/v5/trade

Generic Message Format

Request

{
  "id": "request-id",
  "op": "operation type",
  "args": { ... },
  "timestamp": 1787042800000,
  "validTimeWindow": 5000
}

Field	Type	Required	Description
id	string	No	Request ID, returned as-is in the response
op	string	Yes	Operation type
args	object	Depends on op	Business parameters
timestamp	long	No	Client request timestamp (Unix milliseconds), used for request expiry validation; must be used together with `validTimeWindow`
validTimeWindow	long	No	Valid time window (milliseconds). If provided, it must be greater than 0, otherwise the request is rejected (Param error). When the server receives the request, it is rejected (Timestamp request expired) if `\|serverTime - timestamp\|` exceeds this window. No expiry validation is performed when `timestamp` or `validTimeWindow` is not provided

Note: the envelope-level timestamp here is different from login's args.timestamp (the HMAC signature timestamp); they serve different purposes and do not affect each other.

Response

{
  "id": "request-id",
  "op": "operation type",
  "code": 0,
  "msg": "",
  "data": [...],
  "inTime": 1787060806850,
  "outTime": 1787060806856
}

Field	Type	Description
id	string	Request ID
op	string	Operation type
code	int	0 indicates success, non-zero is an error code
msg	string	Error message (not returned on success)
data	object/array	Business data (returned on success, omitted when null)
inTime	long	Timestamp (milliseconds) when the server received the request; omitted when null
outTime	long	Server timestamp (milliseconds)

Connection Lifecycle

Login must be completed within 30 seconds after the connection is established, otherwise a Login timeout is returned and the connection is closed.
The connection is closed after being idle (no data received) for 30 seconds, returning a Reader idle timeout.
On service shutdown, a countdown notification will be broadcast for 60 seconds at 10-second intervals. Upon receiving this message, the client should initiate a reconnection to a new node to prevent service disruption caused by unexpected disconnects when the countdown expires. Below is the message format the client will receive:
```
{"code":30017,"msg":"Service is going down for maintenance, connection will close in 30 seconds. Please reconnect.","outTime":"1787126511945"}
```

Error Codes

code	msg
30001	{field} doesn't exist
30002	Unrecognized request:{message}
30003	INVALID op:{op}
30004	User not logged in/User must be logged in
30005	Login failure
30006	request too many
30007	request over limit,connection close
30011	Invalid ACCESS_KEY
30013	Invalid ACCESS_TIMESTAMP
30014	Timestamp request expired
30015	Invalid sign
30016	Param error
30017	Service is going down for maintenance, connection will close in {n} seconds. Please reconnect.
30018	Internal error
30019	Reader idle timeout
30020	Login timeout
30021	Your API Key does not have trading permission
30022	Invalid account
30023	Already logged in
30024	Forbidden
30025	Request processing timeout, please retry

Trading error codes (for single-order failures within the data array) are negative numbers.