# SigmaGrid llms.txt
# Last updated: 2026-10-05
# Authoritative contract: https://api.sigmagrid.app/openapi.json (generated by the API; wins if anything here disagrees)

# ─── WHAT IS SIGMAGRID? ───────────────────────────────────────────────
# SigmaGrid sells fair value and related signals for crypto synthetic equity
# perpetuals, paid per call with x402.
#
# CORE PROBLEM: Traditional equity markets close at 4pm ET. Synthetic equity
# perps (on Hyperliquid and Veranta, formerly Avantis) trade 24/7. Off-hours
# there is no institutional reference price. SigmaGrid provides one, anchored
# to the underlying equity and macro inputs rather than the perp order books.
#
# TRACK RECORD: none published yet. Live collection started 4 Oct 2026.

# ─── BASE URLS ────────────────────────────────────────────────────────
# Docs: https://sigmagrid.app/docs
# API base: https://api.sigmagrid.app
# OpenAPI spec: https://api.sigmagrid.app/openapi.json
# x402 discovery: https://api.sigmagrid.app/x402-discovery
# Agent descriptor: https://sigmagrid.app/.well-known/agent.json

# ─── AUTHENTICATION ──────────────────────────────────────────────────
# x402 micropayments (pay-per-request); no API keys, no subscription.
# Flow: (1) call a paid endpoint, (2) receive 402 with price/recipient/chain,
# (3) sign a USDC payment on Base (chain ID 8453), (4) retry with the payment header.
# Free endpoints require nothing.

# ─── TICKERS ─────────────────────────────────────────────────────────
# Stocks: TSLA, NVDA, AAPL, MSFT, META, AMZN, GOOG (Alphabet Class C)
# Index ETFs, fair value only: SPY, QQQ
#   No venue lists a tradeable SPY or QQQ perp, so spread, funding, premium
#   and liquidity answer 400 for them BEFORE payment. Every other route serves them.
# Any other ticker: 400 before payment.

# ─── VENUES ──────────────────────────────────────────────────────────
# Hyperliquid — TSLA, NVDA, AAPL, MSFT, META, AMZN
# Veranta (formerly Avantis) — TSLA, NVDA, AAPL, MSFT, META, AMZN, GOOG

# ═══════════════════════════════════════════════════════════════════════
# ENDPOINT REFERENCE
# ═══════════════════════════════════════════════════════════════════════

# ─── FREE ────────────────────────────────────────────────────────────
# GET /healthz             → 200 {"status":"ok"} or 503 {"status":"degraded"}
# GET /v1/validate         → service reachable
# GET /openapi.json        → OpenAPI 3.1 spec with x-payment-info prices and ticker enums
# GET /x402-discovery      → services, prices, pay-to address, tickers
# GET /.well-known/x402    → list of paid routes
# GET /v1/signals/{ticker} → free teaser: regime + event-risk labels and a gated_endpoints map
#   → USE THIS to decide whether to spend USDC on deeper signals.

# ─── 0.02 USDC PER REQUEST ───────────────────────────────────────────
# GET /v1/fair-value/{ticker}   Fair value, confidence band, z-score vs spot. All 9 tickers.
# GET /v1/premium/{ticker}      Per-venue premiums vs fair value, divergence z-score. Stocks only.
# GET /v1/spread/{ticker}       Bid/ask, effective spread, venue spread dispersion. Stocks only.
# GET /v1/funding/{ticker}      Funding rate, predicted next, carry-adjusted basis. Stocks only.
# GET /v1/regime-basic/{ticker} Regime label + confidence, VIX and 24h change, funding direction.
# GET /v1/regime/{ticker}       Regime, vol forecasts, transition probability, structural stress.
# GET /v1/event-risk/{ticker}   Event risk score, implied move, suppression triggers.
# GET /v1/events/{ticker}       Next event, historical impact, directional bias, risk window.

