Architecture
Artic uses a hub-and-spoke architecture where a central hub orchestrates isolated Docker agent containers.
System Topology
Module Responsibilities
Hub
- Auth: JWT (15 min access token) + API key (SHA-256 hashed)
- Agent Lifecycle: CRUD, Docker spawn/stop, heartbeat monitoring
- Market Cache: TwelveData candles via APScheduler (60s staleness, 8 req/min budget)
- WebSocket: Real-time streaming of agent status, trades, logs to clients
- Secrets: AES-encrypted storage with 3-tier resolution
- Database: PostgreSQL via async SQLAlchemy + Alembic migrations
App (Trading Engine)
- Tick Loop: Configurable interval (default 1s). Fetch price → compute indicators → run strategy → execute trades
- LLM Planner: Analyzes market data, selects optimal strategy, defines risk parameters
- LLM Supervisor: Optional cycle-based check on open positions for dynamic TP/SL adjustments
- Executors: Paper trading (in-memory) or HashKey Global REST API
- On-chain Logging: Supervisor decisions →
DecisionLoggedevent on HashKey Chain
Strategies
- 30+ algorithms across 5 categories
- Dispatcher:
signals.pymaps strategy name → algo function - Contract: Every algo returns
(signal: float, detail: str)
Clients
- Thin presentation layers — all state lives in the hub
- Hub SDK (
hub/client.py) used by all clients
Data Flow
Candle Data
TwelveData → Hub (APScheduler, 60s cache) → Agents (fetch from hub)
Rate-limited to 8 requests/minute. Hub manages budget centrally.
Live Prices
Pyth Hermes → Agent (direct, free, no rate limit)
Agent → Hub (Push-based)
| Endpoint | Frequency | Payload |
|---|---|---|
POST /internal/agents/{id}/status | Every tick | Current state, position, P&L |
POST /internal/trades | On open/close | Trade details |
POST /internal/logs | Every 10 ticks | Log batch |
All internal endpoints use X-Internal-Secret header authentication.
Database Schema
8 PostgreSQL tables:
| Table | Purpose |
|---|---|
users | Accounts (email, password hash, API key hash) |
agents | Agent config (symbol, strategy, risk params, container ID) |
trades | Position records (side, entry/exit price, PnL) |
log_entries | Append-only logs (level, message, timestamp) |
market_cache | Candle cache (symbol, timeframe, JSONB candles) |
user_secrets | Encrypted API keys (AES ciphertext) |
agent_secret_overrides | Per-agent encrypted secrets |
onchain_decisions | On-chain audit trail (tx hash, reasoning) |
See Authentication for secret management details.
Key Invariants
- Agents are stateless across restarts — persistent state lives in hub PostgreSQL
- Clients never talk to agent containers — hub proxies everything
- One agent = one symbol — isolation guarantees
- API keys never stored in plaintext — AES encryption mandatory
- Agent→Hub is push-based — agents POST status/trades/logs to hub
- Hub owns TwelveData rate budget — 8 req/min, centrally managed