Skip to main content

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.

Beta

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​

EnvironmentBase URLWebSocket
UAThttps://apac.uat.atomicvaults.com/v2wss://apac.uat.atomicvaults.com/v2/websocket
Productionhttps://apac.production.atomicvaults.com/v2wss://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​

MarketmarketExample symbolCurrency
United StatesUSAAPLUSD
Hong KongHK700HKD
KoreaKR005930KRW
TaiwanTW2330TWD

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. A symbol listed in more than one market is rejected without market.
  • 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: market or limit (price is required for limit orders).
  • side and position_effect: buy with open, or sell with close.
  • 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 KRW or TWD balance. 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_codeHTTP statusMeaning
BasicInput_Error400A field is missing or invalid, for example a missing account_number or a duplicate order_id
DisallowedOrderAction_Error400The request is valid but not allowed now
AccountBalancesPositions_Error400Not enough cash or shares for the order
Instrument_Error400Unknown symbol, or a symbol that cannot be traded
DataRetrieval_Error400The requested record was not found, for example an unknown order_id
Permission_Error401 / 403401: the access token is missing, invalid or expired. 403: the client cannot trade, or cannot access the account
AVInternal_Error500Internal error, for example system too busy. Check the order's status before retrying
Misc_Error400 / 500400: 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.