atlaas 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,8 +1,16 @@
1
1
  # atlaas
2
2
 
3
- TypeScript SDK for the Atlaas API: MT5 terminals and trading, Expert Advisors and backtests, broker connections, unified instruments and market data, and the live WebSocket stream.
3
+ TypeScript SDK for the Atlaas API: trading and market data on every market, MT5 terminals, Expert Advisors and backtests, and the live WebSocket stream.
4
4
 
5
- Every method here maps to one REST route. The API reference has the full detail of each: [v1](https://atlaas.dev/docs/v1/authentication) for `/api/external` and `/api/atlas`, and [v2](https://atlaas.dev/docs/v2/authentication-scopes) for `/api/v2`. Which key tier can call what is in [Service-key scopes](https://atlaas.dev/docs/v1/service-key-scopes). AI agents can use the same API as tools through the [MCP server](https://atlaas.dev/docs/v1/mcp-server).
5
+ Every method here maps to one REST route, and the SDK follows the API's own split:
6
+
7
+ | Use | For | API reference |
8
+ | --- | --- | --- |
9
+ | `atlas.v2` | Orders, positions, funds, instruments and market data on MT5 and every broker | [v2](https://atlaas.dev/docs/v2) (`/api/v2`) |
10
+ | `atlas.mt5`, `atlas.instances`, `atlas.eas`, `atlas.backtests`, `atlas.subscriptions`, `atlas.serviceKeys` | The MT5 platform: terminals, Expert Advisors, deployments, backtests, keys | [v1](https://atlaas.dev/docs/v1) (`/api/external`, `/api/atlas`) |
11
+ | `atlas.trading`, `atlas.broker()` | Older MT5 and raw broker trading routes. They keep working, and each method is marked `@deprecated` with its `atlas.v2` replacement | [v1](https://atlaas.dev/docs/v1) |
12
+
13
+ [What works where](https://atlaas.dev/docs/coverage) lists every feature by market (Forex, India, Crypto, US), with the API and SDK call for each. Which key tier can call what is in [Service-key scopes](https://atlaas.dev/docs/v1/service-key-scopes). AI agents can use the same API as tools through the [MCP server](https://atlaas.dev/docs/v1/mcp-server).
6
14
 
7
15
  ## Install
8
16
 
@@ -31,16 +39,16 @@ const atlas = new AtlasClient({
31
39
  // Your MT5 terminals
32
40
  const terminals = await atlas.mt5.list()
33
41
 
34
- // Buy 0.01 lots of EURUSD on the first one, by its MT5 login
35
- const login = terminals[0].accountId
36
- const order = await atlas.trading.placeOrder(login, { symbol: "EURUSD", type: "BUY", volume: 0.01 })
42
+ // Buy 0.01 lots of EURUSD on the first one. v2 takes the terminal's Atlaas id (or your externalRef)
43
+ const conn = atlas.v2.connections(terminals[0].id)
44
+ const order = await conn.placeOrder({ instrumentKey: "FX:EURUSD", side: "BUY", orderType: "MARKET", lots: 0.01 })
37
45
 
38
- // Its open positions
39
- const positions = await atlas.trading.getPositions(login)
40
- console.log(order.ticket, positions.length)
46
+ // Its open positions, in the same shape as every broker's
47
+ const { positions } = await conn.positions()
48
+ console.log(order.orderId, positions.length)
41
49
  ```
42
50
 
43
- The rest of this page assumes an `atlas` client built as above.
51
+ The same `atlas.v2.connections(id)` calls work on a Dhan, Kite, Bybit or Alpaca connection. The rest of this page assumes an `atlas` client built as above.
44
52
 
45
53
  ## Client options
46
54
 
@@ -68,7 +76,7 @@ A failed request throws an `AtlasError` (or a subclass). Besides `message` and `
68
76
  import { AtlasAuthError, AtlasError, AtlasNetworkError, AtlasRateLimitError, AtlasValidationError } from "atlaas"
69
77
 
70
78
  try {
71
- await atlas.v2.connections("my-conn-001").place({ instrumentKey: "NSE:EQ:RELIANCE", side: "BUY", orderType: "MARKET", quantity: 1 })
79
+ await atlas.v2.connections("my-conn-001").placeOrder({ instrumentKey: "NSE:EQ:RELIANCE", side: "BUY", orderType: "MARKET", quantity: 1 })
72
80
  } catch (err) {
73
81
  if (err instanceof AtlasAuthError) {
74
82
  // 401: the key is invalid, disabled or expired
@@ -93,7 +101,7 @@ Status codes and every code are listed in the API reference: [v1 errors](https:/
93
101
  The SDK retries a failed request (up to `maxRetries`, with backoff, honouring `Retry-After` up to 10 s) only when sending it again cannot act twice:
94
102
 
95
103
  - **Reads** are retried on a network failure, a 408, a 429 or a 5xx other than 501, unless the server says `retryable: false`.
96
- - **Order writes** are de-duplicated by the server: each call sends one `Idempotency-Key`, every retry reuses it, and the server answers a repeat with the first attempt's stored result. They are retried like reads. These are `trading.placeOrder`, `cancelOrder`, `modifyPosition`, `closePosition` and `closeBySymbol`, the `broker()` order writes, and the `v2.connections()` writes.
104
+ - **Order writes** are de-duplicated by the server: each call sends one `Idempotency-Key`, every retry reuses it, and the server answers a repeat with the first attempt's stored result. They are retried like reads. These are the `v2.connections()` writes, the deprecated `trading.placeOrder`, `cancelOrder`, `modifyPosition`, `closePosition` and `closeBySymbol`, and the deprecated `broker()` order writes.
97
105
  - **Every other write** (creating a terminal, a backtest, an EA version…) is not de-duplicated by the server, so it is sent once. Only the key's own rate limit (a 429 refused before anything ran) is retried.
98
106
  - **Never retried:** `OUTCOME_UNKNOWN`, any answer the server replayed from its key store, and any error the server marks `retryable: false`.
99
107
 
@@ -102,199 +110,375 @@ To retry an order write yourself, across calls or processes, pass your own key.
102
110
  ```typescript
103
111
  const conn = atlas.v2.connections("my-conn-001")
104
112
  const key = "signal-2026-11-12-0915-reliance"
105
- const placed = await conn.place({ instrumentKey: "NSE:EQ:RELIANCE", side: "BUY", orderType: "MARKET", quantity: 1 }, { idempotencyKey: key })
106
- await atlas.trading.placeOrder("51234567", { symbol: "EURUSD", type: "BUY", volume: 0.01 }, { idempotencyKey: `${key}-fx` })
113
+ const placed = await conn.placeOrder({ instrumentKey: "NSE:EQ:RELIANCE", side: "BUY", orderType: "MARKET", quantity: 1 }, { idempotencyKey: key })
114
+ await atlas.v2.connections("my-mt5-001").placeOrder({ instrumentKey: "FX:EURUSD", side: "BUY", orderType: "MARKET", lots: 0.01 }, { idempotencyKey: `${key}-fx` })
107
115
  console.log(placed.orderId)
108
116
  ```
109
117
 
110
118
  See [Idempotent order writes](https://atlaas.dev/docs/v1/idempotent-order-writes) (v1) and [Idempotent writes](https://atlaas.dev/docs/v2/idempotent-writes) (v2).
111
119
 
112
- ## MT5 terminals (`atlas.mt5`)
120
+ # Trading (v2)
113
121
 
114
- Deploy, start, stop and remove MT5 terminals, named by MT5 login. Deploying charges the provisioning fee. [API reference](https://atlaas.dev/docs/v1/mt5-instance-lifecycle)
122
+ One shape for every broker: account-scoped reads and writes on any connection, MT5 terminals included.
123
+
124
+ ## Connections (`atlas.v2.connections()`)
125
+
126
+ Orders, trades, positions, holdings, funds and profile of any connection (Dhan, Kite, Motilal, Angel One, Fyers, Upstox, Shoonya, the crypto and US brokers, MT5) in one shape, and one order shape to write with. Account-scoped: a key only sees its own connections. The id is the Atlaas instance id or its `externalRef`. [API reference](https://atlaas.dev/docs/v2/connections), [what each broker can do](https://atlaas.dev/docs/v2/broker-capabilities)
115
127
 
116
128
  ```typescript
117
- const servers = await atlas.mt5.servers() // [{ serverName, brokerName, displayName, serverType, defaultSymbol }]
118
- const regions = await atlas.mt5.regions() // [{ id, code, displayName, description }], only regions with room
129
+ const conn = atlas.v2.connections("my-conn-001")
119
130
 
120
- const terminal = await atlas.mt5.create({
121
- accountId: "51234567",
122
- password: process.env.MT5_PASSWORD ?? "",
123
- serverName: servers[0].serverName,
124
- regionId: regions[0]?.id, // optional
125
- type: "TICKS_TRADE",
126
- name: "Gold scalper",
127
- externalRef: "user-42-gold" // optional, your own id
128
- })
131
+ const { broker, capabilities } = await conn.capabilities()
132
+ const { orders, dropped } = await conn.orders()
133
+ const order = await conn.order(orders[0].orderId, { includeRaw: true }) // raw: the broker's own payload
134
+ const { positions, scope } = await conn.positions({ scope: "DAY" }) // NET by default
135
+ const { trades } = await conn.trades({ includeRaw: true })
136
+ const { holdings } = await conn.holdings()
137
+ const funds = await conn.funds()
138
+ const profile = await conn.profile()
139
+ console.log(broker, capabilities.fractionalQuantity, dropped.length, order.status, positions.length, scope, trades.length, holdings.length, funds.availableBalance, profile.clientId)
129
140
 
130
- await atlas.mt5.list() // Instance[], newest first
131
- await atlas.mt5.get(terminal.accountId) // state: PENDING → DEPLOYING → RUNNING
132
- await atlas.mt5.stop(terminal.accountId)
133
- await atlas.mt5.start(terminal.accountId)
134
- await atlas.mt5.delete(terminal.accountId) // no refund
141
+ // Everything in one call; each section is ok or an error of its own
142
+ const snap = await conn.snapshot()
143
+ if (snap.sections.funds.ok) console.log(snap.sections.funds.funds.availableBalance)
144
+
145
+ // MT5 only: the symbols this terminal lists, with their contract specs
146
+ const { symbols } = await atlas.v2.connections("my-mt5-001").symbols({ symbol: "XAUUSD" })
147
+ console.log(symbols[0]?.contractSize)
135
148
  ```
136
149
 
137
- | Method | Returns |
138
- | --- | --- |
139
- | `list()` | `Instance[]` |
140
- | `create(body: CreateInstanceBody)` | `Instance` |
141
- | `get(accountId: string)` | `Instance` |
142
- | `delete(accountId: string)` | `void` |
143
- | `start(accountId: string)` | `Instance` |
144
- | `stop(accountId: string)` | `Instance` |
145
- | `servers()` | `DeployServer[]` |
146
- | `regions()` | `DeployRegion[]` |
150
+ Every read takes `includeRaw` to add the broker's untranslated row as `raw`. Every list carries `dropped`: rows Atlaas could not map to an instrument (`INSTRUMENT_UNRESOLVED`) or to the unified shape (`UNMAPPABLE`), reported rather than left out. MT5 and Motilal are net-only, so `positions` answers `scope: "NET"` whatever you ask, and `snapshot` positions are always `NET`. A dropped MT5 position or order also carries `mt5: { ticket, symbol, lots?, side? }` as the terminal reported it, so read `dropped` with `positions`: an empty `positions` with a non-empty `dropped` is not a flat account, and the ticket can still be closed by `positionId`.
147
151
 
148
- ## MT5 trading (`atlas.trading`)
152
+ ### Writes
149
153
 
150
- Trading on one terminal, named by its MT5 login (`/api/external/instances/:accountId`). [Account](https://atlaas.dev/docs/v1/mt5-account), [positions](https://atlaas.dev/docs/v1/mt5-positions), [orders](https://atlaas.dev/docs/v1/mt5-orders), [market data](https://atlaas.dev/docs/v1/mt5-market-data).
154
+ Size an order in `quantity` (units; Atlaas converts to lots or MT5 volume and refuses a quantity it cannot convert exactly) or, on MT5 and Motilal, in `lots` (sent as is). Exactly one of the two. Every write is checked against `capabilities` first and refused with `UNSUPPORTED_CAPABILITY` when the broker cannot do it. [API reference](https://atlaas.dev/docs/v2/placing-and-managing-orders)
151
155
 
152
156
  ```typescript
153
- const login = "51234567"
154
-
155
- // Orders
156
- const order = await atlas.trading.placeOrder(login, { symbol: "EURUSD", type: "BUY_LIMIT", volume: 0.1, price: 1.08, sl: 1.07, tp: 1.1 })
157
- await atlas.trading.getOrders(login)
158
- await atlas.trading.cancelOrder(login, order.ticket)
157
+ const conn = atlas.v2.connections("my-conn-001")
159
158
 
160
- // Positions
161
- const open = await atlas.trading.getPositions(login) // what the EA last pushed
162
- const one = await atlas.trading.getPosition(login, open[0].ticket) // open, or closed from history
163
- if (one.status === "CLOSED") console.log(one.closePrice, one.closeTime)
164
- await atlas.trading.modifyPosition(login, open[0].ticket, { sl: 1.07, tp: 1.12 })
165
- await atlas.trading.closePosition(login, open[0].ticket, { volume: 0.05 }) // partial; omit the body to close it all
166
- await atlas.trading.closeBySymbol(login, { symbol: "EURUSD" }) // { symbol, closedCount, totalProfit, positions }
159
+ const placed = await conn.placeOrder({
160
+ instrumentKey: "NSE:FNO:NIFTY:2026-09-24:24000:CE",
161
+ side: "BUY",
162
+ orderType: "LIMIT",
163
+ quantity: 150, // units: 2 lots of 75
164
+ price: 120.5,
165
+ product: "INTRADAY",
166
+ clientTag: "sig-42"
167
+ })
168
+ await conn.modifyOrder(placed.orderId, { price: 121, quantity: 150 })
169
+ await conn.cancelOrder(placed.orderId)
167
170
 
168
- // Closed positions from the terminal's deal history, paged by close time
169
- let since = 0
170
- for (;;) {
171
- const page = await atlas.trading.getClosedPositions(login, { since, limit: 200 })
172
- for (const p of page.positions) console.log(p.ticket, p.profit)
173
- if (!page.hasMore || page.positions.length === 0) break
174
- since = page.positions[page.positions.length - 1].closeTimeMs
175
- }
171
+ // MT5 in lots, with the position's SL/TP on the order
172
+ const mt5 = atlas.v2.connections("my-mt5-001")
173
+ const fx = await mt5.placeOrder({ instrumentKey: "FX:EURUSD", side: "BUY", orderType: "MARKET", lots: 0.05, stopLoss: 1.08, takeProfit: 1.12 })
174
+ const gold = await mt5.placeOrder({ instrumentKey: "FX:XAUUSD", side: "BUY", orderType: "MARKET", lots: 0.1, symbol: "XAUUSD.r" }) // pin the terminal's spelling
175
+ console.log(gold.symbol) // "XAUUSD.r"
176
+ await mt5.modifyPosition(fx.orderId, { takeProfit: 1.13 }) // SL untouched; 0 clears a level
176
177
 
177
- // Market data and account
178
- await atlas.trading.getPrice(login, "EURUSD") // { symbol, bid, ask, last?, volume?, timestamp? }
179
- await atlas.trading.getSymbols(login)
180
- await atlas.trading.getSymbolSpecs(login) // every symbol's contract spec, raw from the terminal
181
- await atlas.trading.getAccountInfo(login)
182
- await atlas.trading.getCandles(login, { symbol: "EURUSD", timeframe: "H1", startTime: "2026-01-01T00:00:00Z", endTime: "2026-01-02T00:00:00Z" })
183
- await atlas.trading.calculateMargin(login, { symbol: "EURUSD", type: "ORDER_TYPE_BUY", volume: 0.1, openPrice: 1.08 })
178
+ // Close: flatten, or part of one MT5 ticket
179
+ await conn.closePosition({ instrumentKey: "NSE:EQ:RELIANCE" })
180
+ await mt5.closePosition({ instrumentKey: "FX:EURUSD", positionId: fx.orderId, lots: 0.02 })
184
181
  ```
185
182
 
186
- Reads that come from the terminal can tell you how fresh they are. Pass `{ withFreshness: true }` to `getOrders`, `getPositions`, `getPosition`, `getPrice`, `getSymbols`, `getSymbolSpecs` or `getAccountInfo`:
183
+ Per broker:
187
184
 
188
- ```typescript
189
- const { data, dataAsOf, lastHeartbeatAt } = await atlas.trading.getPositions("51234567", { withFreshness: true })
190
- const ageMs = Date.now() - Date.parse(dataAsOf)
191
- if (ageMs > 10_000) console.warn(`positions are ${ageMs} ms old; last EA heartbeat ${lastHeartbeatAt}`)
192
- console.log(data.length)
193
- ```
185
+ - **Motilal**: `orderType: "MARKET"` is synthetic. Atlaas places a marketable LIMIT priced off its feed and chases it (`chase: { maxDriftPct, maxReprices, timeoutMs }`, defaults 1 / 3 / 60000); results and the order book carry a `synthetic` block, and an exhausted chase is cancelled with `CHASE_EXHAUSTED`. A feed that is down answers `FEED_UNAVAILABLE`. `modifyOrder` without `quantity` keeps the resting quantity.
186
+ - **Kite**: a 2xx with no `order_id` is reported as `BROKER_REJECTED`.
187
+ - **Dhan / Kite**: `lots` is refused. `quantity` on `closePosition` closes that many units, capped at what is open.
188
+ - **MT5**: no `STOP_LIMIT`; `modifyOrder` takes only `price` / `triggerPrice`; a partial close needs one ticket (`positionId`). The terminal's own symbol list decides which spelling an order goes to; when it lists several (`XAUUSD.r`, `XAUUSD.cent`), pin one with `symbol` on `placeOrder`, and the result's `symbol` says what was sent. `quantity` converts with that symbol's own contract size and may be fractional on the 0.001-lot grid (`fractionalQuantity` is true); while the terminal's contract size is unknown, a `quantity` place or partial close is refused with `VALIDATION`, so send `lots`. Positions report `mt5.volume` in lots, so prefer `lots` if you keep your books in lots. Rows need the FX instrument import, or they come back in `dropped`. How Atlaas picks the terminal's own spelling of a symbol: [MT5 symbols](https://atlaas.dev/docs/v2/mt5-symbols-the-terminal-decides).
189
+ - **Crypto and fractional shares**: a non-integer `quantity` is accepted where `capabilities.fractionalQuantity` is true. Perpetual positions carry `margin` and `funding`.
194
190
 
195
- A terminal Atlaas cannot see answers 503 `TERMINAL_UNAVAILABLE`, never an empty list.
191
+ `OUTCOME_UNKNOWN` (504) means the order reached the broker and no answer came back: read the order book before you send it again.
196
192
 
197
193
  | Method | Returns |
198
194
  | --- | --- |
199
- | `placeOrder(accountId, body: PlaceOrderBody, options?: WriteOptions)` | `Order` |
200
- | `getOrders(accountId, options?: FreshnessOption)` | `Order[]` |
201
- | `cancelOrder(accountId, ticket: number, options?: WriteOptions)` | `void` |
202
- | `getPositions(accountId, options?: FreshnessOption)` | `Position[]` |
203
- | `getPosition(accountId, ticket: number, options?: FreshnessOption)` | `PositionDetail` |
204
- | `getClosedPositions(accountId, query: ClosedPositionsQuery)` | `ClosedPositionsResult` |
205
- | `modifyPosition(accountId, ticket: number, body: ModifyPositionBody, options?: WriteOptions)` | `ModifyMt5PositionResult` |
206
- | `closePosition(accountId, ticket: number, body?: ClosePositionBody, options?: WriteOptions)` | `CloseMt5PositionResult` |
207
- | `closeBySymbol(accountId, body: CloseBySymbolBody, options?: WriteOptions)` | `CloseBySymbolResult` |
208
- | `getPrice(accountId, symbol: string, options?: FreshnessOption)` | `Price` |
209
- | `getSymbols(accountId, options?: FreshnessOption)` | `string[]` |
210
- | `getSymbolSpecs(accountId, options?: FreshnessOption)` | `Mt5SymbolSpec[]` |
211
- | `getAccountInfo(accountId, options?: FreshnessOption)` | `AccountInfo` |
212
- | `getCandles(accountId, query: GetCandlesQuery)` | `Candle[]` |
213
- | `calculateMargin(accountId, body: CalculateMarginBody)` | `MarginResult` |
195
+ | `orders(params?: IncludeRawParams)` | `OrdersListResult` |
196
+ | `order(orderId, params?: IncludeRawParams)` | `UnifiedOrder` |
197
+ | `trades(params?: IncludeRawParams)` | `TradesListResult` |
198
+ | `positions(params?: PositionsListParams)` | `PositionsListResult` |
199
+ | `holdings(params?: IncludeRawParams)` | `HoldingsListResult` |
200
+ | `funds(params?: IncludeRawParams)` | `UnifiedFunds` |
201
+ | `profile(params?: IncludeRawParams)` | `UnifiedProfile` |
202
+ | `symbols(params?: { symbol?: string })` | `SymbolSpecsResult` |
203
+ | `capabilities()` | `CapabilitiesResult` |
204
+ | `snapshot(params?: IncludeRawParams)` | `V2Snapshot` |
205
+ | `placeOrder(body: PlaceOrderV2Body, options?: V2WriteOptions)` | `PlaceOrderResult` |
206
+ | `modifyOrder(orderId, body: ModifyOrderV2Body, options?: V2WriteOptions)` | `ModifyOrderResult` |
207
+ | `cancelOrder(orderId, options?: V2WriteOptions)` | `CancelOrderResult` |
208
+ | `closePosition(body: ClosePositionV2Body, options?: V2WriteOptions)` | `ClosePositionResult` |
209
+ | `modifyPosition(positionId, body: ModifyPositionV2Body, options?: V2WriteOptions)` | `ModifyPositionResult` |
214
210
 
215
- With `{ withFreshness: true }` each read returns `Fresh<T>` (`{ data, dataAsOf, lastHeartbeatAt }`) instead.
211
+ `V2WriteOptions` is `{ idempotencyKey?, signal?, includeRaw? }`. Before 0.4.0 the three order writes were named `place`, `modify` and `cancel`; those names still work and are marked `@deprecated`.
216
212
 
217
- ## MT5 tick and candle subscriptions (`atlas.subscriptions`)
213
+ # Market data (v2)
218
214
 
219
- Which symbols a terminal streams to the WebSocket, by Atlaas instance id. [API reference](https://atlaas.dev/docs/v1/mt5-real-time-subscriptions-websocket)
215
+ Canonical instruments, and market data that needs no connection.
216
+
217
+ ## Instruments (`atlas.v2.instruments`)
218
+
219
+ Atlaas's canonical `instrumentKey` for each contract, with each broker's reference id attached. Global reference data: any key can read any instrument. [API reference](https://atlaas.dev/docs/v2/instruments)
220
220
 
221
221
  ```typescript
222
- const instanceId = "6f1c2a9e-0000-4000-8000-000000000000"
222
+ const { instruments, nextCursor } = await atlas.v2.instruments.list({
223
+ exchange: "NSE", // NSE | BSE | MCX | FX | US | CRYPTO
224
+ segment: "FNO", // EQ | FNO | IDX | CDS | COMM | FX | SPOT | PERP
225
+ symbol: "NIFTY", // exact symbol
226
+ q: "RELI", // substring of instrumentKey (not the name)
227
+ active: true, // default true; false lists inactive rows only
228
+ limit: 100 // default 100, max 500
229
+ })
230
+ const next = nextCursor ? await atlas.v2.instruments.list({ exchange: "NSE", cursor: nextCursor }) : null
223
231
 
224
- await atlas.subscriptions.subscribeTick(instanceId, { symbol: "EURUSD" })
225
- await atlas.subscriptions.getTickSubscriptions(instanceId) // { instanceId, accountId, symbols, count }
226
- await atlas.subscriptions.unsubscribeTick(instanceId, { symbol: "EURUSD" }) // omit the body for every symbol
232
+ const reliance = await atlas.v2.instruments.get("NSE:EQ:RELIANCE")
233
+ const fromDhan = await atlas.v2.instruments.resolve({ broker: "dhan", refId: "2885", segment: "NSE_EQ" })
234
+ console.log(instruments.length, next?.instruments.length, reliance.brokerRefs.motilal?.symboltoken, fromDhan.instrumentKey)
235
+ ```
227
236
 
228
- await atlas.subscriptions.subscribeCandle(instanceId, { symbol: "EURUSD", timeframe: "M1" })
229
- await atlas.subscriptions.getCandleSubscriptions(instanceId) // { instanceId, accountId, subscriptions, count }
230
- await atlas.subscriptions.unsubscribeCandle(instanceId, { symbol: "EURUSD", timeframe: "M1" })
237
+ Key format: `EXCHANGE:SEGMENT:SYMBOL`, with expiry, strike and right for derivatives:
238
+
239
+ ```
240
+ NSE:EQ:RELIANCE equity
241
+ NSE:IDX:NIFTY index
242
+ NSE:FNO:NIFTY:2026-08-27:FUT future
243
+ NSE:FNO:NIFTY:2026-08-27:24000:CE option
244
+ NSE:FNO:USDINR:2026-08-27:84.25:PE fractional strike
245
+ FX:XAUUSD forex
231
246
  ```
232
247
 
233
- ## Instances and broker connections (`atlas.instances`)
248
+ Expiries are `YYYY-MM-DD`; symbols never contain `:`. Paging is keyset on `instrumentKey`: pass `nextCursor` back as `cursor` until it is `null`. Kite refs are derived from the Dhan and Motilal rows, not synced from a Kite master. `FX:*` rows come from an MT5 terminal's symbol import.
234
249
 
235
- Every instance on the account, MT5 or broker, keyed by your own `externalRef` (`/api/atlas/instances`). [API reference](https://atlaas.dev/docs/v1/instances-by-id-apiatlas), [identifiers](https://atlaas.dev/docs/v1/identifiers-read-this-first)
250
+ ## Market data (`atlas.v2.market`)
251
+
252
+ Quotes, candles and option chains by `instrumentKey`, with no connection. NSE/BSE keys come from the Atlaas market data feed (they need the account's India access); FX keys from an MT5 terminal you own. Crypto and US keys have no source here yet. A feed that is down answers `FEED_UNAVAILABLE` (503, retryable) and an MT5 server with no clock offset set answers `TIMEZONE_UNCONFIGURED` (409). [API reference](https://atlaas.dev/docs/v2/market-data)
236
253
 
237
254
  ```typescript
238
- // Validate broker credentials before storing them (Dhan logs in and returns the minted token)
239
- const check = await atlas.instances.validateBrokerCredentials({
240
- brokerName: "dhan",
241
- credentials: { clientId: "1100000000", pin: "1234", totpSecret: process.env.DHAN_TOTP ?? "" }
242
- })
243
- if (!check.valid) throw new Error(check.error)
255
+ const tick = await atlas.v2.market.quote("NSE:EQ:RELIANCE") // { instrumentKey, ts, mode, ltp, bid?, ask?, ... }
256
+ const { ticks, unresolved } = await atlas.v2.market.quotes(["NSE:EQ:RELIANCE", "NSE:EQ:TCS"]) // up to 200 keys
257
+ console.log(tick.ltp, ticks.length, unresolved)
244
258
 
245
- // Create a broker connection. Brokers need no runnerId: Atlaas places it on a server of its own.
246
- const created = await atlas.instances.create({
247
- instanceKind: "dhan",
248
- externalRef: "my-conn-001",
249
- credentials: check.credentials
259
+ const { candles } = await atlas.v2.market.candles({
260
+ instrumentKey: "NSE:EQ:RELIANCE",
261
+ interval: "5m",
262
+ from: "2026-09-07T03:45:00Z",
263
+ to: new Date("2026-09-07T10:00:00Z")
250
264
  })
251
- console.log(created.runnerReady, created.ipAddress) // whitelist ipAddress with the broker
265
+ const gold = await atlas.v2.market.candles({ instrumentKey: "FX:XAUUSD", interval: "4h", from: "2026-09-01T00:00:00Z", to: "2026-09-07T00:00:00Z", connectionId: "my-mt5-001" })
266
+ console.log(candles.length, gold.source)
252
267
 
253
- const instance = await atlas.instances.get(created.id)
254
- await atlas.instances.getByExternalRef("my-conn-001")
255
- await atlas.instances.getByExternalRefs(["my-conn-001", "my-conn-002"])
256
- await atlas.instances.list({ instanceKind: "dhan", state: "RUNNING", limit: 100 })
257
- await atlas.instances.update(instance.id, { name: "Dhan main", credentialsPatch: { pin: "4321" } }) // { id }
258
- await atlas.instances.disable(instance.id) // stops it on its runner; credentials stay stored
259
- await atlas.instances.enable(instance.id) // redeploys it
260
- await atlas.instances.delete(instance.id)
268
+ const { expiries } = await atlas.v2.market.expiries("NSE:IDX:NIFTY")
269
+ const chain = await atlas.v2.market.optionChain("NSE:IDX:NIFTY", expiries[0])
270
+ const atm = chain.strikes.reduce((a, b) => (Math.abs(b.strike - chain.underlyingLtp) < Math.abs(a.strike - chain.underlyingLtp) ? b : a))
271
+ if (atm.ce) await atlas.v2.connections("my-conn-001").placeOrder({ instrumentKey: atm.ce.instrumentKey, side: "BUY", orderType: "MARKET", quantity: 75 })
261
272
  ```
262
273
 
263
- `create` with an `externalRef` you already used updates that instance instead. An MT5 instance here needs a `runnerId`; `atlas.mt5.create` picks one for you.
274
+ - `quote()` on a key nobody is streaming yet subscribes it and reads the price once from the vendor, so it answers an LTP snapshot (`mode: "LTP"`) straight away. An FX key with no tick yet answers a retryable 404 while its subscription opens.
275
+ - `quotes()` never comes back short: a key it cannot price is listed in `unresolved` with the reason.
276
+ - Candle intervals: NSE/BSE `1m`, `5m`, `15m`, `1h`, `1d`; FX (MT5) all eight (`1m`, `3m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`). Closed bars are cached, so asking again for a window Atlaas has seen costs no vendor call. FX candles take an optional `connectionId`.
277
+ - Option chains are metered at about one call per 3 s per chain; identical calls inside that window share one answer, and a vendor refusal is `RATE_LIMITED` (retryable).
264
278
 
265
279
  | Method | Returns |
266
280
  | --- | --- |
267
- | `list(query?: ListInstancesQuery)` | `AtlasInstance[]` |
268
- | `get(id: string)` | `AtlasInstance` |
269
- | `getByExternalRef(ref: string)` | `AtlasInstance` |
270
- | `getByExternalRefs(refs: string[])` | `AtlasInstance[]` |
271
- | `create(body: CreateAtlasInstanceBody)` | `CreateAtlasInstanceResult` |
272
- | `update(id: string, body: UpdateAtlasInstanceBody)` | `{ id: string }` |
273
- | `disable(id: string)` | `AtlasInstance \| null` |
274
- | `enable(id: string)` | `AtlasInstance \| null` |
275
- | `delete(id: string)` | `void` |
276
- | `validateBrokerCredentials(body: ValidateBrokerCredentialsBody)` | `ValidateBrokerCredentialsResult` |
281
+ | `quote(instrumentKey)` | `UnifiedTick` |
282
+ | `quotes(instrumentKeys: string[])` | `MarketQuotesResult` |
283
+ | `candles(params: MarketCandlesParams)` | `MarketCandlesResult` |
284
+ | `expiries(underlyingKey)` | `UnifiedOptionExpiries` |
285
+ | `optionChain(underlyingKey, expiry)` | `UnifiedOptionChain` |
277
286
 
278
- ## Service keys (`atlas.serviceKeys`)
287
+ ## Scanner (`atlas.v2.scanner`)
279
288
 
280
- [API reference](https://atlaas.dev/docs/v1/service-keys), [scopes](https://atlaas.dev/docs/v1/service-key-scopes)
289
+ The NSE intraday strength scanner: every ranked stock, the picks on each side, breadth and sectors, recomputed each minute of the session. Needs the account's India access. [API reference](https://atlaas.dev/docs/v2/scanner)
281
290
 
282
291
  ```typescript
283
- const accountId = "acc_123"
292
+ const board = await atlas.v2.scanner.board({ paths: true }) // paths: each stock's move per session minute
293
+ console.log(board.session.state, board.picks.bullish, board.rows[0]?.strength)
284
294
 
285
- await atlas.serviceKeys.list(accountId, { isActive: true })
286
- const key = await atlas.serviceKeys.create(accountId, { keyName: "prod-bot", rateLimitPerMinute: 600, allowedIpAddresses: ["203.0.113.7"] })
287
- console.log(key.rawKey) // shown once
288
- await atlas.serviceKeys.update(key.id, { isActive: false })
289
- await atlas.serviceKeys.regenerate(key.id) // a new rawKey
290
- await atlas.serviceKeys.delete(key.id)
295
+ // Later, only the minutes you do not have yet
296
+ const update = await atlas.v2.scanner.board({ paths: true, after: board.session.minute })
297
+
298
+ // Zones, stops and targets for one ranked stock, on its last two sessions of 5m bars
299
+ const zones = await atlas.v2.scanner.zones(board.picks.bullish[0])
300
+ console.log(update.pathsFrom, zones.rr, zones.stops[0]?.price)
291
301
  ```
292
302
 
293
- ## Expert Advisors (`atlas.eas`)
303
+ | Method | Returns |
304
+ | --- | --- |
305
+ | `board(params?: ScannerBoardParams)` | `ScannerBoard` |
306
+ | `zones(instrumentKey)` | `ScannerZones` |
294
307
 
295
- Your EAs, their versions and presets, and their deployments on terminals. [API reference](https://atlaas.dev/docs/v1/eas-deployments-api), [writing an EA for Atlaas](https://atlaas.dev/docs/v1/expert-advisors)
308
+ ## WebSocket stream (`AtlasWebSocket`)
296
309
 
297
- ```typescript
310
+ Live data on `/ws/service`. [Unified channels](https://atlaas.dev/docs/v2/websocket-channels), [MT5 channels](https://atlaas.dev/docs/v1/mt5-real-time-subscriptions-websocket)
311
+
312
+ ```typescript
313
+ import { AtlasWebSocket } from "atlaas"
314
+
315
+ const ws = new AtlasWebSocket({ baseUrl: "https://api.atlaas.dev", apiKey: process.env.ATLAAS_API_KEY ?? "", clientName: "my-bot" })
316
+ await ws.connect() // rejects with AtlasAuthError, e.g. "Account is suspended"
317
+ ws.on("subscribe_failed", (f) => console.error("subscribe refused:", f.reason)) // nothing changed
318
+
319
+ ws.subscribe({ channels: ["market.ticks", "market.candles", "trading.orders"], instrumentKeys: ["NSE:EQ:RELIANCE", "FX:EURUSD"] })
320
+ ws.on("subscribed", (reply) => {
321
+ for (const r of reply.refusedInstrumentKeys ?? []) console.warn(`${r.instrumentKey} not subscribed: ${r.reason}`)
322
+ if (reply.refusedChannels) console.warn("refused:", reply.refusedChannels)
323
+ })
324
+
325
+ ws.on("market.tick", (t) => console.log(t.instrumentKey, t.ltp))
326
+ ws.on("market.candle", (c) => c.isFinal && console.log(c.instrumentKey, c.interval, c.candle.c))
327
+ ws.on("trading.order", (o) => console.log(o.connectionId, o.sequence, o.orderId, o.status))
328
+
329
+ // MT5 frames: name the channels you want, narrowed to some terminals and symbols
330
+ ws.subscribe({ channels: ["ticks", "candles", "positions", "trades"], accountIds: ["51234567"], symbols: ["EURUSD"] })
331
+ ws.on("tick", (t) => console.log(t.accountId, t.symbol, t.bid, t.ask))
332
+ ws.on("candle", (c) => console.log(c.symbol, c.timeframe, c.close))
333
+ ws.on("position_update", (p) => console.log(p.accountId, p.equity, p.positions.length))
334
+ ws.on("trade_event", (e) => console.log(e.transType, e.symbol, e.deal))
335
+ ws.on("heartbeat", (h) => console.log(h.accountId, h.balance))
336
+
337
+ // Option chains and the scanner board
338
+ ws.subscribe({ channels: ["market.chain"], chains: [{ underlyingKey: "NSE:IDX:NIFTY", expiry: "2026-11-26" }] })
339
+ ws.subscribe({ channels: ["market.scanner"] })
340
+ ws.on("market.chain", (chain) => console.log(chain.underlyingKey, chain.strikes.length))
341
+ ws.on("market.scanner", (board) => console.log(board.asOf, board.picks.bullish))
342
+
343
+ // Drop one key, one chain, or whole channels
344
+ ws.unsubscribe({ instrumentKeys: ["FX:EURUSD"] })
345
+ ws.unsubscribe({ chains: [{ underlyingKey: "NSE:IDX:NIFTY", expiry: "2026-11-26" }] })
346
+ ws.unsubscribe(["market.scanner"])
347
+
348
+ ws.on("disconnected", (reason) => console.log("disconnected:", reason)) // reconnects and re-subscribes by itself
349
+ ws.on("error", (err) => console.error(err))
350
+ console.log(ws.isConnected)
351
+ ws.disconnect()
352
+ ```
353
+
354
+ | Channel | Events | Filter | Scope |
355
+ | --- | --- | --- | --- |
356
+ | `market.ticks` | `market.tick` (`UnifiedTick`) | `instrumentKeys` | `feed:r` |
357
+ | `market.candles` | `market.candle` (`{ instrumentKey, interval, isFinal, candle, source }`) | `instrumentKeys` | `feed:r` |
358
+ | `market.chain` | `market.chain` (`UnifiedOptionChain`) | `chains` | `feed:r`, India |
359
+ | `market.scanner` | `market.scanner` (the scanner board plus `append`) | none | `feed:r`, India |
360
+ | `trading.orders` | `trading.order` (`UnifiedOrder` plus `eventTs`, `sequence`) | `brokerOrderConnectionIds` | `orders:r` |
361
+ | `broker_ticks` (deprecated: use `market.ticks`) | `broker_tick` (Dhan / Kite ticks, untranslated) | `brokerConnectionIds`, `brokerSecurityKeys` (empty: all yours) | `feed:r` |
362
+ | `broker_orders` (deprecated: use `trading.orders`) | `broker_order_update` (the broker's own order alert) | `brokerOrderConnectionIds` (empty: all yours) | `orders:r` |
363
+ | `ticks` | `tick` | `accountIds`, `symbols` | `feed:r` |
364
+ | `candles` | `candle` | `accountIds`, `symbols` | `feed:r` |
365
+ | `positions` | `position_update` | `accountIds` | `orders:r` |
366
+ | `trades` | `trade_event` | `accountIds` | `orders:r` |
367
+
368
+ The MT5 channels (`ticks`, `candles`, `positions`, `trades`) work like this:
369
+
370
+ - Once a subscribe has accepted one of them, the socket gets only the MT5 channels it named, narrowed by `accountIds` (MT5 logins; empty means every terminal you own), with `symbols` narrowing ticks and candles. The terminal `heartbeat` follows `accountIds` only. Unsubscribing all four stops MT5 frames; it does not bring back the unfiltered stream.
371
+ - A socket that never names one of them gets every MT5 frame from every terminal on the account, whatever else it subscribed to.
372
+ - Which symbols a terminal streams at all is set with `atlas.subscriptions`.
373
+ - `orders` is retired: a subscribe naming it gets it back in `refusedChannels` (`"orders (retired: use trading.orders)"`). Follow MT5 orders on `trading.orders`, or as raw `trade_event` frames on `trades`.
374
+
375
+ An inactive or suspended account is refused at connect (`connect()` rejects with an `AtlasAuthError` carrying the reason, such as `Account is suspended`). If that happens while the socket is open, it keeps streaming what it already subscribed to, but each new `subscribe` is answered with a `subscribe_failed` event (`{ reason }`) and changes nothing until the account is back in good standing. `unsubscribe` always works.
376
+
377
+ - A market channel only carries the keys you name: an empty `instrumentKeys` is nothing, not everything. NSE/BSE keys open a feed subscription; FX keys ride your terminal's own tick subscriptions (`atlas.subscriptions`).
378
+ - An account streams up to 500 instruments across all its sockets. A key over the limit, or one the feed or your access cannot serve, is left out and named in the `subscribed` reply's `refusedInstrumentKeys` with a reason: `account_quota`, `capacity`, `unsupported`, `india_entitlement` or `no_account`. A key read cold through `v2.market.quote` counts toward the limit for 10 minutes.
379
+ - Channels the key's scope cannot read come back in `refusedChannels`, and account or connection ids it does not own in `refusedAccountIds`, `refusedBrokerConnectionIds` and `refusedBrokerOrderConnectionIds`.
380
+ - `trading.orders` is at-least-once; Atlaas dedupes on `(orderId, status, filledQuantity, price)` and stamps a per-connection `sequence` so you can spot gaps.
381
+ - `subscribe` adds to what the socket holds, and a reconnect re-sends all of it. Listen for `subscribed` (and `subscribe_failed`) to see what the server accepted.
382
+
383
+ | Option | Default | Description |
384
+ | --- | --- | --- |
385
+ | `baseUrl` | — | Atlaas API base URL |
386
+ | `apiKey` | — | Service key (`atsk_*`) with `feed:r` or `orders:r` |
387
+ | `clientName` | — | Optional name for this client |
388
+ | `autoReconnect` | `true` | Reconnect after a drop |
389
+ | `reconnectDelayMs` | `2000` | Base reconnect delay |
390
+ | `maxReconnectAttempts` | `10` | Give up after this many |
391
+
392
+ # MT5 platform (v1)
393
+
394
+ Terminals, broker connections, Expert Advisors, backtests and service keys.
395
+
396
+ ## MT5 terminals (`atlas.mt5`)
397
+
398
+ Deploy, start, stop and remove MT5 terminals, named by MT5 login. Deploying charges the provisioning fee. [API reference](https://atlaas.dev/docs/v1/mt5-instance-lifecycle)
399
+
400
+ ```typescript
401
+ const servers = await atlas.mt5.servers() // [{ serverName, brokerName, displayName, serverType, defaultSymbol }]
402
+ const regions = await atlas.mt5.regions() // [{ id, code, displayName, description }], only regions with room
403
+
404
+ const terminal = await atlas.mt5.create({
405
+ accountId: "51234567",
406
+ password: process.env.MT5_PASSWORD ?? "",
407
+ serverName: servers[0].serverName,
408
+ regionId: regions[0]?.id, // optional
409
+ type: "TICKS_TRADE",
410
+ name: "Gold scalper",
411
+ externalRef: "user-42-gold" // optional, your own id
412
+ })
413
+
414
+ await atlas.mt5.list() // Instance[], newest first
415
+ await atlas.mt5.get(terminal.accountId) // state: PENDING → DEPLOYING → RUNNING
416
+ await atlas.mt5.stop(terminal.accountId)
417
+ await atlas.mt5.start(terminal.accountId)
418
+ await atlas.mt5.delete(terminal.accountId) // no refund
419
+ ```
420
+
421
+ | Method | Returns |
422
+ | --- | --- |
423
+ | `list()` | `Instance[]` |
424
+ | `create(body: CreateInstanceBody)` | `Instance` |
425
+ | `get(accountId: string)` | `Instance` |
426
+ | `delete(accountId: string)` | `void` |
427
+ | `start(accountId: string)` | `Instance` |
428
+ | `stop(accountId: string)` | `Instance` |
429
+ | `servers()` | `DeployServer[]` |
430
+ | `regions()` | `DeployRegion[]` |
431
+
432
+ ## Instances and broker connections (`atlas.instances`)
433
+
434
+ Every instance on the account, MT5 or broker, keyed by your own `externalRef` (`/api/atlas/instances`). [API reference](https://atlaas.dev/docs/v1/instances-by-id-apiatlas), [identifiers](https://atlaas.dev/docs/v1/identifiers-read-this-first)
435
+
436
+ ```typescript
437
+ // Validate broker credentials before storing them (Dhan logs in and returns the minted token)
438
+ const check = await atlas.instances.validateBrokerCredentials({
439
+ brokerName: "dhan",
440
+ credentials: { clientId: "1100000000", pin: "1234", totpSecret: process.env.DHAN_TOTP ?? "" }
441
+ })
442
+ if (!check.valid) throw new Error(check.error)
443
+
444
+ // Create a broker connection. Brokers need no runnerId: Atlaas places it on a server of its own.
445
+ const created = await atlas.instances.create({
446
+ instanceKind: "dhan",
447
+ externalRef: "my-conn-001",
448
+ credentials: check.credentials
449
+ })
450
+ console.log(created.runnerReady, created.ipAddress) // whitelist ipAddress with the broker
451
+
452
+ const instance = await atlas.instances.get(created.id)
453
+ await atlas.instances.getByExternalRef("my-conn-001")
454
+ await atlas.instances.getByExternalRefs(["my-conn-001", "my-conn-002"])
455
+ await atlas.instances.list({ instanceKind: "dhan", state: "RUNNING", limit: 100 })
456
+ await atlas.instances.update(instance.id, { name: "Dhan main", credentialsPatch: { pin: "4321" } }) // { id }
457
+ await atlas.instances.disable(instance.id) // stops it on its runner; credentials stay stored
458
+ await atlas.instances.enable(instance.id) // redeploys it
459
+ await atlas.instances.delete(instance.id)
460
+ ```
461
+
462
+ `create` with an `externalRef` you already used updates that instance instead. An MT5 instance here needs a `runnerId`; `atlas.mt5.create` picks one for you.
463
+
464
+ | Method | Returns |
465
+ | --- | --- |
466
+ | `list(query?: ListInstancesQuery)` | `AtlasInstance[]` |
467
+ | `get(id: string)` | `AtlasInstance` |
468
+ | `getByExternalRef(ref: string)` | `AtlasInstance` |
469
+ | `getByExternalRefs(refs: string[])` | `AtlasInstance[]` |
470
+ | `create(body: CreateAtlasInstanceBody)` | `CreateAtlasInstanceResult` |
471
+ | `update(id: string, body: UpdateAtlasInstanceBody)` | `{ id: string }` |
472
+ | `disable(id: string)` | `AtlasInstance \| null` |
473
+ | `enable(id: string)` | `AtlasInstance \| null` |
474
+ | `delete(id: string)` | `void` |
475
+ | `validateBrokerCredentials(body: ValidateBrokerCredentialsBody)` | `ValidateBrokerCredentialsResult` |
476
+
477
+ ## Expert Advisors (`atlas.eas`)
478
+
479
+ Your EAs, their versions and presets, and their deployments on terminals. [API reference](https://atlaas.dev/docs/v1/eas-deployments-api), [writing an EA for Atlaas](https://atlaas.dev/docs/v1/expert-advisors)
480
+
481
+ ```typescript
298
482
  import { createHash } from "node:crypto"
299
483
  import { readFile } from "node:fs/promises"
300
484
  import { AtlasError, type EaCompileFailure } from "atlaas"
@@ -389,7 +573,7 @@ A version saved from `.mq5` source carries an `inputManifest` (its parsed inputs
389
573
 
390
574
  ## Backtests (`atlas.backtests`)
391
575
 
392
- MT5 strategy tester runs on Atlaas hardware, against your terminal's broker history. A backtest is a group of runs: a single test, an optimization, or a walk-forward. Creating one holds credits; `estimate` says how many first. [API reference](https://atlaas.dev/docs/v1/backtests)
576
+ MT5 strategy tester runs on Atlaas hardware, against your terminal's broker history. A backtest is a group of runs: a single test, an optimization, or a walk-forward. Creating one uses your plan's monthly backtest allowance; `estimate` says how much first. [API reference](https://atlaas.dev/docs/v1/backtests)
393
577
 
394
578
  ```typescript
395
579
  const base = {
@@ -402,7 +586,7 @@ const base = {
402
586
  }
403
587
 
404
588
  const estimate = await atlas.backtests.estimate({ fromDate: base.fromDate, toDate: base.toDate, tickMode: "EVERY_TICK" })
405
- console.log(estimate.credits, estimate.estimatedFinishAt)
589
+ console.log(estimate.cost.amount, estimate.cost.currency, estimate.estimatedFinishAt)
406
590
 
407
591
  // One run, with the last two months locked as out-of-sample until you reveal them
408
592
  const { group, runs } = await atlas.backtests.create({ ...base, name: "Breakout 2025", tickMode: "EVERY_TICK", oos: { splitDate: "2025-11-01" } })
@@ -485,331 +669,191 @@ None of these writes is de-duplicated by the server, so the SDK sends each once.
485
669
  | `swapArbitrage()` | `SwapArbitrageReport` |
486
670
  | `spreadCalibration(instanceId, symbol)` | `SpreadCalibration` |
487
671
 
488
- ## Broker connections, raw (`atlas.broker()`)
672
+ ## MT5 tick and candle subscriptions (`atlas.subscriptions`)
489
673
 
490
- A broker's own API through Atlaas (`/api/external/brokers/:broker/connections/:id`), in the broker's own field names. `connectionId` is the connection's `externalRef`. Brokers: `dhan`, `kite`, `motilal`, `angelone`, `fyers`, `upstox`, `shoonya`, `bybit`, `deribit`, `kraken`, `hyperliquid`, `coindcx`, `delta`, `alpaca`, `tastytrade`, `lime`. Prefer the [unified API](#connections-atlasv2connections) unless you need a broker-specific field. [API reference](https://atlaas.dev/docs/v1/broker-connections-raw-routes)
674
+ Which symbols a terminal streams to the WebSocket, by Atlaas instance id. [API reference](https://atlaas.dev/docs/v1/mt5-real-time-subscriptions-websocket)
491
675
 
492
676
  ```typescript
493
- const dhan = atlas.broker("dhan", "my-conn-001")
494
-
495
- const placed = await dhan.placeOrder({ securityId: "11536", exchangeSegment: "NSE_EQ", transactionType: "BUY", quantity: 1, orderType: "MARKET", productType: "INTRADAY" })
496
- await dhan.getOrders()
497
- await dhan.getOrder("1124091136546")
498
- await dhan.modifyOrder("1124091136546", { orderType: "LIMIT", price: 2450, quantity: 1, validity: "DAY" })
499
- await dhan.cancelOrder("1124091136546")
500
- await dhan.getTrades()
501
- await dhan.getPositions()
502
- await dhan.getHoldings()
503
- await dhan.getCandles({ securityId: "1333", exchangeSegment: "NSE_EQ", interval: "5", n: 100 }) // Dhan and Kite only
504
- console.log(placed)
677
+ const instanceId = "6f1c2a9e-0000-4000-8000-000000000000"
505
678
 
506
- // Option chain through your own Dhan connection (Dhan only)
507
- const expiries = await dhan.getOptionExpiries({ underlyingSecurityId: "13", underlyingSegment: "IDX_I" })
508
- const chain = await dhan.getOptionChain({ underlyingSymbol: "NIFTY" }, expiries[0])
509
- console.log(chain.spot, chain.strikes.length)
679
+ await atlas.subscriptions.subscribeTick(instanceId, { symbol: "EURUSD" })
680
+ await atlas.subscriptions.getTickSubscriptions(instanceId) // { instanceId, accountId, symbols, count }
681
+ await atlas.subscriptions.unsubscribeTick(instanceId, { symbol: "EURUSD" }) // omit the body for every symbol
510
682
 
511
- // Tick subscriptions for the broker_ticks channel (Dhan and Kite only)
512
- await dhan.subscriptions.subscribe({ refs: [{ securityId: "1333", exchangeSegment: "NSE_EQ" }], mode: "quote" })
513
- await dhan.subscriptions.list()
514
- await dhan.subscriptions.unsubscribe({ refs: [{ securityId: "1333", exchangeSegment: "NSE_EQ" }] })
683
+ await atlas.subscriptions.subscribeCandle(instanceId, { symbol: "EURUSD", timeframe: "M1" })
684
+ await atlas.subscriptions.getCandleSubscriptions(instanceId) // { instanceId, accountId, subscriptions, count }
685
+ await atlas.subscriptions.unsubscribeCandle(instanceId, { symbol: "EURUSD", timeframe: "M1" })
515
686
  ```
516
687
 
517
- Motilal Oswal takes MOFSL fields and sizes in **lots**, not shares. It has no market data, so `getCandles` and `subscriptions` do not apply; Atlaas logs it in again each morning.
688
+ ## Service keys (`atlas.serviceKeys`)
689
+
690
+ [API reference](https://atlaas.dev/docs/v1/service-keys), [scopes](https://atlaas.dev/docs/v1/service-key-scopes)
518
691
 
519
692
  ```typescript
520
- const mo = atlas.broker("motilal", "my-mofsl-001")
521
- await mo.placeOrder({
522
- exchange: "NSE",
523
- symboltoken: 1660,
524
- buyorsell: "BUY",
525
- ordertype: "LIMIT",
526
- producttype: "NORMAL",
527
- orderduration: "DAY",
528
- price: 235.5,
529
- triggerprice: 0,
530
- quantityinlot: 1
531
- })
693
+ const accountId = "acc_123"
694
+
695
+ await atlas.serviceKeys.list(accountId, { isActive: true })
696
+ const key = await atlas.serviceKeys.create(accountId, { keyName: "prod-bot", rateLimitPerMinute: 600, allowedIpAddresses: ["203.0.113.7"] })
697
+ console.log(key.rawKey) // shown once
698
+ await atlas.serviceKeys.update(key.id, { isActive: false })
699
+ await atlas.serviceKeys.regenerate(key.id) // a new rawKey
700
+ await atlas.serviceKeys.delete(key.id)
532
701
  ```
533
702
 
534
- | Method | Returns |
703
+ # Automation
704
+
705
+ ## Automation features
706
+
707
+ These are not wrapped by the SDK yet. [What works where](https://atlaas.dev/docs/coverage) shows which markets each one reaches.
708
+
709
+ | Feature | How to reach it |
535
710
  | --- | --- |
536
- | `placeOrder(order: BrokerOrder, options?: WriteOptions)` | broker's reply |
537
- | `getOrders()` / `getOrder(orderId)` | broker's reply |
538
- | `modifyOrder(orderId, changes: BrokerOrder, options?: WriteOptions)` | broker's reply |
539
- | `cancelOrder(orderId, body?: BrokerCancelOrderBody, options?: WriteOptions)` | broker's reply |
540
- | `getTrades()` / `getPositions()` / `getHoldings()` | broker's reply |
541
- | `getCandles(query: BrokerCandlesQuery)` | broker's reply |
542
- | `getOptionExpiries(underlying: DhanUnderlying)` | `string[]` |
543
- | `getOptionChain(underlying: DhanUnderlying, expiry: string)` | `DhanOptionChain` |
544
- | `subscriptions.subscribe(body)` / `.unsubscribe(body)` / `.list()` | broker's reply |
711
+ | Strategy webhooks | `POST /hooks/{slug}` with the strategy's own secret, no service key: any HTTP client or a TradingView alert. [Reference](https://atlaas.dev/docs/v1/strategy-webhooks) |
712
+ | Live strategy deploys | `/api/external/live-deployments` with a service key, or the MCP tools |
713
+ | Outbound webhooks | Managed on the portal's **Webhooks** page. [Events and signatures](https://atlaas.dev/docs/v1/webhooks) |
714
+ | Notifications | Managed in the portal under **Settings, Notifications**. [Reference](https://atlaas.dev/docs/v1/alerts-notifications) |
715
+ | Copy trading | Managed in the portal under **Copy trading**. [Reference](https://atlaas.dev/docs/v1/copy-trading) |
545
716
 
546
- ## Unified API (`atlas.v2`)
717
+ # Deprecated v1 wrappers
547
718
 
548
- One shape for every broker: canonical instruments, account-scoped reads and writes on any connection, and market data that needs no connection.
719
+ These still work exactly as before. Each method is marked `@deprecated` in the types, naming its `atlas.v2` replacement, so your editor shows the way across.
549
720
 
550
- ### Instruments (`atlas.v2.instruments`)
721
+ ## MT5 trading (`atlas.trading`)
551
722
 
552
- Atlaas's canonical `instrumentKey` for each contract, with each broker's reference id attached. Global reference data: any key can read any instrument. [API reference](https://atlaas.dev/docs/v2/instruments)
723
+ Trading on one terminal, named by its MT5 login (`/api/external/instances/:accountId`).
553
724
 
554
- ```typescript
555
- const { instruments, nextCursor } = await atlas.v2.instruments.list({
556
- exchange: "NSE", // NSE | BSE | MCX | FX | US | CRYPTO
557
- segment: "FNO", // EQ | FNO | IDX | CDS | COMM | FX | SPOT | PERP
558
- symbol: "NIFTY", // exact symbol
559
- q: "RELI", // substring of instrumentKey (not the name)
560
- active: true, // default true; false lists inactive rows only
561
- limit: 100 // default 100, max 500
562
- })
563
- const next = nextCursor ? await atlas.v2.instruments.list({ exchange: "NSE", cursor: nextCursor }) : null
725
+ | Deprecated | Use instead |
726
+ | --- | --- |
727
+ | `placeOrder`, `getOrders`, `cancelOrder` | `atlas.v2.connections(id).placeOrder()`, `.orders()`, `.cancelOrder()` |
728
+ | `getPositions`, `modifyPosition`, `closePosition`, `closeBySymbol` | `atlas.v2.connections(id).positions()`, `.modifyPosition()`, `.closePosition()` |
729
+ | `getAccountInfo` | `atlas.v2.connections(id).funds()` |
730
+ | `getSymbols`, `getSymbolSpecs` | `atlas.v2.connections(id).symbols()` |
731
+ | `getPrice`, `getCandles` | `atlas.v2.market.quote()`, `.candles()` |
564
732
 
565
- const reliance = await atlas.v2.instruments.get("NSE:EQ:RELIANCE")
566
- const fromDhan = await atlas.v2.instruments.resolve({ broker: "dhan", refId: "2885", segment: "NSE_EQ" })
567
- console.log(instruments.length, next?.instruments.length, reliance.brokerRefs.motilal?.symboltoken, fromDhan.instrumentKey)
568
- ```
733
+ `getPosition`, `getClosedPositions` and `calculateMargin` have no v2 equivalent yet and are not deprecated. [Account](https://atlaas.dev/docs/v1/mt5-account), [positions](https://atlaas.dev/docs/v1/mt5-positions), [orders](https://atlaas.dev/docs/v1/mt5-orders), [market data](https://atlaas.dev/docs/v1/mt5-market-data).
569
734
 
570
- Key format: `EXCHANGE:SEGMENT:SYMBOL`, with expiry, strike and right for derivatives:
735
+ ```typescript
736
+ const login = "51234567"
571
737
 
572
- ```
573
- NSE:EQ:RELIANCE equity
574
- NSE:IDX:NIFTY index
575
- NSE:FNO:NIFTY:2026-08-27:FUT future
576
- NSE:FNO:NIFTY:2026-08-27:24000:CE option
577
- NSE:FNO:USDINR:2026-08-27:84.25:PE fractional strike
578
- FX:XAUUSD forex
579
- ```
580
-
581
- Expiries are `YYYY-MM-DD`; symbols never contain `:`. Paging is keyset on `instrumentKey`: pass `nextCursor` back as `cursor` until it is `null`. Kite refs are derived from the Dhan and Motilal rows, not synced from a Kite master. `FX:*` rows come from an MT5 terminal's symbol import.
582
-
583
- ### Connections (`atlas.v2.connections()`)
584
-
585
- Orders, trades, positions, holdings, funds and profile of any connection (Dhan, Kite, Motilal, Angel One, Fyers, Upstox, Shoonya, the crypto and US brokers, MT5) in one shape, and one order shape to write with. Account-scoped: a key only sees its own connections. The id is the Atlaas instance id or its `externalRef`. [API reference](https://atlaas.dev/docs/v2/connections), [what each broker can do](https://atlaas.dev/docs/v2/broker-capabilities)
586
-
587
- ```typescript
588
- const conn = atlas.v2.connections("my-conn-001")
738
+ // Orders
739
+ const order = await atlas.trading.placeOrder(login, { symbol: "EURUSD", type: "BUY_LIMIT", volume: 0.1, price: 1.08, sl: 1.07, tp: 1.1 })
740
+ await atlas.trading.getOrders(login)
741
+ await atlas.trading.cancelOrder(login, order.ticket)
589
742
 
590
- const { broker, capabilities } = await conn.capabilities()
591
- const { orders, dropped } = await conn.orders()
592
- const order = await conn.order(orders[0].orderId, { includeRaw: true }) // raw: the broker's own payload
593
- const { positions, scope } = await conn.positions({ scope: "DAY" }) // NET by default
594
- const { trades } = await conn.trades({ includeRaw: true })
595
- const { holdings } = await conn.holdings()
596
- const funds = await conn.funds()
597
- const profile = await conn.profile()
598
- console.log(broker, capabilities.fractionalQuantity, dropped.length, order.status, positions.length, scope, trades.length, holdings.length, funds.availableBalance, profile.clientId)
743
+ // Positions
744
+ const open = await atlas.trading.getPositions(login) // what the EA last pushed
745
+ const one = await atlas.trading.getPosition(login, open[0].ticket) // open, or closed from history
746
+ if (one.status === "CLOSED") console.log(one.closePrice, one.closeTime)
747
+ await atlas.trading.modifyPosition(login, open[0].ticket, { sl: 1.07, tp: 1.12 })
748
+ await atlas.trading.closePosition(login, open[0].ticket, { volume: 0.05 }) // partial; omit the body to close it all
749
+ await atlas.trading.closeBySymbol(login, { symbol: "EURUSD" }) // { symbol, closedCount, totalProfit, positions }
599
750
 
600
- // Everything in one call; each section is ok or an error of its own
601
- const snap = await conn.snapshot()
602
- if (snap.sections.funds.ok) console.log(snap.sections.funds.funds.availableBalance)
751
+ // Closed positions from the terminal's deal history, paged by close time
752
+ let since = 0
753
+ for (;;) {
754
+ const page = await atlas.trading.getClosedPositions(login, { since, limit: 200 })
755
+ for (const p of page.positions) console.log(p.ticket, p.profit)
756
+ if (!page.hasMore || page.positions.length === 0) break
757
+ since = page.positions[page.positions.length - 1].closeTimeMs
758
+ }
603
759
 
604
- // MT5 only: the symbols this terminal lists, with their contract specs
605
- const { symbols } = await atlas.v2.connections("my-mt5-001").symbols({ symbol: "XAUUSD" })
606
- console.log(symbols[0]?.contractSize)
760
+ // Market data and account
761
+ await atlas.trading.getPrice(login, "EURUSD") // { symbol, bid, ask, last?, volume?, timestamp? }
762
+ await atlas.trading.getSymbols(login)
763
+ await atlas.trading.getSymbolSpecs(login) // every symbol's contract spec, raw from the terminal
764
+ await atlas.trading.getAccountInfo(login)
765
+ await atlas.trading.getCandles(login, { symbol: "EURUSD", timeframe: "H1", startTime: "2026-01-01T00:00:00Z", endTime: "2026-01-02T00:00:00Z" })
766
+ await atlas.trading.calculateMargin(login, { symbol: "EURUSD", type: "ORDER_TYPE_BUY", volume: 0.1, openPrice: 1.08 })
607
767
  ```
608
768
 
609
- Every read takes `includeRaw` to add the broker's untranslated row as `raw`. Every list carries `dropped`: rows Atlaas could not map to an instrument (`INSTRUMENT_UNRESOLVED`) or to the unified shape (`UNMAPPABLE`), reported rather than left out. MT5 and Motilal are net-only, so `positions` answers `scope: "NET"` whatever you ask, and `snapshot` positions are always `NET`. A dropped MT5 position or order also carries `mt5: { ticket, symbol, lots?, side? }` as the terminal reported it, so read `dropped` with `positions`: an empty `positions` with a non-empty `dropped` is not a flat account, and the ticket can still be closed by `positionId`.
610
-
611
- #### Writes
612
-
613
- Size an order in `quantity` (units; Atlaas converts to lots or MT5 volume and refuses a quantity it cannot convert exactly) or, on MT5 and Motilal, in `lots` (sent as is). Exactly one of the two. Every write is checked against `capabilities` first and refused with `UNSUPPORTED_CAPABILITY` when the broker cannot do it. [API reference](https://atlaas.dev/docs/v2/placing-and-managing-orders)
769
+ Reads that come from the terminal can tell you how fresh they are. Pass `{ withFreshness: true }` to `getOrders`, `getPositions`, `getPosition`, `getPrice`, `getSymbols`, `getSymbolSpecs` or `getAccountInfo`:
614
770
 
615
771
  ```typescript
616
- const conn = atlas.v2.connections("my-conn-001")
617
-
618
- const placed = await conn.place({
619
- instrumentKey: "NSE:FNO:NIFTY:2026-09-24:24000:CE",
620
- side: "BUY",
621
- orderType: "LIMIT",
622
- quantity: 150, // units: 2 lots of 75
623
- price: 120.5,
624
- product: "INTRADAY",
625
- clientTag: "sig-42"
626
- })
627
- await conn.modify(placed.orderId, { price: 121, quantity: 150 })
628
- await conn.cancel(placed.orderId)
629
-
630
- // MT5 in lots, with the position's SL/TP on the order
631
- const mt5 = atlas.v2.connections("my-mt5-001")
632
- const fx = await mt5.place({ instrumentKey: "FX:EURUSD", side: "BUY", orderType: "MARKET", lots: 0.05, stopLoss: 1.08, takeProfit: 1.12 })
633
- const gold = await mt5.place({ instrumentKey: "FX:XAUUSD", side: "BUY", orderType: "MARKET", lots: 0.1, symbol: "XAUUSD.r" }) // pin the terminal's spelling
634
- console.log(gold.symbol) // "XAUUSD.r"
635
- await mt5.modifyPosition(fx.orderId, { takeProfit: 1.13 }) // SL untouched; 0 clears a level
636
-
637
- // Close: flatten, or part of one MT5 ticket
638
- await conn.closePosition({ instrumentKey: "NSE:EQ:RELIANCE" })
639
- await mt5.closePosition({ instrumentKey: "FX:EURUSD", positionId: fx.orderId, lots: 0.02 })
772
+ const { data, dataAsOf, lastHeartbeatAt } = await atlas.trading.getPositions("51234567", { withFreshness: true })
773
+ const ageMs = Date.now() - Date.parse(dataAsOf)
774
+ if (ageMs > 10_000) console.warn(`positions are ${ageMs} ms old; last EA heartbeat ${lastHeartbeatAt}`)
775
+ console.log(data.length)
640
776
  ```
641
777
 
642
- Per broker:
643
-
644
- - **Motilal**: `orderType: "MARKET"` is synthetic. Atlaas places a marketable LIMIT priced off its feed and chases it (`chase: { maxDriftPct, maxReprices, timeoutMs }`, defaults 1 / 3 / 60000); results and the order book carry a `synthetic` block, and an exhausted chase is cancelled with `CHASE_EXHAUSTED`. A feed that is down answers `FEED_UNAVAILABLE`. `modify` without `quantity` keeps the resting quantity.
645
- - **Kite**: a 2xx with no `order_id` is reported as `BROKER_REJECTED`.
646
- - **Dhan / Kite**: `lots` is refused. `quantity` on `closePosition` closes that many units, capped at what is open.
647
- - **MT5**: no `STOP_LIMIT`; `modify` takes only `price` / `triggerPrice`; a partial close needs one ticket (`positionId`). The terminal's own symbol list decides which spelling an order goes to; when it lists several (`XAUUSD.r`, `XAUUSD.cent`), pin one with `symbol` on `place`, and the result's `symbol` says what was sent. `quantity` converts with that symbol's own contract size and may be fractional on the 0.001-lot grid (`fractionalQuantity` is true); while the terminal's contract size is unknown, a `quantity` place or partial close is refused with `VALIDATION`, so send `lots`. Positions report `mt5.volume` in lots, so prefer `lots` if you keep your books in lots. Rows need the FX instrument import, or they come back in `dropped`. How Atlaas picks the terminal's own spelling of a symbol: [MT5 symbols](https://atlaas.dev/docs/v2/mt5-symbols-the-terminal-decides).
648
- - **Crypto and fractional shares**: a non-integer `quantity` is accepted where `capabilities.fractionalQuantity` is true. Perpetual positions carry `margin` and `funding`.
649
-
650
- `OUTCOME_UNKNOWN` (504) means the order reached the broker and no answer came back: read the order book before you send it again.
778
+ A terminal Atlaas cannot see answers 503 `TERMINAL_UNAVAILABLE`, never an empty list.
651
779
 
652
780
  | Method | Returns |
653
781
  | --- | --- |
654
- | `orders(params?: IncludeRawParams)` | `OrdersListResult` |
655
- | `order(orderId, params?: IncludeRawParams)` | `UnifiedOrder` |
656
- | `trades(params?: IncludeRawParams)` | `TradesListResult` |
657
- | `positions(params?: PositionsListParams)` | `PositionsListResult` |
658
- | `holdings(params?: IncludeRawParams)` | `HoldingsListResult` |
659
- | `funds(params?: IncludeRawParams)` | `UnifiedFunds` |
660
- | `profile(params?: IncludeRawParams)` | `UnifiedProfile` |
661
- | `symbols(params?: { symbol?: string })` | `SymbolSpecsResult` |
662
- | `capabilities()` | `CapabilitiesResult` |
663
- | `snapshot(params?: IncludeRawParams)` | `V2Snapshot` |
664
- | `place(body: PlaceOrderV2Body, options?: V2WriteOptions)` | `PlaceOrderResult` |
665
- | `modify(orderId, body: ModifyOrderV2Body, options?: V2WriteOptions)` | `ModifyOrderResult` |
666
- | `cancel(orderId, options?: V2WriteOptions)` | `CancelOrderResult` |
667
- | `closePosition(body: ClosePositionV2Body, options?: V2WriteOptions)` | `ClosePositionResult` |
668
- | `modifyPosition(positionId, body: ModifyPositionV2Body, options?: V2WriteOptions)` | `ModifyPositionResult` |
782
+ | `placeOrder(accountId, body: PlaceOrderBody, options?: WriteOptions)` | `Order` |
783
+ | `getOrders(accountId, options?: FreshnessOption)` | `Order[]` |
784
+ | `cancelOrder(accountId, ticket: number, options?: WriteOptions)` | `void` |
785
+ | `getPositions(accountId, options?: FreshnessOption)` | `Position[]` |
786
+ | `getPosition(accountId, ticket: number, options?: FreshnessOption)` | `PositionDetail` |
787
+ | `getClosedPositions(accountId, query: ClosedPositionsQuery)` | `ClosedPositionsResult` |
788
+ | `modifyPosition(accountId, ticket: number, body: ModifyPositionBody, options?: WriteOptions)` | `ModifyMt5PositionResult` |
789
+ | `closePosition(accountId, ticket: number, body?: ClosePositionBody, options?: WriteOptions)` | `CloseMt5PositionResult` |
790
+ | `closeBySymbol(accountId, body: CloseBySymbolBody, options?: WriteOptions)` | `CloseBySymbolResult` |
791
+ | `getPrice(accountId, symbol: string, options?: FreshnessOption)` | `Price` |
792
+ | `getSymbols(accountId, options?: FreshnessOption)` | `string[]` |
793
+ | `getSymbolSpecs(accountId, options?: FreshnessOption)` | `Mt5SymbolSpec[]` |
794
+ | `getAccountInfo(accountId, options?: FreshnessOption)` | `AccountInfo` |
795
+ | `getCandles(accountId, query: GetCandlesQuery)` | `Candle[]` |
796
+ | `calculateMargin(accountId, body: CalculateMarginBody)` | `MarginResult` |
669
797
 
670
- `V2WriteOptions` is `{ idempotencyKey?, signal?, includeRaw? }`.
798
+ With `{ withFreshness: true }` each read returns `Fresh<T>` (`{ data, dataAsOf, lastHeartbeatAt }`) instead.
671
799
 
672
- ### Market data (`atlas.v2.market`)
800
+ ## Broker connections, raw (`atlas.broker()`)
673
801
 
674
- Quotes, candles and option chains by `instrumentKey`, with no connection. NSE/BSE keys come from the Atlaas market data feed (they need the account's India access); FX keys from an MT5 terminal you own. A feed that is down answers `FEED_UNAVAILABLE` (503, retryable) and an MT5 server with no clock offset set answers `TIMEZONE_UNCONFIGURED` (409). [API reference](https://atlaas.dev/docs/v2/market-data)
802
+ A broker's own API through Atlaas (`/api/external/brokers/:broker/connections/:id`), in the broker's own field names. `connectionId` is the connection's `externalRef`. Brokers: `dhan`, `kite`, `motilal`, `angelone`, `fyers`, `upstox`, `shoonya`, `bybit`, `deribit`, `kraken`, `hyperliquid`, `coindcx`, `delta`, `alpaca`, `tastytrade`, `lime`. Every method is deprecated in favour of [`atlas.v2.connections()`](#connections-atlasv2connections), which takes the same `connectionId`, and [`atlas.v2.market`](#market-data-atlasv2market) for candles and option chains. Use these only for a broker-specific field. [API reference](https://atlaas.dev/docs/v1/broker-connections-raw-routes)
675
803
 
676
804
  ```typescript
677
- const tick = await atlas.v2.market.quote("NSE:EQ:RELIANCE") // { instrumentKey, ts, mode, ltp, bid?, ask?, ... }
678
- const { ticks, unresolved } = await atlas.v2.market.quotes(["NSE:EQ:RELIANCE", "NSE:EQ:TCS"]) // up to 200 keys
679
- console.log(tick.ltp, ticks.length, unresolved)
680
-
681
- const { candles } = await atlas.v2.market.candles({
682
- instrumentKey: "NSE:EQ:RELIANCE",
683
- interval: "5m",
684
- from: "2026-09-07T03:45:00Z",
685
- to: new Date("2026-09-07T10:00:00Z")
686
- })
687
- const gold = await atlas.v2.market.candles({ instrumentKey: "FX:XAUUSD", interval: "4h", from: "2026-09-01T00:00:00Z", to: "2026-09-07T00:00:00Z", connectionId: "my-mt5-001" })
688
- console.log(candles.length, gold.source)
689
-
690
- const { expiries } = await atlas.v2.market.expiries("NSE:IDX:NIFTY")
691
- const chain = await atlas.v2.market.optionChain("NSE:IDX:NIFTY", expiries[0])
692
- const atm = chain.strikes.reduce((a, b) => (Math.abs(b.strike - chain.underlyingLtp) < Math.abs(a.strike - chain.underlyingLtp) ? b : a))
693
- if (atm.ce) await atlas.v2.connections("my-conn-001").place({ instrumentKey: atm.ce.instrumentKey, side: "BUY", orderType: "MARKET", quantity: 75 })
694
- ```
695
-
696
- - `quote()` on a key nobody is streaming yet subscribes it and reads the price once from the vendor, so it answers an LTP snapshot (`mode: "LTP"`) straight away. An FX key with no tick yet answers a retryable 404 while its subscription opens.
697
- - `quotes()` never comes back short: a key it cannot price is listed in `unresolved` with the reason.
698
- - Candle intervals: NSE/BSE `1m`, `5m`, `15m`, `1h`, `1d`; FX (MT5) all eight (`1m`, `3m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`). Closed bars are cached, so asking again for a window Atlaas has seen costs no vendor call. FX candles take an optional `connectionId`.
699
- - Option chains are metered at about one call per 3 s per chain; identical calls inside that window share one answer, and a vendor refusal is `RATE_LIMITED` (retryable).
700
-
701
- | Method | Returns |
702
- | --- | --- |
703
- | `quote(instrumentKey)` | `UnifiedTick` |
704
- | `quotes(instrumentKeys: string[])` | `MarketQuotesResult` |
705
- | `candles(params: MarketCandlesParams)` | `MarketCandlesResult` |
706
- | `expiries(underlyingKey)` | `UnifiedOptionExpiries` |
707
- | `optionChain(underlyingKey, expiry)` | `UnifiedOptionChain` |
708
-
709
- ### Scanner (`atlas.v2.scanner`)
710
-
711
- The NSE intraday strength scanner: every ranked stock, the picks on each side, breadth and sectors, recomputed each minute of the session. Needs the account's India access. [API reference](https://atlaas.dev/docs/v2/scanner)
805
+ const dhan = atlas.broker("dhan", "my-conn-001")
712
806
 
713
- ```typescript
714
- const board = await atlas.v2.scanner.board({ paths: true }) // paths: each stock's move per session minute
715
- console.log(board.session.state, board.picks.bullish, board.rows[0]?.strength)
807
+ const placed = await dhan.placeOrder({ securityId: "11536", exchangeSegment: "NSE_EQ", transactionType: "BUY", quantity: 1, orderType: "MARKET", productType: "INTRADAY" })
808
+ await dhan.getOrders()
809
+ await dhan.getOrder("1124091136546")
810
+ await dhan.modifyOrder("1124091136546", { orderType: "LIMIT", price: 2450, quantity: 1, validity: "DAY" })
811
+ await dhan.cancelOrder("1124091136546")
812
+ await dhan.getTrades()
813
+ await dhan.getPositions()
814
+ await dhan.getHoldings()
815
+ await dhan.getCandles({ securityId: "1333", exchangeSegment: "NSE_EQ", interval: "5", n: 100 }) // Dhan and Kite only
816
+ console.log(placed)
716
817
 
717
- // Later, only the minutes you do not have yet
718
- const update = await atlas.v2.scanner.board({ paths: true, after: board.session.minute })
818
+ // Option chain through your own Dhan connection (Dhan only)
819
+ const expiries = await dhan.getOptionExpiries({ underlyingSecurityId: "13", underlyingSegment: "IDX_I" })
820
+ const chain = await dhan.getOptionChain({ underlyingSymbol: "NIFTY" }, expiries[0])
821
+ console.log(chain.spot, chain.strikes.length)
719
822
 
720
- // Zones, stops and targets for one ranked stock, on its last two sessions of 5m bars
721
- const zones = await atlas.v2.scanner.zones(board.picks.bullish[0])
722
- console.log(update.pathsFrom, zones.rr, zones.stops[0]?.price)
823
+ // Tick subscriptions for the broker_ticks channel (Dhan and Kite only)
824
+ await dhan.subscriptions.subscribe({ refs: [{ securityId: "1333", exchangeSegment: "NSE_EQ" }], mode: "quote" })
825
+ await dhan.subscriptions.list()
826
+ await dhan.subscriptions.unsubscribe({ refs: [{ securityId: "1333", exchangeSegment: "NSE_EQ" }] })
723
827
  ```
724
828
 
725
- | Method | Returns |
726
- | --- | --- |
727
- | `board(params?: ScannerBoardParams)` | `ScannerBoard` |
728
- | `zones(instrumentKey)` | `ScannerZones` |
729
-
730
- ## WebSocket stream (`AtlasWebSocket`)
731
-
732
- Live data on `/ws/service`. [Unified channels](https://atlaas.dev/docs/v2/websocket-channels), [MT5 channels](https://atlaas.dev/docs/v1/mt5-real-time-subscriptions-websocket)
829
+ Motilal Oswal takes MOFSL fields and sizes in **lots**, not shares. It has no market data, so `getCandles` and `subscriptions` do not apply; Atlaas logs it in again each morning.
733
830
 
734
831
  ```typescript
735
- import { AtlasWebSocket } from "atlaas"
736
-
737
- const ws = new AtlasWebSocket({ baseUrl: "https://api.atlaas.dev", apiKey: process.env.ATLAAS_API_KEY ?? "", clientName: "my-bot" })
738
- await ws.connect() // rejects with AtlasAuthError, e.g. "Account has no credits remaining"
739
- ws.on("subscribe_failed", (f) => console.error("subscribe refused:", f.reason)) // nothing changed
740
-
741
- ws.subscribe({ channels: ["market.ticks", "market.candles", "trading.orders"], instrumentKeys: ["NSE:EQ:RELIANCE", "FX:EURUSD"] })
742
- ws.on("subscribed", (reply) => {
743
- for (const r of reply.refusedInstrumentKeys ?? []) console.warn(`${r.instrumentKey} not subscribed: ${r.reason}`)
744
- if (reply.refusedChannels) console.warn("refused:", reply.refusedChannels)
832
+ const mo = atlas.broker("motilal", "my-mofsl-001")
833
+ await mo.placeOrder({
834
+ exchange: "NSE",
835
+ symboltoken: 1660,
836
+ buyorsell: "BUY",
837
+ ordertype: "LIMIT",
838
+ producttype: "NORMAL",
839
+ orderduration: "DAY",
840
+ price: 235.5,
841
+ triggerprice: 0,
842
+ quantityinlot: 1
745
843
  })
746
-
747
- ws.on("market.tick", (t) => console.log(t.instrumentKey, t.ltp))
748
- ws.on("market.candle", (c) => c.isFinal && console.log(c.instrumentKey, c.interval, c.candle.c))
749
- ws.on("trading.order", (o) => console.log(o.connectionId, o.sequence, o.orderId, o.status))
750
-
751
- // MT5 frames: name the channels you want, narrowed to some terminals and symbols
752
- ws.subscribe({ channels: ["ticks", "candles", "positions", "trades"], accountIds: ["51234567"], symbols: ["EURUSD"] })
753
- ws.on("tick", (t) => console.log(t.accountId, t.symbol, t.bid, t.ask))
754
- ws.on("candle", (c) => console.log(c.symbol, c.timeframe, c.close))
755
- ws.on("position_update", (p) => console.log(p.accountId, p.equity, p.positions.length))
756
- ws.on("trade_event", (e) => console.log(e.transType, e.symbol, e.deal))
757
- ws.on("heartbeat", (h) => console.log(h.accountId, h.balance))
758
-
759
- // Option chains and the scanner board
760
- ws.subscribe({ channels: ["market.chain"], chains: [{ underlyingKey: "NSE:IDX:NIFTY", expiry: "2026-11-26" }] })
761
- ws.subscribe({ channels: ["market.scanner"] })
762
- ws.on("market.chain", (chain) => console.log(chain.underlyingKey, chain.strikes.length))
763
- ws.on("market.scanner", (board) => console.log(board.asOf, board.picks.bullish))
764
-
765
- // Drop one key, one chain, or whole channels
766
- ws.unsubscribe({ instrumentKeys: ["FX:EURUSD"] })
767
- ws.unsubscribe({ chains: [{ underlyingKey: "NSE:IDX:NIFTY", expiry: "2026-11-26" }] })
768
- ws.unsubscribe(["market.scanner"])
769
-
770
- ws.on("disconnected", (reason) => console.log("disconnected:", reason)) // reconnects and re-subscribes by itself
771
- ws.on("error", (err) => console.error(err))
772
- console.log(ws.isConnected)
773
- ws.disconnect()
774
844
  ```
775
845
 
776
- | Channel | Events | Filter | Scope |
777
- | --- | --- | --- | --- |
778
- | `market.ticks` | `market.tick` (`UnifiedTick`) | `instrumentKeys` | `feed:r` |
779
- | `market.candles` | `market.candle` (`{ instrumentKey, interval, isFinal, candle, source }`) | `instrumentKeys` | `feed:r` |
780
- | `market.chain` | `market.chain` (`UnifiedOptionChain`) | `chains` | `feed:r`, India |
781
- | `market.scanner` | `market.scanner` (the scanner board plus `append`) | none | `feed:r`, India |
782
- | `trading.orders` | `trading.order` (`UnifiedOrder` plus `eventTs`, `sequence`) | `brokerOrderConnectionIds` | `orders:r` |
783
- | `broker_ticks` | `broker_tick` (Dhan / Kite ticks, untranslated) | `brokerConnectionIds`, `brokerSecurityKeys` (empty: all yours) | `feed:r` |
784
- | `broker_orders` | `broker_order_update` (the broker's own order alert) | `brokerOrderConnectionIds` (empty: all yours) | `orders:r` |
785
- | `ticks` | `tick` | `accountIds`, `symbols` | `feed:r` |
786
- | `candles` | `candle` | `accountIds`, `symbols` | `feed:r` |
787
- | `positions` | `position_update` | `accountIds` | `orders:r` |
788
- | `trades` | `trade_event` | `accountIds` | `orders:r` |
789
-
790
- The MT5 channels (`ticks`, `candles`, `positions`, `trades`) work like this:
791
-
792
- - Once a subscribe has accepted one of them, the socket gets only the MT5 channels it named, narrowed by `accountIds` (MT5 logins; empty means every terminal you own), with `symbols` narrowing ticks and candles. The terminal `heartbeat` follows `accountIds` only. Unsubscribing all four stops MT5 frames; it does not bring back the unfiltered stream.
793
- - A socket that never names one of them gets every MT5 frame from every terminal on the account, whatever else it subscribed to.
794
- - Which symbols a terminal streams at all is set with `atlas.subscriptions`.
795
- - `orders` is retired: a subscribe naming it gets it back in `refusedChannels` (`"orders (retired: use trading.orders)"`). Follow MT5 orders on `trading.orders`, or as raw `trade_event` frames on `trades`.
796
-
797
- An inactive, suspended or out-of-credit account is refused at connect (`connect()` rejects with an `AtlasAuthError` carrying the reason, such as `Account has no credits remaining`). If that happens while the socket is open, it keeps streaming what it already subscribed to, but each new `subscribe` is answered with a `subscribe_failed` event (`{ reason }`) and changes nothing until the account is back in good standing. `unsubscribe` always works.
798
-
799
- - A market channel only carries the keys you name: an empty `instrumentKeys` is nothing, not everything. NSE/BSE keys open a feed subscription; FX keys ride your terminal's own tick subscriptions (`atlas.subscriptions`).
800
- - An account streams up to 500 instruments across all its sockets. A key over the limit, or one the feed or your access cannot serve, is left out and named in the `subscribed` reply's `refusedInstrumentKeys` with a reason: `account_quota`, `capacity`, `unsupported`, `india_entitlement` or `no_account`. A key read cold through `v2.market.quote` counts toward the limit for 10 minutes.
801
- - Channels the key's scope cannot read come back in `refusedChannels`, and account or connection ids it does not own in `refusedAccountIds`, `refusedBrokerConnectionIds` and `refusedBrokerOrderConnectionIds`.
802
- - `trading.orders` is at-least-once; Atlaas dedupes on `(orderId, status, filledQuantity, price)` and stamps a per-connection `sequence` so you can spot gaps.
803
- - `subscribe` adds to what the socket holds, and a reconnect re-sends all of it. Listen for `subscribed` (and `subscribe_failed`) to see what the server accepted.
804
-
805
- | Option | Default | Description |
806
- | --- | --- | --- |
807
- | `baseUrl` | — | Atlaas API base URL |
808
- | `apiKey` | — | Service key (`atsk_*`) with `feed:r` or `orders:r` |
809
- | `clientName` | — | Optional name for this client |
810
- | `autoReconnect` | `true` | Reconnect after a drop |
811
- | `reconnectDelayMs` | `2000` | Base reconnect delay |
812
- | `maxReconnectAttempts` | `10` | Give up after this many |
846
+ | Method | Returns |
847
+ | --- | --- |
848
+ | `placeOrder(order: BrokerOrder, options?: WriteOptions)` | broker's reply |
849
+ | `getOrders()` / `getOrder(orderId)` | broker's reply |
850
+ | `modifyOrder(orderId, changes: BrokerOrder, options?: WriteOptions)` | broker's reply |
851
+ | `cancelOrder(orderId, body?: BrokerCancelOrderBody, options?: WriteOptions)` | broker's reply |
852
+ | `getTrades()` / `getPositions()` / `getHoldings()` | broker's reply |
853
+ | `getCandles(query: BrokerCandlesQuery)` | broker's reply |
854
+ | `getOptionExpiries(underlying: DhanUnderlying)` | `string[]` |
855
+ | `getOptionChain(underlying: DhanUnderlying, expiry: string)` | `DhanOptionChain` |
856
+ | `subscriptions.subscribe(body)` / `.unsubscribe(body)` / `.list()` | broker's reply |
813
857
 
814
858
  ## Zod schemas
815
859