Backend API

Overview#

The backend API serves three critical roles:

1. Hidden payload store: Stores target price, direction, and salt until they should be revealed
2. Event indexer: Reads contract events and indexes them into PostgreSQL for fast queries
3. Public API: Serves indexed data and delivers payloads to authenticated buyers

Built with FastAPI + uvicorn, PostgreSQL 16, SQLAlchemy 2, and Alembic for migrations.

API Routes#

Public Routes (No Auth)#

Query params: status (active, resolved, cancelled), asset, maker, sort (newest, cheapest, most_buyers), limit, page.

Query params: sort (win_rate, total_signals, volume), limit, page.

Authenticated Routes (EIP-191 Signature)#

Body: { asset, target_price, direction, expiry_time, confidence? }. Returns commitment_hash. The backend generates a 32-byte salt and stores the full payload.

Body: { signal_id, commitment_hash }. Called after on-chain createSignal() confirms.

Returns target price and direction. Only accessible to addresses with a purchase record on-chain. Returns 403 for unauthorized access — deliberately returns the same error whether the signal doesn't exist or the caller hasn't purchased (anti-enumeration).

Internal Routes (API Key)#

Returns target price, direction, and salt for the keeper to submit resolveSignal().

Authentication#

Two authentication methods:

EIP-191 signatures have a ±5 minute timestamp tolerance. Authorization headers are capped at 2KB. API key comparison uses hmac.compare_digest for timing-safety.

Database Schema#

signals
  signal_id (PK), maker, asset, expiry_time, cost_usdc,
  commitment_hash, resolved, outcome, target_price,
  direction, protocol_fee, entry_price, resolution_price,
  quality_score, direction_score, precision_multiplier,
  difficulty_weight, confidence, signal_name, signal_description

purchases
  signal_id (FK), buyer, amount, purchased_at,
  refunded, refund_amount
  UNIQUE(signal_id, buyer)

makers
  address (PK), total_signals, wins, losses,
  active_signals, total_volume, win_rate,
  avg_quality_score, brier_score, first_seen_at, last_active_at

signal_payloads
  commitment_hash (UNIQUE), signal_id (FK after linking),
  maker, asset, target_price, direction, salt

indexer_state
  last_indexed_block

Event Indexer#

The indexer polls eth_getLogs every 5 seconds and processes four event types:

• SignalCreated: Inserts signal record with public metadata
• SignalPurchased: Inserts purchase record, updates signal escrow total
• SignalResolved: Updates signal with outcome, revealed price/direction, computes quality score, updates maker stats
• RefundClaimed: Updates purchase refund status and amount

Rate Limiting#

Price Format#

All monetary values are serialized as strings in API responses to prevent JavaScript floating-point precision loss. On-chain prices are uint256 scaled by 1e8. USDC amounts use 6 decimal places.