AgentCanary/Source Contracts
Public reference · agent gating logic

Source contracts.

28 datasets, each with a published freshness SLA. Fresh = age < SLA. Degraded = SLA ≤ age < 2×SLA. Stale = age ≥ 2×SLA.

Every /api/data/:name response includes a provenance field with observed_at, age_seconds, and freshness_status. Agents should gate on status before consuming.

Prices

Dataset What it covers Freshness SLA Origin
realtime-prices Real-time crypto prices (100+ tokens) 5min CoinGecko + exchange APIs
yahoo-quotes SPY/QQQ/VIX/TLT/DXY + 16 sector ETFs 15min Yahoo Finance
exchange-volumes Exchange trading volumes 30min CoinGecko aggregated

Macro

Dataset What it covers Freshness SLA Origin
macro-snapshot 30+ FRED series, regime, risk gauge, z-scores 6h FRED (St. Louis Fed)
vix-term-structure VIX term structure (contango/backwardation) 15min CBOE via Yahoo
cftc-cot CFTC Commitment of Traders positioning 7d CFTC weekly Friday
treasury-stats US Treasury statistics 1d US Treasury Direct

Crypto

Dataset What it covers Freshness SLA Origin
whale-alerts Large on-chain transactions ($10M+ filter) 30min Whale Alert + Hyperliquid
funding-rates Perpetual funding rates across exchanges 1h Coinglass + exchange APIs
btc-etf-flows Bitcoin ETF daily flows (IBIT, FBTC, etc.) 1d ETF issuer disclosures
fear-greed Crypto Fear & Greed Index 1d Alternative.me
coingecko-global Global crypto market cap + dominance 1h CoinGecko global
btc-options BTC options open interest + put/call 1h Deribit + Coinglass
coinglass-v2 Aggregate open interest + liquidations 6h Coinglass v2 API

News & Sentiment

Dataset What it covers Freshness SLA Origin
breaking-news Breaking financial news + sentiment scores 30min Multiple wire aggregators
newsletters Curated newsletter intelligence digest 12h AC-curated sources
reddit-sentiment Cross-subreddit sentiment (14 subs) 6h Reddit API
narrative-scores Narrative crowding scores (21 themes) 1d AC proprietary scoring

Institutional

Dataset What it covers Freshness SLA Origin
sec-13f SEC 13F institutional holdings 7d SEC EDGAR
wikipedia-pageviews Wikipedia pageview trends for assets 1d Wikipedia REST API
short-interest Short interest data for 39 stocks 14d FINRA bi-monthly
etf-fund-flows ETF fund flow estimates (44 ETFs) 1d Issuer + exchange disclosures
etf-options-pcr Options put/call ratios (42 ETFs) 1d CBOE + exchange options data

Calendar & Proprietary

Dataset What it covers Freshness SLA Origin
financial-calendar High-impact economic events 6h AC-curated + Investing.com
polymarket Polymarket prediction market events 1h Polymarket public API
decision-engine Multi-factor crypto re-entry scoring (AC) 6h AC proprietary
risk-summary Daily risk assessment (AC) 6h AC proprietary
scenario-probs 6 macro scenario probabilities (AC) 6h AC proprietary

Reading provenance from /api/data

Each dataset response includes:

{
  "dataset": "yahoo-quotes",
  "date": "2026-05-19",
  "data": { ... },
  "provenance": {
    "source": "yahoo-quotes",
    "observed_at": "2026-05-19T06:00:00.000Z",
    "age_seconds": 420,
    "sla_seconds": 900,
    "freshness_status": "fresh"
  }
}

Defensive agent pattern: skip the dataset if freshness_status === "stale"; degrade gracefully (warn, use fallback, or proceed with annotation) if "degraded"; consume freely if "fresh".

If you spot drift between published SLA and observed behavior, that is a bug — file at github.com/MrCerq/agentcanary-backend/issues.