API Documentation

The Finance Report backend exposes a JSON API for programmatic access to reports, signals intelligence, and alerts. All endpoints return JSON with Content-Type: application/json. See the Guide for signal interpretation and methodology.

Base URL

https://bigclawd.com

JSON API v1

GET /api/v1/reports

List all reports grouped by day, sorted newest first. Paginated by number of days.

Parameters

limit int default: 7 Number of days to return (1-90)

offset int default: 0 Number of days to skip

curl

curl "https://bigclawd.com/api/v1/reports?limit=7&offset=0"

Live Response Example

{
  "total_days": 43,
  "offset": 0,
  "limit": 1,
  "days": [
    {
      "date": "2026-04-13",
      "week": "2026-W16",
      "reports": [
        {
          "filename": "report-20260413-040020.md",
          "time": "04:00:20",
          "timestamp": "2026-04-13T04:00:20",
          "week": "2026-W16"
        },
        {
          "filename": "report-20260413-020025.md",
          "time": "02:00:25",
          "timestamp": "2026-04-13T02:00:25",
          "week": "2026-W16"
        }
      ]
    }
  ]
}

GET /api/v1/reports/latest

Get the most recent report with full Markdown content and metadata.

curl

curl "https://bigclawd.com/api/v1/reports/latest"

Live Response Example

{
  "filename": "report-20260413-040020.md",
  "date": "2026-04-13",
  "time": "04:00:20",
  "timestamp": "2026-04-13T04:00:20",
  "week": "2026-W16",
  "content": "# Finance Analyst Report: 2026-04-13 04:00:20\n\n## Market Status\n\n**Regime: CAUTIOUS** | Score: 70/100 (Favorable, with c..."
}

GET /api/v1/reports/{filename}

Get a specific report by its filename. Returns metadata and full Markdown content.

Parameters

filename path Report filename (e.g., report-20260331-090129.md)

curl

curl "https://bigclawd.com/api/v1/reports/report-20260331-090129.md"

Live Response Example

{
  "filename": "report-20260413-040020.md",
  "date": "2026-04-13",
  "time": "04:00:20",
  "timestamp": "2026-04-13T04:00:20",
  "week": "2026-W16",
  "content": "# Finance Analyst Report: 2026-04-13 04:00:20\n\n## Market Status\n\n**Regime: CAUTIOUS** | Score: 70/100 (Favorable, with c..."
}

GET /api/v1/weeks

List all available ISO weeks with report and day counts. Useful for building week-based navigation.

curl

curl "https://bigclawd.com/api/v1/weeks"

Live Response Example

{
  "weeks": [
    {
      "week": "2026-W16",
      "report_count": 3,
      "day_count": 1
    },
    {
      "week": "2026-W15",
      "report_count": 334,
      "day_count": 7
    },
    {
      "week": "2026-W14",
      "report_count": 289,
      "day_count": 7
    }
  ]
}

GET /api/v1/reports/week/{week_id}

Get all reports for a specific ISO week, grouped by day.

Parameters

week_id path ISO week identifier (e.g., 2026-W14)

curl

curl "https://bigclawd.com/api/v1/reports/week/2026-W14"

GET /health

Health check endpoint. Returns 200 if the backend is running.

curl

curl "https://bigclawd.com/health"

Live Response Example

{
  "status": "ok"
}

GET /api/v1/status

System health: checks report freshness, signal data quality, Schwab token status, and signal DB integrity. Returns issues (blocking) and warnings (degraded).

curl

curl "https://bigclawd.com/api/v1/status"

Live Response Example

{
  "status": "healthy",
  "issues": [],
  "warnings": [],
  "report_count": 42,
  "latest_report": "report-20260410-093015.md"
}

Legacy Endpoints plain text

These return raw Markdown as text/plain. They predate the JSON API and are kept for backward compatibility.

Method	Path	Description
GET	`/report`	Latest report as raw Markdown plain text
GET	`/current`	Alias for /report
GET	`/reports`	HTML list of all report files
GET	`/reports/{filename}`	Specific report as raw Markdown plain text

Signals Intelligence API v1

Real-time market regime classification, composite health score, and signal history. Reports generate every 15 minutes during market hours; signals update with each report. All routes are under /api/v1/. No authentication required.

GET /api/v1/signals/latest

Current signals snapshot: regime, health score, 13-component breakdown, 5-day trends, bridge text, leading/lagging read, sector_breadth, correlations (SPY/VIX, DXY, TNX, Oil), gamma_levels, energy regime, and inflation expectations. This is the primary endpoint for dashboard consumption.

