API Reference

BrokerBridge exposes a REST API on http://localhost:8080. All endpoints return JSON. Swagger UI is available at /docs.

Endpoints

HealthSetupCredentialsProposalsPositionsActivityWebhooks

Health

GET/api/health

System health check with service status.

response
{
  "status": "ok",
  "version": "0.1.0",
  "trading_loop_active": true,
  "services": {
    "api": "healthy",
    "ibkr": { "connected": true, "message": "" },
    "anthropic": { "connected": true, "message": "" }
  }
}

Setup

GET/api/setup/status

Check whether initial setup is complete.

POST/api/setup/config

Save configuration from setup wizard.

curl
curl -X POST http://localhost:8080/api/setup/config \
  -H "Content-Type: application/json" \
  -d '{
    "ai_provider": { "provider": "claude", "auth_type": "api_key" },
    "broker": { "host": "127.0.0.1", "port": 4002, "client_id": 1 },
    "risk": { "max_position_size_pct": 5.0, "max_open_trades": 5 },
    "trading_mode": "paper"
  }'

Credentials

POST/api/credentials/test

Test a credential without saving it.

curl
curl -X POST http://localhost:8080/api/credentials/test \
  -H "Content-Type: application/json" \
  -d '{"provider": "claude", "auth_type": "api_key", "credential": "sk-ant-..."}'
POST/api/credentials/save

Save credential to encrypted keyring storage.

GET/api/credentials/status

Get connection status for all providers.

response
{
  "providers": {
    "claude": "connected",
    "openai": "disconnected",
    "openrouter": "disconnected",
    "google": "disconnected",
    "ibkr": "connected"
  }
}
DELETE/api/credentials/{provider}

Remove stored credential. Valid: claude, openai, openrouter, google, ibkr.

POST/api/credentials/ibkr/test

Test IB Gateway/TWS connection.

curl
curl -X POST http://localhost:8080/api/credentials/ibkr/test \
  -H "Content-Type: application/json" \
  -d '{"host": "127.0.0.1", "port": 4002, "client_id": 1}'

Proposals

GET/api/proposals

List trade proposals. Filter by status and date.

curl
curl "http://localhost:8080/api/proposals?status=pending"
GET/api/proposals/{proposal_id}

Get a single proposal with full details.

POST/api/proposals/{id}/approve

Approve with optional modifications.

curl
curl -X POST http://localhost:8080/api/proposals/prp-abc123/approve \
  -H "Content-Type: application/json" \
  -d '{"final_size": 40, "final_stop": 184.00}'
POST/api/proposals/{id}/reject

Reject with optional reason.

curl
curl -X POST http://localhost:8080/api/proposals/prp-abc123/reject \
  -H "Content-Type: application/json" \
  -d '{"reason": "Market too volatile"}'

Positions

GET/api/positions

Get current open positions with unrealized P&L.

GET/api/positions/history

Get closed positions. Optional date filter.

Activity

GET/api/activity

Recent activity items (newest first, max 50).

GET/api/activity/stream

SSE stream for real-time updates. Heartbeats every 15s.

python
import httpx

with httpx.stream("GET", "http://localhost:8080/api/activity/stream") as r:
    for line in r.iter_lines():
        if line.startswith("data: "):
            print(line[6:])

Webhooks

POST/api/webhooks/stripe

Stripe webhook for subscription events. Requires Stripe-Signature header.

← Data & ReportsPlugin System →