Interfaces & Data Contracts

Terminology (Canon)

Cornice uses a consistent naming model across docs, code, and schemas:

• Exchange: the platform/company (Polymarket, Kalshi).
• Venue: Cornice-internal alias for Exchange (used in logs and fields).
• Market: the event definition + resolution rules (cross-venue concept).
• Contract: the tradable instrument for a specific Outcome (venue-specific).

Internal Messaging (RabbitMQ)

Use RabbitMQ for internal events and decouple data from execution.

Exchanges and Routing

• market.data (topic): normalized market and orderbook updates
• market.signal (topic): derived signals for strategy
• execution.intent (topic): selected trade intents
• execution.result (topic): fills, rejects, and errors

Example Routing Keys

• kalshi.orderbook.update
• polymarket.orderbook.update
• signal.arb.detected
• intent.place_order
• result.order_filled

Normalized Data Shapes (Draft)

Keep fields minimal and consistent. All prices in cents.

MarketUpdate

market_id: string
venue: "kalshi" | "polymarket"
symbol: string
title: string
end_time: iso8601 | null
timestamp: iso8601
best_yes: int
best_no: int

MarketMetadata

market_id: string
venue: "kalshi" | "polymarket"
symbol: string
title: string
category: string | null
end_time: iso8601 | null
outcomes: [ "YES", "NO" ]
venue_tokens: { yes: string, no: string } | null
active: bool

OrderBookDepth

market_id: string
venue: "kalshi" | "polymarket"
timestamp: iso8601
yes_bids: [ [price, size] ]
yes_asks: [ [price, size] ]
no_bids: [ [price, size] ]
no_asks: [ [price, size] ]

Signal

signal_id: string
type: "arb"
legs: [ { venue, side, price, size } ]
edge_cents: int
timestamp: iso8601

ExecutionIntent

intent_id: string
signal_id: string
orders: [ { venue, side, price, size } ]
dry_run: bool

ExecutionResult

intent_id: string
status: "filled" | "partial" | "rejected" | "error"
fills: [ { venue, side, price, size, order_id } ]
error: string | null

Socket.io Events (UI)

• market:update: latest normalized market snapshot
• signal:update: newly detected opportunities
• execution:update: intent status and fills
• health:update: heartbeat + latency

HTTP API (FastAPI)

• GET /health basic status and version
• GET /config non-secret config snapshot
• POST /admin/pause toggle trading pause

Raw -> Normalized Field Mapping (Phase 1)

Polymarket (Gamma + CLOB)

• event.id -> markets.venue_market_id
• event.slug -> markets.slug
• event.title -> markets.title
• event.tags[].label -> markets.category (pick primary tag)
• markets[0].clobTokenIds -> markets.venue_tokens
• markets[0].outcomes -> markets.outcomes (normalize to ["YES","NO"])
• CLOB book best ask -> MarketUpdate.best_yes/best_no
• event.active/closed -> markets.active (active && !closed)

Kalshi (Public Trade API)

• market.id or market.ticker -> markets.venue_market_id
• market.subtitle / market.title -> markets.title
• market.event_ticker -> markets.symbol
• market.close_time -> markets.end_time
• market.yes_ask/no_ask -> MarketUpdate.best_yes/best_no
• market.status -> markets.active