# Pythia Agent Skill

## Overview

Pythia is a machine-readable sports signal layer for autonomous agents. It provides ranked Pythia Premium and Strongest signals for Polymarket, Kalshi, and other prediction market venues.

**Base URL:** `https://pythiaterminal.xyz`

**Key Principle:** Pythia delivers structured signal JSON only. No custody. No direct execution. Your agent reads the signal and executes externally.

---

## Endpoints

### Free Endpoints

#### `GET /signals/latest`
Ranked executable-fresh signals — Pythia Premium first, then Strongest, then native scanner.

```
GET https://pythiaterminal.xyz/signals/latest
```

**Response shape:**
```json
{
  "signals": [ { "provider": "pythia", "provider_lane": "PREMIUM", ... } ],
  "pythia_count": 9,
  "pythia_executable_fresh_count": 5,
  "pythia_stale_count": 4,
  "native_count": 3,
  "latest_scan_finished_at": "2025-06-01T12:00:00.000Z",
  "scan_interval_seconds": 60
}
```

#### `GET /signal/preview`
Free cache-first strongest preview (no payment required).

```
GET https://pythiaterminal.xyz/signal/preview
```

Returns the single strongest executable-fresh signal, or `{ "is_null": true }` if none available.

#### `GET /status`
Service health check.

```
GET https://pythiaterminal.xyz/status
```

#### `GET /inventory`
Active lanes, scan loop state, historical prior WR.

```
GET https://pythiaterminal.xyz/inventory
```

#### `GET /capabilities`
API capability discovery document.

```
GET https://pythiaterminal.xyz/capabilities
```

#### `GET /schema`
Signal contract shape documentation.

```
GET https://pythiaterminal.xyz/schema
```

#### `GET /.well-known/x402`
x402 payment manifest (used for paid endpoint).

```
GET https://pythiaterminal.xyz/.well-known/x402
```

### Paid Endpoint (x402)

#### `POST /signal/strongest`
x402 paywall — 0.50 USDC on Base for the strongest executable-fresh signal.

```
POST https://pythiaterminal.xyz/signal/strongest
Content-Type: application/json
X-Payment: <x402-payment-header>

{}
```

---

## Signal Structure

Each signal follows this schema:

| Field | Type | Description |
|-------|------|-------------|
| `signal_id` | string | Unique signal identifier |
| `provider` | `"pythia"` \| `"native"` | Signal source |
| `provider_lane` | `"PREMIUM"` \| `"STRONGEST"` \| `null` | Pythia lane rank |
| `sport_key` | string | Sport identifier (e.g. `baseball_mlb`) |
| `event_title` | string | Matchup (e.g. `NYY @ BOS`) |
| `market_ticker` | string | Market identifier |
| `market_family` | string | Sport family (e.g. `MLB`) |
| `market_type` | string | Contract type (e.g. `moneyline`) |
| `venue` | `"polymarket"` \| `"kalshi"` \| `"betfair"` | Target venue |
| `outcome` | string | Predicted outcome |
| `yes_sub_title` | string | Team/outcome name |
| `side` | `"YES"` \| `"NO"` | Bet direction |
| `current_buy_edge` | number (pythia) | Current buy edge |
| `edge_pct` | number (native) | Edge percentage |
| `fair_prob` | number | Fair probability |
| `max_safe_notional_usd` | number | Max safe notional (USD) |
| `api_signal_status` | `"executable_fresh"` \| `"stale_signal_not_executable"` \| `null` | Execution eligibility |
| `api_execution_allowed` | boolean \| null | Whether execution is allowed |
| `cache_fresh` | boolean \| null | Freshness flag (native) |
| `historical_win_rate` | number \| null | Historical win rate (pythia) |
| `resolved_n` | number \| null | Resolution sample size |
| `api_snapshot_age_minutes` | number \| null | Snapshot age in minutes |
| `freshness_seconds` | number \| null | Freshness in seconds (native) |

---

## Agent Integration Steps

1. **Discover** → `GET /capabilities` — what the API exposes
2. **Schema** → `GET /schema` — signal contract shape
3. **Poll** → `GET /signals/latest` — poll for current signals (free)
4. **Preview** → `GET /signal/preview` — free cache-first preview
5. **Pay** → `GET /.well-known/x402` → `POST /signal/strongest` — paid path

---

## Execution Model

Pythia does **not** execute trades. Your agent is responsible for:

1. Reading the signal JSON
2. Connecting to the target venue (Polymarket, Kalshi, etc.)
3. Executing the trade externally
4. Managing its own custody and keys

---

## Pricing

| Endpoint | Cost | Description |
|----------|------|-------------|
| `GET /signals/latest` | Free | Ranked signals (Premium first) |
| `GET /signal/preview` | Free | Single strongest preview |
| `POST /signal/strongest` | 0.50 USDC on Base | Strongest executable-fresh signal |

Payment via **x402** — stateless USDC paywall. No API keys, no invoicing, no support tickets.

---

## Example (curl)

```bash
# Free: ranked signals
curl "https://pythiaterminal.xyz/signals/latest" | python3 -m json.tool

# Free: preview
curl "https://pythiaterminal.xyz/signal/preview" | python3 -m json.tool

# Paid: strongest signal (x402)
curl -X POST "https://pythiaterminal.xyz/signal/strongest" \
  -H "Content-Type: application/json" \
  -H "X-Payment: <x402-payment-header>" \
  -d '{}'
```

---

## Support

- X: [@pythiasol](https://x.com/pythiasol)

---

*Pythia — machine-readable sports signal for agents. External execution only.*