my-NexusTradingForexBot/agents/APISkill.md

agents/APISkill.md — NEXUS API AGENT SKILL (CANONICAL OPERATIONAL CONTRACT)

Machine-oriented contract for Hermes/Nexus agents working with the Nexus Scalp Engine APIs. Read this file before touching any API: it tells you WHAT exists, WHICH endpoint answers WHICH question, HOW to call it, WHAT it depends on, WHAT can fail, HOW to test it, and WHAT MUST NEVER be done.

• Spec of record (design): docs/api/API_PLATFORM_V1.md
• Developer reference (usage): docs/api/API_REFERENCE.md
• This file: agent-facing operational contract + drift-protected registry
• Drift validator: scripts/dev/api_skill_drift_check.py (exit 0 = in sync)

Maintainer: Hermes-Main (API Platform owner, TASK-API-PLATFORM, CHG-0043). Companion file convention: see agents/skill.md (architecture map).

---

0. STATE AT A GLANCE (verify before trusting)

fact	value	how to re-verify
canonical tree	src/nexus_scalp/web/api_v1/	ls src/nexus_scalp/web/api_v1/
mount point	ONE call: web/api_v1_wiring.register_api_v1(app) at end of web/server.create_app()	grep -n "register_api_v1" src/nexus_scalp/web/server.py
live operation count	68 (63 GET + 5 POST)	.venv/Scripts/python.exe scripts/dev/api_contract_check.py
legacy dashboard routes	280 decorators, still served, additive-untouched	grep @(app|router).(get|post...) over web/*.py excluding api_v1*
superseded tree	src/nexus_scalp/api/v1 — REMOVED (was 45 routes, commit e51a910 removed it)	must NOT exist; do not resurrect
envelope	{data, meta} / {error{...}}	§4
auth	none (localhost bind; no broker mutations by design)	§7
platform owner registry	TASK-API-PLATFORM → VERIFIED (CHG-0043)	agents/taskboard.md

---

1. API LANDSCAPE: FOUR STATUS CLASSES

Every API path in this repository is exactly ONE of these. Never blur them.

class	meaning	examples
CURRENT / CANONICAL	/api/v1/* — the platform of record. Build here.	all 68 operations in §4/§5
LEGACY / HISTORICAL	the ~280 dashboard routes (/api/status, /api/live/state, /api/models/*, /api/research/*, /api/diagnostics/*, /api/db/console/*, …). Still served for the Web UI. Do NOT build new client work on them; consume via /api/v1 equivalents where they exist.	§2
DEPRECATED / SUPERSEDED	legacy paths whose truth now has a canonical v1 endpoint. Keep working (UI depends on them) but prefer v1.	/api/status → /api/v1/system/status; /api/models/champion → /api/v1/model/champion
REMOVED	trees deleted from the codebase. They do not exist. Any doc claiming otherwise is a defect.	src/nexus_scalp/api/v1/* (the first 45-route v1, superseded envelope) — removed in consolidation commit e51a910

Hard rule: an agent must never resurrect src/nexus_scalp/api/v1, never mount a second v1 tree, and never add routes outside web/api_v1/ for new platform capabilities. Extension workflow: §14.

---

2. LEGACY / HISTORICAL INVENTORY (verified from source, not memory)

Current decorator scan of web/*.py (excluding api_v1*): 280 routes across 10 route modules + server.py static/JS file routes. Families (count = decorators):

module	count	family / path pattern	status	canonical v1 replacement
debug_research_routes.py	50	/api/debug/*, /api/research/*, /api/experience/*, /api/account/*	LEGACY (UI-owned)	/api/v1/research/*, /api/v1/decisions/*, /api/v1/audit/*
model_governance_routes.py	45	/api/models/* (train/worker/shadow/governance/promotion/emergency)	LEGACY — operator+UI only	/api/v1/model/* (read-only truth); POST governance actions stay legacy
diagnostics_state_routes.py	43	/api/status, /health, /api/live/*, /api/account/*, /api/engine/*, /api/config, /api/settings/*, /api/db/*, /api/rules/*	LEGACY — UI control plane	/api/v1/system/*, /api/v1/config/*, /api/v1/database/*
news_liquidity_mslie_routes.py	23	/api/news/*, /api/liquidity/*, /api/mslie/*	LEGACY	none in v1 (news/liquidity domain not yet versioned)
intelligence_routes.py	10	/api/intelligence/*	LEGACY	none in v1
server.py (inline)	9	/api/ticks/stream (SSE), /api/chart, /api/mt5, /api/positions, /api/status helpers, /ws	LEGACY	/api/v1/market/*, /api/v1/positions (polling; SSE remains UI-owned)
command_center_integration.py	8	/api/command-center/*	LEGACY	none in v1
operator_routes.py	6	operator console routes	LEGACY	none in v1
factory_routes.py	~18	/api/factory/*, /loop/*, /generations/*, /llm-config/*, /analyze/*	LEGACY	none in v1
replay_routes.py	5	/api/replay/*	LEGACY	none in v1 (replay sessions are CHG-0043-adjacent, not yet versioned)
db_console.py	10	/api/db/console/* (SQL console, API keys)	LEGACY — read-only by contract, UI-owned	/api/v1/database/* (metadata only; v1 NEVER executes user SQL)
dependency_routes.py	9	/api/dependency/*	LEGACY	none in v1
news_intelligence_routes.py	7	/pro/*, /apikey/*, /vendor/*	LEGACY	none in v1
server.py static files	~10	/app.js, /api_client.js, *.css	static assets (not APIs)	n/a

Migration rule: v1 duplicates legacy read truths only where a stable contract was worth publishing; legacy control endpoints (engine toggle, model training, promotion, SQL console) are deliberately NOT in v1 — they stay operator-console/CLI owned. Do not search for them under /api/v1.

---

3. CURRENT CANONICAL API MAP (per-domain operational entries)

Format per operation: Purpose / Returns / Dependencies / Errors / Agent use / CLI / Tests / Smoke. All GETs unless marked POST. All paths below are verified against the live OpenAPI (scripts/dev/api_skill_drift_check.py enforces this).

3.1 SYSTEM — module web/api_v1/system.py

GET /api/v1/system/status

• Purpose: one-shot operational snapshot (health verdict + version + mode + freshness + check counts).
• Returns: data{health_verdict, critical_failures[], version{product,version,commit,channel}, runtime{engine_attached,engine_running,mode,freshness_overall}, checks_count}.
• Dependencies: HealthEngine (3s TTL cache + prewarm thread); engine attrs if attached.
• Errors: 503 DEPENDENCY_UNAVAILABLE (health engine itself failed).
• Agent use: FIRST call to answer "what is the engine doing right now?" — but read §11 truth rules: health_verdict is a layered verdict, not a trading guarantee.
• CLI: nexus api status (human rendering).
• Tests: tests/unit/test_api_v1_contracts.py, tests/integration/test_api_v1_platform.py.
• Smoke: python scripts/dev/api_smoke.py --embedded|--live.

GET /api/v1/system/health

• Purpose: full HealthEngine check list (verbatim per-layer entries).
• Returns: data{verdict, checks[{category,verdict,...}], critical_failures[]}.
• Dependencies: HealthEngine (cached 3s).
• Errors: 503 DEPENDENCY_UNAVAILABLE.
• Agent use: WHEN a status layer failed and you need the per-layer detail.
• CLI: nexus api health.

GET /api/v1/system/readiness

• Purpose: can the system accept work? Required layers (SYSTEM/RUNTIME/CONFIGURATION/DATABASE/MODEL/FEATURE_SCHEMA) must have no FAIL.
• Returns: data{ready: bool, verdict, required_layers[], optional_layers[]}.
• Errors: 503 DEPENDENCY_UNAVAILABLE.
• Agent use: gate any automation on data.ready — never on HTTP 200 alone.

GET /api/v1/system/version

• Purpose: build/revision identity.
• Returns: full get_version_info() dict (product, version, commit, channel, python, platform, mode…).
• Dependencies: build metadata (memoized).
• Errors: 503 DEPENDENCY_UNAVAILABLE.
• CLI: nexus api version.

GET /api/v1/system/runtime

• Purpose: runtime environment + mode + warmup + inference flag + freshness contract.
• Returns: data{engine_attached, engine_running, warmup_state, inference_enabled, freshness, mode, effective_mode}.
• Errors: truthful nulls when engine absent (HTTP 200, engine_attached:false).

GET /api/v1/system/capabilities

• Purpose: platform discovery — domains + endpoint counts + pagination model + read_only flag; built from the REAL mounted route table.
• Returns: data{api_version, spec, read_only, domains{}, domain_count, endpoint_count, pagination{...}, generated_at}.
• Agent use: always the first discovery step on an unfamiliar deployment.
• CLI: nexus api capabilities.

GET /api/v1/system/workers

• Purpose: worker lifecycle (accounting/incident/hygiene/model-lifecycle workers).
• Returns: data{workers[{name,state,attached}], engine_attached}; honest NOT_ATTACHED when absent.

POST /api/v1/system/refresh

• Purpose: safe refresh of runtime-observable state (re-read account/symbol snapshots, bump versioner).
• Body: none. Headers: optional Idempotency-Key (echoed in meta.idempotency_key).
• Returns: data{refreshed{account{available}}, at}.
• Dependencies: ENGINE + adapter → 503 ENGINE_UNAVAILABLE when absent.
• Side effects: NONE that reach a broker (snapshot reads only).

POST /api/v1/system/diagnostics/run

• Purpose: run the bounded observability selftest; caches result on app.state for /diagnostics.
• Returns: selftest result dict. Idempotency-Key echoed.

GET /api/v1/system/diagnostics

• Purpose: latest diagnostics = adapter diagnostics_summary() (or null) + last selftest + version.
• Returns: data{mt5, last_selftest, version}; never 503 — truthful nulls when no adapter.

3.2 RUNTIME — module web/api_v1/runtime.py

GET /api/v1/runtime/mode

• Purpose: configured mode + effective _runtime_mode + replay flag.
• Returns: data{mode, effective_mode, engine_attached, replaying}; HTTP 200 with nulls when engine absent.
• CLI: nexus api mode.

GET /api/v1/runtime/freshness

• Purpose: the live-freshness contract (market/inference stages + overall) from engine.compute_live_freshness().
• Returns: data{freshness, available}.
• Errors: 503 ENGINE_UNAVAILABLE.

POST /api/v1/runtime/mode/validate

• Purpose: pure transition validation of a PROPOSED mode — never applies.
• Body: {"mode": "PAPER"} (ModeProposal). Returns data{valid, current_mode, proposed_mode, errors[], warnings[]}; invalid → HTTP 422 with the same body (valid:false).
• Agent use: pre-flight any mode reasoning; LIVE proposals always carry a warning that v1 has no mutation path.

POST /api/v1/runtime/mode/preview

• Purpose: impact matrix of a proposed mode (which subsystems it would touch).
• Body: ModeProposal. Returns data{validation, impact{touches[],matrix{...}}}; 422 on invalid mode.

3.3 MARKET — module web/api_v1/market.py (ALL → 503 ENGINE_UNAVAILABLE without engine)

GET /api/v1/market/snapshot — data{symbol, account, symbol_spec} from real adapter snapshots (?symbol= override).

GET /api/v1/market/quote — data = broker tick (bid/ask/spread/freshness/stale) from get_broker_tick.

GET /api/v1/market/bars — ?limit≤500 completed M-bars from the engine aggregator (engine-local scope, stated in response).

GET /api/v1/market/regime — data{regime, evidence} from _last_regime_state; None before first inference (truthful, not 404).

GET /api/v1/market/symbols — configured symbol(s) + spec block.

3.4 SIGNALS — module web/api_v1/signals.py (audit_signals DB)

GET /api/v1/signals/latest — most recent audit_signals row (ORDER BY id DESC) + sanitized parsed payload; 404 truthful when table empty.

GET /api/v1/signals/history — paginated; filters symbol, action (upper-cased), hours_back (≤720); 422 pagination errors.

3.5 DECISIONS — module web/api_v1/decisions.py (audit_signals; decision_id = request_id)

GET /api/v1/decisions — paginated history; filters symbol/action/execution_mode/decision_stage/hours_back.

GET /api/v1/decisions/latest — full summary (decision_id, action, confidence, gates-adjacent fields, risk_checks).

GET /api/v1/decisions/stats — ?hours_back window; data{window_hours,total,by_action{},by_stage{}}.

GET /api/v1/decisions/no-trade — NO_TRADE analytics: data{total,reasons[],latest}.

GET /api/v1/decisions/no-trade/reasons — data{total, reasons{reason_code:count}}.

GET /api/v1/decisions/{decision_id} — detail by request_id; 404 truthful.

GET /api/v1/decisions/{decision_id}/evidence — raw payload (sanitized of secret-shaped keys).

GET /api/v1/decisions/{decision_id}/gates — ordered gate trace: decision_stage, blocked_by, reason_code, guardian_status, risk_allowed each with {value,passed:bool}.

GET /api/v1/decisions/{decision_id}/explanation — human-readable sentence composed ONLY from real fields.

3.6 POSITIONS / EXECUTION / MODEL / FEATURES — module web/api_v1/positions.py

GET /api/v1/positions — real adapter.get_all_positions() snapshots (MT5 field contract); 503 ENGINE_UNAVAILABLE without engine.

GET /api/v1/positions/{ticket} — one open position; 404 truthful if ticket not open.

GET /api/v1/positions/history/{ticket} — ledger row + broker deals for a historical ticket (DB-backed; works without engine).

GET /api/v1/execution/status — data{adapter_present, connection_state, connected, engine_running, mode}; 503 without engine.

GET /api/v1/execution/history — paginated audit_executions (order events), filters status,symbol.

GET /api/v1/model/status — data{bundle_loaded, inference_enabled, warmup_state, runtime_mode}; 503 without engine.

GET /api/v1/model/identity — bundle manifest identity + feature_schema_hash; {available:false} truthful when no bundle.

GET /api/v1/model/contracts — expected_schema_ids() + compatible_model_schemas() matrix.

GET /api/v1/model/champion — champion identity from the SERVING bundle (authoritative for "what is actually serving"); not the governance registry.

GET /api/v1/features/status — warmup + last-vector availability + missing features from last proposal.

GET /api/v1/features/contract — canonical 70D SSoT: SCHEMA_ID, feature_count, schema hash, family groups, registry_canonical.

GET /api/v1/features/groups — family → names/counts.

GET /api/v1/features/current — last computed vector (dimension + named dict or honest absence).

3.7 RISK — module web/api_v1/risk.py

GET /api/v1/risk/status — last proposal risk_checks (sanitized) + risk config block; 503 without engine.

GET /api/v1/risk/summary — open exposure by symbol (volume/profit) + account margin metrics from the adapter; exposure.available:false truthful.

3.8 RESEARCH — module web/api_v1/research.py (research store/registry over audit DB)

GET /api/v1/research/status — health + registry summaries; 503 DEPENDENCY_UNAVAILABLE if stores unreadable.

GET /api/v1/research/strategies — paginated registry entries; ?lifecycle=.

GET /api/v1/research/strategies/{strategy_id} — detail + invariant_check; 404 truthful.

GET /api/v1/research/runs — paginated run inventory; ?strategy_id=.

GET /api/v1/research/datasets — distinct dataset_ids + run counts (real rows only).

3.9 SHADOW — module web/api_v1/shadow.py (ShadowStore + Shadow70Store)

GET /api/v1/shadow/status — both stores' summary(); per-block failure isolation (null block ≠ fake zero).

GET /api/v1/shadow/runs — paginated PHASE-11 run inventory.

GET /api/v1/shadow/runs/{run_id} — run + comparison + promotion; 404 truthful.

GET /api/v1/shadow/decisions — paginated decision records; ?run_id=.

GET /api/v1/shadow/70d — 70D observer: summary + disagreement counts (valid-only) + drift alerts + feature health.

3.10 OBSERVABILITY / AUDIT / INCIDENTS / DATABASE / CONFIG — module web/api_v1/incidents.py

GET /api/v1/observability/events — paginated audit_events tail; ?event_type=.

GET /api/v1/observability/metrics — real process counters (threads; POSIX rusage; UNAVAILABLE on Windows — never fabricated) + SSE diag + engine peak equity.

GET /api/v1/audit/events — paginated audit_ledger tail; ?status=.

GET /api/v1/incidents — paginated incident inventory; filters status/severity/category/component.

GET /api/v1/incidents/stats — counts + by-component + recurring fingerprints.

GET /api/v1/incidents/{incident_id} — full Incident.as_dict(); 404 truthful.

GET /api/v1/incidents/{incident_id}/timeline — timeline events; 404 truthful.

GET /api/v1/database/status — O(1) metadata (filename, size, table_count); integrity_endpoint pointer. Never per-call PRAGMA.

GET /api/v1/database/integrity — quick_check + bounded row counts (explicit heavier route).

GET /api/v1/database/tables — table names only (no row dumps ever).

GET /api/v1/config — full engine config sanitized (secret-shaped keys → ***); 503 without engine.

GET /api/v1/config/schema — AppConfig section/field inventory (pydantic-derived).

POST /api/v1/config/validate — validate a partial config dict against real pydantic models; no apply (422 with field errors on invalid; applied:false always).

---

4. MACHINE-READABLE REGISTRY (drift-protected)

Every current operation. Columns: METHOD | PATH | DOMAIN | MODULE | READ/WRITE | ENGINE | DB | primary errors | tests | CLI. E = requires engine (503 otherwise) · E-soft = degrades truthfully without engine · S = static/config/schema-backed.

METHOD	PATH	DOMAIN	MODULE	READ/WRITE	ENGINE	DB	ERRORS	TESTS	CLI
GET	/api/v1/system/status	system	system.py	READ_ONLY	E-soft	S	503 DEP	contracts+integration	nexus api status
GET	/api/v1/system/health	system	system.py	READ_ONLY	E-soft	S	503 DEP	contracts+integration	nexus api health
GET	/api/v1/system/readiness	system	system.py	READ_ONLY	E-soft	S	503 DEP	contracts	—
GET	/api/v1/system/version	system	system.py	READ_ONLY	N	S	503 DEP	contracts+integration	nexus api version
GET	/api/v1/system/runtime	system	system.py	READ_ONLY	E-soft	N	—	contracts	—
GET	/api/v1/system/capabilities	system	system.py	READ_ONLY	N	N	—	contracts+integration	nexus api capabilities
GET	/api/v1/system/workers	system	system.py	READ_ONLY	E-soft	N	—	contracts	—
POST	/api/v1/system/refresh	system	system.py	REFRESH	E (adapter)	N	503 ENGINE	integration	—
POST	/api/v1/system/diagnostics/run	system	system.py	DIAGNOSTIC	N	N	500	contracts	nexus api diagnostics --run
GET	/api/v1/system/diagnostics	system	system.py	READ_ONLY	N (adapter null)	N	—	integration	nexus api diagnostics
GET	/api/v1/runtime/mode	runtime	runtime.py	READ_ONLY	E-soft	N	—	contracts+integration	nexus api mode
GET	/api/v1/runtime/freshness	runtime	runtime.py	READ_ONLY	E	N	503 ENGINE	contracts	—
POST	/api/v1/runtime/mode/validate	runtime	runtime.py	SAFE_VALIDATION	E-soft	N	422	contracts	—
POST	/api/v1/runtime/mode/preview	runtime	runtime.py	SAFE_VALIDATION	E-soft	N	422	contracts	—
GET	/api/v1/market/snapshot	market	market.py	READ_ONLY	E	N	503 ENGINE	integration	—
GET	/api/v1/market/quote	market	market.py	READ_ONLY	E	N	503 ENGINE	contracts+integration	—
GET	/api/v1/market/bars	market	market.py	READ_ONLY	E	N	503 ENGINE	contracts	—
GET	/api/v1/market/regime	market	market.py	READ_ONLY	E	N	503 ENGINE	contracts	—
GET	/api/v1/market/symbols	market	market.py	READ_ONLY	E	N	503 ENGINE	integration	—
GET	/api/v1/signals/latest	signals	signals.py	READ_ONLY	N	Y	404	contracts+integration	nexus api signals
GET	/api/v1/signals/history	signals	signals.py	READ_ONLY	N	Y	422	contracts+integration	—
GET	/api/v1/decisions	decisions	decisions.py	READ_ONLY	N	Y	422	contracts+integration	nexus api decisions
GET	/api/v1/decisions/latest	decisions	decisions.py	READ_ONLY	N	Y	404	contracts+integration	nexus api decisions --latest
GET	/api/v1/decisions/stats	decisions	decisions.py	READ_ONLY	N	Y	—	integration	—
GET	/api/v1/decisions/no-trade	decisions	decisions.py	READ_ONLY	N	Y	—	integration	—
GET	/api/v1/decisions/no-trade/reasons	decisions	decisions.py	READ_ONLY	N	Y	—	integration	—
GET	/api/v1/decisions/{decision_id}	decisions	decisions.py	READ_ONLY	N	Y	404	contracts+integration	nexus api decisions --id X
GET	/api/v1/decisions/{decision_id}/evidence	decisions	decisions.py	READ_ONLY	N	Y	404	integration	—
GET	/api/v1/decisions/{decision_id}/gates	decisions	decisions.py	READ_ONLY	N	Y	404	contracts+integration	nexus api decisions --id X --gates
GET	/api/v1/decisions/{decision_id}/explanation	decisions	decisions.py	READ_ONLY	N	Y	404	contracts	—
GET	/api/v1/positions	positions	positions.py	READ_ONLY	E	N	503 ENGINE, 503 DEP	contracts+integration	—
GET	/api/v1/positions/{ticket}	positions	positions.py	READ_ONLY	E	N	404, 503 ENGINE	integration	—
GET	/api/v1/positions/history/{ticket}	positions	positions.py	READ_ONLY	N	Y	404	integration	—
GET	/api/v1/execution/status	execution	positions.py	READ_ONLY	E	N	503 ENGINE	contracts+integration	—
GET	/api/v1/execution/history	execution	positions.py	READ_ONLY	N	Y	422	contracts+integration	—
GET	/api/v1/model/status	model	positions.py	READ_ONLY	E	N	503 ENGINE	contracts+integration	—
GET	/api/v1/model/identity	model	positions.py	READ_ONLY	E	N	503 ENGINE	contracts+integration	nexus api model
GET	/api/v1/model/contracts	model	positions.py	READ_ONLY	E-soft	N	—	contracts	—
GET	/api/v1/model/champion	model	positions.py	READ_ONLY	E-soft	N	—	contracts	—
GET	/api/v1/features/status	features	positions.py	READ_ONLY	E	N	503 ENGINE	contracts	—
GET	/api/v1/features/contract	features	positions.py	READ_ONLY	N	S	503 DEP	contracts+integration	nexus api features
GET	/api/v1/features/groups	features	positions.py	READ_ONLY	N	S	503 DEP	contracts	—
GET	/api/v1/features/current	features	positions.py	READ_ONLY	E	N	503 ENGINE	contracts	—
GET	/api/v1/risk/status	risk	risk.py	READ_ONLY	E	N	503 ENGINE	contracts+integration	—
GET	/api/v1/risk/summary	risk	risk.py	READ_ONLY	E	N	503 ENGINE	contracts	—
GET	/api/v1/research/status	research	research.py	READ_ONLY	N	Y	503 DEP	contracts+integration	—
GET	/api/v1/research/strategies	research	research.py	READ_ONLY	N	Y	422, 503 DEP	contracts	—
GET	/api/v1/research/strategies/{strategy_id}	research	research.py	READ_ONLY	N	Y	404, 503 DEP	contracts	—
GET	/api/v1/research/runs	research	research.py	READ_ONLY	N	Y	422, 503 DEP	contracts+integration	—
GET	/api/v1/research/datasets	research	research.py	READ_ONLY	N	Y	503 DEP	contracts	—
GET	/api/v1/shadow/status	shadow	shadow.py	READ_ONLY	N	Y	—	contracts+integration	—
GET	/api/v1/shadow/runs	shadow	shadow.py	READ_ONLY	N	Y	422	contracts+integration	—
GET	/api/v1/shadow/runs/{run_id}	shadow	shadow.py	READ_ONLY	N	Y	404	contracts	—
GET	/api/v1/shadow/decisions	shadow	shadow.py	READ_ONLY	N	Y	422	contracts	—
GET	/api/v1/shadow/70d	shadow	shadow.py	READ_ONLY	N	Y	—	contracts	—
GET	/api/v1/observability/events	observability	incidents.py	READ_ONLY	N	Y	422	contracts	—
GET	/api/v1/observability/metrics	observability	incidents.py	READ_ONLY	E-soft	N	—	contracts+integration	—
GET	/api/v1/audit/events	audit	incidents.py	READ_ONLY	N	Y	422	contracts+integration	—
GET	/api/v1/incidents	incidents	incidents.py	READ_ONLY	N	Y	422	contracts+integration	—
GET	/api/v1/incidents/stats	incidents	incidents.py	READ_ONLY	N	Y	—	contracts	—
GET	/api/v1/incidents/{incident_id}	incidents	incidents.py	READ_ONLY	N	Y	404	contracts+integration	—
GET	/api/v1/incidents/{incident_id}/timeline	incidents	incidents.py	READ_ONLY	N	Y	404	contracts	—
GET	/api/v1/database/status	database	incidents.py	READ_ONLY	N	Y	—	contracts+integration	—
GET	/api/v1/database/integrity	database	incidents.py	READ_ONLY	N	Y	503 DEP	contracts	—
GET	/api/v1/database/tables	database	incidents.py	READ_ONLY	N	Y	503 DEP	contracts	—
GET	/api/v1/config	config	incidents.py	READ_ONLY	E	N	503 ENGINE	contracts	—
GET	/api/v1/config/schema	config	incidents.py	READ_ONLY	N	S	—	contracts+integration	—
POST	/api/v1/config/validate	config	incidents.py	SAFE_VALIDATION	N	S	422	contracts+integration	—

68 documented operations (63 GET + 5 POST). Drift-protected by scripts/dev/api_skill_drift_check.py.

---

5. ENVELOPE CONTRACT (§3 of spec of record)

Success — data present:

{"data": <payload>, "meta": {"request_id": "req_ab12cd34", "generated_at": "2026-09-02T10:00:00+00:00"}}

Error — error present, data absent:

{"error": {"code": "RESOURCE_NOT_FOUND", "message": "...", "details": {}, "request_id": "req_...", "retryable": false}}

Rules:

• Exactly one of data/error at top level. Never both, never neither (2xx always has data).
• meta.request_id: echoes the client X-Request-ID when supplied (truncated 64 chars), else server-generated req_<10hex>.
• meta.generated_at: server wall clock at response build, UTC ISO-8601 (+00:00). It is a RESPONSE time, not an event time — never use it to order domain events (use the domain's own timestamps, e.g. generated_at on audit rows).
• Serialization: enums → .value strings; datetimes → UTC-aware ISO-8601 (naive datetimes are stamped UTC); Pydantic models → model_dump(). Handled centrally in common.jsonable()/ok() — routes never hand-roll it.
• null semantics: None means unknown/unavailable/not-yet-computed (e.g. regime:null before first inference, mt5:null without adapter). It NEVER means zero/empty/healthy.
• Unavailable subsystem blocks inside a 200 body (e.g. shadow store blocks) carry their own null/available:false and are failure-isolated — a null block is not a platform error.

6. ERROR CONTRACT (all real codes — none invented)

code	HTTP	retryable	server condition	client/agent action
VALIDATION_ERROR	422	no	bad query/pagination/body (incl. FastAPI request validation)	fix the request; error.details.errors[] names fields
RESOURCE_NOT_FOUND	404	no	id unknown OR dataset legitimately empty (e.g. no incidents yet)	do NOT retry blindly; distinguish empty-vs-missing via list endpoints
METHOD_NOT_ALLOWED	405	no	wrong verb on v1 path	use the documented method
PAYLOAD_TOO_LARGE	413	no	oversized body	shrink request
CONFLICT	409	no	state conflict (reserved)	re-read state first
ENGINE_UNAVAILABLE	503	yes	API server running without attached engine/adapter	NOT an empty dataset, NOT zero positions, NOT a healthy engine — a missing dependency; retry after engine start or use DB-backed routes
DEPENDENCY_UNAVAILABLE	503	yes	backing store/registry/health-engine read failed	retry with backoff; check logs via request_id
RESOURCE_UNAVAILABLE	503	yes	transient resource (reserved, same family)	retry
TIMEOUT	504	yes	upstream timeout (reserved)	retry bounded
INTERNAL_ERROR	500	no	unhandled exception (full detail logged under request_id)	report bug with request_id; never assume data validity

Handlers: web/api_v1/errors.py (path-guarded — legacy routes keep legacy bodies).

7. ENGINE-DEPENDENT BEHAVIOR MATRIX

Dependency classes (verified per route, §4 registry):

class	behavior when ENGINE absent (server up, engine=None)	routes
E (engine/adapter hard)	503 ENGINE_UNAVAILABLE	market/* (5), positions (2 GET on adapter), risk/* (2), execution/status, model/status, model/identity, features/status, features/current, runtime/freshness, system/refresh
E-soft (engine fields degrade truthfully)	HTTP 200 with engine_attached:false / nulls	system/status·health·readiness·runtime·workers, runtime/mode, model/contracts, model/champion, observability/metrics
DB (audit DB-backed)	fully functional (real SQLite reads); empty tables → truthful 404/empty pages	signals/, decisions/, execution/history, positions/history/{ticket}, research/, shadow/, incidents/, observability/events, audit/events, database/
STATIC (schema/config/build)	fully functional offline	features/contract·groups, config/schema, system/version

Interpretation rules for agents:

• 503 ENGINE_UNAVAILABLE ≠ empty dataset ≠ zero positions ≠ healthy engine ≠ successful operation. It means: the dependency was absent at request time.
• Engine states: READY (all E routes 200), STOPPED (server may still be up; E routes may attach but return stopped-state truthfully), NOT_INITIALIZED/UNAVAILABLE (E routes → 503), DEGRADED (see /system/health layers).
• Environment matrix (verified):

environment	behavior
EMBEDDED (create_v1_app() + TestClient)	no engine → E routes 503; DB routes need a repo on app.state.audit_v1_repo or default-path artifacts DB
LIVE uvicorn (dashboard create_app)	full surface; engine-dependent routes reflect the attached engine
PAPER/REPLAY/SHADOW/LIVE engine modes	no route-class change — modes affect engine payload content, not API availability
NO ENGINE at all	v1 standalone app still serves DB/STATIC routes (CLI + tests rely on this)

8. READ/WRITE & SIDE-EFFECT CLASSIFICATION

class	count	operations	broker reach
READ_ONLY	63	all GETs in §4	none
SAFE_VALIDATION	3	runtime/mode/validate, runtime/mode/preview, config/validate — pure functions, zero state change	none
REFRESH	1	system/refresh — re-reads adapter snapshots, bumps UI versioner	none (snapshot reads only)
DIAGNOSTIC	1	system/diagnostics/run — bounded offline selftest, caches result	none
STATE_AFFECTING	0	—	none
EXECUTION_CAPABLE	0	v1 can never submit/modify/close an order	none

ABSOLUTE RULE: NO REAL TRADING FROM AGENT API TESTS. The v1 platform has no order path at all; still, tests must use TestClient / embedded apps / PAPER / REPLAY / MOCK fixtures only. Live-mode selection, engine toggling, model training/promotion and SQL consoles remain legacy-console/CLI owned and are out of scope for agent API testing.

9. PAGINATION CONTRACT

• Params: page (default 1, ≥1), page_size (default 50, 1..200). Violations → 422 VALIDATION_ERROR.
• Shape: data{items[], page, page_size, has_more}. has_more is the ONLY continuation signal; no total counts (full-scan protection).
• Ordering: stable (id DESC or documented store order); repeated identical queries return identical data (meta timestamp varies).
• Invariants proven by tests: no duplicates across pages, no skipped rows, page k = exact slice rows[(k-1)*s : k*s] of the unpaginated order.
• Filters compose with pagination; indexed columns only (see §10).

Example:

GET /api/v1/decisions?page=2&page_size=5
→ {"data": {"items": [...5...], "page": 2, "page_size": 5, "has_more": true}, "meta": {...}}

10. FILTER CONTRACT (verified bounds)

filter	routes	type	semantics	bound
symbol	signals/history, decisions, execution/history, market/quote·snapshot, positions	str ≤32	exact match	—
action	signals/history, decisions	str	upper-cased exact (BUY/SELL/NO_TRADE)	—
status	execution/history, audit/events, incidents	str ≤24	exact match	—
severity/category/component	incidents	str ≤24/32/48	exact match	—
execution_mode, decision_stage	decisions	str	exact match	—
event_type	observability/events	str ≤48	exact match	—
lifecycle	research/strategies	str ≤32	exact match	—
strategy_id	research/runs	str ≤64	exact match	—
run_id	shadow/decisions	str ≤64	exact match	—
hours_back	signals/history, decisions	int	generated_at lower bound (UTC)	1..720 (decisions enforce via Query ge/le; signals caps server-side)
limit	market/bars	int	bar count	≤500

All filters are parameterized SQL/store parameters — never string-interpolated. Unbounded queries are impossible (server-side LIMIT always injected).

11. TIME CONTRACT

• Transport: ISO-8601, timezone-aware, UTC (+00:00). Naive datetimes are stamped UTC by common.jsonable() before serialization.
• meta.generated_at = response build time — NOT event time.
• Domain event times (e.g. generated_at on decisions, timestamp on ledger rows) are the ONLY ordering truth for domain events.
• freshness endpoints carry engine-model stage ages — the authoritative "is data fresh" signal.
• WARNING: never mix local time, UTC, and broker/server time. MT5 epochs are SERVER-LOCAL (GMT+3, BUG-070) — raw epoch fields from broker snapshots are not UTC. Convert only with the broker-aware providers; do not epoch-math in agents.

12. REQUEST ID / CORRELATION / IDEMPOTENCY

• X-Request-ID (any HTTP request): accepted on ALL v1 routes; echoed as meta.request_id + X-Request-ID response header + server log correlation. Max 64 chars.
• Idempotency-Key (POSTs): echoed as meta.idempotency_key (≤128 chars). v1 POSTs are naturally idempotent (validate/refresh/diagnostics) — no server-side dedup store; the echo is for caller-side correlation.
• Retry guidance: retryable codes (503/504) may be retried with backoff using the SAME request id for traceability; non-retryable (4xx/500) must not be retried unchanged.
• All failures are logged internally with the same request_id — quote it in bug reports.

13. VERSIONING + OPENAPI

• Single mount: /api/v1 from web/api_v1_wiring.py. Incompatible changes → /api/v2 (never break v1 in place).
• OpenAPI: GET /openapi.json on the v1 app (or dashboard app) — 100% operation coverage enforced (68/68).
• Regenerate snapshot: .venv/Scripts/python.exe scripts/dev/api_openapi_snapshot.py → artifacts/api/openapi_snapshot.json (sorted, timestamp-free, deterministic).
• Detect drift: .venv/Scripts/python.exe scripts/dev/api_openapi_diff.py OLD.json NEW.json --fail-on-breaking — BREAKING = removed endpoint/method or request-schema change → exit 2; additions → note, exit 0.
• APISkill drift: .venv/Scripts/python.exe scripts/dev/api_skill_drift_check.py — this file ↔ live OpenAPI (missing/extra ops, count mismatch) → exit 1 on drift.
• Breaking changes REQUIRE explicit review (change-control entry + taskboard row) before merge.

14. EXTENSION WORKFLOW (adding an API — the ONLY sanctioned path)

1. Define the contract (purpose, request, response, errors) in docs/api/API_PLATFORM_V1.md §7 inventory.
2. Implement the route in the matching web/api_v1/<domain>.py (reuse common.ok/fail/parse_pagination/build_page/fetch_rows_bounded; no god router, no inline SQL from user input).
3. Wire nothing new if the domain router already exists (single mount covers it); new domains require a new module + wiring import in _include_routers.
4. Add contract tests (tests/unit/test_api_v1_contracts.py) + integration tests (tests/integration/test_api_v1_platform.py) incl. engineless 503 or DB fixture paths.
5. ruff check --fix && ruff format && mypy on touched files.
6. Regenerate snapshot; run api_openapi_diff.py OLD NEW --fail-on-breaking; run api_contract_check.py (expect N+1 ops documented).
7. Update docs/api/API_REFERENCE.md + §3/§4 of THIS file (drift check must PASS).
8. api_smoke.py --embedded PASS; benchmark if performance-sensitive.
9. Commit (<AGENT>:<task> convention), push, verify origin/main == HEAD.

Removal workflow: deprecate first (mark in docs + snapshot note), name the replacement, keep serving through the compatibility window, then remove code + docs + snapshot entries + add a regression test asserting the removal — never leave dead documentation claiming the route exists.

15. TOOLING REFERENCE (scripts/dev/)

tool	purpose	input	output	exit codes
api_smoke.py	per-domain reachability + truthfulness	--embedded (no server) or --live BASE_URL	per-domain ✓/○/✗ + API_SMOKE = PASS|FAIL	0/1
api_contract_check.py	OpenAPI quality gate: route↔spec parity, summaries/tags, schema refs, secret-shape scan, min-capability floor	none (embedded app)	API CONTRACT CHECK = PASS (68 operations…)	0/1
api_openapi_snapshot.py	deterministic artifact for drift detection	--out PATH	sorted JSON snapshot	0
api_openapi_diff.py	snapshot-vs-snapshot breaking-change classifier	OLD.json NEW.json [--fail-on-breaking]	BREAKING/note lines + verdict	0 compatible, 2 breaking, 1 IO
api_benchmark.py	bounded local perf (median/p95/p99, ≤300 req/route, read-only)	--requests N	per-route table + API_BENCHMARK = PASS|PASS_WITH_NOTES (p95 budget 250ms)	0
api_skill_drift_check.py	THIS file ↔ live OpenAPI sync	none	APISKILL DRIFT = PASS|FAIL	0/1

16. CLI → API MAP (verified from cli/api_commands.py)

command	endpoint(s)
nexus api status	/api/v1/system/status (human rendering)
nexus api health	/api/v1/system/health
nexus api version	/api/v1/system/version
nexus api capabilities	/api/v1/system/capabilities
nexus api mode	/api/v1/runtime/mode
nexus api signals	/api/v1/signals/latest
nexus api decisions [--latest | --id X [--gates]]	/api/v1/decisions/latest, /api/v1/decisions, /api/v1/decisions/{id}, /decisions/{id}/gates
nexus api model	/api/v1/model/identity
nexus api features	/api/v1/features/contract
nexus api diagnostics [--run]	POST /api/v1/system/diagnostics/run, GET /api/v1/system/diagnostics
nexus api get PATH [--page --page-size]	any /api/v1/* path
nexus api smoke	all domains via the Python client → API_SMOKE = PASS

All CLI commands consume NexusApiClient over real HTTP (--base-url / NEXUS_API_BASE, default http://127.0.0.1:8080) — the SAME contracts as external clients; zero duplicated logic.

17. NEXUSAPICLIENT CONTRACT

from nexus_scalp.api_client import NexusApiClient, NexusApiError, DEFAULT_BASE_URL

client = NexusApiClient("http://127.0.0.1:8080", timeout=10.0, headers={})
client.get(
    path, params=...
)  # → envelope dict {"data","meta"} (+ "pagination" keys inside data on lists)
client.post(path, json_body=..., idempotency_key=...)
# typed shortcuts: system_status/health/version, capabilities, runtime_mode,
# market_quote, signals_latest/history, decisions_latest/decisions/
# decision_detail/decision_gates, positions, risk_status, execution_status,
# model_status/identity, features_contract, research_status, shadow_status,
# incidents, database_status, observability_metrics, run_diagnostics

• Path normalization: leading /api/v1 auto-prepended (client.get("incidents") works).
• Errors raise NexusApiError(code, message, request_id, retryable, status, details) — parsed from the v1 error envelope; transport failures raise the same type with code=DEPENDENCY_UNAVAILABLE, retryable=True.
• No automatic retries inside the client (agents decide policy per retryable).
• No pagination helpers beyond passing params — the envelope IS the contract.

18. AGENT CALLING PATTERNS (verified commands)

# discovery
nexus api capabilities
curl -s http://127.0.0.1:8080/api/v1/system/capabilities

# operational truth
nexus api status
curl -s -H "X-Request-ID: req_agent_001" http://127.0.0.1:8080/api/v1/system/status

# decision forensics
nexus api decisions --latest
curl -s http://127.0.0.1:8080/api/v1/decisions/req_ab12cd34/gates

# paginated + filtered
curl -s "http://127.0.0.1:8080/api/v1/decisions?page=2&page_size=50&symbol=XAUUSD&action=NO_TRADE"

# validation POST (no state change)
curl -s -X POST http://127.0.0.1:8080/api/v1/runtime/mode/validate \
     -H "Content-Type: application/json" -d '{"mode": "PAPER"}'

# test batteries (NO live trading — embedded/TestClient/PAPER only)
python scripts/dev/api_smoke.py --embedded
python scripts/dev/api_smoke.py --live http://127.0.0.1:8080
python scripts/dev/api_contract_check.py
python scripts/dev/api_skill_drift_check.py
.venv/Scripts/python.exe -m pytest tests/unit/test_api_v1_contracts.py tests/integration/test_api_v1_platform.py -q

19. TEST MAP (real files — do not invent others)

domain/aspect	tests
envelope/pagination/sanitize/errors/capabilities/versioning	tests/unit/test_api_v1_contracts.py
full request paths + fixtures + fuzz + security + additive wiring	tests/integration/test_api_v1_platform.py
cross-surface state truth (CLI/API/runtime parity)	tests/unit/test_state_truth_parity.py
client E2E golden journeys (live HTTP against the API)	tests/e2e_client/ (e2e_harness.py, j1_golden.py, j2_mode_switch.py, j3_signal_decisions.py, j4_resilience.py)
perf	scripts/dev/api_benchmark.py (manual, bounded)

20. SECURITY RULES FOR AGENTS

MUST NOT:

• expose secrets/tokens/passwords/broker credentials (sanitizer masks token|password|secret|apikey|api_key|credential|login|account_number-shaped keys → ***; report any leak as a BUG)
• expect or extract stack traces/filesystem paths/SQL from error bodies (they are contractually absent; internal detail lives in logs only)
• attempt SQL/shell/command injection via params or IDs — hostile-input handling is tested (bounded fuzz: 4xx envelope, never 500); do not try to bypass it
• execute arbitrary SQL anywhere (v1 has no SQL endpoint; the legacy db-console SQL route is UI-owned and out of scope for agents)
• call anything that could reach a broker in tests (§8: v1 has zero execution path; keep it that way — TestClient/PAPER/REPLAY only)
• hammer endpoints: bounded requests only (pagination caps exist for a reason; benchmark tool is the sanctioned load path)

21. PERFORMANCE CONTRACT

Protections (verified): health 3s TTL cache + daemon prewarm at mount; version memoization; O(1) /database/status (integrity is explicit); pagination caps; server-side LIMITs; hours_back windows.

• Run api_benchmark.py after adding routes or touching stores. Regression = p95 > 250ms on a previously-green route, or any route newly over budget.
• Do not hard-code old numbers in agent logic; measure current.

22. DOMAIN GUIDANCE (avoid asking the wrong endpoint)

domain	USE WHEN	does NOT answer	dependencies	common misuse
decisions	why was X traded/rejected; NO_TRADE analysis; evidence replay	live market state, model weights	audit DB	treating decision_id as broker ticket (that's positions/{ticket})
model	which artifact is SERVING (/model/identity), warmup/inference state	training/provenance lineage (use /research/runs, legacy /api/models/*)	engine bundle	conflating champion-registry with serving-bundle truth — /model/champion is bundle-authoritative
features	active 70D contract (SSoT), last vector	historical vectors (not stored per-tick for API)	schema contract / engine	expecting per-feature history
risk	last proposal risk checks, current exposure	policy edits (none exist in v1)	engine + adapter	reading risk_checks as a guarantee of future acceptance
runtime	mode/freshness truth	mode CHANGES (validate-only; apply is console/CLI)	engine	applying a mode via API (impossible by design)
shadow	70D observer health/disagreements/drift	promotion decisions (governance legacy)	audit DB	interpreting observer counters as champion impact
research	runs/strategies/datasets lineage	live training control	audit DB	using /research/runs as model registry
incidents	incident inventory/timelines/stats	real-time alerting (that's Telegram notifier)	audit DB	polling faster than bounded pages allow

23. ONE QUESTION → ONE API (routing table)

question	endpoint
What is the engine currently doing?	/api/v1/system/status
Can the system accept work?	/api/v1/system/readiness (data.ready)
Which layers failed and why?	/api/v1/system/health (checks)
What model is actually serving?	/api/v1/model/identity
What feature contract is active?	/api/v1/features/contract
Why was a decision rejected?	/api/v1/decisions/{id}/gates (+ /evidence)
What NO_TRADE reasons occurred?	/api/v1/decisions/no-trade (+ /no-trade/reasons)
Is market data fresh?	/api/v1/runtime/freshness
What capabilities exist?	/api/v1/system/capabilities
What incidents exist?	/api/v1/incidents (+ /stats)
Current exposure/margin?	/api/v1/risk/summary
What changed in the audit ledger?	/api/v1/audit/events
Is the broker connected?	/api/v1/execution/status
Database healthy?	/api/v1/database/status (+ /integrity)
What config is effective (sanitized)?	/api/v1/config
Would a mode change be valid?	POST /api/v1/runtime/mode/validate (never apply)

24. TRUTH / CONSISTENCY RULES

• Never infer READY/HEALTHY/LIVE/TRADING/MODEL_VALID/DATA_FRESH from a single field unless the contract states it. Compose: readiness.ready + health.checks + runtime/freshness.
• Authoritative endpoints per fact: serving model → /model/identity (bundle), NOT governance pages; mode → /runtime/mode; data freshness → /runtime/freshness; decision truth → audit-backed /decisions/*.
• Compare snapshots via meta.request_id/generated_at; different endpoints sampled at different times legitimately differ — do not manufacture contradictions from timestamp skew.
• 503 ≠ empty. null ≠ zero. available:false ≠ error.

25. DISCOVERY WORKFLOW (recommended for a fresh agent)

1. nexus api capabilities (or read §4 registry here)
2. nexus api status (operational posture)
3. consult §23 routing table → call the specific endpoint
4. verify assumptions with api_smoke.py --embedded / --live
5. extend? → §14 workflow; check drift after docs edits: api_skill_drift_check.py

26. HISTORICAL RECONCILIATION (why the old tree is gone)

legacy 257→280 dashboard routes (UI-owned, still served) → first /api/v1 tree (src/nexus_scalp/api/v1, 45 routes, superseded envelope — committed mid-flight by a parallel session) → spec-of-record authored (docs/api/API_PLATFORM_V1.md, 65 capabilities) → consolidation decision: the WIP web/api_v1 tree matched the spec's envelope/pagination/error contracts, so it became canonical; the 45-route tree was DELETED (e51a910) and its salvable patterns (store queries, exception handlers) were ported → current 68 operations, drift-protected.

Never resurrect src/nexus_scalp/api/v1. Its paths are NOT current. Any agent finding references to it (old docs, old sessions) must treat them as historical context only.

27. STALENESS / DRIFT DETECTION (contract)

Sync axes: implementation ↔ OpenAPI ↔ API reference ↔ APISkill ↔ tests. Any mismatch = documentation/contract defect (file it, don't paper over it).

python scripts/dev/api_contract_check.py      # implementation ↔ OpenAPI
python scripts/dev/api_openapi_snapshot.py    # regenerate artifact
python scripts/dev/api_openapi_diff.py OLD NEW --fail-on-breaking   # snapshot ↔ snapshot
python scripts/dev/api_skill_drift_check.py   # THIS FILE ↔ OpenAPI

Update order when changing APIs: code → tests → snapshot → docs → THIS file → re-run all four checks.

28. SKILL SELF-AUDIT (Phase 33 — answered)

1. discover every current API? ✅ §3 + §4 registry (drift-enforced 68/68)
2. current vs legacy? ✅ §1/§2 status classes + §26 reconciliation
3. right endpoint for common questions? ✅ §23
4. engine-dependency per endpoint? ✅ §4 E/E-soft/N columns + §7 matrix
5. error semantics? ✅ §6 (all real codes)
6. construct a valid request? ✅ §5/§9/§10/§18
7. correct smoke/contract test? ✅ §15/§19
8. safe testing (no live trading)? ✅ §8/§20
9. identify breaking change? ✅ §13 (diff tool + exit codes)
10. extend without a second API tree? ✅ §14 (single-mount, single-tree rule)