AI Agent & Programmatic Access

The platform exposes the same signal intelligence three ways — a versioned JSON REST API, a Model Context Protocol (MCP) server, and a Server-Sent Events (SSE) push stream. Every surface returns the same numbers from the same in-process helpers, so an agent reading /signals/latest, calling the MCP market_pulse tool, and watching the SSE stream cannot see the dashboard drift from itself.

Your environment

• Base URL: https://bigclawd.com — versioned routes live under /api/v1/...
• Timezone: Eastern Time (ET). Every persisted and emitted timestamp is ET ISO 8601 with explicit offset (Law 1).
• Asset universe: stocks, ETFs, options supported by the brokerage market-data feed. /api/v1/trading/tickers returns a curated S&P 500 + ETF reference list.
• Market hours: Monday–Friday, 09:30–16:00 ET. Public read routes serve 24/7; trading routes enforce the clock at both initiation and confirmation. Full release / cycle / lifecycle posture lives at /kb/operations/schedule.

Three ways to consume

REST JSON API. 104 routes under /api/v1/.... Public read routes (signals, alerts, reports, agents) are unauthenticated; trading routes require a Bearer token; FinRep-AI + ai-brief routes require an internal token. Versioned; pinned via schema_version on every typed surface. → details below and per-route articles at /kb/api.

MCP server. 11 tools at https://bigclawd.com/mcp — 8 public (no auth), 3 trading (Bearer token in Authorization). Suitable for Claude Desktop, Claude Code, Cursor, and any other MCP-aware client. Each tool wraps a curated cluster of REST routes into one round-trip. → details at /kb/mcp and the per-tool articles.

SSE event stream. GET /api/v1/agents/stream opens a persistent connection. Emits a snapshot event on connect, then regime_change, critical_fired, critical_resolved events as they happen, plus a heartbeat every ~30s of silence. Use instead of busy-looping /agents/pulse when you want push notification of regime flips and critical alerts. → details at /kb/api.

Authentication

Four tiers. The header / posture each surface requires:

