Developer documentation API v1

Liquidity and execution quality

Estimate tradable costs, then compare them with observed fills.

A quote is specific to size and time

liquidity.quote_curve evaluates explicit quantities for one instrument, side and venue against a common observation. Each point records executable or indicative status, fillable quantity, average price, fees included and expiry. Book sequence gaps invalidate executable book-derived estimates until resynchronization. Cross-venue comparison accounts for inventory, transfer, currency and settlement constraints.

Compare executable sizes

Illustrative sizes and age bound. A connection without a supported executable quoting route returns unsupported capability; historical bars never substitute for it.

json

{
  "agent_revision_id": "agr_example_3",
  "tool": "liquidity.quote_curve",
  "input": {
    "instrument_id": "equity:listing:apple-common-xnas",
    "venue": "XNAS",
    "side": "buy",
    "quantities": [
      {
        "asset": "equity:listing:apple-common-xnas",
        "atoms": "10",
        "scale": 0
      },
      {
        "asset": "equity:listing:apple-common-xnas",
        "atoms": "50",
        "scale": 0
      }
    ],
    "max_age_seconds": 5
  }
}

Spread and displayed imbalance

a and b are simultaneous best ask and bid in one venue and quote currency, with m>0. Quantities use the same base units. Empty depth makes imbalance undefined. Displayed imbalance is a liquidity descriptor; hidden liquidity, cancellations and venue selection limit its interpretation.

m=\frac{a+b}{2},\qquad s_{\mathrm{bps}}=10^4\frac{a-b}{m},\qquad I_K=\frac{\sum_{k=1}^K q_k^{\mathrm{bid}}-\sum_{k=1}^K q_k^{\mathrm{ask}}}{\sum_{k=1}^K q_k^{\mathrm{bid}}+\sum_{k=1}^K q_k^{\mathrm{ask}}}

Cost decomposition

execution.cost_estimate uses the quote curve, urgency and pinned cost-model revision. It separates explicit fees, half-spread, modeled impact, delay and financing where applicable. Quote-included fees and impact are not charged again. Historical cost models retain calibration sample, venue, size regime and uncertainty; an equity model is not automatically transferable to a token pool.

Immediate and staged schedules have different fill risk. A participation constraint limits scheduled quantity relative to a declared volume estimate; it does not guarantee future volume or completion. A limit touched within a bar is not automatically filled. Queue position and latency require their own fill model.

Implementation shortfall with unfilled quantity

s=+1 for a buy and −1 for a sell, Q is intended quantity, P₀ the decision benchmark, q_j and P_j observed fills, and P_T the end-of-window benchmark for the remainder. All prices refer to the same instrument and currency. Positive IS is a cost. The unfilled term is an opportunity-cost convention, not booked P&L. A changed decision starts a new benchmark record.

\operatorname{IS}=s\sum_jq_j(P_j-P_0)+s\left(Q-\sum_jq_j\right)(P_T-P_0)+C_{\mathrm{explicit}}

Worked cost example

For a buy of 10 units with decision price $100, six units fill at $100.20. The four unfilled units are marked at $101 at the evaluation endpoint, and explicit fees are $0.50. Implementation shortfall is 6×$0.20 + 4×$1 + $0.50 = $5.70, or 57 basis points of the $1,000 intended notional. Of that amount, $4 is attributed opportunity cost on the unfilled remainder, not a cash charge.

Where implementation shortfall comes from

Waterfall decomposition: 1.20 dollars of fill slippage, 0.50 dollars of fees and 4 dollars of unfilled opportunity cost sum to 5.70 dollars, or 57 basis points. — The chart uses the exact worked example above. Fill slippage is measured against the decision price. The unfilled component is attributed opportunity cost under the endpoint-mark convention; it is not a cash fee or a realized account loss. View full size ↗

After the trade

execution.quality references the existing action, benchmark revision and measurement window. Its result separates fill price, fees, timing, unfilled quantity and reconciliation coverage. Live reports use venue fills. Paper reports retain the simulator revision and stay in their own evaluation mode. Differences between estimates and realized costs inform subsequent model evaluation without rewriting the original estimate.

Execution research

Frazzini, Israel and Moskowitz: Trading CostsEmpirical cost variation by trade size, instrument and execution context.Man AHL: machine learning in investment managementHorizon, capacity, diversification and cost sensitivity.Portfolio optimization with costsSelf-financing portfolios and explicit trading/holding costs.