# Data Source: Pyth Network Price Oracles

## Overview

Pyth Network is a decentralized oracle network that provides high-fidelity, real-time price data for crypto assets. The LuckySt Syndicate uses Pyth oracles as the primary price feed for CDF strategy calculations and fair value estimation.

## Why Pyth

- **Low latency**: Sub-second price updates
- **Cross-chain**: Available on Base and other chains
- **Wide coverage**: 500+ price feeds including all major crypto assets
- **Confidence intervals**: Each price comes with a confidence band
- **Pull-based**: Agents pull prices when needed (no push overhead)

## Architecture

```
Pyth Network (Solana/Pythnet)
    |
    v
Pyth Cross-Chain (Wormhole)
    |
    v
Pyth on Base (Contract)
    |
    v
LuckySt Agent reads price
    |
    v
CDF/Fair Value Calculation
    |
    v
Trading Decision -> Terminal
```

## Key Price Feeds

For Kalshi crypto markets, agents primarily need:

| Asset | Pyth Price ID |
|-------|--------------|
| BTC/USD | `0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43` |
| ETH/USD | `0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace` |
| SOL/USD | `0xef0d8b6fda2ceba41da15d4095d1da392a0d2f8ed0c6c7bc0f4cfac8c280b56d` |

## Reading Pyth Prices

### On-Chain (Solidity/Base EVM)

```solidity
IPyth pyth = IPyth(PYTH_BASE_ADDRESS);
PythStructs.Price memory price = pyth.getPrice(priceId);

// price.price = price value (int64)
// price.expo = exponent (int32, usually -8)
// price.conf = confidence interval
// price.publishTime = timestamp
// Actual price = price.price * 10^(price.expo)
```

### Off-Chain (Python - for agent calculations)

```python
import httpx

# Pyth Hermes API (off-chain, free, low latency)
HERMES_URL = "https://hermes.pyth.network"

async def get_pyth_price(price_id: str) -> dict:
    """Fetch latest price from Pyth Hermes"""
    async with httpx.AsyncClient() as client:
        resp = await client.get(
            f"{HERMES_URL}/v2/updates/price/latest",
            params={"ids[]": price_id}
        )
        data = resp.json()
        price_feed = data["parsed"][0]["price"]
        return {
            "price": int(price_feed["price"]) * 10 ** int(price_feed["expo"]),
            "confidence": int(price_feed["conf"]) * 10 ** int(price_feed["expo"]),
            "timestamp": price_feed["publish_time"]
        }
```

## Integration with CDF Strategy

The CDF strategy uses Pyth prices as the spot price (S) in the probability model:

1. **Fetch current spot** from Pyth (`S = pyth_price`)
2. **Use confidence interval** as a short-term vol estimate
3. **Feed into CDF calculation**: `P(S > K) = 1 - CDF(K | S, sigma, T)`

## Integration with Fair Value

The Midpoint Rolling Average can incorporate Pyth as an external reference:

1. **Orderbook midpoint** gives the market's implied fair value
2. **Pyth price** gives the external reference fair value
3. **Divergence** between the two signals a potential mispricing

## Staleness & Error Handling

- Check `publish_time` - reject prices older than 60 seconds
- Check `confidence` - if conf > 1% of price, the estimate is unreliable
- Fall back to CCXT if Pyth is unavailable
- Agents should log price staleness events for debugging

## Cost

- **Hermes API** (off-chain): Free, no gas costs
- **On-chain reads**: Gas cost on Base (~$0.001 per read)
- **On-chain updates**: If agent needs to push a price update, gas cost applies

For most agent use cases, the Hermes API is sufficient and preferred.