Proposed Standard v0.1
/.well-known/ai-world-state
A well-known URL for AI agents to auto-discover calibrated world state from any domain.
Motivation
robots.txt tells crawlers what to index. llms.txt tells LLMs how to use a website. /.well-known/ai-world-state tells AI agents what's happening in the world right now.
AI agents need real-time world awareness but have no standard way to discover it. Web search returns narratives. News APIs return headlines. Neither provides calibrated probabilities that agents can reason over.
This spec proposes a convention: any domain can host a structured world state at a well-known URL. Agent frameworks auto-discover it, like browsers auto-discover favicons.
Specification
A conforming server MUST respond to GET /.well-known/ai-world-state with a JSON object containing:
{
"$schema": "https://simplefunctions.dev/specs/ai-world-state.schema.json",
"version": "0.1.0",
"spec": "ai-world-state",
"provider": {
"name": "Provider Name",
"url": "https://example.com",
"api": "https://example.com/api/world"
},
"capabilities": {
"topics": ["geopolitics", "economy", "energy", ...],
"delta": true, // supports incremental updates
"focus": true, // supports topic filtering
"feed": true // supports RSS/Atom feed
},
"state": {
"index": {
"uncertainty": 22, // 0-100
"geopolitical": 62, // 0-100
"momentum": 0.06 // -1 to +1
},
"traditional": [...],
"topics": [...],
"divergences": [...]
}
}Required Fields
version — Spec version (currently 0.1.0)
provider.name — Human-readable provider name
provider.url — Provider website
provider.api — Full world state API endpoint
state — Current world state object (embedded inline)
Optional Fields
capabilities.topics — Available topic categories
capabilities.delta — Whether incremental updates are supported
capabilities.focus — Whether topic filtering is supported
capabilities.feed — Whether RSS/Atom feed is available
provider.feed — RSS/Atom feed URL
provider.delta — Delta endpoint URL
provider.mcp — MCP server URL
Agent Discovery Flow
# 1. Agent checks for world state on a domain GET https://example.com/.well-known/ai-world-state # 2. If present, extract the embedded state state = response["state"] # 3. Inject into context system_prompt += state["markdown"] # 4. For ongoing sessions, use delta endpoint GET https://example.com/api/world/delta?since=1h
Reference Implementation
SimpleFunctions provides the reference implementation:
curl https://simplefunctions.dev/.well-known/ai-world-state
Data source: 9,706 prediction market contracts from Kalshi (CFTC-regulated) and Polymarket. Updated every 15 minutes. No authentication required.
Why Prediction Markets?
A prediction market price of 53c on "Iran invasion" encodes the aggregate judgment of everyone with money at risk on that question. Get it wrong, lose money. This punishment mechanism produces calibrated probabilities more reliable than news, polls, or LLM reasoning.
Status
Draft v0.1 — open for feedback. Contact: hello@simplefunctions.dev