Hub API Reference

The Hub exposes REST and WebSocket endpoints on port 9000. All client communication goes through the hub.

Authentication

All /api/* endpoints require authentication via one of:

• JWT: Authorization: Bearer <access_token> (15 min lifetime)
• API Key: X-API-Key: <raw_key> (permanent until regenerated)

See Authentication for details.

Auth Endpoints

Login

POST /auth/login
Content-Type: application/json

{ "email": "user@example.com", "password": "secret" }

Response:

{
  "access_token": "eyJ...",
  "refresh_token": "...",
  "token_type": "bearer"
}

Refresh Token

POST /auth/refresh
Content-Type: application/json

{ "refresh_token": "..." }

Generate API Key

POST /api/keys
Authorization: Bearer <token>

Response: Returns raw API key once. Hub stores SHA-256 hash only.

Agent Endpoints

List Agents

GET /api/agents
Authorization: Bearer <token>

Returns all agents owned by the authenticated user.

Create Agent

POST /api/agents
Authorization: Bearer <token>
Content-Type: application/json

{
  "symbol": "BTC/USDT",
  "strategy_name": "momentum_breakout",
  "interval_seconds": 1,
  "live_mode": false,
  "risk_params": { ... }
}

Get Agent

GET /api/agents/{id}
Authorization: Bearer <token>

Stop Agent

POST /api/agents/{id}/stop
Authorization: Bearer <token>

Delete Agent

DELETE /api/agents/{id}
Authorization: Bearer <token>

Stops the container and removes the agent record.

Market Data

Get Candles

GET /api/market/candles?symbol=BTC/USDT&timeframe=1h
Authorization: Bearer <token>

Returns cached OHLCV candle data. Hub manages TwelveData rate budget (8 req/min). Cache staleness tolerance: 60 seconds.

Secrets Management

Store User Secret

POST /api/secrets
Authorization: Bearer <token>
Content-Type: application/json

{
  "key_name": "OPENAI_API_KEY",
  "encrypted_value": "<AES-encrypted>"
}

List User Secrets

GET /api/secrets
Authorization: Bearer <token>

Returns key names only (never values).

Store Agent Secret Override

POST /api/agents/{id}/secrets
Authorization: Bearer <token>
Content-Type: application/json

{
  "key_name": "ANTHROPIC_API_KEY",
  "encrypted_value": "<AES-encrypted>"
}

WebSocket

Connect

ws://localhost:9000/ws?token=YOUR_ACCESS_TOKEN

Message Types

The WebSocket broadcasts real-time updates:

Internal Endpoints

These are agent→hub push endpoints, authenticated via X-Internal-Secret header.

Clients never call these endpoints directly.

Agent Container Endpoints

These run inside each agent container on port 8000. Only the hub calls them.

Port Map

Rate Limits