Skip to content

Phase 01 Paper E2E Verification

This runbook proves the active continuation path remains paper-safe and reconciles broker execution into the journal.

What It Verifies

  • Production /ready is healthy before triggering the pipeline.
  • /pipeline/run is called with confirm_live=false.
  • The pipeline reaches status=executed.
  • The broker stage reports execution_mode=paper and paper_trading=true.
  • The journal stage returns a journal_trade_id.
  • The response includes a trace_id for SigNoz/Phoenix follow-up.

Required Environment

```bash export TRADEMATE_API_URL="https://api.yourtrademate.io" export TRADEMATE_API_BEARER_TOKEN="" export TRADEMATE_CONFIRM_PAPER_E2E="paper" export TRADEMATE_PHASE01_TICKER="AAPL"

Optional deterministic mode, only after enabling the API env gate:

export TRADEMATE_PHASE01_TEST_MODE="true"

```

The authenticated user must have an active paper Alpaca broker connection and a paper portfolio that the pipeline can select. Do not use a live-only portfolio for this check.

For deterministic broker + journal reconciliation evidence, enable the API env gate TRADEMATE_PAPER_E2E_TEST_MODE_ENABLED=true and run the verifier with --test-mode. This uses /pipeline/paper-e2e, synthesizes a tiny paper-only verification signal, and still requires an authenticated user, paper portfolio, active Alpaca paper connection, broker execution, local trade persistence, and journal webhook success. The normal /pipeline/run path remains strategy-led and may legitimately block when agents issue hold.

Dry Run

bash python scripts/verify_phase01_paper_e2e.py --dry-run

Preflight

Run the read-only prerequisite check before placing a paper order:

bash python scripts/verify_phase01_paper_e2e.py --preflight

Preflight validates:

  • Production /ready.
  • The bearer token is accepted by authenticated API routes.
  • The user has an active Alpaca connection.
  • At least one paper portfolio is attached to that active Alpaca connection.

Do not run the full paper E2E until preflight succeeds.

Run Verification

```bash python scripts/verify_phase01_paper_e2e.py --confirm-paper-e2e

Deterministic paper-only route, after the API env gate is enabled:

python scripts/verify_phase01_paper_e2e.py --confirm-paper-e2e --test-mode ```

The script prints JSON evidence containing the API URL, ticker, idempotency key, readiness status, broker order id, journal trade id, and trace id. It does not print the bearer token.

Trace Follow-Up

Use the emitted trace_id to confirm traces in:

  • SigNoz: API and HTTPX spans for /pipeline/run, broker, and journal calls.
  • Phoenix: LLM/agent spans if the strategy/risk path used model-backed agents.

Failure Handling

  • Set --confirm-paper-e2e: the safety acknowledgement was missing.
  • TRADEMATE_API_BEARER_TOKEN is required: fetch a fresh short-lived JWT from the authenticated app session and set it only in the local shell running this verification.
  • /ready did not report ready: fix production dependencies before retrying.
  • no active Alpaca connection: reconnect Alpaca in the app, then rerun preflight.
  • no paper portfolio attached: create or update a paper portfolio that uses the active Alpaca broker connection, then rerun preflight.
  • Pipeline did not execute: inspect the returned stage and block reason. If /pipeline/run blocks at run_strategy_agents because agents issue hold, use the env-gated --test-mode run for deterministic Phase 01 broker/journal evidence.
  • POST /pipeline/paper-e2e returned HTTP 404: enable TRADEMATE_PAPER_E2E_TEST_MODE_ENABLED=true on the API service and redeploy.
  • does not prove paper execution: stop immediately; the selected portfolio or environment is unsafe for this verification.
  • missing journal_trade_id: broker execution happened but journal reconciliation failed; inspect canonical trade journal_status and pending reconciliation audit events.

Evidence To Attach To Phase 01

  • Script JSON output.
  • SigNoz trace screenshot or link for the emitted trace_id.
  • Phoenix trace screenshot or link when LLM spans are produced.
  • Journal trade URL or id.
  • Any reconciliation retry output if the first journal write failed and later recovered.