# OathScore

> Every API makes promises. OathScore checks the receipts.

**The trust layer for AI agents.** Two products:

1. **`/now`** — A single endpoint returning the current state of the world for trading agents. Exchange status, volatility, events, regime, data health — one call.
2. **OathScore Ratings** — Independent, continuous verification of data API accuracy, uptime, freshness, and reliability. The credit bureau for data APIs.

## For AI Agents

```bash
# What's happening right now?
curl https://api.oathscore.dev/now

# Should I trust this data source?
curl https://api.oathscore.dev/score/curistat

# Compare two sources
curl https://api.oathscore.dev/compare?apis=curistat,alphavantage
```

## For MCP-Compatible Agents (Claude Code, Cursor, etc.)

```json
{
  "mcpServers": {
    "oathscore": {
      "command": "python",
      "args": ["-m", "oathscore_mcp"]
    }
  }
}
```

Requires: `pip install httpx mcp[cli]` and clone this repo.

## MCP Tools

| Tool | Description |
|------|-------------|
| `get_now` | Current world state: exchanges, volatility, events, data health |
| `get_exchanges` | Open/close status for 7 exchanges with next transition times |
| `get_volatility` | VIX, VIX9D, VIX3M, VVIX, SKEW, term structure |
| `get_events` | Next event, FOMC/CPI countdowns, week high-impact count |
| `get_score` | OathScore rating for a specific API (0-100 composite + grade) |
| `compare_apis` | Side-by-side comparison of two or more data APIs |
| `get_alerts` | Active degradation alerts for monitored APIs |
| `check_health` | Service health and data freshness |

## What OathScore Monitors

For each rated API:

| Metric | Weight | How Measured |
|--------|--------|-------------|
| Accuracy | 35% | Compare forecasts/claims to actual outcomes daily |
| Uptime | 20% | Synthetic monitoring every 60 seconds |
| Freshness | 15% | Is "real-time" actually real-time? |
| Latency | 15% | P50/P95/P99 from multiple regions |
| Schema stability | 5% | Detect breaking changes |
| Documentation | 5% | OpenAPI spec, llms.txt, examples |
| Trust signals | 5% | Published accuracy data, response signing |

## Rated APIs (v1)

| API | Category | Score | Status |
|-----|----------|-------|--------|
| Curistat | Futures volatility | -- | Monitoring |
| Alpha Vantage | Equities/macro | -- | Monitoring |
| Polygon.io | Market data | -- | Monitoring |
| Finnhub | Multi-asset | -- | Monitoring |
| Twelve Data | Market data | -- | Monitoring |
| EODHD | Historical data | -- | Monitoring |
| Financial Modeling Prep | Fundamentals | -- | Monitoring |

Scores populate after 30 days of monitoring data.

## Machine-Readable Discovery

- [`/llms.txt`](https://api.oathscore.dev/llms.txt) — Agent-readable product description
- [`/llms-full.txt`](https://api.oathscore.dev/llms-full.txt) — Complete endpoint documentation
- [`/.well-known/ai-plugin.json`](https://api.oathscore.dev/.well-known/ai-plugin.json) — ChatGPT plugin manifest
- [`/openapi.json`](https://api.oathscore.dev/openapi.json) — OpenAPI 3.0.3 spec
- [`/docs`](https://api.oathscore.dev/docs) — Interactive Swagger UI

## Pricing

| Tier | `/now` Calls | Score Queries | Price |
|------|-------------|---------------|-------|
| Free | 10/day | 5/day | $0 |
| Founding (first 50) | 5,000/day | 2,500/day | $9/mo (lifetime) |
| Pro | 10,000/day | 5,000/day | $29/mo |
| Enterprise | 100,000/day | 50,000/day | $99/mo |
| Pay-per-request (x402) | Unlimited | Unlimited | $0.001-0.005/call |

**x402 micropayments**: No signup needed. Agents pay per request with USDC stablecoins via the [x402 protocol](https://www.x402.org). When rate limited, the API returns `402 Payment Required` with payment instructions.

**API audits**: Independent 7-day quality audit of your API — $299-499. [Contact us](mailto:hello@oathscore.dev).

## Architecture

```
[Monitoring Service - Railway $5/mo]
  Every 60s: ping all rated APIs (uptime, latency)
  Every 5m: check data freshness
  Every 1h: record forecast snapshots
  Every 24h: compare forecasts to actuals (accuracy)
  Store: Supabase (free tier)

[/now Endpoint - Cloudflare Workers $0/mo]
  Every 60s: fetch VIX, compute exchange status, read events
  Serve: cached JSON, max-age=30, ETag support

[Scoring Engine - Cloudflare Workers $0/mo]
  Every 5m: recompute composite scores from raw metrics
  Serve: /score, /compare, /alerts endpoints
```

## Integration Examples

### CrewAI

```python
from crewai import Agent, Task
from crewai_tools import MCPTool

# Connect to OathScore MCP
oathscore = MCPTool(server_command="python -m oathscore_mcp")

analyst = Agent(
    role="Market Analyst",
    tools=[oathscore],
    goal="Assess current market conditions before trading"
)

task = Task(
    description="Check if markets are open and get current volatility regime",
    agent=analyst
)
```

### LangChain

```python
from langchain_mcp import MCPToolkit

toolkit = MCPToolkit(server_command="python -m oathscore_mcp")
tools = toolkit.get_tools()

# Use in any LangChain agent
from langchain.agents import initialize_agent
agent = initialize_agent(tools, llm, agent="zero-shot-react-description")
agent.run("What's the current VIX level and are US markets open?")
```

### Direct HTTP (any language)

```python
import httpx

# World state in one call
now = httpx.get("https://api.oathscore.dev/now").json()
print(f"VIX: {now['volatility']['vix']}")
print(f"CME: {'OPEN' if now['exchanges']['CME']['is_open'] else 'CLOSED'}")
print(f"Next event: {now['events']['next_event']}")

# API quality check before committing to a data source
score = httpx.get("https://api.oathscore.dev/score/polygon").json()
if score.get("composite_score", 0) < 70:
    print("Warning: data source quality below threshold")
```

### Claude Desktop / Claude Code

Add to your MCP config (`~/.claude/mcp.json` or Claude Desktop settings):

```json
{
  "mcpServers": {
    "oathscore": {
      "command": "python",
      "args": ["-m", "oathscore_mcp"]
    }
  }
}
```

Then ask Claude: *"What's the current market state?"* or *"How reliable is Alpha Vantage?"*

---

If this is useful, star the repo — it helps others find it.

## License

Proprietary. All rights reserved.