v0.1.0-alpha

Specification

The APEX Protocol defines how AI agents communicate with financial brokers, exchanges, dealers, and other execution venues via MCP (Model Context Protocol). The spec is organized into a mandatory core and modular asset-class profiles.

Layer 1 — Required

Core Specification

The mandatory baseline that every APEX alpha-compatible implementation must implement. Covers five capability domains:

apex.session.* Authentication, capability negotiation, heartbeat
apex.account.* Account summary, balances, positions, open orders, transaction history
apex.order.* Place, modify, cancel orders. Close positions. Market, limit, stop, stop-limit. SL/TP.
apex.market.* Quotes, OHLCV snapshots, instrument search, contract details
apex.risk.* Pre-trade risk checks, margin requirements, account limits

19 mandatory tools across these five domains form the Layer 1 baseline.

Read the core spec on GitHub
Layer 2 — Profile

FX

Spot FX, CFD FX, rollovers, swap rates, currency exposure, pip calculations.

v0.1-alpha
Layer 2 — Profile

CFD

Equity CFDs, index CFDs, commodity CFDs, corporate actions, dividend adjustments.

v0.1-alpha
Layer 2 — Profile

Crypto

Spot crypto, perpetual futures, funding rates, cross/isolated margin modes.

v0.1-alpha
Layer 2 — Profile

Derivatives

Listed options, futures contracts, greeks, exercise/assignment.

planned
Layer 2 — Profile

Fixed Income

Bonds, yield, duration, coupon schedules.

planned

Realtime State Model

APEX defines an agent-native realtime state plane. Tools handle actions and queries. MCP resources expose live state. Notifications signal change. This architecture replaces polling with event-driven state management.

Market Resources

apex://market/quote/{instrument_id} Top-of-book bid/ask/spread with freshness metadata
apex://market/candles/{id}?timeframe=M1|M5|H1 OHLCV candle arrays with completion flags
apex://market/features/{instrument_id} Derived features: returns, volatility, regime, liquidity

Account Resources

apex://account/summary/{account_id} Balance, equity, margin, P&L
apex://account/positions/{account_id} Open positions with live P&L
apex://account/orders/{account_id} Order lifecycle state
apex://account/fills/{account_id} Execution history
apex://account/risk/{account_id} Risk limits and kill switch state

Agent Resources

apex://agent/decision-context/{instrument_id} Packaged market + account + risk state for model consumption

Every resource carries a monotonic sequence number, a freshness timestamp, and a stale_after_ms threshold. Agents detect gaps, reject stale data, and halt autonomy deterministically — before the model is asked to decide.

All resources validate against normative JSON schemas published in spec/core/schemas/.

Instrument Taxonomy

The spec defines a canonical identifier format for tradeable instruments. A universal ID means the same thing at every broker — no per-broker symbol mapping.

ID Format

APEX:{ASSET_CLASS}:{SUB_CLASS?}:{SYMBOL}
APEX:FX:EURUSD Euro / US Dollar spot
APEX:CFD:IDX:SPX500 S&P 500 index CFD
APEX:CFD:EQ:AAPL.XNAS Apple equity CFD
APEX:CRYPTO:SPOT:BTCUSDT Bitcoin / Tether spot
View the taxonomy on GitHub

Design Principles

Direct broker authentication

Agents authenticate directly with providers. Tokens must be redacted from logs and traces and protected in transit.

No recommendations

No APEX tool may return a directional trading recommendation. Protocol-level prohibition, non-negotiable.

Consistent errors

Every error follows a standard envelope: code, category, message, details, request_id, retry_after. Categories: auth, validation, risk, operational, broker, rate_limit, internal.

MCP-native annotations

Every tool declares readOnlyHint, destructiveHint, and idempotentHint for safe agent behavior.

Agent-native realtime

Tools for actions, resources for live state, notifications for change. Resources are the primary state plane — polling is not the intended architecture.

Deterministic safety

Autonomous runtimes halt on stale data, broken sequences, or kill switch activation. The runtime enforces, the model proposes. Safety decisions happen before the model is asked.

Notifications

APEX defines seven mandatory notification types, emitted alongside standard MCP notifications/resources/updated signals.

apex.order.filled Complete fill with price, quantity, fill_id
apex.order.partially_filled Partial fill with accumulated quantity
apex.order.rejected Rejection with category and reason
apex.market.candle_closed Bar close with complete OHLCV candle
apex.risk.kill_switch_engaged Kill switch activation, halt all trading
apex.session.gap_fill Consecutive ephemeral events elided during replay, with elided count and ID range
apex.session.replay_failed SSE replay buffer exhausted, rebuild state

Each notification uses a structured envelope: event_id, event_type, account_id, instrument_id, resource_uri, timestamp, sequence, and payload.

Production Profiles

Beyond the Layer 1 tool baseline, APEX defines two production capability profiles for serious trading.

Production Realtime

  • Streamable HTTP transport with SSE notifications
  • 19 mandatory tools + all realtime resources
  • Acknowledgment-driven session replay with gap fill — agent controls retention, execution events replayed, ephemeral data elided
  • Freshness tracking, monotonic sequencing
  • Last-Event-ID reconnect with replay

Production Autonomous

Everything in Realtime, plus:

  • Decision context resource for model consumption
  • Kill switch, max position size, max open orders, daily loss limits
  • Stale-data rejection, sequence-gap rejection
  • Market-hours gating, restricted instrument enforcement
  • Runtime halts before the model decides, not after

Execution Semantics

The spec tightens the meaning of execution-critical trading objects to prevent behavioral drift across implementations.

Order states 7 canonical states: accepted, working, partially_filled, filled, cancelled, rejected, expired
Fill semantics Each fill has fill_id, order_id, quantity, price, timestamp. Partial fills accumulate.
Quantity model filled_quantity + remaining_quantity ≤ quantity. Terminal states have remaining_quantity == 0.
Cancel/modify Cancel applies to executable remaining; modify supports order amendment and position protection (SL/TP)
Position semantics Live exposure after broker-side netting. Document netted vs hedged.
Read execution semantics on GitHub

Operations

Runtime rules for freshness, sequencing, replay, session health, and autonomous halt conditions.

Freshness classes Market Fast (quotes, features), Market Slow (candles), Account/Risk (execution-critical)
Staleness rule Resource stale when current_time > timestamp + stale_after_ms
Reconnect modes Four modes: no_replay, session_replay, best_effort_replay, guaranteed_replay
Session health States: ok, degraded, paused, halted
Autonomous halt conditions Stale quote, stale account/risk, broken sequence, kill switch, restricted instrument
Read operations spec on GitHub

Stability & Compatibility

Alpha-phase stability classes and compatibility rules for protocol evolution.

Alpha Core Tool namespaces, resource URIs, normative schemas, production profile names
Alpha Optional Vendor extensions, broker-specific notifications
Alpha Experimental Explicitly experimental capabilities (no stability promise)
Reserved apex.*, apex://, notifications/apex.* reserved across all implementations

Changes follow an additive model: new optional fields, tools, profiles, and resource families are compatible. Removing or renaming core tools, changing field semantics, or tightening schemas is incompatible.

Read stability spec on GitHub