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.

WalletPublicService is the recommended entry point for all wallet operations. It wraps the lower-level WalletPrivateService with three layers of safety that the raw service deliberately omits: argument validation that throws descriptive errors before any network call is made, a per-symbol serialized execution queue that prevents concurrent orders on the same pair from racing each other, and a structured console.log audit record emitted after every commit* operation regardless of success or failure. You should reach for WalletPublicService in all normal usage. WalletPrivateService exists as a debugging surface and should not be called directly in production code.

​
Accessing the service

wallet-manager is a private package and is not published to npm. When you start the REPL with npm start, a wallet global is injected into the session automatically. In scripts or other modules, import from the local build output: 
// In the REPL (available as a global — no import needed):
const service = wallet.walletPublicService;

// In a local script, import from the build output:
import wallet from './build/index.mjs';
const service = wallet.walletPublicService;

​
Key behaviors

​
Per-symbol execution queue

Every method call is routed through an internal EventListener instance that is memoized per symbol using functools-kit’s queued() wrapper. All operations on the same symbol are serialized — a second commitBuy("SOLUSDT", …) called while the first is still polling Binance will wait in the queue rather than running concurrently. Operations on different symbols run independently.

​
Input validation

Before delegating to WalletPrivateService, WalletPublicService validates caller-supplied arguments and throws descriptive Error instances:
  • amountUSDT must be a finite number (typeof amountUSDT !== "number" || isNaN(amountUSDT)) and must not be negative.
  • For commitTrade, both caller-supplied price arguments (takeProfitPrice and stopLossPrice) are checked for finiteness. After the current market price is fetched internally, takeProfitPrice must be strictly above it, stopLossPrice must be strictly below it, and stopLossPrice must be less than takeProfitPrice.

​
Structured audit log on every commit

After every commit* call — in the finally block, so it fires on both success and failure — the service emits a structured log entry: 
{
  symbol: string;
  action: "buy" | "sell" | "trade" | "cancel";
  amountUSDT: number;
  averagePrice: number;
  date: Date;
  status: "success" | "failed";
}

​
TTL cache invalidation

WalletPrivateService caches fetchOrders and fetchPnl for 10 minutes. After every commit* call, WalletPublicService calls walletPrivateService.clear() to bust both caches so the next read reflects the new state of the account.

​
Method summary

MethodSignatureReturns
commitBuy(symbol, amountUSDT)Promise<number>
commitSell(symbol, amountUSDT)Promise<number>
commitTrade(symbol, amountUSDT, takeProfitPrice, stopLossPrice)Promise<0 | { status: string, content: string }>
commitCancel(symbol)Promise<number>
commitReload(symbol)Promise<void>
fetchPrice(symbol)Promise<number>
fetchBalance(symbol)Promise<{ usdt: number, quantity: number }>
fetchFiat(symbol)Promise<number>
fetchOrders(symbol, limit?)Promise<IOrderData[]>
fetchPnl(symbol, limit?)Promise<IDailyPnL[]>

​
Type definitions

​
IOrderData

Returned by fetchOrders. Each entry represents a single order from Binance trade history or the open order book. 
interface IOrderData {
  symbol: string;
  orderId: number;
  status: "FILLED" | "CANCELED" | "NEW";
  amount: string;        // origQty — the originally requested quantity
  executedQty: string;   // actually filled quantity
  price: string;
  time: string;          // ISO 8601
  side: "BUY" | "SELL";
}

​
IDailyPnL

Returned by fetchPnl. Each entry aggregates realized PnL and balance state for one calendar day. 
interface IDailyPnL {
  date: string;          // ISO 8601 day
  pnl: string;           // realized PnL for the day (USDT)
  walletCost: string;    // average cost basis of traded quantity
  amountQty: string;     // cumulative coin balance at end of day
  amountUSDT: string;    // amountQty × VWAP for the day
  averagePrice: string;  // VWAP from 1h candles
}

​
Method pages

commitBuy

Guarded limit buy with market fallback on timeout

commitSell

Limit sell with poll loop and market fallback

commitTrade

Buy with OCO take-profit and stop-loss brackets

commitCancel

Flatten symbol and exit entire balance to USDT

fetchPrice

Current average market price for a symbol

fetchBalance

Coin balance including locked amounts

fetchFiat

Total USDT balance (free and locked)

fetchOrders

Recent order history for a symbol

fetchPnl

Daily PnL estimate from trade history

commitReload

Flush per-symbol cache without placing an order

Build docs developers (and LLMs) love

Get started for freeTalk to us