Multi-Market Trading (Beta)
The Multi-Market Trading API gives you US, Hong Kong, Korean and Taiwanese equities through one integration. A single set of credentials, account list, order flow and WebSocket covers every market; the market field on each request selects where it trades.
The Multi-Market API is in beta. Endpoints and fields may change before general availability. Contact our team to enable it for your firm.
Base URLs
| Environment | Base URL | WebSocket |
|---|---|---|
| UAT | https://apac.uat.atomicvaults.com/v2 | wss://apac.uat.atomicvaults.com/v2/websocket |
| Production | https://apac.production.atomicvaults.com/v2 | wss://apac.production.atomicvaults.com/v2/websocket |
All paths in this reference are relative to the base URL, for example POST https://apac.uat.atomicvaults.com/v2/orders/new.
Authentication
Every request carries an OAuth 2.0 access token in the Authorization header:
Authorization: Bearer <access_token>
Your integration gets its token with the client credentials grant. See Authentication for the full flow.
Markets
| Market | market | Example symbol | Currency |
|---|---|---|---|
| United States | US | AAPL | USD |
| Hong Kong | HK | 700 | HKD |
| Korea | KR | 005930 | KRW |
| Taiwan | TW | 2330 | TWD |
Send symbols as strings so Korean and Taiwanese codes keep their leading zeros.
Identifying an instrument
The same code can be listed in more than one market, so identify an instrument in one of two ways:
market+symbol: send both on every order. Asymbollisted in more than one market is rejected withoutmarket.security_id: the instrument ID returned by Search securities. It identifies one instrument in one market on its own.
Use market on reads too (Get orders, Get order) when you reuse symbols or order IDs across markets.
Accounts and Balances
One account can trade every market it is enabled for. Accounts lists the accounts your client can access.
Cash is held per currency. Call Balances with the currency of the market you plan to trade (USD, HKD, KRW or TWD). Positions returns holdings across every market, each tagged with its market.
Orders
This beta covers whole-share equity orders:
order_type:marketorlimit(priceis required for limit orders).sideandposition_effect:buywithopen, orsellwithclose.execution_instruction:held.time_in_force:day.order_id: your own ID, unique within the account.
A successful New order returns 201 with the av_order_id assigned by Atomic Vaults. The order can still be rejected later, for example by the exchange; that arrives as a rejected update on the WebSocket, not as an HTTP error.
Use Modify order to change quantity or limit price, and Cancel order to cancel.
Korea and Taiwan
- Buys are paid from the account's
KRWorTWDbalance. Automatic currency conversion is not available yet. - Market and limit orders are accepted during the regular session and closing auction. At other times, only limit orders are accepted.
Market status returns the current session of any market.
Order Updates
One WebSocket connection streams order updates for every market. Connect with the same bearer token and renew it on the open connection before it expires. Updates are not replayed, so reconcile with Get orders after reconnecting. See Order-update WebSocket for details.
Error Handling
Failed HTTP requests return a JSON body with an error_code and a human-readable error_msg:
{
"error_code": "BasicInput_Error",
"error_msg": "received duplicate order_id (must be unique)"
}
Use error_code for programmatic handling; the wording of error_msg can change.
error_code | HTTP status | Meaning |
|---|---|---|
BasicInput_Error | 400 | A field is missing or invalid, for example a missing account_number or a duplicate order_id |
DisallowedOrderAction_Error | 400 | The request is valid but not allowed now |
AccountBalancesPositions_Error | 400 | Not enough cash or shares for the order |
Instrument_Error | 400 | Unknown symbol, or a symbol that cannot be traded |
DataRetrieval_Error | 400 | The requested record was not found, for example an unknown order_id |
Permission_Error | 401 / 403 | 401: the access token is missing, invalid or expired. 403: the client cannot trade, or cannot access the account |
AVInternal_Error | 500 | Internal error, for example system too busy. Check the order's status before retrying |
Misc_Error | 400 / 500 | 400: the request body is not valid JSON. 500: an unexpected server error |
A 503 means the service is temporarily unavailable; retry later.
Browse the individual endpoints in the sidebar to see request and response details. Use the server selector on each endpoint page to switch between UAT and Production.