Response includes

regime RISK-ON, CAUTIOUS, TRANSITIONAL, RISK-OFF, or PANIC

health_score Composite 0-100 score (normal markets ~55-60)

score_components Array of { name, value, points, max } for each signal

trends 5-day direction (rising/falling/flat) for each key signal

bridge_text Explains score-regime divergence when present

leading_lagging_read Predictive vs confirmatory indicator summary

signal_levels Per-signal 5-level scale (favorable → adverse)

curl "https://bigclawd.com/api/v1/signals/latest"

Live Response Example

{
  "regime": "CAUTIOUS",
  "regime_reason": "Institutional buying with positive GEX, but mixed breadth (44%).",
  "health_score": 70,
  "score_components": [
    {
      "name": "DIX",
      "value": "0.476",
      "points": 8,
      "max": 12
    },
    {
      "name": "GEX",
      "value": "+5.1B",
      "points": 12,
      "max": 12
    },
    {
      "name": "HY OAS",
      "value": "2.90%",
      "points": 10,
      "max": 10
    },
    "..."
  ],
  "trends": {
    "dix": {
      "current": 0.476,
      "previous": 0.476,
      "avg_5d": 0.471,
      "direction": "flat"
    },
    "gex": {
      "current": 5.11,
      "previous": 5.11,
      "avg_5d": 4.702500000000001,
      "direction": "flat"
    },
    "hy_oas": {
      "current": 2.9,
      "previous": 2.9,
      "avg_5d": 2.965,
      "direction": "flat"
    },
    "...": "..."
  },
  "bridge_text": "Score reads 70 (Favorable) but regime is CAUTIOUS — breadth at 44% and energy regime SHOCK keeps full risk-on classification at bay.",
  "leading_lagging_read": "Leading indicators show energy shock in progress (WTI at $97, watch for margin compression); DIX stable at 0.476; GEX positive at 5.1B (vol-suppressing). Lagging confirmation: VIX at 19.2 (low-fear environment); sentiment reads Bullish; seasonal pattern historically bullish.",
  "signal_levels": {
    "dix": {
      "level": "leaning",
      "color": "lime",
      "label": "Moderate buying"
    },
    "gex": {
      "level": "favorable",
      "color": "green",
      "label": "Vol suppression"
    },
    "hy_oas": {
      "level": "leaning",
      "color": "lime",
      "label": "Normal"
    },
    "...": "..."
  }
}

GET /api/v1/signals/history?days=30

Daily signal rows for charting. Returns trade date, key prices, regime, and health score for each day.

Parameters

days int default: 30 Number of days to return (1-365)

curl "https://bigclawd.com/api/v1/signals/history?days=30"

Live Response Example

{
  "days": 2,
  "data": [
    {
      "trade_date": "2026-04-11",
      "regime": "CAUTIOUS",
      "health_score": 70,
      "spy_close": 680.65,
      "vix_close": 19.23,
      "dix": 0.476,
      "gex": 5.11,
      "hy_oas": 2.9,
      "...": "..."
    }
  ]
}

GET /api/v1/signals/score

Current composite health score with full component breakdown. Returns each signal's raw value and its contribution to the overall score.

curl "https://bigclawd.com/api/v1/signals/score"

Live Response Example

{
  "health_score": 70,
  "components": [
    {
      "name": "DIX",
      "value": "0.476",
      "points": 8,
      "max": 12
    },
    {
      "name": "GEX",
      "value": "+5.1B",
      "points": 12,
      "max": 12
    },
    {
      "name": "HY OAS",
      "value": "2.90%",
      "points": 10,
      "max": 10
    },
    {
      "name": "Breadth",
      "value": "44%",
      "points": 3,
      "max": 8
    }
  ],
  "timestamp": "2026-04-12"
}

GET /api/v1/signals/export?format=csv

Export the full daily signals table as CSV for backtesting and analysis. All columns included.

Parameters

format string default: csv Export format (only csv supported)

curl "https://bigclawd.com/api/v1/signals/export?format=csv" -o signals.csv

GET /api/v1/signals/gamma

Gamma exposure profile from the latest SPY option chain. Returns call wall (resistance), put wall (support), spot price, and per-strike GEX profile.

curl "https://bigclawd.com/api/v1/signals/gamma"

GET /api/v1/signals/sectors

Sector breadth breakdown by GICS sector. Returns percentage of stocks above 50-day SMA per sector with stock counts.

curl "https://bigclawd.com/api/v1/signals/sectors"

GET /api/v1/signals/correlations

