Polytraders Dev Guide
internal
v3 spine Phase 1 · Shared contracts 9 demo-wired · 0 shadow-ready · 0 production-live · 100 pending · 109 total 15/33 infra tasks the plan status board

Data flow

How raw market and external data becomes the trusted internal objects every bot reads.

  1. Raw ingest — CLOB v2 WebSocket, CLOB v2 REST, on-chain subgraph, sports feeds, news feeds. Each source has its own adapter.
  2. Adapter normalisation — Each adapter (intel.sportsfeed_adapter, intel.news_ingest, etc.) maps the raw payload to a typed schema with a freshness stamp.
  3. Provenance hashing — Every normalised object carries the hash of its source response. Two bots seeing the same MarketSnapshot have identical provenance.
  4. Quality rankingintel.market_quality_ranker assigns a quality score per market. Bots can require a minimum quality threshold.
  5. Freshness budgets — Every consumer declares the maximum age it will accept. Anything older fires INTEL_FEED_STALE and the safe fallback runs.
  6. Internal trust boundary — Once an object is in the internal store, no bot is allowed to consume the raw upstream payload. The boundary is enforced at code-review time.

Freshness budgets per object

ObjectDefault budgetOn stale
MarketSnapshot1000 msREJECT
OrderBookSnapshot500 msREJECT
Sports feed30 sIGNORE_SIGNAL
News feed120 sIGNORE_SIGNAL
On-chain reconcile60 sPAUSE_MARKET

Why this layer exists

Raw exchange feeds change shape. Network conditions vary. Sources disagree. Without a normalisation layer, every bot reinvents the same parsing and the same staleness handling, and they disagree in subtle ways. The data-flow layer makes "the world" a single typed object that every bot reads from.