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 +473 -429
- package/dist/index.d.ts +108 -28
- package/dist/index.js +66 -19
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,8 +1,16 @@
|
|
|
1
1
|
# atlaas
|
|
2
2
|
|
|
3
|
-
TypeScript SDK for the Atlaas API:
|
|
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
|
|
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
|
|
35
|
-
const
|
|
36
|
-
const order = await
|
|
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
|
|
40
|
-
console.log(order.
|
|
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").
|
|
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
|
|
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.
|
|
106
|
-
await atlas.
|
|
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
|
-
|
|
120
|
+
# Trading (v2)
|
|
113
121
|
|
|
114
|
-
|
|
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
|
|
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
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
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
|
-
|
|
131
|
-
await
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
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
|
-
|
|
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
|
-
|
|
152
|
+
### Writes
|
|
149
153
|
|
|
150
|
-
|
|
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
|
|
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
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
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
|
-
//
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
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
|
-
//
|
|
178
|
-
await
|
|
179
|
-
await
|
|
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
|
-
|
|
183
|
+
Per broker:
|
|
187
184
|
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
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
|
-
|
|
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
|
-
| `
|
|
200
|
-
| `
|
|
201
|
-
| `
|
|
202
|
-
| `
|
|
203
|
-
| `
|
|
204
|
-
| `
|
|
205
|
-
| `
|
|
206
|
-
| `
|
|
207
|
-
| `
|
|
208
|
-
| `
|
|
209
|
-
| `
|
|
210
|
-
| `
|
|
211
|
-
| `
|
|
212
|
-
| `
|
|
213
|
-
| `
|
|
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
|
-
|
|
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
|
-
|
|
213
|
+
# Market data (v2)
|
|
218
214
|
|
|
219
|
-
|
|
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
|
|
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.
|
|
225
|
-
await atlas.
|
|
226
|
-
|
|
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
|
-
|
|
229
|
-
|
|
230
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
239
|
-
const
|
|
240
|
-
|
|
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
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
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
|
-
|
|
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
|
|
254
|
-
await atlas.
|
|
255
|
-
|
|
256
|
-
await atlas.
|
|
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
|
-
`
|
|
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
|
-
| `
|
|
268
|
-
| `
|
|
269
|
-
| `
|
|
270
|
-
| `
|
|
271
|
-
| `
|
|
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
|
-
##
|
|
287
|
+
## Scanner (`atlas.v2.scanner`)
|
|
279
288
|
|
|
280
|
-
[API reference](https://atlaas.dev/docs/
|
|
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
|
|
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
|
-
|
|
286
|
-
const
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
await atlas.
|
|
290
|
-
|
|
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
|
-
|
|
303
|
+
| Method | Returns |
|
|
304
|
+
| --- | --- |
|
|
305
|
+
| `board(params?: ScannerBoardParams)` | `ScannerBoard` |
|
|
306
|
+
| `zones(instrumentKey)` | `ScannerZones` |
|
|
294
307
|
|
|
295
|
-
|
|
308
|
+
## WebSocket stream (`AtlasWebSocket`)
|
|
296
309
|
|
|
297
|
-
|
|
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
|
|
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.
|
|
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
|
-
##
|
|
672
|
+
## MT5 tick and candle subscriptions (`atlas.subscriptions`)
|
|
489
673
|
|
|
490
|
-
|
|
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
|
|
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
|
-
|
|
507
|
-
|
|
508
|
-
|
|
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
|
-
|
|
512
|
-
await
|
|
513
|
-
await
|
|
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
|
-
|
|
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
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
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
|
-
|
|
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
|
-
|
|
|
537
|
-
|
|
|
538
|
-
|
|
|
539
|
-
|
|
|
540
|
-
|
|
|
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
|
-
|
|
717
|
+
# Deprecated v1 wrappers
|
|
547
718
|
|
|
548
|
-
|
|
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
|
-
|
|
721
|
+
## MT5 trading (`atlas.trading`)
|
|
551
722
|
|
|
552
|
-
|
|
723
|
+
Trading on one terminal, named by its MT5 login (`/api/external/instances/:accountId`).
|
|
553
724
|
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
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
|
-
|
|
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
|
-
|
|
735
|
+
```typescript
|
|
736
|
+
const login = "51234567"
|
|
571
737
|
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
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
|
-
|
|
591
|
-
const
|
|
592
|
-
const
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
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
|
-
//
|
|
601
|
-
|
|
602
|
-
|
|
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
|
-
//
|
|
605
|
-
|
|
606
|
-
|
|
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
|
-
|
|
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
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
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
|
-
|
|
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
|
-
| `
|
|
655
|
-
| `
|
|
656
|
-
| `
|
|
657
|
-
| `
|
|
658
|
-
| `
|
|
659
|
-
| `
|
|
660
|
-
| `
|
|
661
|
-
| `
|
|
662
|
-
| `
|
|
663
|
-
| `
|
|
664
|
-
| `
|
|
665
|
-
| `
|
|
666
|
-
| `
|
|
667
|
-
| `
|
|
668
|
-
| `
|
|
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
|
-
`
|
|
798
|
+
With `{ withFreshness: true }` each read returns `Fresh<T>` (`{ data, dataAsOf, lastHeartbeatAt }`) instead.
|
|
671
799
|
|
|
672
|
-
|
|
800
|
+
## Broker connections, raw (`atlas.broker()`)
|
|
673
801
|
|
|
674
|
-
|
|
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
|
|
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
|
-
|
|
714
|
-
|
|
715
|
-
|
|
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
|
-
//
|
|
718
|
-
const
|
|
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
|
-
//
|
|
721
|
-
|
|
722
|
-
|
|
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
|
-
|
|
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
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
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
|
-
|
|
|
777
|
-
| --- | --- |
|
|
778
|
-
| `
|
|
779
|
-
| `
|
|
780
|
-
| `
|
|
781
|
-
| `
|
|
782
|
-
| `
|
|
783
|
-
| `
|
|
784
|
-
| `
|
|
785
|
-
| `
|
|
786
|
-
| `
|
|
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
|
|