# ─── 0.03 USDC PER REQUEST ───────────────────────────────────────────
# GET /v1/liquidity/{ticker}      Execution cost by trade size per venue. Stocks only.
#   → cost in bps per venue at $10k / $100k / $1m (order-book walk or published spread, fees excluded)
#   → cheapest venue per size; crossover = size where the cheapest venue changes
#     (13-step grid $10k–$2.5m, trading cost only and with one-way opening fee)
#   → fees, size caps, 24h volume, and why a venue was excluded
#   → WHEN TO USE: before sizing up, or when choosing a venue for a large order.
# GET /v1/drift/{ticker}          Drift 1h and overnight, confidence, positioning bias.
# GET /v1/historical/{ticker}     Stored history: fair value, regime, drift, premiums.
# GET /v1/alpha-snapshot/{ticker} Every signal column for one ticker in one call.

# ─── 0.05 USDC PER REQUEST ───────────────────────────────────────────
# GET /v1/snapshot                Snapshot of all covered tickers (no ticker filter).
# GET /v1/alpha-snapshot/batch    AlphaSnapshot for all covered tickers (no ticker filter).


# ═══════════════════════════════════════════════════════════════════════
# DECISION FLOW FOR AGENTS
# ═══════════════════════════════════════════════════════════════════════
# 1. GET /healthz — confirm the API is up.
# 2. GET /v1/signals/{ticker} — free regime and event-risk labels.
# 3. Need a reference price?   → /v1/fair-value/{ticker}
#    Choosing venue or size?   → /v1/liquidity/{ticker}
#    Carry matters?            → /v1/funding/{ticker}
#    Everything for one name?  → /v1/alpha-snapshot/{ticker}
#    Whole universe?           → /v1/alpha-snapshot/batch
# 4. Check each response's timestamp before acting on it.

# ═══════════════════════════════════════════════════════════════════════
# HTTP STATUS CODES
# ═══════════════════════════════════════════════════════════════════════
# 200 — Success.
# 400 — Ticker not covered, or SPY/QQQ on a venue-data route. Sent before payment; never charged.
# 402 — Payment required. Parse the x402 payment requirements.
# 5xx — Server error. Retry with backoff.

# ═══════════════════════════════════════════════════════════════════════
# DISCLAIMER
# ═══════════════════════════════════════════════════════════════════════
# Data and model outputs for information only; not investment advice. Estimates
# can be wrong, late or unavailable. Paid calls are charged when served, whatever
# the result, with no warranty of accuracy or uptime.

[product]
name = "SigmaGrid"
description = "Fair value and execution-cost signals for crypto synthetic equity perps, paid per call via x402."
track_record = "none published yet; collecting since 2026-10-04"

[api]
base_url = "https://api.sigmagrid.app"
schema = "https://api.sigmagrid.app/openapi.json"
health = "https://api.sigmagrid.app/healthz"
agent_descriptor = "https://sigmagrid.app/.well-known/agent.json"
paid_endpoints = 14

[coverage]
tickers = "TSLA, NVDA, AAPL, MSFT, META, AMZN, GOOG, SPY, QQQ"
fair_value_only = "SPY, QQQ"
venues = "Hyperliquid, Veranta (formerly Avantis)"

[pricing]
free = "/healthz, /v1/validate, /openapi.json, /x402-discovery, /.well-known/x402, /v1/signals/{ticker}"
single_signal = "0.02 USDC"
rich_data = "0.03 USDC (historical, alpha-snapshot, drift, liquidity)"
bulk_batch = "0.05 USDC"
currency = "USDC on Base (chain ID 8453)"
protocol = "x402"

[discovery]
openapi = "https://api.sigmagrid.app/openapi.json"
x402 = "https://api.sigmagrid.app/x402-discovery"
agent_json = "https://sigmagrid.app/.well-known/agent.json"
erc8004 = "https://sigmagrid.app/.well-known/erc8004.json"
llms_txt = "https://sigmagrid.app/llms.txt"