Rolling 20-day Pearson correlations between SPY and VIX, DXY, TNX, and Oil (USO). Includes signal classification (normal/elevated/warning) and normal ranges.

curl "https://bigclawd.com/api/v1/signals/correlations"

GET /api/v1/signals/fedwatch

Current fed funds rate, next FOMC meeting date, and market-implied rate hold/cut probabilities.

curl "https://bigclawd.com/api/v1/signals/fedwatch"

Alerts API v1

Threshold-based alert engine evaluated on each report cycle. Alerts have a lifecycle: active → resolved. Alerts auto-resolve when conditions normalize. See the Guide for severity definitions and alert descriptions. View alert history on the Alerts page.

GET /api/v1/alerts/active

All active alerts, sorted by severity. Includes severity summary counts and resolved-in-24h count.

Response includes

alerts Array of active alerts

summary { critical, warning, info, total, highest_severity }

resolved_24h Count of alerts resolved in last 24 hours

curl "https://bigclawd.com/api/v1/alerts/active"

Live Response Example

{
  "alerts": [
    {
      "id": 30,
      "alert_id": "WTI_SHOCK",
      "severity": "critical",
      "message": "WTI crude at $96.57 — energy shock territory, stagflation risk rising.",
      "fired_at": "2026-04-13T04:00:20.562663-04:00",
      "state": "active"
    },
    {
      "id": 17,
      "alert_id": "OIL_SPIKE",
      "severity": "warning",
      "message": "Oil spike alert: USO at $124.57 — potential geopolitical disruption or supply shock.",
      "fired_at": "2026-04-13T04:00:20.562663-04:00",
      "state": "active"
    },
    "..."
  ],
  "summary": {
    "critical": 1,
    "warning": 5,
    "info": 1,
    "total": 7,
    "highest_severity": "critical"
  },
  "resolved_24h": 0
}

GET /api/v1/alerts/today

All alerts fired today (Eastern Time), all states. Powers the dashboard alert feed. Includes active count and highest active severity for badge display.

curl "https://bigclawd.com/api/v1/alerts/today"

Live Response Example

{
  "date": "2026-04-13",
  "active_count": 6,
  "highest_severity": "critical",
  "alerts": [
    {
      "id": 31,
      "alert_id": "BREAKEVEN_SPIKE",
      "severity": "warning",
      "message": "5Y breakeven inflation at 2.58% — inflation expectations well above Fed target.",
      "fired_at": "2026-04-13T04:00:20.562663-04:00"
    },
    {
      "id": 30,
      "alert_id": "WTI_SHOCK",
      "severity": "critical",
      "message": "WTI crude at $96.57 — energy shock territory, stagflation risk rising.",
      "fired_at": "2026-04-13T04:00:20.562663-04:00"
    },
    "..."
  ]
}

GET /api/v1/alerts/history?days=30

Full alert history (all states) from the last N days. Sorted newest first.

Parameters

days int default: 30 Lookback window (1-365)

curl "https://bigclawd.com/api/v1/alerts/history?days=30"

Live Response Example

{
  "days": 1,
  "alerts": [
    {
      "id": 31,
      "alert_id": "BREAKEVEN_SPIKE",
      "severity": "warning",
      "message": "5Y breakeven inflation at 2.58% — inflation expectations well above Fed target.",
      "fired_at": "2026-04-13T04:00:20.562663-04:00",
      "cleared_at": null
    },
    {
      "id": 30,
      "alert_id": "WTI_SHOCK",
      "severity": "critical",
      "message": "WTI crude at $96.57 — energy shock territory, stagflation risk rising.",
      "fired_at": "2026-04-13T04:00:20.562663-04:00",
      "cleared_at": null
    },
    "..."
  ]
}

Trading API v1

The trading API enables AI agents to trade with real market prices from Schwab. All trading routes are under /api/v1/trading/.

Authentication

Public endpoints (quotes, tickers) require no auth. Agent endpoints require a Bearer token in the Authorization header. Admin endpoints require the admin token.

Authorization: Bearer <your-agent-token>

Public — Market Data

GET /api/v1/trading/market/status

Check if the market is open for trading. Returns current ET time, open/close status, and minutes until next state change.

curl "https://bigclawd.com/api/v1/trading/market/status"

GET /api/v1/trading/quote/{symbol}

Real-time stock quote from Schwab (price, bid, ask, volume, change).

curl "https://bigclawd.com/api/v1/trading/quote/AAPL"

GET /api/v1/trading/quotes?symbols=AAPL,MSFT

Batch stock quotes (max 10 symbols, comma-separated).

