atlaas 0.0.0-stage → 0.1.1

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,3 +1,576 @@
1
- # Temporary Holding Version
1
+ # atlaas
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ TypeScript SDK for the Atlaas SaaS API — MT5 instance management, trading, live tick/candle streams, and broker integrations.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npm install atlaas
9
+ # or
10
+ bun add atlaas
11
+ ```
12
+
13
+ For Node.js WebSocket support, also install `ws`:
14
+
15
+ ```bash
16
+ npm install ws
17
+ ```
18
+
19
+ Browser environments use the native WebSocket — no extra dependency needed.
20
+
21
+ ## Quickstart
22
+
23
+ ```typescript
24
+ import { AtlasClient } from "atlaas"
25
+
26
+ const atlas = new AtlasClient({
27
+ baseUrl: "https://api.atlaas.dev",
28
+ apiKey: "atsk_your_key_here",
29
+ })
30
+
31
+ // List instances
32
+ const instances = await atlas.instances.list({ instanceKind: "mt5" })
33
+
34
+ // Place an order
35
+ const order = await atlas.trading.placeOrder("12345", {
36
+ symbol: "EURUSD",
37
+ type: "BUY",
38
+ volume: 0.01,
39
+ })
40
+
41
+ // Get positions
42
+ const positions = await atlas.trading.getPositions("12345")
43
+ ```
44
+
45
+ ## REST API Resources
46
+
47
+ ### Instances (`atlas.instances`)
48
+
49
+ Manages Atlaas-domain instances via `/api/atlas/instances`.
50
+
51
+ ```typescript
52
+ await atlas.instances.list({ instanceKind: "mt5", state: "RUNNING" })
53
+ await atlas.instances.get("instance-id")
54
+ await atlas.instances.getByExternalRef("my-ref")
55
+ await atlas.instances.getByExternalRefs(["ref1", "ref2"])
56
+ await atlas.instances.create({ instanceKind: "mt5", runnerId: "...", credentials: { ... } })
57
+ await atlas.instances.update("instance-id", { enabled: true })
58
+ await atlas.instances.disable("instance-id") // winddown: runner kills the terminal + deletes the instance folder
59
+ await atlas.instances.enable("instance-id") // re-enable: runner redeploys fresh
60
+ await atlas.instances.delete("instance-id")
61
+ ```
62
+
63
+ ### Trading (`atlas.trading`)
64
+
65
+ MT5 trading operations via `/api/external/instances/:accountId`.
66
+
67
+ ```typescript
68
+ // Orders
69
+ await atlas.trading.placeOrder(accountId, { symbol: "EURUSD", type: "BUY", volume: 0.1 })
70
+ await atlas.trading.getOrders(accountId)
71
+ await atlas.trading.cancelOrder(accountId, ticket)
72
+
73
+ // Positions
74
+ await atlas.trading.getPositions(accountId)
75
+ await atlas.trading.getPosition(accountId, ticket)
76
+ await atlas.trading.modifyPosition(accountId, ticket, { sl: 1.07, tp: 1.12 })
77
+ await atlas.trading.closePosition(accountId, ticket)
78
+ await atlas.trading.closePosition(accountId, ticket, { volume: 0.05 }) // partial
79
+ await atlas.trading.closeBySymbol(accountId, { symbol: "EURUSD" })
80
+
81
+ // Market data
82
+ await atlas.trading.getPrice(accountId, "EURUSD")
83
+ await atlas.trading.getSymbols(accountId)
84
+ await atlas.trading.getAccountInfo(accountId)
85
+
86
+ // Historical candles
87
+ await atlas.trading.getCandles(accountId, {
88
+ symbol: "EURUSD",
89
+ timeframe: "H1",
90
+ startTime: "2026-01-01T00:00:00Z",
91
+ endTime: "2026-01-02T00:00:00Z",
92
+ })
93
+
94
+ // Margin calculation
95
+ await atlas.trading.calculateMargin(accountId, {
96
+ symbol: "EURUSD",
97
+ type: "ORDER_TYPE_BUY",
98
+ volume: 0.1,
99
+ openPrice: 1.08,
100
+ })
101
+ ```
102
+
103
+ ### Subscriptions (`atlas.subscriptions`)
104
+
105
+ Tick and candle data subscriptions via `/api/instances/:accountId`.
106
+
107
+ ```typescript
108
+ await atlas.subscriptions.subscribeTick(instanceId, { symbol: "EURUSD" })
109
+ await atlas.subscriptions.unsubscribeTick(instanceId, { symbol: "EURUSD" })
110
+ await atlas.subscriptions.getTickSubscriptions(instanceId)
111
+
112
+ await atlas.subscriptions.subscribeCandle(instanceId, { symbol: "EURUSD", timeframe: "M1" })
113
+ await atlas.subscriptions.unsubscribeCandle(instanceId)
114
+ await atlas.subscriptions.getCandleSubscriptions(instanceId)
115
+ ```
116
+
117
+ ### Service Keys (`atlas.serviceKeys`)
118
+
119
+ Manage API keys via `/api/public/`.
120
+
121
+ ```typescript
122
+ await atlas.serviceKeys.list(accountId)
123
+ await atlas.serviceKeys.create(accountId, { keyName: "prod-key" })
124
+ await atlas.serviceKeys.update(keyId, { isActive: false })
125
+ await atlas.serviceKeys.regenerate(keyId)
126
+ await atlas.serviceKeys.delete(keyId)
127
+ ```
128
+
129
+ ### Expert Advisors (`atlas.eas`)
130
+
131
+ Manage user strategy EAs, their versions, and chart deployments via
132
+ `/api/external/eas` and `/api/external/deployments`. Everything is scoped to the
133
+ key's account.
134
+
135
+ ```typescript
136
+ // Registry
137
+ await atlas.eas.list()
138
+ await atlas.eas.create({ name: "Breakout", description: "..." })
139
+ await atlas.eas.get(eaId) // detail incl. versions[]; each version has an inputManifest
140
+ await atlas.eas.update(eaId, { name: "Breakout v2" })
141
+ await atlas.eas.remove(eaId)
142
+
143
+ // Versions — upload a compiled .ex5 (deployable now) or .mq5 source (compiled for you)
144
+ const { url, r2Key } = await atlas.eas.presignVersion(eaId, { version: "1.0.0", sourceType: "MQ5", sizeBytes })
145
+ // PUT the file to `url`, then register it:
146
+ await atlas.eas.registerVersion(eaId, { r2Key, version: "1.0.0", sourceType: "MQ5", sizeBytes })
147
+ await atlas.eas.listVersions(eaId)
148
+ await atlas.eas.promoteVersion(eaId, versionId)
149
+ await atlas.eas.deleteVersion(eaId, versionId)
150
+
151
+ // Deployments — bind a version to a chart on an instance; setBlob is the EA's .set inputs
152
+ await atlas.eas.deploy({ versionId, instanceId, symbol: "EURUSD", timeframe: "H1", setBlob })
153
+ await atlas.eas.listDeployments({ instanceId })
154
+ await atlas.eas.getDeployment(deploymentId)
155
+ await atlas.eas.updateDeployment(deploymentId, { setBlob }) // tune inputs / symbol / timeframe / enabled
156
+ await atlas.eas.removeDeployment(deploymentId)
157
+ ```
158
+
159
+ > A version built from `.mq5` source carries a typed `inputManifest` (its parsed
160
+ > input parameters) so you can build a settings UI or generate a `.set`. A
161
+ > compiled `.ex5` has no readable inputs — supply a `.set` (`setBlob`) yourself.
162
+
163
+ ### Broker Trading (`atlas.broker()`)
164
+
165
+ Broker-agnostic trading (Dhan, Kite, Motilal Oswal) via `/api/external/brokers/:name/connections/:id`. The broker name is just a string, so any supported broker works through the same surface.
166
+
167
+ ```typescript
168
+ const dhan = atlas.broker("dhan", connectionId)
169
+
170
+ await dhan.placeOrder({ order: { ... } })
171
+ await dhan.getOrders()
172
+ await dhan.getOrder(orderId)
173
+ await dhan.modifyOrder(orderId, { changes: { ... } })
174
+ await dhan.cancelOrder(orderId)
175
+ await dhan.getTrades()
176
+ await dhan.getPositions()
177
+ await dhan.getHoldings()
178
+ await dhan.getCandles({ securityId: "1333", exchangeSegment: "NSE_EQ", interval: "5", n: 100 })
179
+
180
+ // Broker tick subscriptions
181
+ await dhan.subscriptions.subscribe({ refs: [{ securityId: "1333", exchangeSegment: "NSE_EQ" }] })
182
+ await dhan.subscriptions.list()
183
+ await dhan.subscriptions.unsubscribe({ refs: [{ securityId: "1333", exchangeSegment: "NSE_EQ" }] })
184
+ ```
185
+
186
+ #### Motilal Oswal
187
+
188
+ Motilal Oswal (`atlas.broker("motilal", connectionId)`) exposes the order +
189
+ order-data surface — `placeOrder`, `modifyOrder`, `cancelOrder`, `getOrders`,
190
+ `getOrder`, `getTrades`, `getPositions`, `getHoldings`. Order field names follow
191
+ MOFSL (`exchange`, `symboltoken`, `buyorsell`, `ordertype`, `producttype`,
192
+ `orderduration`, `price`, `triggerprice`, `quantityinlot` — note **lots, not
193
+ shares**). It has **no market/tick data**, so `getCandles` and `subscriptions`
194
+ are not supported. Atlaas re-logs in to Motilal automatically each morning.
195
+
196
+ ```typescript
197
+ const mo = atlas.broker("motilal", connectionId)
198
+
199
+ await mo.placeOrder({
200
+ order: {
201
+ exchange: "NSE",
202
+ symboltoken: 1660,
203
+ buyorsell: "BUY",
204
+ ordertype: "LIMIT",
205
+ producttype: "NORMAL",
206
+ orderduration: "DAY",
207
+ price: 235.5,
208
+ triggerprice: 0,
209
+ quantityinlot: 1
210
+ }
211
+ })
212
+ await mo.getOrder(uniqueOrderId) // poll until orderstatus is terminal
213
+ await mo.getTrades()
214
+ ```
215
+
216
+ See [`docs/integrations/motilal-oswal.md`](../../docs/integrations/motilal-oswal.md) for the full integration guide (provisioning, session init, enums, error handling).
217
+
218
+ ### Instruments (`atlas.v2.instruments`)
219
+
220
+ Atlaas-owned canonical instrument identity via `/api/v2/instruments`. One
221
+ `instrumentKey` per contract, with the per-broker reference ids attached — so
222
+ you look an instrument up once and get Dhan's `securityId`, Motilal's
223
+ `symboltoken`, the Kite tradingsymbol and the MT5 symbol together, instead of
224
+ maintaining a mapping table per broker.
225
+
226
+ Instruments are **global reference data**, identical for every account. Any
227
+ valid service key may read any instrument; nothing here is account-scoped.
228
+
229
+ ```typescript
230
+ // Browse / search
231
+ const { instruments, nextCursor } = await atlas.v2.instruments.list({
232
+ exchange: "NSE", // NSE | BSE | MCX | FX
233
+ segment: "FNO", // EQ | FNO | IDX | CDS | COMM | FX
234
+ symbol: "NIFTY", // exact symbol match (upper-cased for you)
235
+ q: "RELI", // substring match on instrumentKey (see below)
236
+ active: true, // default true; false returns *inactive* rows only
237
+ limit: 100, // default 100, max 500
238
+ cursor: nextCursor ?? undefined
239
+ })
240
+
241
+ // Fetch one by canonical key
242
+ const rel = await atlas.v2.instruments.get("NSE:EQ:RELIANCE")
243
+
244
+ // Reverse lookup: broker ref id -> canonical instrument
245
+ const inst = await atlas.v2.instruments.resolve({
246
+ broker: "dhan", // dhan | motilal | kite | mt5
247
+ refId: "1333",
248
+ segment: "NSE_EQ"
249
+ })
250
+
251
+ inst.brokerRefs.motilal?.symboltoken // the same contract at another broker
252
+ ```
253
+
254
+ **`instrumentKey` format** — `EXCHANGE:SEGMENT:SYMBOL` for cash and indices,
255
+ plus expiry/strike/right for derivatives:
256
+
257
+ ```
258
+ NSE:EQ:RELIANCE (equity)
259
+ NSE:IDX:NIFTY (index)
260
+ NSE:FNO:NIFTY:2026-08-27:FUT (future — note the :FUT suffix)
261
+ NSE:FNO:NIFTY:2026-08-27:24000:CE (option)
262
+ NSE:FNO:USDINR:2026-08-27:84.25:PE (fractional strikes keep their decimals)
263
+ FX:XAUUSD (forex — no exchange segment)
264
+ ```
265
+
266
+ Expiries are always `YYYY-MM-DD`; symbols may not contain `:`.
267
+
268
+ Notes:
269
+
270
+ - **`q` matches the `instrumentKey` only**, as an upper-cased substring — not
271
+ the company `name`. `q: "RELI"` finds `NSE:EQ:RELIANCE`; `q: "Reliance
272
+ Industries"` finds nothing. Use `symbol` when you know the exact ticker.
273
+ - **Paging is keyset on `instrumentKey`**, ascending. Pass the returned
274
+ `nextCursor` straight back as `cursor`; a `null` cursor means the last page.
275
+ - **Kite refs are derived, not synced.** Atlaas has no Kite master; the
276
+ `brokerRefs.kite.tradingsymbol` is derived from the Dhan/MOFSL rows using
277
+ Kite's naming convention, and `instrumentToken` is absent until the U4 Kite
278
+ stream work lands. `resolve({ broker: "kite" })` is therefore not backed by a
279
+ synced index.
280
+ - **`FX:*` rows come from an MT5 terminal**, populated by the admin
281
+ symbol-specs import rather than the daily master sync — expect none until
282
+ that has been run for the account.
283
+ - NSE/BSE rows refresh daily at 03:00 UTC (08:30 IST) from the Dhan detailed
284
+ scrip master and the MOFSL NSEFO master. F&O coverage is the curated index
285
+ universe (NIFTY, BANKNIFTY, FINNIFTY, MIDCPNIFTY, SENSEX, BANKEX) within 60
286
+ days; equity coverage is all NSE/BSE ES/ETF series.
287
+
288
+ The response shape is exported as `UnifiedInstrument`.
289
+
290
+ ### Connections (`atlas.v2.connections`)
291
+
292
+ Every connection — Dhan, Zerodha/Kite, Motilal Oswal, MT5 — serves its orders, trades, positions,
293
+ holdings, funds, and profile in **one canonical shape**. Unlike `v2.instruments`, this resource is
294
+ **account-scoped**: a service key only sees connections it owns.
295
+
296
+ ```typescript
297
+ const conn = atlas.v2.connections("my-conn-001") // Atlaas instance id or externalRef
298
+
299
+ const { capabilities } = await conn.capabilities()
300
+ if (capabilities.closePosition !== "none") {
301
+ const { orders, dropped } = await conn.orders({ includeRaw: false })
302
+ const { positions, scope } = await conn.positions({ scope: "DAY" })
303
+ }
304
+
305
+ // Everything in one call — each section reports ok/error independently
306
+ const snap = await conn.snapshot()
307
+ if (snap.sections.funds.ok) console.log(snap.sections.funds.funds.availableBalance)
308
+ ```
309
+
310
+ `orders` and `positions` take an optional `{ includeRaw?: boolean }` — `true` adds the
311
+ untranslated broker payload as `raw` on each item; omitted/`false` strips it. `trades()` and
312
+ `holdings()` take no params: the server accepts `?includeRaw=true` on trades too (`UnifiedTrade`
313
+ rows do carry a `raw` field), but this SDK's typed `trades()` method doesn't expose the flag yet.
314
+ `UnifiedHolding` rows never carry a `raw` field, so there's nothing to include for `holdings()`.
315
+ `positions({ scope })` defaults to `"NET"`; MT5 and Motilal are net-only and always report
316
+ `scope: "NET"` regardless of what you pass. `.order(orderId)` and `.snapshot({ includeRaw })` take
317
+ the same `includeRaw` flag; snapshot's positions section is always `scope: "NET"` (the `scope`
318
+ param only applies to `.positions()`).
319
+
320
+ Every list result carries `dropped: DroppedRow[]` — rows Atlaas couldn't resolve to a canonical
321
+ instrument, reported rather than silently omitted (`reason: "INSTRUMENT_UNRESOLVED" |
322
+ "UNMAPPABLE"`). A failed call throws with a typed `code` (`BROKER_REJECTED` · `OUTCOME_UNKNOWN` ·
323
+ `UNSUPPORTED_CAPABILITY` · `INSTRUMENT_UNRESOLVED` · `SESSION_DOWN` · `RATE_LIMITED` ·
324
+ `VALIDATION`) and a `retryable` flag — see [Error Handling](#error-handling). `OUTCOME_UNKNOWN`
325
+ (HTTP 504) means the command reached the runner but no reply came back in time: do not blind-retry,
326
+ reconcile with a fresh read first.
327
+
328
+ Caveats, in brief (full detail in the [API reference](../../apps/backend/docs/README.md#connections-unified-reads)):
329
+
330
+ - **Motilal quantities are units** per the MOFSL docs (`lots` is derived from the row's
331
+ `lotsize`); order-book **prices** pass through as reported until the scale is confirmed on a
332
+ live fill.
333
+ - **Kite resolution is derived**, not synced from a Zerodha master — unresolved Kite rows drop
334
+ with `INSTRUMENT_UNRESOLVED`.
335
+ - **MT5 rows need the FX instrument import** run first, or every MT5 order/position drops with
336
+ `INSTRUMENT_UNRESOLVED`; MT5 orders also never populate `placedAt`.
337
+
338
+ Types exported: `UnifiedOrder`, `UnifiedPosition`, `UnifiedHolding`, `UnifiedFunds`,
339
+ `UnifiedTrade`, `UnifiedProfile`, `UnifiedError`, `DroppedRow`, `BrokerCapabilities`, `V2Snapshot`.
340
+
341
+ #### Writes
342
+
343
+ One order shape for every broker. Size it in `quantity` (**units**: Atlaas resolves the broker ref
344
+ from `instrumentKey`, converts to MOFSL lots or MT5 volume, and fails closed with `VALIDATION` /
345
+ `INSTRUMENT_UNRESOLVED` on a quantity it cannot convert exactly) or, on MT5 and Motilal, in `lots`
346
+ (sent to the broker as-is, no contract-size arithmetic; Dhan and Kite refuse it). Exactly one of
347
+ the two. `clientTag` is sanitized per broker. Every write is gated on `capabilities` first and
348
+ returns `UNSUPPORTED_CAPABILITY` when the matrix says no.
349
+
350
+ ```typescript
351
+ const placed = await conn.place({
352
+ instrumentKey: "NSE:FNO:NIFTY:2026-09-24:24000:CE",
353
+ side: "BUY",
354
+ orderType: "LIMIT",
355
+ quantity: 150, // units; 2 lots of 75 on MOFSL, reported back as `lots`
356
+ price: 120.5,
357
+ product: "INTRADAY",
358
+ clientTag: "sig-42"
359
+ })
360
+
361
+ await conn.modify(placed.orderId, { price: 121, quantity: 150 })
362
+ await conn.cancel(placed.orderId)
363
+
364
+ // MT5 in lots, with the position's SL/TP on the order.
365
+ const fx = await conn.place({ instrumentKey: "FX:EURUSD", side: "BUY", orderType: "MARKET", lots: 0.05, stopLoss: 1.08, takeProfit: 1.12 })
366
+ await conn.modifyPosition(fx.orderId, { takeProfit: 1.13 }) // SL untouched
367
+
368
+ // Flatten: MT5 closes every open ticket on the symbol natively (or one, with `positionId`);
369
+ // Dhan/Kite place the opposite-side MARKET order for the NET position. `product` is inferred
370
+ // from the one open position when omitted.
371
+ await conn.closePosition({ instrumentKey: "NSE:EQ:RELIANCE" })
372
+ await conn.closePosition({ instrumentKey: "FX:EURUSD", positionId: fx.orderId, lots: 0.02 }) // partial, one ticket
373
+ ```
374
+
375
+ Per-broker notes:
376
+
377
+ - **Motilal** — `orderType: "MARKET"` is **synthetic**: Atlaas places a marketable LIMIT priced
378
+ off its vendor feed and chases it from ticks (`chase: { maxDriftPct, maxReprices, timeoutMs }`,
379
+ defaults 1 / 3 / 60000). The result and the order book carry a `synthetic` block; exhaustion
380
+ cancels at the broker with `CHASE_EXHAUSTED`. Vendor feed down → `FEED_UNAVAILABLE`. An explicit
381
+ LIMIT price is never chased. `closePosition` reads the NET position and places an opposite-side
382
+ synthetic MARKET (partial `quantity` honoured, capped at the open size); `closeOrders[].synthetic`
383
+ carries the chase. Book quantities are units (the row's `lotsize` derives `lots`); `modify`
384
+ without `quantity` keeps the resting quantity.
385
+ - **Kite** — a 2xx with no `order_id` is reported as `BROKER_REJECTED`, never as success.
386
+ - **Dhan / Kite** — `quantity` on `closePosition` closes that many units (the runner re-reads the
387
+ position and clamps to what is open); omit it to flatten. `lots` is refused, these brokers have
388
+ no lots.
389
+ - **MT5** — `STOP_LIMIT` is unsupported; `modify` accepts only `price`/`triggerPrice`; a partial
390
+ close needs exactly one open ticket on the symbol (name it with `positionId`). `stopLoss` /
391
+ `takeProfit` on `place` become the position's levels; `modifyPosition(positionId, { stopLoss?,
392
+ takeProfit? })` moves them afterwards, and an omitted side keeps its current level (0 clears it).
393
+ Positions report `mt5.volume` in lots; `quantity` on results is units derived from Atlaas's
394
+ contract size for the symbol, so prefer `lots` when your own bookkeeping is in lots.
395
+
396
+ Types exported: `PlaceOrderV2Body`, `ModifyOrderV2Body`, `ClosePositionV2Body`,
397
+ `ModifyPositionV2Body`, `PlaceOrderResult`, `ModifyOrderResult`, `CancelOrderResult`,
398
+ `ClosePositionResult`, `ModifyPositionResult`.
399
+
400
+ ### Market data (`atlas.v2.market`)
401
+
402
+ Connection-independent quotes and candles by `instrumentKey`. NSE/BSE keys are served by the
403
+ Atlaas **data vendor feed** (one Dhan data plan per deployment, opened in-process by the backend);
404
+ FX keys by an MT5 connection you own. Nothing is priced off a stale or wrong source: a vendor that
405
+ is not configured or disconnected answers `FEED_UNAVAILABLE` (503, retryable), and an MT5 server
406
+ without a configured clock offset answers `TIMEZONE_UNCONFIGURED` (409). Closed bars are cached
407
+ server-side and kept past Dhan's ~90-day intraday history, so a repeat `candles` call for a window
408
+ Atlaas has already seen costs no vendor request.
409
+
410
+ ```typescript
411
+ const tick = await atlas.v2.market.quote("NSE:FNO:NIFTY:2026-09-24:24000:CE")
412
+ // { instrumentKey, ts, mode: "FULL", ltp, bid, ask, volume, oi, source: "dhan" }
413
+
414
+ const { candles } = await atlas.v2.market.candles({
415
+ instrumentKey: "NSE:EQ:RELIANCE",
416
+ interval: "5m", // vendor: 1m 5m 15m 1h 1d; MT5: all seven
417
+ from: "2026-09-07T03:45:00Z",
418
+ to: "2026-09-07T10:00:00Z"
419
+ })
420
+ ```
421
+
422
+ `quote()` on a vendor key nobody has asked for yet opens the subscription and returns a retryable
423
+ 404 — call again a moment later. FX candles take an optional `connectionId`.
424
+
425
+ Option chains come from the same vendor feed, so they need no broker connection:
426
+
427
+ ```typescript
428
+ const { expiries } = await atlas.v2.market.expiries("NSE:IDX:NIFTY") // ["2026-09-24", "2026-10-01", …]
429
+ const chain = await atlas.v2.market.optionChain("NSE:IDX:NIFTY", expiries[0])
430
+ // { underlyingLtp, strikes: [{ strike, ce?: { instrumentKey, ltp, oi, volume, bid?, ask?, iv?, greeks? }, pe? }] }
431
+ const atm = chain.strikes.reduce((a, b) => (Math.abs(b.strike - chain.underlyingLtp) < Math.abs(a.strike - chain.underlyingLtp) ? b : a))
432
+ await conn.place({ instrumentKey: atm.ce!.instrumentKey, side: "BUY", orderType: "MARKET", quantity: 75 })
433
+ ```
434
+
435
+ Dhan meters the chain at about one call per 3 s; Atlaas coalesces identical concurrent calls and
436
+ reuses a fresh answer for that window, and reports a vendor refusal as `RATE_LIMITED` (retryable).
437
+
438
+ MT5 contract specs are per broker server, not per instrument, so they hang off the connection:
439
+
440
+ ```typescript
441
+ const { symbols } = await atlas.v2.connections("conn_mt5").symbols({ symbol: "XAUUSD" })
442
+ // [{ symbol: "XAUUSD.sc", instrumentKey: "FX:XAUUSD", contractSize: 1, volumeMin, volumeStep, volumeMax, tickSize, digits, tradeMode, … }]
443
+ ```
444
+
445
+ ## WebSocket Streams
446
+
447
+ Real-time tick and candle data via `/ws/service`.
448
+
449
+ ```typescript
450
+ import { AtlasWebSocket } from "atlaas"
451
+
452
+ const ws = new AtlasWebSocket({
453
+ baseUrl: "https://api.atlaas.dev",
454
+ apiKey: "atsk_your_key_here",
455
+ clientName: "my-bot",
456
+ })
457
+
458
+ await ws.connect()
459
+
460
+ ws.subscribe({
461
+ channels: ["ticks", "candles"],
462
+ accountIds: ["12345"],
463
+ symbols: ["EURUSD", "GBPUSD"],
464
+ })
465
+
466
+ ws.on("tick", (tick) => {
467
+ console.log(`${tick.symbol} bid=${tick.bid} ask=${tick.ask}`)
468
+ })
469
+
470
+ ws.on("candle", (candle) => {
471
+ console.log(`${candle.symbol} ${candle.timeframe} close=${candle.close}`)
472
+ })
473
+
474
+ ws.on("broker_tick", (tick) => {
475
+ console.log(`${tick.brokerName} ${tick.securityId}`, tick.data)
476
+ })
477
+
478
+ ws.on("disconnected", (reason) => {
479
+ console.log("Disconnected:", reason)
480
+ // Auto-reconnect is enabled by default
481
+ })
482
+
483
+ // When done
484
+ ws.disconnect()
485
+ ```
486
+
487
+ ### WebSocket Options
488
+
489
+ | Option | Default | Description |
490
+ |--------|---------|-------------|
491
+ | `baseUrl` | — | Atlaas API base URL |
492
+ | `apiKey` | — | Service key (`atsk_*`) |
493
+ | `clientName` | — | Optional name for this client |
494
+ | `autoReconnect` | `true` | Reconnect on disconnect |
495
+ | `reconnectDelayMs` | `2000` | Base reconnect delay |
496
+ | `maxReconnectAttempts` | `10` | Max reconnect attempts |
497
+
498
+ ### Unified channels (v2)
499
+
500
+ Three additive channels carry the same canonical shapes as the REST surface:
501
+
502
+ | Channel | Event | Payload | Filter |
503
+ | --- | --- | --- | --- |
504
+ | `market.ticks` | `market.tick` | `UnifiedTick` | `instrumentKeys` (NSE/BSE keys open a vendor subscription on demand) |
505
+ | `market.candles` | `market.candle` | `{ instrumentKey, interval, isFinal, candle, source }` from Atlaas's one NSE-grid aggregator (IST 09:15–15:30) or the MT5 stream | `instrumentKeys` |
506
+ | `trading.orders` | `trading.order` | `UnifiedOrder + { eventTs, sequence }` from the Dhan order WS, MT5 trade events, and an Atlaas-side poll for Kite/MOFSL | `brokerOrderConnectionIds` |
507
+
508
+ ```typescript
509
+ ws.subscribe({ channels: ["market.ticks", "market.candles", "trading.orders"], instrumentKeys: ["NSE:EQ:RELIANCE"] })
510
+ ws.on("market.tick", (t) => console.log(t.instrumentKey, t.ltp))
511
+ ws.on("market.candle", (c) => c.isFinal && console.log(c.interval, c.candle))
512
+ ws.on("trading.order", (o) => console.log(o.sequence, o.orderId, o.status))
513
+ ```
514
+
515
+ Delivery on `trading.orders` is at-least-once; Atlaas dedupes on `(orderId, status, filledQuantity,
516
+ price)` and stamps a per-connection `sequence`. The raw `ticks` / `candles` / `broker_ticks` /
517
+ `broker_orders` channels keep working until their announced retirement.
518
+
519
+ ### Channels
520
+
521
+ `ticks`, `candles`, `positions`, `trades`, `orders`, `broker_ticks`
522
+
523
+ ## Error Handling
524
+
525
+ All API errors throw typed exceptions:
526
+
527
+ ```typescript
528
+ import {
529
+ AtlasError,
530
+ AtlasAuthError,
531
+ AtlasRateLimitError,
532
+ AtlasValidationError,
533
+ AtlasNetworkError,
534
+ } from "atlaas"
535
+
536
+ try {
537
+ await atlas.trading.placeOrder(accountId, body)
538
+ } catch (err) {
539
+ if (err instanceof AtlasAuthError) {
540
+ // 401 — invalid or expired API key
541
+ } else if (err instanceof AtlasRateLimitError) {
542
+ // 429 — retry after err.retryAfter seconds
543
+ } else if (err instanceof AtlasValidationError) {
544
+ // 400 — bad request
545
+ } else if (err instanceof AtlasNetworkError) {
546
+ // Network failure or timeout
547
+ } else if (err instanceof AtlasError) {
548
+ // Other API error (403, 404, 500, etc.)
549
+ console.log(err.statusCode, err.message)
550
+ }
551
+ }
552
+ ```
553
+
554
+ ## Client Options
555
+
556
+ | Option | Default | Description |
557
+ |--------|---------|-------------|
558
+ | `baseUrl` | — | Atlaas API base URL |
559
+ | `apiKey` | — | Service key (`atsk_*`) |
560
+ | `timeoutMs` | `30000` | Request timeout |
561
+ | `maxRetries` | `2` | Retries on 5xx / network errors |
562
+ | `logger` | — | Optional logger (`{ debug, info, warn, error }`) |
563
+
564
+ ## Zod Schemas
565
+
566
+ For runtime validation, import schemas directly:
567
+
568
+ ```typescript
569
+ import { PositionSchema, OrderSchema, MT5TickSchema } from "atlaas/schemas"
570
+
571
+ const position = PositionSchema.parse(rawData)
572
+ ```
573
+
574
+ ## License
575
+
576
+ Proprietary. Copyright Vedus. All rights reserved.