The X-Internal-Token tier is what gates /finrep-ai/*, /ai-brief/*, /ai1/*, /ai2/* (except the two deliberate public exceptions, /ai2/verdict and /ai2/history), brief calibration + drift + datapoints + pack-stats + calendar-lookahead, and the FinRep-AI usage ledger, plus a handful of internal-token routes on the company/screener surfaces. Public clients without the header get 401; misconfigured deployments (env var unset on the backend) return 503 with a CRITICAL server-side log. The count churns as the platform grows — CLAUDE.md’s route-decorator inventory is the live source of truth (42 as of this writing); treat “40+” here as a floor, not a ceiling. The catalog generator excludes them from the public per-route articles, so they only surface here.

Common queries — worked examples

Start every session with /agents/pulse. Drill into the typed shape when you need it.

Start-of-session pulse check

One round-trip; same helpers as the rendered report.

curl -s https://bigclawd.com/api/v1/agents/pulse

Returns {schema_version, generated_at, age_seconds, regime, health_score, headline, summary, what_changed, active_alerts: {count, by_severity, top: [...]}, key_numbers: {...}}. Mirrors /signals/latest so the agent narrative cannot drift from the dashboard. → details at /kb/api/get-agents-pulse.

The MCP equivalent is the market_pulse tool — same payload, slightly trimmed for token economy. → /kb/mcp/market-pulse.

Full signal snapshot

curl -s https://bigclawd.com/api/v1/signals/latest

Carries schema_version: "2027.28" and ~40 typed sub-objects (positioning, correlations, energy, inflation, volatility, zero_dte, gamma_levels, dealer_gamma, alignment, freshness, rotation, …). Pin on schema_version if your code depends on the shape. The legacy ?flat=* shim returns HTTP 410 Gone — read the typed sub-objects, not the flat duplicates (Law 5).

Event feed — transition stream

curl -N https://bigclawd.com/api/v1/agents/stream

-N disables curl’s output buffering so the SSE frames arrive as they fire. Use this instead of polling /agents/pulse every 5 seconds — the server polls every 5s internally and pushes the deltas. Heartbeat every ~30s tells you the connection is alive. → details at /kb/api/get-agents-stream.

Historical pattern match — “when has this happened before?”

curl -s 'https://bigclawd.com/api/v1/signals/base-rates?mode=hybrid&top_k=100'

Matches today’s 13-numeric + 3-categorical signal vector against history. Returns forward 1d/3d/5d SPY return distribution with bootstrap CIs across the top-K analogues. Pin on the response payload’s own matcher_version field — read it fresh each call rather than hardcoding a copy here; it churns whenever the matcher’s dims, weights, or gates change (see CLAUDE.md’s Historical Base Rate Engine section for the bump policy). Defaults to mode=soft; pass mode=hybrid to opt into the tag-prefilter + Euclidean dispatch — per DOCTRINE P0 the response surfaces hybrid_fallback=true when the filter under-shoots 30 analogues and the matcher fell back to unfiltered Euclidean. → matcher details at /kb/framework/hybrid-matcher. MCP equivalent: /kb/mcp/compare-to-history.

Position-read — filter dashboard noise to your book

curl -s 'https://bigclawd.com/api/v1/agents/position-read?symbol=SPY&side=long&type=call&expiry=2026-06-21&strike=560'

Returns only the signal categories, active alerts, regime factors, and alignments that materially affect that specific position. Use when you’re holding ten positions and don’t want to re-derive relevance for each from the full snapshot. → details at /kb/api/get-agents-position-read.

REST API surface

112 routes across five files. Each row links into the per-endpoint article at /kb/api/<slug> (where the catalog generator has built one). Counts per group:

→ Full per-route articles at /kb/api. Trading specifics are at /kb/framework/trading.

MCP surface

11 tools. The MCP transport is JSON-RPC over HTTP (no SSE); every tool is a synchronous round-trip that wraps the corresponding REST cluster.

Client config (Claude Desktop / Claude Code / Cursor):

{
  "mcpServers": {
    "bigclawd": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://bigclawd.com/mcp"]
    }
  }
}

For Bearer-gated tools, add the token to the upstream environment per your client’s docs — never embed it in the JSON checked into source. → full per-tool detail at /kb/mcp.

Trading

A fully separate agent-facing surface — paper-tracked positions in /app/data/trading.db, real brokerage market prices, two-step plan-then-confirm flow with a 60-second quote window, single-execute claim via BEGIN IMMEDIATE. Account model, order shapes (stocks vs options — different endpoints!), guardrails (non-binding by default — cash is the real cap; read GET /trading/limits for the live values), and admin endpoints all live at /kb/framework/trading. Read that page before sending the first POST /trades.

Alerts for agents

The platform fires 63 defined alerts when signal conditions cross threshold (see the full catalog at /kb/alerts). Agents subscribe in three ways: poll GET /alerts/active for the current state, subscribe to GET /agents/stream (SSE) for real-time regime changes + critical fires, or register an alert_fired / alert_resolved webhook via the admin endpoints. Payloads include alert_id, severity, rendered message, and the signal value that triggered the fire.

Response conventions

• schema_version pinning. Every typed surface emits a schema_version constant (/signals/latest → "2027.28"; /signals/alignment → "2026.07"; per-route versions on the calibration / drift / datapoints surfaces). Bumped on breaking shape changes; pin on it if your code reads the typed objects.
• Law 1 timestamps. Every persisted and emitted timestamp is ET ISO 8601 with explicit offset ("2026-05-04T14:30:00-04:00"). Round-trips through datetime.fromisoformat(). Display layers emit ET — they never need to convert.
• Law 5 typed sub-objects. Group-related signals live under typed paths (energy, inflation, volatility, correlations, gamma_levels, zero_dte, alignment, positioning, freshness, rotation). The flat signals dict prunes anything that has a typed home. ?flat=* returns HTTP 410 — no escape hatch.
• Freshness classes. Every metric carries a publish-cadence tag: intraday, prior_close, weekly, monthly, quarterly, ad_hoc. Plus a staleness layer with max_age, age_seconds, status ∈ stale. Read both before trusting a value — see the per-metric freshness sub-object on /signals/latest.
• Empty data is loud. Sparse windows on the brief calibration / drift / datapoints surfaces return HTTP 200 with explicit zero counts and a _legacy_rows_skipped / unmatured_briefs field rather than 404 (DOCTRINE P0 — never silently drop, never mask coverage gaps).

Rate limits and caching

Moving-window limiter; exceeded requests return 429 Too Many Requests with a Retry-After header and {error, message, retry_after} body. Back off exponentially (2s → 4s → 8s, capped at Retry-After).

Cache-Control headers per path class:

Steady pollers: cap at ≤1 req/sec per token to stay well under the 120/min trading limit with headroom for bursty confirms. Prefer /agents/stream over busy-loop polling when you need event latency.

Error semantics

• 401 — missing or invalid auth. Bearer absent / wrong token. For X-Internal-Token, the header didn’t match; for Authorization: Bearer, the trading token didn’t match. Don’t retry; fix credentials.
• 403 — auth present but wrong tier (e.g. agent Bearer hitting an admin route). Don’t retry.
• 410 Gone — ?flat=* on /signals/latest. Read the typed sub-objects instead. No escape hatch.
• 429 — rate limited. Back off per Retry-After. Exponential retry (capped at Retry-After); never tight-loop.
• 503 — backend not ready or X-Internal-Token env var unset (default-deny on internal routes). Retry after a few seconds; check /health to see if the backend is up.

Trading-specific:

• 400 with detail dict on POST /trades/options — expired_expiration / non_trading_day / no_market / contract_not_found. Parse the dict; don’t string-match the message.
• 400 on confirm — status was already executing / executed / cancelled. Concurrent confirms hit a single-claim guard; only the first request proceeds.
• Market closed on POST /trades* and POST /trades/{id}/confirm — check /trading/market/status before the call.

Rules and limitations

• Law 3 — one canonical name per concept. “GEX” specifically means aggregate dealer gamma from the third-party dealer-gamma analytics feed. The brokerage option-chain per-strike profile is “Gamma Walls” (gamma_levels). The per-ticker gamma × OI proxy is “γ-Sent / Gamma Skew” — never call it GEX.
• news_sentiment alignment category is flag-gated. 11 categories ship by default; the 12th (news_sentiment) is gated behind ENABLE_AI_SENTIMENT_ALIGNMENT. Default off — the alignment response is the 11-category shape until the calibration gate flips it on.
• No SSE in MCP transport. MCP is request/response over JSON-RPC; the /agents/stream push surface lives only on the REST API.
• Market-hours enforcement on trading tools. plan_trade and execute_trade enforce 09:30–16:00 ET, Monday–Friday, US-equity holiday-aware. The MCP wrappers inherit the same rejection — check market_pulse first.
• Whole shares only, long only. No fractional shares, no short selling, no naked option writing.
• 60-second confirmation window. Quote expires automatically; reset by re-planning. Confirm immediately after plan_trade.

Schema version reference

Pin on these. Bumps are loud — every new shape adds an integer / dot-segment, never silently mutates an existing one.

See also

• /kb/framework/trading — trading-specific surface (account, orders, options, guardrails, admin).
• /kb/framework/hybrid-matcher — base-rate matcher modes, tag pre-filter, fallback rule.
• /kb/framework/five-level-scale — universal signal classification (Favorable / Leaning / Neutral / Cautionary / Adverse).
• /kb/framework/regime-overrides — regime-conditional health-score weighting schema.
• /kb/framework/alignment — 12-category signal-price alignment methodology.
• /kb/indicators/health-score — 18-component composite scoring.
• /kb/alerts — full alert catalog (63 defined).
• /kb/operations/schedule — cycle profiles + release calendar.
• /kb/operations/source-health — per-source health surface.
• /kb/api — per-route catalog (auto-generated).
• /kb/mcp — per-tool catalog.