Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/backtest-kit/wallet-manager/llms.txt

Use this file to discover all available pages before exploring further.

Wallet Manager is a focused internal toolkit built around Binance spot trading. It has two jobs: let you drive the exchange by hand — inspect balances, place and cancel orders, read PnL — without touching a trading engine; and serve as the reference implementation for the exchange side of a backtest-kit broker adapter. Every commit* function in the source encodes the exact order-management flows (post → poll → cancel → market fallback) that a production adapter must get right to avoid leaving ghost orders on the book.
Live keys, real money. Every commit* call places real orders on Binance spot. There is no dry-run mode.

​
The Frozen-Balance Problem

The most common broker-adapter mistake on Binance spot is trying to sell an asset while its funds are still frozen in a pending order. On spot, every resting order locks its quantity — the base coin for a SELL order, USDT for a BUY order. If you attempt to sell on top of that lock, the order will either fail outright with an insufficient-balance error or silently fill only the unlocked remainder while the original TP, SL, or stale entry orders continue holding the rest. The position ends up partially closed with live orders still accumulating risk. The correct sequence is always:
  1. Cancel all pending orders on the symbol.
  2. Verify the book is clean — zero open orders remain.
  3. Sell the entire free coin balance to cash with a fresh order.
This is exactly why commitCancel (and the onOrderCloseCommit broker-adapter example) cancels everything on the symbol and verifies zero open orders before executing the exit sell. Skipping either of the first two steps — or reversing their order — reliably produces partially-closed, underfunded positions that the engine has no way to detect.

​
Architecture

Wallet Manager is composed of two service layers sitting on top of node-binance-api, wired together through a lightweight DI container built with di-kit. WalletPublicService is the layer you should use in the REPL and when building adapter flows. It adds three things on top of the raw layer:
  • Argument validation — numeric types and logical constraints (e.g. takeProfitPrice > currentPrice > stopLossPrice) are checked before any exchange call is made.
  • Per-symbol execution queue — every method call goes through a queued() wrapper (from functools-kit) keyed to the symbol. Concurrent calls on the same symbol are serialized automatically, so two simultaneous commitBuy("SOLUSDT", …) calls can never race each other to the exchange.
  • Structured audit log — after every commit* call completes (or throws), a console.log record is emitted. For commitBuy and commitSell:
{
  "symbol": "SOLUSDT",
  "action": "buy",
  "amountUSDT": 20,
  "averagePrice": 77.56,
  "date": "2024-11-15T10:32:01.000Z",
  "status": "success"
}
For commitTrade, two additional fields are included: 
{
  "symbol": "SOLUSDT",
  "action": "trade",
  "amountUSDT": 20,
  "averagePrice": 77.56,
  "takeProfitPrice": 85.0,
  "stopLossPrice": 74.0,
  "date": "2024-11-15T10:32:01.000Z",
  "status": "success"
}
The action field is one of "buy", "sell", "trade", or "cancel". status is "success" or "failed".

​
Public method signatures

MethodSignatureDescription
commitBuy(symbol: string, amountUSDT: number) => Promise<number>Guarded limit buy. Returns average fill price, or 0 if skipped.
commitSell(symbol: string, amountUSDT: number) => Promise<number>Limit sell for amountUSDT worth of coin. Returns average fill price.
commitTrade(symbol: string, amountUSDT: number, takeProfitPrice: number, stopLossPrice: number) => Promise<void>Buy + OCO bracket in one call. Validates takeProfitPrice > currentPrice > stopLossPrice.
commitCancel(symbol: string) => Promise<void>Cancel all orders on symbol, verify book is clean, then sell entire free coin balance to USDT.
commitReload(symbol: string) => Promise<void>Clears the TTL cache on the private service for the symbol. Useful after manually modifying orders outside this toolkit.
fetchPrice(symbol: string) => Promise<number>Current market price.
fetchFiat(symbol: string) => Promise<number>Total account USDT balance (free + locked).
fetchBalance(symbol: string) => Promise<{ quantity: number; usdt: number }>Coin holdings for the symbol’s base asset. quantity includes amounts locked in open orders.
fetchOrders(symbol: string, limit?: number) => Promise<IOrderData[]>Recent orders (FILLED / CANCELED / NEW). limit defaults to 25.
fetchPnl(symbol: string, limit?: number) => Promise<IDailyPnL[]>Daily PnL estimate reconstructed from trade history and 1h candles. limit defaults to 25.

​
WalletPrivateService — raw layer

WalletPrivateService makes Binance API calls directly, with no validation or queueing. It is the engine beneath WalletPublicService and is exposed on the wallet global only for debugging — inspecting raw responses, checking TTL cache state, or calling clear() to flush cached data. It should not be used for order placement in normal operation. The private service applies TTL caching to the two most expensive read operations:
MethodCache TTL
fetchOrders10 minutes per symbol+limit key
fetchPnl10 minutes per symbol+limit key
A background interval flushes stale entries every 30 seconds. fetchPrice is not cached; a fresh price is fetched before every commit* call. On initialization, the private service also assigns the underlying node-binance-api client to globalThis.binance$, which makes it available in the REPL for low-level inspection.

​
DI container

Both services are registered with di-kit inside src/core/provide.ts and resolved via inject() at construction time. The exported wallet object contains both services and is also assigned to globalThis so the REPL can reach it without an import: 
const wallet = {
  walletPublicService,   // WalletPublicService — use this
  walletPrivateService,  // WalletPrivateService — debug only
};
WalletPublicService internally holds a per-symbol EventListener instance memoized by symbol string. The execution queue lives on that instance, so calling getRunner("SOLUSDT") twice always returns the same queue — calls never bypass serialization by accident.

​
What’s Included

REPL Guide

All read and mutating commands with expected outputs, tips for dumping results to disk with fs, and how to chain commands interactively.

Order Management

The cancel-verify-sell sequence, poll-with-timeout logic, market fallback behavior, and how commitCancel guarantees a clean exit.

Broker Adapter

The full reference adapter wiring these flows into the backtest-kit broker gate, with the three rules for transient-safe order management.

API Reference

Complete method signatures for WalletPublicService — parameters, return types, validation rules, and audit log fields.

Build docs developers (and LLMs) love

Get started for freeTalk to us