@nemesis-oss/binance-sdk 2.0.0 → 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shubham Taywade
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -26,6 +26,11 @@ const client = new BinanceClient({
   testnet: true,               // or demo: true; defaults to live
 });
 
+// v3: lazy product namespaces over one shared CoreContext — nothing is built
+// until first access, and `client.core` exposes the shared runtime.
+client.core.credentials.canSign;   // true
+client.core.http('fapi');          // cached per-host transport
+
 // Public market data (no keys needed)
 const klines = await client.spot.market.klines('SOLUSDT', '15m', { limit: 500 });
 const funding = await client.futures.data.fundingRateHistory('ETHUSDT', { limit: 100 });
@@ -211,8 +216,13 @@ creation, futures/margin enablement, deposit address/history.
 `apiKey`, `apiSecret`, `privateKey` + `signatureAlgorithm` (Ed25519/RSA, instead of HMAC),
 `testnet`, `demo`, `recvWindow`, `apiBase`, `wsBase`, `wsUserBase`, `wsApiBase`, `dapiBase`,
 `wsSpotApiBase`, `wsDapiBase`, `timeoutMs`, `maxRetries`, `retryBaseDelayMs`, `retryMaxDelayMs`,
-`rateLimitWeightPerMinute`, `rateLimitSafetyMargin`, `httpsAgent`, `proxy`, `safety`
-(see [Agent safety](#agent-safety)).
+`retryPolicy` (`strict` default / `legacy`), `idempotentPaths`, `rateLimitWeightPerMinute`,
+`rateLimitSafetyMargin`, `httpsAgent`, `proxy`, `events` (observability bus),
+`safety` (see [Agent safety](#agent-safety)).
+
+Product aliases: `client.futures.usdm` and `client.futures.coinm` point at the USDⓈ-M and
+COIN-M surfaces; `client.products` gives the product-oriented view
+(`spot` / `usdm` / `coinm` / `margin` / `wallet` / `subaccount`).
 
 ### Reliability
 
@@ -223,14 +233,118 @@ creation, futures/margin enablement, deposit address/history.
   `client.getRateLimitUsage()`.
 - **Server time sync**: `client.syncTime()` fetches each REST host's server time and applies the
   offset to every signed request's `timestamp`, mitigating `-1021` errors from local clock drift.
-- **Retry**: exponential backoff with jitter on `429`/`418`/`5xx`, configurable via
-  `maxRetries`/`retryBaseDelayMs`/`retryMaxDelayMs`.
+- **Endpoint-aware retries (strict by default)**: exponential backoff with jitter on `429`/`418`
+  (rejected before processing — safe for any method) and `5xx`/network errors on idempotent
+  methods (GET/DELETE, whitelisted paths such as `order/test`). A `POST` order placement that
+  times out is **not** blindly retried — the request may already be live on the exchange.
+  Retried signed requests are re-signed with a fresh timestamp. Set `retryPolicy: 'legacy'` to
+  restore retry-everything behavior.
+- **WebSocket lifecycle**: every WS client is an explicit state machine
+  (`IDLE → CONNECTING → OPEN → RECONNECTING → CLOSING → CLOSED`, via `ws.getState()` and
+  `ws.state` events) with race-free reconnection (a retired socket can never trigger a duplicate
+  connection) and **proactive 24-hour rotation**: Binance kills stream connections at 24h, so the
+  SDK opens a replacement at T-23h and swaps traffic with no data gap.
+- **Subscription acknowledgement**: `await ws.subscribe([...])` resolves only after the server
+  confirms the subscription, and every (re)connect verifies the live subscription set with
+  `LIST_SUBSCRIPTIONS` and repairs drift automatically.
+- **Exact numbers**: all WS frames are parsed with large-integer preservation (identifiers above
+  2^53 surface as decimal strings instead of silently-corrupted floats — also available as
+  `parseJsonLossless` for your own payloads), and money math in the execution/risk/state layers
+  runs on a BigInt-backed `Decimal` (`0.1 + 0.2 === 0.3`, exactly).
+
+### Execution (idempotent placement + reconciliation)
+
+`client.futures.execution` and `client.spot.execution` are the safe way to place orders — one
+execution semantics across USDⓈ-M, spot and the paper simulator (see
+[Multi-backend execution](#multi-backend-execution-live--paper) below):
+
+```typescript
+const execution = await client.futures.execution.placeOrder({
+  symbol: 'BTCUSDT',
+  side: 'BUY',
+  type: 'MARKET',
+  quantity: 0.001,
+  intentId: 'my-strategy-signal-42', // idempotency key: replays return the original execution
+});
+// {
+//   intentId, clientOrderId, exchangeOrderId, status, executedQuantity: '0.001',
+//   averagePrice: '…', fills: [...], reconciliationState: 'acked' | 'reconciled' | …
+// }
+```
+
+- Every order carries a deterministic `newClientOrderId` derived from the intent — the exchange
+  itself becomes the idempotency guard; duplicate intents return the recorded execution.
+- On a transport failure the outcome is **reconciled** by polling
+  `GET /fapi/v1/order?origClientOrderId=…`: found → the execution is recovered and returned;
+  `-2013` (order does not exist) → one safe resubmission with the same clientOrderId; still
+  ambiguous → `ExecutionUnknownError` carrying the intent for manual follow-up — never a guess.
+- With a user-data stream attached (`execution.setUserStream(wsUser)`), execution reports
+  (`ORDER_TRADE_UPDATE` on futures, `executionReport` on spot) stream live fills into the ledger.
+- `cancelOrder` reconciles the same way, and `execution.reconcile(intentId)` forces a refresh.
+
+### Multi-backend execution (live + paper)
+
+Product specifics live behind `ExecutionAdapter` implementations
+(`FuturesExecutionAdapter`, `SpotExecutionAdapter`, `PaperExecutionAdapter`), so paper trading
+is a first-class execution backend — the same envelope, idempotency and reconciliation
+semantics, zero exchange traffic:
+
+```typescript
+// Paper manager: identical API to client.futures.execution
+const paper = client.createPaperExecutionManager({ initialBalance: 50_000 });
+const fill = await paper.placeOrder({
+  symbol: 'BTCUSDT', side: 'BUY', type: 'MARKET', quantity: 0.01, intentId: 'strategy-1',
+});
+// fill.status === 'FILLED', fill.fills[0].price — exact decimal strings
+
+// Gateway: route live/paper through one interface, independent ledgers
+const gateway = client.createExecutionGateway({ defaultBackend: 'paper' });
+await gateway.placeOrder({ ... });                        // paper (default)
+await gateway.placeOrder({ ...order }, { backend: 'live' }); // one live order
+gateway.paperEngine.getAccountInfo();                    // simulation state
+```
+
+Standalone single-product clients for focused integrations. v2 factories
+still ship for back-compat; the v3 first-class `ProductClient` classes
+(`SpotClient`, `USDMClient`, `CoinMClient`) own their own `CoreContext`,
+the v3 execution platform (Spot / USDⓈ-M) and the v3 state engine
+(Spot / USDⓈ-M):
+
+```typescript
+import { createSpotClient, createUSDMClient } from '@nemesis-oss/binance-sdk';
+const spot = createSpotClient({ apiKey, apiSecret }); // v2 factory
+await spot.syncTime();
+await spot.market.depth('BTCUSDT', 20);
+spot.close();
+
+// v3 first-class product client — owns CoreContext, owns the platform
+import { CoreContext, SpotClient, USDMClient, CoinMClient } from '@nemesis-oss/binance-sdk';
+const core = new CoreContext({ apiKey, apiSecret });
+const usdm = new USDMClient(core);
+await usdm.executionPlatform.startUserSession(); // managed listen-key + 30-min keep-alive
+const book = await usdm.books.watch('BTCUSDT');    // local L2 book, synced
+usdm.close();
+```
+
+### Local order books
+
+```typescript
+const books = client.createFuturesOrderBookEngine();
+const btc = await books.subscribe('BTCUSDT');
+btc.metrics(); // bestBid / bestAsk / midPrice / spread / spreadBps / microprice /
+               // imbalance / bidDepth / askDepth / lastUpdateId / synced
+btc.vwap('bids', 5); // size-weighted VWAP of the top 5 levels (exact decimal string)
+```
+
+The engine seeds each book from a REST snapshot, applies `@depth@100ms` diffs in sequence,
+detects gaps (`pu` / sequence discontinuity) and self-heals with a fresh snapshot.
 
 ### Agent safety
 
-`BinanceClientOptions.safety` configures a `TradingPolicy`, evaluated on every mutating request
-before it leaves the process — for autonomous/LLM-driven callers where a misread prompt
-shouldn't be able to spend the account. Shared across every product namespace.
+`BinanceClientOptions.safety` configures a `RiskGateway` (a superset of the v2.0
+`TradingPolicy`), evaluated on every mutating request before it leaves the process — for
+autonomous/LLM-driven callers where a misread prompt shouldn't be able to spend the account.
+Shared across every product namespace, and fed live state by `client.futures.execution`.
 
 ```typescript
 const client = new BinanceClient({
@@ -239,9 +353,14 @@ const client = new BinanceClient({
     dryRun: true,                          // throws DryRunError instead of sending the request
     allowedSymbols: ['BTCUSDT', 'ETHUSDT'],
     maxNotionalPerOrder: 100,              // an order whose notional can't be verified is refused
+    maxLeverage: 20,                       // leverage changes above this are refused
+    maxOpenNotional: 5_000,                // aggregate tracked open-order notional budget
+    maxDailyLoss: 1_000,                   // realized-loss kill switch (UTC day window)
+    maxConsecutiveFailures: 5,             // exchange-rejection streak circuit breaker
     allowWithdrawals: false,               // default once `safety` is set at all
   },
 });
+client.getRiskStatus(); // { circuitBreaker, openNotional: '500', dailyPnl: '-12.5', ... }
 ```
 
 - `dryRun` — intercepts `POST`/`PUT`/`DELETE` and throws `DryRunError` (carrying the request that
@@ -252,6 +371,10 @@ const client = new BinanceClient({
 - `maxNotionalPerOrder` — caps a single order's notional (from `price*quantity` or
   `quoteOrderQty`); an order whose notional can't be determined (e.g. a MARKET order with no
   price) is refused rather than waved through.
+- `maxLeverage` / `maxOpenNotional` / `maxDailyLoss` / `maxConsecutiveFailures` — layered
+  account-state limits. The circuit breaker trips on the daily loss limit or a rejection streak,
+  refuses every mutating request while tripped, and rolls over at the UTC day boundary (or via
+  `resetBreaker()` after human review).
 - `allowWithdrawals` / `allowTransfers` / `blockedPaths` — withdrawals are denied by default the
   moment any `safety` config is set; transfers and arbitrary endpoints can be pinned off too.
 
@@ -271,13 +394,141 @@ Simulates fills against live public prices — nothing is sent to the exchange.
 at the requested leverage and released pro-rata as a position is reduced.
 
 ```typescript
-import { PaperTradingEngine } from '@nemesis-oss/binance-sdk';
+import { PaperTradingEngine, SlippageModel, BinanceUsdmFeeModel } from '@nemesis-oss/binance-sdk';
 
+// Legacy behaviour (instant fills, zero fees) is the default:
 const engine = new PaperTradingEngine({ initialBalance: 10_000 });
 await engine.placeOrder({ symbol: 'BTCUSDT', side: 'BUY', type: 'MARKET', quantity: 0.05, leverage: 5 });
 await engine.updatePositions();               // re-mark against live prices
 const close = await engine.placeOrder({ symbol: 'BTCUSDT', side: 'SELL', type: 'MARKET', quantity: 0.05 });
 console.log(close.realizedPnl, engine.getAccountInfo().balance);
+
+// Or approximate reality in layers:
+const realistic = new PaperTradingEngine({
+  initialBalance: 10_000,
+  executionModel: new SlippageModel(10),      // 10 bps market impact
+  feeModel: new BinanceUsdmFeeModel(),        // 5 bps taker / 2 bps maker
+});
+```
+
+Execution models compose: `SlippageModel`, `PartialFillModel`, `OrderBookModel` (VWAP walks
+against a real/injected book), `LatencyModel`, `CompositeModel`. Fee models implement
+`FeeModel` (`TakerMakerFeeModel` / `BinanceUsdmFeeModel`).
+
+### Observability
+
+`client.events` is a structured, JSON-serializable event bus wired through every subsystem:
+
+```typescript
+client.events.on('execution.', (event) => console.log(event.scope, event.name, event.payload));
+client.events.on('risk.denied', (event) => audit(event.payload));
+client.events.on('ws.', (event) => console.log(event.name, event.payload));
+// http.request.start / http.request.end / http.request.retry / http.request.error
+//   — each carrying contract metadata: product, operation, security, declaredWeight
+// ws.connecting / ws.open / ws.state / ws.reconnecting / ws.rotated / ws.resynced / ws.stale
+// execution.submitted / execution.acked / execution.reconciled / execution.retry / risk.*
+// orderBook.synced / orderBook.desync
+```
+
+Events carry `ts`/`seq`/`scope`/`name`/`payload`; subscribe with exact names, trailing-dot
+prefixes (`'ws.'`) or `'*'`. Pass your own bus via `new BinanceClient({ events })`, or forward
+everything to a logger with `forwardEventsToLogger(bus, logger)`.
+
+### Endpoint maps & agent-native docs
+
+- `llms.txt` / `llms-full.txt` — machine-oriented SDK index and flattened endpoint list
+  (Binance Agent-Native convention).
+- `docs/endpoint-map/*.md` — per-product tables of every implemented endpoint
+  (operation → method → path → auth → SDK surface).
+- **`contracts/` (v3)** — machine-readable inventory of the SDK surface:
+  `endpoint-catalog.json` (every REST operation: product, method, path, security, weight,
+  implementer), `security-catalog.json` (auth matrix per product),
+  `websocket-catalog.json` (WS families, stream ceilings, renewal/liveness policy),
+  `catalog.json` (index).
+  Generated with `npm run contracts:generate` and CI-validated against the registry —
+  the input layer for generated bindings, tool metadata and coverage accounting.
+- `ENDPOINT_REGISTRY` / `listEndpoints({ product, method, authentication })` in code.
+- **Contract layer**: `getContract(product, operation)` / `findContract(path, method)` /
+  `contractFor(baseURL, method, path)` — registry entries with normalized security schemes
+  (`none`/`apiKey`/`signature`) and declared request weights; `describeContract()` renders a
+  one-line description for logs and agents.
+- Regenerate everything from the registry with `npm run docs:generate` (the generator
+  cross-checks the registry against the actual `http.<verb>()` calls in `src/resources`)
+  and `npm run contracts:generate`.
+- `docs/architecture/v3-foundation.md` — the v3 platform architecture and migration plan.
+- `docs/architecture/v3-websocket.md` — the v3 WebSocket platform design (milestone 2).
+- `docs/architecture/v3-execution.md` — the v3 execution platform design (milestone 3).
+- `docs/architecture/v3-state.md` — the v3 state engine + paper backend design (milestone 4).
+
+## v3 Platform (stable since 3.0.0)
+
+`3.0.0` ships the platform rewrite: the foundation (see
+`docs/architecture/v3-foundation.md`), the WebSocket platform (see
+`docs/architecture/v3-websocket.md`), the execution platform (see
+`docs/architecture/v3-execution.md`), the state engine + paper execution
+backend (see `docs/architecture/v3-state.md`), the first-class
+Spot / USDⓈ-M / COIN-M product clients, and the execution audit sink;
+every v2.x surface keeps
+working unchanged.
+
+```typescript
+import { BinanceClient, CoreContext, USDMClient, Credentials } from '@nemesis-oss/binance-sdk';
+
+// Standalone product client over a caller-owned shared runtime
+const core = new CoreContext({ apiKey, apiSecret });
+const usdm = new USDMClient(core);
+await core.syncTime();                     // one clock sync, every host
+const fill = await usdm.execution.placeOrder({
+  symbol: 'BTCUSDT', side: 'BUY', type: 'MARKET', quantity: '0.01',
+});
+usdm.close();                              // product-scoped cleanup
+
+// Two products, one runtime: shared transports, shared event bus
+const other = new USDMClient(core);        // same weight budget, same events
+
+// The multi-product facade is lazy now — namespaces build on first access
+// (stable identity) and share client.core:
+const client = new BinanceClient({ apiKey, apiSecret });
+client.core.credentials.describe();        // 'hmac key ****xxxx'
+client.futures.execution === client.futures.execution;  // true — cached
+
+// --- WebSocket platform (milestone 2): client.ws ---
+const sub = await client.ws.usdm.subscribe('btcusdt@aggTrade');
+sub.on('message', (tick) => console.log(tick.p));   // parsed payload
+await sub.waitForReady();
+client.ws.stats();                          // pools, renewal deadlines, WS API state
+await client.ws.api.usdm.accountStatus();  // persistent multiplexed WS API
+sub.close();                               // refcounted UNSUBSCRIBE
+
+// --- Execution platform (milestone 3): usdm.executionPlatform ---
+const session = await usdm.executionPlatform.startUserSession();
+// listen key created + WS connected + 30-min keep-alive + auto key rotation;
+// the product's execution manager now tracks live fills from the stream:
+
+const execution = await usdm.execution.placeOrder({
+  symbol: 'BTCUSDT', side: 'BUY', type: 'MARKET', quantity: '0.001',
+});
+const record = usdm.executionPlatform.orders.get(execution.clientOrderId);
+// → live OrderRecord: status, exact decimal quantities, per-trade fills
+await usdm.executionPlatform.orders.waitForTerminal(execution.clientOrderId);
+usdm.executionPlatform.positions.get('BTCUSDT');   // from ACCOUNT_UPDATE
+usdm.executionPlatform.classify(err).safety;
+// → 'safe' | 'idempotent' | 'reconciliation-required' | 'never-retry'
+
+// --- State engine + paper backend (milestone 4) ---
+const book = await usdm.books.watch('BTCUSDT');  // local L2 book, synced
+book.bestBid;                                    // exact decimal strings
+book.metrics();                                  // spread, microprice, imbalance
+await usdm.executionPlatform.reconcile();        // REST fold: startup gap-fill
+
+import { createPaperExecutionPlatform } from '@nemesis-oss/binance-sdk';
+const paper = createPaperExecutionPlatform(client.core, { initialBalance: 25_000 });
+await paper.platform.startUserSession();          // local session, zero network
+const fill = await paper.execution.placeOrder({
+  symbol: 'BTCUSDT', side: 'BUY', type: 'MARKET', quantity: '0.01',
+});
+paper.platform.orders.get(fill.clientOrderId);   // same OrderRecord as live
+paper.platform.positions.get('BTCUSDT');         // same PositionRecord as live
 ```
 
 ## LLM Tools & MCP
@@ -292,11 +543,31 @@ const { openai, anthropic, mcp } = toolkitToFormats(tk); // tool schemas per for
 ```
 
 - **Tool groups**: `market`, `account`, `trading` (USD-M futures), `spot` (Spot), `ws`
-  (streams + WS API), `derived` (composites like size/close/bracket), `paper`.
+  (streams + WS API), `derived` (composites like size/close/bracket), `paper`, and
+  `execution` (v2.3).
+- **Execution tools (v2.3)** — order tools routed through the `ExecutionGateway`, so agents
+  get idempotency, reconciliation and backend routing for free:
+
+```ts
+// Run the whole toolkit against the simulator — no API-key trading risk
+const tk = createFuturesToolkit(client, { executionBackend: 'paper', paper: { initialBalance: 50_000 } });
+
+// Same schema, one extra param per call: backend: 'live' | 'paper' (optional)
+const fill = await call('execution_place_order', {
+  symbol: 'BTCUSDT', side: 'BUY', type: 'MARKET', quantity: 0.01,
+  intentId: 'strategy-1',            // idempotency: retries return the original execution
+});
+// execution_get_order finds intents across both ledgers; execution_status returns
+// default backend + risk-gateway state + paper account; execution_cancel_order
+// resolves already-gone orders to a terminal CANCELED execution (never a thrown -2011).
+```
+
 - **MCP server**: `npx binance-sdk-mcp` (stdio) auto-registers every tool plus reference
   resources (`binance://futures/symbols`, `binance://futures/premium-index`, `binance://spot/symbols`).
   For local development against source instead of the published package, point your MCP host at
   `mcp-config/local-dev.json` (runs `npx tsx src/mcp/index.ts` directly).
+  `createBinanceMcpServer(client, { executionBackend: 'paper' })` builds a paper-mode server —
+  every order tool routes through the simulator, safe to expose to untrusted hosts.
 - **Agent skills**: Markdown skills under `skills/` — futures trading / market-data / algo /
   portfolio-margin, plus spot trading / market-data — for Skills-Hub-style agents.