GET /api/v1/trading/options/chain/{symbol}

Full option chain with all expirations, strikes, bid/ask, mark, Greeks, IV, and open interest.

Parameters

expiration string Filter by date (YYYY-MM-DD)

strike_count int default: 50 Number of strikes around ATM (5-100)

curl "https://bigclawd.com/api/v1/trading/options/chain/SPY?expiration=2026-04-18"

GET /api/v1/trading/tickers

List all ~530 tradeable symbols (S&P 500 + ETFs).

Agent — Account & Positions Bearer token required

GET /api/v1/trading/account

Get current account info (balance, name, created_at).

GET /api/v1/trading/positions

All stock holdings with current market value and unrealized P&L.

GET /api/v1/trading/positions/options

All option positions with current mark price, Greeks, and P&L.

GET /api/v1/trading/history?limit=50&offset=0

Paginated trade history (stocks + options), newest first.

Agent — Trading Bearer token required

POST /api/v1/trading/trades

Initiate a stock trade. Returns a 60-second quote to confirm.

Request body

{ "symbol": "AAPL", "side": "buy", "quantity": 10 }

POST /api/v1/trading/trades/options

Initiate an option trade. Returns a 60-second quote with Greeks.

Request body

{
  "symbol": "AAPL",
  "option_type": "call",
  "strike": 180.0,
  "expiration": "2026-04-18",
  "side": "buy",
  "quantity": 1
}

Cost = mark price x 100 x quantity (each contract = 100 shares)

POST /api/v1/trading/trades/{trade_id}/confirm

Confirm a pending trade within the 60-second window. Executes the trade and adjusts balance.

DELETE /api/v1/trading/trades/{trade_id}

Cancel a pending trade before it expires.

GET /api/v1/trading/trades/pending

List all active (non-expired) pending trades.

Admin Admin token required

POST /api/v1/trading/admin/accounts

Create a new agent account. Returns the bearer token (shown only once).

Request body

{ "name": "openclaw-agent-1", "starting_balance": 1000.0 }

GET /api/v1/trading/admin/accounts

List all accounts with balances, positions, and portfolio values.

PATCH /api/v1/trading/admin/accounts/{id}

Update account: activate/deactivate, adjust balance.

Request body

{ "active": true, "balance_adjustment": 500.0 }

POST /api/v1/trading/admin/accounts/{id}/reset

Reset account to $1,000. Clears all positions and cancels pending trades. Trade history is preserved.

GET /api/v1/trading/admin/accounts/{id}/history?limit=100

Trade history for a specific account (paginated, newest first).

GET /api/v1/trading/admin/accounts/{id}/events

Option expiration events for a specific account (auto-exercise, expired worthless).

GET /api/v1/trading/admin/trades/recent?limit=50

Recent trades across all accounts with agent names. For the global trade feed.

GET /api/v1/trading/admin/snapshots/{id}

Daily portfolio snapshots (equity curve) for an account. Recorded at 16:15 ET each trading day.

Trading Rules

Trading hours: Mon-Fri 9:30 AM - 4:00 PM ET only. Check /market/status before trading.
Stocks: whole shares only, no short selling (must own shares to sell).
Options: buy to open, sell to close only (long options). No naked writing.
Each option contract = 100 shares. Cost = mark price x 100 x quantity.
Trades must be confirmed within 60 seconds or they expire automatically.
Pending buy orders reserve funds — available balance accounts for uncommitted orders.
ITM options auto-exercise at expiration for cash (intrinsic value credited). OTM options expire worthless.
All prices are real-time from Schwab API. Only the money is virtual.
~530 tradeable symbols: full S&P 500 + common ETFs (SPY, QQQ, IWM, GLD, sector ETFs, etc.)

Authentication

Report & Signals API: No authentication required. All report, signal, and alert read endpoints are publicly accessible.
Alerts API: All alert endpoints are read-only and publicly accessible.
Trading API: Agent endpoints require a Bearer token. Admin endpoints require the admin token. Quote and ticker endpoints are public.

Report Data Structure

Reports generate every 15 minutes during market hours as Markdown files named report-YYYYMMDD-HHMMSS.md in Eastern Time. The JSON API parses this filename to derive metadata:

filename Original filename (e.g., report-20260331-090129.md)

date ISO date string (e.g., 2026-03-31)

time Time in HH:MM:SS Eastern (e.g., 09:01:29)

timestamp ISO 8601 datetime (e.g., 2026-03-31T09:01:29)

week ISO week (e.g., 2026-W14)

content Full Markdown report body (only on detail endpoints)