Building VWAP & Order fills engine in ADAMANT Market-making bot

In ADAMANT Market-making bot, we already support dynamic order book management, spread control, liquidity provisioning, and volume strategies. But without accurate fill analytics, we only see half the picture.

Issue #87 introduces a major architectural upgrade:

Implementation of a VWAP engine and Order Fills engine (Premium module)

This is not just a feature. It is a foundation for professional-grade execution analytics.

Overview. Why VWAP?

Most exchange APIs provide fragmented information:

• Orders may be partially filled
• Status updates can lag
• Some exchanges return incomplete execution data
• Restarts can cause loss of internal execution context

If a bot does not persist and verify fill data correctly:

• PnL becomes inaccurate
• Position tracking becomes unreliable
• Risk management logic breaks
• Spread and liquidity adjustments are based on assumptions, not reality

To operate at an institutional level, we use:

1. Persistent execution tracking
2. Verified fill reconciliation
3. Proper VWAP computation
4. Inventory-aware analytics

The solution: Dedicated VWAP & Fills engine

Issue #87 proposes introducing a dedicated subsystem responsible for:

1️⃣ Raw fill event storage (Append-Only)

A dedicated fillsDb:

• Stores raw execution events
• Works in append-only mode
• Persists across restarts
• Does not immediately aggregate data

This ensures no execution data is lost or overwritten.

2️⃣ Exchange verification layer

Each fill event must be:

• Verified against exchange API
• Confirmed as fully or partially executed
• Marked as processed only after confirmation

This prevents false-positive fills when:

• Bot has no connectivity
• Exchange nodes are unavailable
• API responses are incomplete

Execution verification only happen when:

• Network connectivity exists
• Exchange endpoints are reachable

Otherwise, we risk incorrectly marking valid trades as failed.

Core function:

/**
 * Verifies a fill order using exchange API.
 *
 * Policy "always verify if possible":
 *  - If api.getOrderDetails() is missing -> cannot disprove -> treat as confirmed
 *  - If status missing or exception -> return undefined (try again later)
 *  - If API says 'filled' -> confirmed
 *  - If API says explicitly not filled ('new'|'part_filled'|'cancelled') -> rejected
 *  - If API says 'unknown' -> keep (cannot disprove) but warn
 *
 * @param {FillOrder|Object} order Fill order record or Order object
 * @param {any} api API instance (spot first/second account, or other compatible trader api)
 * @param {string} callerName Log context id (usually module and method which calls) to quickly find related logs
 * @returns {Promise}
 */
async function verifyOrderFilled(order, api, callerName)

3️⃣ Aggregated execution statistics

A second persistent store filledStatsDb accumulates:

• Total base asset bought
• Total base asset sold
• Total quote asset spent/received
• Counters of full/partial/rejected/missing fills

From this, we compute core metrics.

Core Metrics

Metrics overview:

/**
 * Creates a base FillsEngineStatsResult object with zeroed / default values.
 *
 * @param {string} statsId Format: `${exchange}:${pair}:${purpose}:${startTs}`
 * @param {string} pair Trading pair, e.g., `BTC/USDT`
 * @param {FilledStatsRecord | undefined | null} stats Epoch stats (optional)
 * @returns {FillsEngineStatsResult}
 */
function createBaseEpochStats(statsId, pair, stats) {
  return {
    statsId,
    pair,
    updatedAt: stats?.updatedAt || 0,

    buy: stats?.buy ? { ...stats.buy } : emptySide(),
    sell: stats?.sell ? { ...stats.sell } : emptySide(),

    // Calculated later
    boughtVwap: 0,
    soldVwap: 0,

    hasBothSides: false,
    vwapSpread: 0,
    vwapSpreadPercent: 0,

    pnlQuoteCashflow: 0,
    inventoryBase: 0,
    markPrice: undefined,
    pnlQuoteMtm: undefined,
  };
}

📊 VWAP (Volume Weighted Average Price)

VWAP per side: Buy VWAP and Sell VWAP.

Formula:

VWAP = Total Quote Volume / Total Base Volume

This reflects actual execution quality, not just order placement price.

📉 VWAP spread

Difference between Buy VWAP and Sell VWAP.

This shows real realized trading spread, not theoretical spread.

📦 Inventory Delta

Difference between Total base bought and Total base sold.

Used for:

• Risk management
• Position exposure tracking
• Rebalancing logic

💰 Realized PnL

Cashflow-based result from executed trades.

And optional Mark-to-market PnL using current market price.

Why Fills engine matters

Without proper fill analytics, a trading bot operates in partial darkness. It may place orders efficiently, but it has no real understanding of how those orders are actually executed in the market.

A well-designed VWAP engine changes that dynamic completely. It allows the system to measure execution quality with precision, evaluate real performance instead of theoretical placement, and base its logic on confirmed trading activity.

This becomes critically important in environments where the bot is used for token market making, where execution quality directly impacts perceived liquidity and price stability.

Advanced strategies such as liquidity bucket management or dynamic spread maintenance rely heavily on accurate execution data to function correctly. For premium trading modules, execution analytics is not a bonus feature — it is a core requirement for professional-grade operation.

Architectural Impact

The new engine is designed as a fully modular component that integrates cleanly into the existing architecture without disrupting the current order placement logic. It operates alongside existing systems rather than replacing them, preserving stability while adding a deeper analytical layer.

At the same time, this architecture lays the groundwork for future expansion. It transforms TradeBot from an order placement tool into a true execution analytics system.

Simplified diagram representation:

          Exchange API
                │
                ▼
       Order Placement Engine
                │
                ▼
         Fills Collector
                │
                ▼
       Verification Engine
                │
                ▼
         Aggregation Engine
                │
                ▼
      VWAP / Inventory / PnL
                │
                ▼
    Risk & Strategy Modules

Conclusion

Issue #87 represents a major step toward institutional-grade trading infrastructure inside ADAMANT TradeBot. We significantly improve robustness, transparency, and strategic capability.

This is a foundational upgrade — not a cosmetic enhancement.

The feature is available in the Premium mm bot version.

If you want to use the ADAMANT Market-making bot for your token, start with the free basic version.

Building VWAP & Order fills engine in ADAMANT Market-making bot was originally published in ADAMANT on Medium, where people are continuing the conversation by highlighting and responding to this story.