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.

A limit order that misses the market should never be left alive on the exchange. Resting orders are invisible to the engine: if a forgotten limit fills hours later at a price the engine no longer controls, it creates a real position that no engine state tracks. Wallet Manager prevents this by coupling every limit order to a bounded poll loop and a mandatory fallback: after a fixed waiting window, the limit is cancelled and any unfilled remainder is immediately market-ordered. The entry or exit is guaranteed to complete — one way or another — within the polling window.

​
The Poll Loop

After placing a limit order, commitBuy and commitSell enter a loop that checks order status every 10 seconds for up to 10 iterations — a maximum wait of 100 seconds: 
let isNotClosed = true;
let lastStatus: Order = null;
for (let i = 0; i !== 10; i++) {
  await sleep(10_000);
  lastStatus = await binance.orderStatus(symbol, orderId);
  if (lastStatus.status === "FILLED") {
    isNotClosed = false;
    break;
  }
}
isNotClosed starts as true and is only flipped to false on a confirmed "FILLED" status. If the loop exhausts all 10 iterations without seeing a fill, isNotClosed remains true and the timeout path fires.
The loop checks for "FILLED" only. A "PARTIALLY_FILLED" status does not break the loop early — the function continues waiting, giving the limit order more time to complete its fill before the timeout triggers.

​
Timeout Handling

When isNotClosed is still true after the poll loop, three things happen in sequence:
  1. Cancel the limit order — remove it from the book so it cannot fill later.
  2. Compute the unfilled remainder — subtract executedQty (the amount already filled) from the original quantity.
  3. Market-order the remainder — guarantee the full position is entered or exited at current market price.
if (isNotClosed) {
  await binance.cancel(symbol, orderId);
  const orderQty = await formatQuantity(
    symbol,
    Number(quantity) - Number(lastStatus?.executedQty || 0),
    binance
  );
  lastStatus = await binance.marketBuy(symbol, Number(orderQty));
  return getAveragePrice(lastStatus, Number(orderPrice));
}
commitSell uses binance.marketSell in the same position; the structure is identical. The final return value is the average fill price computed across all fills reported by the market order response (with orderPrice as a fallback if the fills array is empty).

​
Price Offsets

Neither commitBuy nor commitSell posts a limit order exactly at the current market price. Each applies a small offset to improve fill probability:
FunctionLimit priceDirectionRationale
commitBuyaveragePrice × 1.001Slightly above marketA buy above the current ask is likely to match immediately
commitSellaveragePrice (no offset)At marketThe order is submitted at the raw averagePrice; orderPrice (averagePrice × 0.999) is computed but used only as the getAveragePrice fallback, not as the submitted limit price
commitBuy’s 0.1 % premium is narrow enough that price impact is negligible on liquid spot pairs, but wide enough to win queue position over resting orders at exactly the mid-price. commitCancel’s exit sell — a separate code path in commit_cancel.function.ts — does apply the × 0.999 offset and posts slightly below market to favour a fast fill.

​
Partial Fills

When a limit order partially fills before the 100-second timeout, only the remaining quantity is market-ordered: 
Number(quantity) - Number(lastStatus?.executedQty || 0)
The resulting lastStatus from the market order carries its own fills array. getAveragePrice averages the prices across those fills using the orderPrice as a fallback when fills is empty: 
const getAveragePrice = (order: Order, fallbackPrice: number) => {
  const fallback = { price: fallbackPrice };
  const { fills = [fallback] } = order;
  const price = fills.reduce((acm, { price }) => acm + Number(price), 0);
  return price / fills.length;
};
This means the return value of commitBuy or commitSell is the average price of the market fills only — not a blended average across both the partial limit fill and the market fill. The caller (the broker adapter engine) uses this price to record the entry or exit cost.

​
Where This Pattern Applies

The poll-with-timeout + market fallback is used in three places:
  • commitBuy — entry limit buy, market-buy fallback on timeout
  • commitSell — sized exit limit sell (for a specified amountUSDT), market-sell fallback on timeout
  • commitCancel (sell leg) — after the cancel-verify phase, the exit sell uses the same loop and falls back to binance.marketSell on timeout
In the broker adapter example (onOrderOpenCommit), a structurally identical loop is also used directly, with the added dimension of Rule 1: any timeout on open causes the partial fill to be rolled back with a market sell before the transient throw.
To force the market fallback path during local testing, place a limit buy at roughly 50 % of the current market price — it will not fill within 100 s and the fallback will trigger automatically. Watch for the binance.cancel call followed immediately by binance.marketBuy in your exchange log or console.log output to confirm the path fired.

Build docs developers (and LLMs) love

Get started for freeTalk to us