atlaas 0.0.0-stage → 0.1.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 +575 -2
- package/dist/index.d.ts +1361 -0
- package/dist/index.js +1074 -0
- package/dist/index.js.map +1 -0
- package/dist/schemas.d.ts +518 -0
- package/dist/schemas.js +191 -0
- package/dist/schemas.js.map +1 -0
- package/package.json +52 -5
package/README.md
CHANGED
|
@@ -1,3 +1,576 @@
|
|
|
1
|
-
#
|
|
1
|
+
# atlaas
|
|
2
2
|
|
|
3
|
-
|
|
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.
|