# Polystrike API Documentation for LLMs

Generated on: 2026-03-23T08:59:29.669Z


--- FILE: SKILL.md (Agent API Guide) ---

---
name: polystrike-agent-api
description: Finding risk-free arbitrage and prediction market edges on Polymarket using Polystrike data.
license: MIT
metadata:
  version: "1.2"
  subject: "Elon Musk"
  platform: "Polymarket"   # The venue where trades are executed
  provider: "Polystrike"   # The source of the API/Data
---

# Polystrike Agent API

> **Context**: This skill provides the tools and strategies for AI agents to trade on **Polymarket's** Elon Musk tweet count markets using **Polystrike's** real-time data layer.

**Contact**: [@dizpers](https://x.com/dizpers) on X.

## 1. Scope & Capabilities

This skill provides a **Real-Time Data Layer** for Polymarket, enabling AI agents to trade with an information advantage.

### A. Market Metadata (Elon Musk & Ted Cruz)
We provide the **Ground Truth** for Elon Musk and Ted Cruz tweet markets.
- **Real-Time Counters**: Precise count of *qualified* tweets vs *settled* tweets.
- **Tweet Stream**: Raw feed of every new tweet (including deleted ones) for sentiment analysis.
- **State Tracking**: Monitoring of sleep/wake state for velocity modeling.

**Why it matters**:
Polymarket's UI varies by 30s-5m from reality. Without this metadata, you are trading blind. With it, you can front-run settlement.

### B. Alpha Detection
- **Detect Arbitrage**: Find "risk-free" trades where the Polystrike settlement count is ahead of the official oracle.
- **Monitor Latency**: Track the `display_delta` (UI lag) to exploit retail traders' delayed data.

### C. Predictive Modeling & Signals (Pro Only)
- **Forecast Outcomes**: Access Monte Carlo simulations (1000 runs) that account for sleep schedules and mean reversion.
- **EV-Based Signals**: Receive actionable `BUY` / `SELL` signals automatically optimized for Expected Value (EV), with optimal Kelly Criterion bet sizing and Information Asymmetry Edge detection.

**Current Scope**: Elon Musk and Ted Cruz Tweet Count Markets.

## 2. Authentication

The API has two tiers:

1. **Anonymous (Public)**
   - **No Key Required**
   - **Rate Limit**: 100 requests/hour
   - **Access**: Metadata, Counters, Delta tracking. Perfect for lag-based arbitrage.

2. **Pro ($79/mo)**
   - **Requires Key**: `X-API-Key: ps_pro_...`
   - **Rate Limit**: 10,000 requests/hour
   - **Access**: Forecasts (`p5`/`p95`), EV-Based Trade Signals, `is_counted` flag on tweets, Portfolio Analysis.
   - **Upgrade**: Contact [@dizpers](https://x.com/dizpers) or `dizpers@gmail.com`.

- **Base URL**: `https://api.polystrike.xyz`
- **OpenAPI Spec**: `https://polystrike.xyz/openapi.json`

## 3. Endpoints & Strategies

### 1. Market Metadata (The Ground Truth)
**Endpoints**:
- `GET /api/v1/meta/elon` - Elon Musk markets
- `GET /api/v1/meta/cruz` - Ted Cruz markets

**Tier**: **Public** (Free)
**Goal**: Identify arbitrage opportunities via counters and deltas.

```bash
curl https://api.polystrike.xyz/api/v1/meta/elon
curl https://api.polystrike.xyz/api/v1/meta/cruz
```

**Response**:
```json
{
  "timestamp": 1770733363222,
  "data": [
    {
      "event_id": 194167,
      "event_title": "Elon Musk # tweets Feb 3-10",
      "polymarket_xtracker_counter": 215, // Settlement (Oracle)
      "real_counter": 220,                // Reality (Ground Truth)
      "polymarket_ui_counter": 215,       // Display (Website)
      "settlement_delta": 5,              // real - xtracker
      "display_delta": 5,                 // real - ui
      "internal_delta": 0                 // ui - xtracker
    }
  ]
}
```

**Key Fields**:
- `image`: Event image URL from Polymarket.
- `settlement_delta`: The gap between Reality and Oracle. If `> 0`, **Buy YES**. You know the count will rise.
- `display_delta`: The gap between Reality and UI. If `> 5`, **Front-run UI**. Retail is blind to recent tweets.
- `real_counter`: The actual number of qualified tweets sent by Elon.
- `polymarket_xtracker_counter`: The number currently recognized by the UMA oracle/Polymarket settlement.

---

### 2. Tweet Stream (Sentiment & Velocity)
**Endpoint**: `GET /api/v1/meta/elon/tweets`
**Tier**: **Public** (Masked) / **Pro** (Full)
**Goal**: Analyze raw tweet content or detect deletions.

**Query Parameters (Pro Only)**:
- `limit`: Number of tweets to return (max 100).
- `offset`: Number of tweets to skip.

> **Note**: Free users are fixed at the latest **15 tweets**. Query parameters are ignored.

```bash
curl https://api.polystrike.xyz/api/v1/meta/elon/tweets
```

**Response (Public)**:
```json
{
  "timestamp": 1770734408963,
  "data": [
    {
      "tweet_id": "2021230513298473031",
      "text": "SpaceX is launching...",
      "created_ts": 1770733881000,
      "is_reply": false,
      "is_quote": false,
      "is_retweet": false,
      "is_counted": null // Pro users see true/false
    }
  ],
  "limit": 15,
  "offset": 0
}
```

**Key Fields**:
- `text`: The raw content of the tweet.
- `is_counted`: **Pro Only**. Returns `true` if the tweet counts towards the market resolution (filtering replies/retweets). Public users see `null`.
- `created_ts`: Unix timestamp of the tweet (in milliseconds).

---

### 3. Prediction Model (Monte Carlo)
**Endpoint**: `GET /api/v1/prediction/elon`
**Tier**: **Pro Only** (for forecasts)
**Goal**: Forecast the final count using our sleep-aware model.

```bash
curl -H "X-API-Key: ps_pro_..." https://api.polystrike.xyz/api/v1/prediction/elon
```

**Response (Pro)**:
```json
{
  "timestamp": 1770733363222,
  "data": [
    {
      "event_id": 194167,
      "seconds_remaining": 43200,
      "forecast": {
        "p5": 224,   // 5% chance count < 224
        "p50": 242,  // Median forecast
        "p95": 272   // 95% chance count < 272
      },
      "markets": [
        {
          "title": "240-259",
          "model_prob": 0.45,
          "market_price": 0.35,
          "edge": 0.10,
          "signal": "BUY"
        }
      ]
    }
  ]
}
```

**Key Fields**:
- `forecast`: Probabilistic outcome range. `p5` is the floor, `p95` is the ceiling.
- `model_prob`: The probability of the outcome falling in this bucket according to our simulation.
- `market_price`: The current price on Polymarket (implied probability).
- `signal`: Trading recommendation (`BUY`, `SELL`, `HOLD`).

---

### 4. EV-Based Signals
**Endpoint**: `GET /api/v1/signals/elon`
**Tier**: **Pro Only**
**Goal**: Get a sorted list of actionable trading signals optimizing for Expected Value (EV).

```bash
curl -H "X-API-Key: ps_pro_..." https://api.polystrike.xyz/api/v1/signals/elon
```

**Response**:
```json
{
  "timestamp": 1771246739535,
  "data": [
    {
      "event_id": 206602,
      "signals": [
        {
          "bucket": "65-89",
          "action": "BUY",
          "model_prob": 1.0,
          "market_price": 0.945,
          "edge": 0.055,
          "ev": 0.058,
          "kelly_fraction": 0.058,
          "suggested_bet": 2.50,
          "confidence": "HIGH",
          "moneyness": 0.5,
          "time_confidence": "HIGH",
          "asymmetry_edge": 0,
          "reasons": [
            "Strong signal: 100% prob, +5.8% EV"
          ]
        }
      ]
    }
  ]
}
```

---

### 5. Portfolio Analysis
**Endpoint**: `GET /api/v1/portfolio/elon?wallet=0x...`
**Tier**: **Pro Only**
**Goal**: Manage positions against model predictions.

```bash
curl -H "X-API-Key: ps_pro_..." "https://api.polystrike.xyz/api/v1/portfolio/elon?wallet=0xYourWalletAddress"
```

---

## 4. Integration Examples

### Example: Arbitrage Bot (Python / Public Tier)

```python
import aiohttp
import asyncio

async def check_arb():
    async with aiohttp.ClientSession() as session:
        # 1. Fetch Metadata (Public Endpoint)
        async with session.get("https://api.polystrike.xyz/api/v1/meta/elon") as resp:
            data = await resp.json()
            
            for event in data["data"]:
                # 2. Check for Settlement Lag (God View)
                if event["settlement_delta"] > 0:
                     print(f"🚨 ARB: Oracle is behind by {event['settlement_delta']} tweets!")
                     # BUY YES on current bucket
                
                # 3. Check for UI Lag (Front-Running)
                if event["display_delta"] > 5:
                     print(f"⚡ SPEED: UI is lagging by {event['display_delta']} tweets.")
                     # BUY YES before UI updates
```

---

## 5. Risk Warnings

- **Deleted Tweets**: Tweets are counted instantly. If Elon deletes a tweet, `real_counter` drops. `settlement_delta` will vanish.
  - *Mitigation*: Wait for `settlement_delta >= 2` before going all-in.
- **Model Variance**: Predictions >48h out have ±40% error bars. Trust the model signals (`p5`/`p95`) mainly in the final 24h.

---
built with 🤖 by [Polystrike](https://polystrike.xyz)



--- FILE: docs/api/cruz.md ---

---
title: Ted Cruz Tweet Markets
description: Documentation for Polystrike's Ted Cruz tweet-tracking data feed.
---

Polystrike provides accurate and low-latency tracking for Polymarket's Ted Cruz tweet count markets.

## Endpoints

### Metadata Overview
`GET /meta/cruz`

**Public**. Returns real-time counters and "Lag Edges" for all active Cruz events.

**Sample Response:**
```json
{
  "timestamp": 1774250948000,
  "data": [
    {
      "event_id": 262360,
      "event_title": "Ted Cruz # posts March 17 - March 24, 2026?",
      "start_ts": 1773964800000,
      "end_ts": 1774569600000,
      "polymarket_xtracker_counter": 67,
      "real_counter": 67,
      "polymarket_ui_counter": 67,
      "settlement_delta": 0,
      "display_delta": 0,
      "internal_delta": 0
    }
  ]
}
```

#### Field Descriptions
| Field | Type | Description |
|-------|------|-------------|
| `event_id` | number | Unique ID of the Polymarket event. |
| `event_title` | string | Human-readable event title from Polymarket. |
| `image` | string | Event image URL from Polymarket. |
| `start_ts` / `end_ts` | number | Event window start/end times (UTC milliseconds). |
| `polymarket_xtracker_counter` | number | Settlement oracle count. This is what Polymarket pays out on. |
| `real_counter` | number | Polystrike's real-time count. Faster than the oracle; includes deleted tweet captures. |
| `polymarket_ui_counter` | number | Count currently displayed on the Polymarket trading UI. |
| `settlement_delta` | number | `real_counter − xtracker`. Positive = we're ahead of the oracle. |
| `display_delta` | number | `real_counter − ui_counter`. Positive = UI is showing a stale number. |
| `internal_delta` | number | `ui_counter − xtracker`. Positive = UI is ahead of the oracle. |

### Predictive Models
`GET /prediction/cruz`

**Public** (Limited) / **Pro** (Full).
- **Public**: Counters + Market Prices only.
- **Pro**: Forecasts (p5/p50/p95), Signals (Buy/Sell), and Alpha.

**Sample Response (Pro):**
```json
{
  "timestamp": 1774250948000,
  "data": [
    {
      "event_id": 262360,
      "seconds_remaining": 115200,
      "sleep_probability": 0.092,
      "forecast": {
        "p5": 75,
        "p50": 89,
        "p95": 105
      },
      "markets": [
        {
          "title": "80-99",
          "model_prob": 0.62,
          "market_price": 0.32,
          "edge": 0.30,
          "signal": "STRONG_BUY"
        }
      ]
    }
  ]
}
```

#### Field Descriptions
| Field | Type | Description |
|-------|------|-------------|
| `forecast.p5/p50/p95` | number | **Pro Only**. Monte Carlo forecast percentiles. |
| `sleep_probability` | number | Probability Cruz is currently sleeping. |
| `markets.model_prob` | number | **Pro Only**. Our calculated win probability. |
| `markets.market_price` | number | Current "Yes" price on Polymarket. |
| `markets.edge` | number | **Pro Only**. `model_prob - market_price`. |
| `markets.signal` | string | **Pro Only**. `STRONG_BUY`, `BUY`, `HOLD`, `SELL`. |

### EV-Based Signals
`GET /signals/cruz`

**Pro Only**. Returns actionable trading signals optimized for Expected Value (EV), with optimal Kelly Criterion bet sizing and Information Asymmetry edge detection.

**Query Parameters:**
| Parameter | Required | Description |
|-----------|----------|-------------|
| `bankroll` | No | Your bankroll in USD (1-1,000,000). Sizes `suggested_bet` via Kelly criterion. If omitted, a server default is used. |

```
GET /api/v1/signals/cruz?bankroll=100
```

**Sample Response:**
```json
{
  "timestamp": 1774250948000,
  "data": [
    {
      "event_id": 262360,
      "event_title": "Ted Cruz # posts March 17 - March 24, 2026?",
      "signals": [
        {
          "bucket": "80-99",
          "token_id": "0x1234...",
          "action": "BUY",
          "model_prob": 0.62,
          "market_price": 0.32,
          "edge": 0.30,
          "ev": 0.938,
          "kelly_fraction": 0.042,
          "suggested_bet": 4.20,
          "confidence": "HIGH",
          "moneyness": 0.95,
          "time_confidence": "MEDIUM",
          "asymmetry_edge": 0,
          "reasons": [
            "Strong signal: 62% prob, +93.8% EV"
          ],
          "bankroll": 100.0
        }
      ]
    }
  ]
}
```

#### Field Descriptions
| Field | Type | Description |
|-------|------|-------------|
| `bucket` | string | Market outcome bucket (e.g., "80-99"). |
| `token_id` | string | Polymarket CLOB token ID for trade execution. |
| `action` | string | `BUY`, `HOLD`, or `SKIP`. |
| `model_prob` | number | Model's calculated win probability (0-1). |
| `market_price` | number | Current market price. |
| `edge` | number | `model_prob - market_price`. Positive = undervalued. |
| `ev` | number | Expected value per $1 bet. |
| `kelly_fraction` | number | Optimal bet fraction per Kelly Criterion. |
| `suggested_bet` | number | Dollar amount based on Kelly + your bankroll. |
| `confidence` | string | `HIGH`, `MEDIUM`, or `LOW` based on multiple factors. |
| `moneyness` | number | How deep p50 falls into bucket (0=edge, 1=center). |
| `time_confidence` | string | `HIGH` (<24h), `MEDIUM` (24-48h), `LOW` (>72h). |
| `asymmetry_edge` | number | XTracker - UI counter. Positive = UI lagging. |
| `reasons` | array | Human-readable explanations for the signal. |

### Portfolio Analysis
`GET /portfolio/cruz`

**Pro Only**. Fetches your open Cruz tweet market positions directly from Polymarket, then overlays our model predictions to tell you where each position stands.

**Query Parameters:**
| Parameter | Required | Description |
|-----------|----------|-------------|
| `wallet` | Yes | Your Ethereum wallet address (e.g. `0xabc...123`) |

**Sample Response:**
```json
{
  "timestamp": 1774250948000,
  "data": [
    {
      "wallet": "0xabc...123",
      "event": {
        "id": 262360,
        "title": "Ted Cruz # posts March 17 - March 24, 2026?",
        "end_ts": 1774569600000
      },
      "prediction": {
        "p5": 75,
        "p50": 89,
        "p95": 105,
        "real_counter": 67,
        "seconds_remaining": 115200,
        "velocity_counted_1h": 2.1
      },
      "positions": [
        {
          "event_id": "262360",
          "bucket": "80-99",
          "tokens": 50.0,
          "avg_price": 0.30,
          "cost_basis": 15.00,
          "current_price": 0.32,
          "current_value": 16.00,
          "pnl": 1.00,
          "pnl_percent": 6.67,
          "analysis": {
            "win_probability": 0.62,
            "market_implied": 0.32,
            "edge": 0.30,
            "edge_percent": 93.75,
            "signal": "STRONG_BUY",
            "recommendation": "STRONG_HOLD"
          }
        }
      ],
      "portfolio": {
        "total_positions": 1,
        "total_cost": 15.00,
        "current_value": 16.00,
        "total_pnl": 1.00,
        "total_pnl_percent": 6.67
      }
    }
  ]
}
```

#### How It Works

The endpoint has three steps:

1. **Fetches your open positions** from the Polymarket API using your wallet address
2. **Filters to active Cruz tweet markets** — positions in other market types are excluded
3. **Overlays model predictions** for each bucket you hold, computing edge and generating a signal

If no active Cruz events are running, `positions` will be empty and a `message` field explains why.

#### Field Descriptions — prediction

| Field | Type | Description |
|-------|------|-------------|
| `p5` / `p50` / `p95` | number | Monte Carlo forecast percentiles for final tweet count. |
| `real_counter` | number | Current real tweet count at time of prediction. |
| `seconds_remaining` | number | Seconds until the event closes. |
| `velocity_counted_1h` | number | Average counted tweets per hour over the last hour. Useful for projecting how much more is likely before close. |

#### Field Descriptions — positions

| Field | Type | Description |
|-------|------|-------------|
| `bucket` | string | The Polymarket outcome bucket you hold (e.g. `"80-99"`). |
| `tokens` | number | Number of shares/tokens you hold. |
| `avg_price` | number | Your average purchase price per token. |
| `cost_basis` | number | Total amount paid for this position. |
| `current_price` | number | Current market price per token. |
| `current_value` | number | Current mark-to-market value. |
| `pnl` | number | Unrealised profit/loss in USDC. |
| `pnl_percent` | number | Unrealised PnL as a percentage. |

#### Field Descriptions — analysis

| Field | Type | Description |
|-------|------|-------------|
| `win_probability` | number | Model's estimated probability this bucket wins (0–1). |
| `market_implied` | number | Current market price — the crowd's implied probability. |
| `edge` | number | `win_probability − market_implied`. Positive = model sees more value than the market. |
| `edge_percent` | number | Edge expressed as a percentage of the market price. |
| `signal` | string | See signal table below. |
| `recommendation` | string | See recommendation table below. |

#### Signal Values

The `signal` field is based on `edge_percent`:

| Signal | Condition | Meaning |
|--------|-----------|---------|
| `STRONG_BUY` | `edge_percent > 30%` | Model sees strong undervaluation — consider adding |
| `BUY` | `edge_percent > 10%` | Clear positive edge exists |
| `HOLD` | `edge_percent > 0%` | Slight edge — worth keeping |
| `AVOID` | `edge_percent > -10%` | Near fair value, slightly unfavourable |
| `SELL` | `edge_percent ≤ -10%` | Model sees meaningful overvaluation — consider exiting |

#### Recommendation Values

The `recommendation` field is based on raw `edge` (not percentage):

| Recommendation | Condition | Meaning |
|----------------|-----------|---------|
| `STRONG_HOLD` | `edge > 0.20` | High absolute edge — hold firmly |
| `HOLD` | `edge > 0.05` | Positive edge — no reason to exit |
| `MONITOR` | `edge > -0.05` | Near fair value — watch closely |
| `CONSIDER_SELLING` | `edge ≤ -0.05` | Model favours exiting this position |

:::tip
`signal` and `recommendation` use different scales. `signal` is more sensitive (percentage-based) and useful for deciding whether to *add*. `recommendation` uses absolute edge and is better for deciding whether to *exit*.
:::

#### Error Responses

| Status | Condition |
|--------|-----------|
| `400` | Wallet address is not a valid Ethereum address (`0x` + 40 hex chars) |
| `401` | Missing or invalid Pro API key |
| `503` | Could not reach the Polymarket API to fetch positions |

### Raw Tweet Stream
`GET /meta/cruz/tweets`

**Public** (Masked) / **Pro** (Full).
- **Public**: Fixed at the latest **15 tweets**. `is_counted` is null.
- **Pro**: Custom pagination using `limit` (max 100) and `offset`. `is_counted` (`true`/`false`) reveals which tweets count toward resolution.

**Query Parameters (Pro Only):**
- `limit`: Number of tweets to return (max 100).
- `offset`: Number of tweets to skip.

**Sample Response:**
```json
{
  "timestamp": 1774250948000,
  "data": [
    {
      "tweet_id": "1771234567890123456",
      "text": "Great meeting with constituents today...",
      "created_ts": 1774234718000,
      "is_reply": false,
      "is_quote": false,
      "is_retweet": false,
      "is_counted": true
    }
  ],
  "limit": 15,
  "offset": 0
}
```

#### Field Descriptions
| Field | Type | Description |
|-------|------|-------------|
| `tweet_id` | string | Twitter status ID. |
| `text` | string | Tweet content. |
| `is_counted` | boolean\|null | **Pro Only**. Whether tweet counts for resolution. Null for public users. |
| `is_reply` / `is_quote` / `is_retweet` | boolean | Tweet type flags. |
| `limit` / `offset` | number | Pagination values used for the request. |

## Model Characteristics

The Cruz prediction model uses the same Monte Carlo simulation approach as the Elon model, but with Cruz-specific parameters:

- **Sleep Probability**: ~9.2% (calculated from Cruz's actual tweet gaps)
- **Rolling Window**: 14-day lookback for velocity estimation
- **Bias Correction**: Uses Cruz-specific historical event data (when sufficient data available)
- **Independence**: Completely separate from Elon model - no cross-contamination

:::note
Cruz markets have less historical data than Elon markets. Model confidence will improve as more events complete and historical patterns emerge.
:::



--- FILE: docs/api/crypto.md ---

---
title: Crypto Price Markets
description: Real-time price tracking for 15-minute prediction markets.
---

Polystrike tracks high-frequency crypto price markets on Polymarket, ensuring you have the latest price data to capture volatility.

## Endpoints

### Market Metadata
`GET /meta/crypto`

> **Note**: This endpoint is currently in **Active Development**. It currently returns an empty list `[]` as we finalize the 15-minute price resolution engine. The schema below represents the **planned** response structure.

Returns status and pricing for active 15-minute crypto outcome markets.

**Planned Response Schema:**
```json
{
  "timestamp": 1770789357226,
  "data": [
    {
      "event_id": 12345,
      "event_title": "BTC price at 19:15 UTC?",
      "symbol": "BTC",
      "polymarket_price": 97500.00,
      "chainlink_price": 97495.20
    }
  ]
}
```

#### Field Descriptions
| Field | Type | Description |
|-------|------|-------------|
| `event_id` | number | Unique ID of the Polymarket event. |
| `event_title` | string | Title containing the strike time and condition. |
| `symbol` | string | Crypto asset symbol (e.g., `BTC`, `ETH`). |
| `polymarket_price` | number | The strike price defined in the market title. |
| `chainlink_price` | number | The current reference price from the Chainlink oracle (or null if unavailable). |

## Coming Soon: Phase 2 Integration

We are currently optimizing our historical data feeds for Phase 2, which will include:
- **Historical Volatility Index**: Customized for 15-minute windows.
- **Settlement Predictors**: Analyzing order book depth and whale activity near market close.



--- FILE: docs/api/elon.md ---

---
title: Elon Musk Tweet Markets
description: Documentation for Polystrike's core tweet-tracking data feed.
---

Polystrike provides the most accurate and low-latency tracking for Polymarket's Elon Musk tweet count markets.

## Endpoints

### Metadata Overview
`GET /meta/elon`

**Public**. Returns real-time counters and "Lag Edges" for all active Elon events.

**Sample Response:**
```json
{
  "timestamp": 1771246725679,
  "data": [
    {
      "event_id": 206602,
      "event_title": "Elon Musk # tweets February 14 - February 16, 2026?",
      "start_ts": 1771088400000,
      "end_ts": 1771261200000,
      "polymarket_xtracker_counter": 65,
      "real_counter": 68,
      "polymarket_ui_counter": 65,
      "settlement_delta": 3,
      "display_delta": 3,
      "internal_delta": 0
    }
  ]
}
```

#### Field Descriptions
| Field | Type | Description |
|-------|------|-------------|
| `event_id` | number | Unique ID of the Polymarket event. |
| `event_title` | string | Human-readable event title from Polymarket. |
| `image` | string | Event image URL from Polymarket. |
| `start_ts` / `end_ts` | number | Event window start/end times (UTC milliseconds). |
| `polymarket_xtracker_counter` | number | Settlement oracle count. This is what Polymarket pays out on. |
| `real_counter` | number | Polystrike's real-time count. Faster than the oracle; includes deleted tweet captures. |
| `polymarket_ui_counter` | number | Count currently displayed on the Polymarket trading UI. |
| `settlement_delta` | number | `real_counter − xtracker`. Positive = we're ahead of the oracle. |
| `display_delta` | number | `real_counter − ui_counter`. Positive = UI is showing a stale number. |
| `internal_delta` | number | `ui_counter − xtracker`. Positive = UI is ahead of the oracle. |

### Predictive Models
`GET /prediction/elon`

**Public** (Limited) / **Pro** (Full).
- **Public**: Counters + Market Prices only.
- **Pro**: Forecasts (p5/p50/p95), Signals (Buy/Sell), and Alpha.

**Sample Response (Pro):**
```json
{
  "timestamp": 1771246734873,
  "data": [
    {
      "event_id": 206602,
      "seconds_remaining": 14528,
      "sleep_probability": 0.016,
      "forecast": {
        "p5": 68,
        "p50": 68,
        "p95": 69
      },
      "markets": [
        {
          "title": "65-89",
          "model_prob": 1.0,
          "market_price": 0.945,
          "edge": 0.055,
          "signal": "SLIGHT_BUY"
        }
      ]
    }
  ]
}
```

#### Field Descriptions
| Field | Type | Description |
|-------|------|-------------|
| `forecast.p5/p50/p95` | number | **Pro Only**. Monte Carlo forecast percentiles. |
| `sleep_probability` | number | Probability Elon is currently sleeping. |
| `markets.model_prob` | number | **Pro Only**. Our calculated win probability. |
| `markets.market_price` | number | Current "Yes" price on Polymarket. |
| `markets.edge` | number | **Pro Only**. `model_prob - market_price`. |
| `markets.signal` | string | **Pro Only**. `STRONG_BUY`, `BUY`, `HOLD`, `SELL`. |

### EV-Based Signals
`GET /signals/elon`

**Pro Only**. Returns actionable trading signals optimized for Expected Value (EV), with optimal Kelly Criterion bet sizing and Information Asymmetry edge detection.

**Query Parameters:**
| Parameter | Required | Description |
|-----------|----------|-------------|
| `bankroll` | No | Your bankroll in USD (1-1,000,000). Sizes `suggested_bet` via Kelly criterion. If omitted, a server default is used. |

```
GET /api/v1/signals/elon?bankroll=100
```

**Sample Response:**
```json
{
  "timestamp": 1771246739535,
  "data": [
    {
      "event_id": 206602,
      "signals": [
        {
          "bucket": "65-89",
          "action": "BUY",
          "model_prob": 1.0,
          "market_price": 0.945,
          "edge": 0.055,
          "ev": 0.058,
          "kelly_fraction": 0.058,
          "suggested_bet": 5.80,
          "confidence": "HIGH",
          "moneyness": 0.5,
          "time_confidence": "HIGH",
          "asymmetry_edge": 0,
          "reasons": [
            "Strong signal: 100% prob, +5.8% EV"
          ],
          "bankroll": 100.0
        }
      ]
    }
  ]
}
```

### Portfolio Analysis
`GET /portfolio/elon`

**Pro Only**. Fetches your open Elon tweet market positions directly from Polymarket, then overlays our model predictions to tell you where each position stands.

**Query Parameters:**
| Parameter | Required | Description |
|-----------|----------|-------------|
| `wallet` | Yes | Your Ethereum wallet address (e.g. `0xabc...123`) |

**Sample Response:**
```json
{
  "timestamp": 1771246750000,
  "data": [
    {
      "wallet": "0xabc...123",
      "event": {
        "id": 206602,
        "title": "Elon Musk # tweets February 14 - February 16, 2026?",
        "end_ts": 1771261200000
      },
      "prediction": {
        "p5": 68,
        "p50": 72,
        "p95": 78,
        "real_counter": 68,
        "seconds_remaining": 14528,
        "velocity_counted_1h": 4.2
      },
      "positions": [
        {
          "event_id": "206602",
          "bucket": "65-89",
          "tokens": 50.0,
          "avg_price": 0.82,
          "cost_basis": 41.00,
          "current_price": 0.945,
          "current_value": 47.25,
          "pnl": 6.25,
          "pnl_percent": 15.24,
          "analysis": {
            "win_probability": 1.0,
            "market_implied": 0.945,
            "edge": 0.055,
            "edge_percent": 5.82,
            "signal": "BUY",
            "recommendation": "HOLD"
          }
        }
      ],
      "portfolio": {
        "total_positions": 1,
        "total_cost": 41.00,
        "current_value": 47.25,
        "total_pnl": 6.25,
        "total_pnl_percent": 15.24
      }
    }
  ]
}
```

#### How It Works

The endpoint has three steps:

1. **Fetches your open positions** from the Polymarket API using your wallet address
2. **Filters to active Elon tweet markets** — positions in other market types are excluded
3. **Overlays model predictions** for each bucket you hold, computing edge and generating a signal

If no active Elon events are running, `positions` will be empty and a `message` field explains why.

#### Field Descriptions — prediction

| Field | Type | Description |
|-------|------|-------------|
| `p5` / `p50` / `p95` | number | Monte Carlo forecast percentiles for final tweet count. |
| `real_counter` | number | Current real tweet count at time of prediction. |
| `seconds_remaining` | number | Seconds until the event closes. |
| `velocity_counted_1h` | number | Average counted tweets per hour over the last hour. Useful for projecting how much more is likely before close. |

#### Field Descriptions — positions

| Field | Type | Description |
|-------|------|-------------|
| `bucket` | string | The Polymarket outcome bucket you hold (e.g. `"65-89"`). |
| `tokens` | number | Number of shares/tokens you hold. |
| `avg_price` | number | Your average purchase price per token. |
| `cost_basis` | number | Total amount paid for this position. |
| `current_price` | number | Current market price per token. |
| `current_value` | number | Current mark-to-market value. |
| `pnl` | number | Unrealised profit/loss in USDC. |
| `pnl_percent` | number | Unrealised PnL as a percentage. |

#### Field Descriptions — analysis

| Field | Type | Description |
|-------|------|-------------|
| `win_probability` | number | Model's estimated probability this bucket wins (0–1). |
| `market_implied` | number | Current market price — the crowd's implied probability. |
| `edge` | number | `win_probability − market_implied`. Positive = model sees more value than the market. |
| `edge_percent` | number | Edge expressed as a percentage of the market price. |
| `signal` | string | See signal table below. |
| `recommendation` | string | See recommendation table below. |

#### Signal Values

The `signal` field is based on `edge_percent`:

| Signal | Condition | Meaning |
|--------|-----------|---------|
| `STRONG_BUY` | `edge_percent > 30%` | Model sees strong undervaluation — consider adding |
| `BUY` | `edge_percent > 10%` | Clear positive edge exists |
| `HOLD` | `edge_percent > 0%` | Slight edge — worth keeping |
| `AVOID` | `edge_percent > -10%` | Near fair value, slightly unfavourable |
| `SELL` | `edge_percent ≤ -10%` | Model sees meaningful overvaluation — consider exiting |

#### Recommendation Values

The `recommendation` field is based on raw `edge` (not percentage):

| Recommendation | Condition | Meaning |
|----------------|-----------|---------|
| `STRONG_HOLD` | `edge > 0.20` | High absolute edge — hold firmly |
| `HOLD` | `edge > 0.05` | Positive edge — no reason to exit |
| `MONITOR` | `edge > -0.05` | Near fair value — watch closely |
| `CONSIDER_SELLING` | `edge ≤ -0.05` | Model favours exiting this position |

:::tip
`signal` and `recommendation` use different scales. `signal` is more sensitive (percentage-based) and useful for deciding whether to *add*. `recommendation` uses absolute edge and is better for deciding whether to *exit*.
:::

#### Error Responses

| Status | Condition |
|--------|-----------|
| `400` | Wallet address is not a valid Ethereum address (`0x` + 40 hex chars) |
| `401` | Missing or invalid Pro API key |
| `503` | Could not reach the Polymarket API to fetch positions |

### Raw Tweet Stream
`GET /meta/elon/tweets`

**Public** (Masked) / **Pro** (Full).
- **Public**: Fixed at the latest **15 tweets**. `is_counted` is null.
- **Pro**: Custom pagination using `limit` (max 100) and `offset`. `is_counted` (`true`/`false`) reveals which tweets count toward resolution.

**Query Parameters (Pro Only):**
- `limit`: Number of tweets to return (max 100).
- `offset`: Number of tweets to skip.

**Sample Response:**
```json
{
  "timestamp": 1771246730263,
  "data": [
    {
      "tweet_id": "2023331176019370170",
      "text": "Yes https://t.co/C7Eo7s...",
      "created_ts": 1771234718000,
      "is_reply": false,
      "is_quote": true,
      "is_retweet": false,
      "is_counted": true
    }
  ],
  "limit": 15,
  "offset": 0
}
```

#### Field Descriptions
| Field | Type | Description |
|-------|------|-------------|
| `tweet_id` | string | Twitter status ID. |
| `text` | string | Tweet content. |
| `is_counted` | boolean\|null | **Pro Only**. Whether tweet counts for resolution. Null for public users. |
| `is_reply` / `is_quote` / `is_retweet` | boolean | Tweet type flags. |
| `limit` / `offset` | number | Pagination values used for the request. |




--- FILE: docs/api/overview.md ---

---
title: API Overview
description: How to authenticate and interact with the Polystrike data engine.
---

The Polystrike API is designed for low-latency access to prediction market metadata and signals.

## Infrastructure

All endpoints are hosted on high-performance bare-metal servers to ensure maximum uptime and minimal response times.

**Base URL:** `https://polystrike.xyz/api/v1`

## Authentication

Endpoints are either **Public** (no key needed) or **Pro** (requires `X-API-Key` header).

- **Public (Anonymous):** Free access to metadata/counters. Rate limited to 100 requests/hour.
- **Pro ($79/mo):** Full access to predictions, signals, and portfolio analysis. Rate limited to 10,000 requests/hour.

### Access Methods

**Direct HTTP API** (this documentation):
```bash
curl -H "X-API-Key: ps_pro_..." https://polystrike.xyz/api/v1/prediction/elon
```

**OpenAPI Specification** (for automated discovery):
```bash
curl https://polystrike.xyz/openapi.json
```

The OpenAPI spec provides machine-readable documentation of all endpoints, parameters, authentication schemes, and response types. Use it to:
- Generate client libraries in any language
- Integrate with AI agents and automated systems
- Understand the API structure programmatically

**MCP Server** (for Claude Desktop users):
Natural language access through the Model Context Protocol. See [MCP Server Setup](/docs/guides/mcp-setup) for configuration.

**To upgrade to Pro:**
- **Telegram**: [@dizpers](https://t.me/dizpers)
- **X**: [@dizpers](https://x.com/dizpers)
- **Email**: `dizpers@gmail.com` (Subject: Polystrike PRO)

## Response Format

All responses are standard JSON. Timestamps are **UTC Milliseconds**.

```json
{
  "timestamp": 1770188662000,
  "data": [ ... ]
}
```

## Rate Limits

| Tier | Limit |
|---|---|
| **Anonymous** | 100 req/hour (by IP) |
| **Pro** | 10,000 req/hour (by Key) |

## Feature Comparison by Tier

Below is the exact field visibility for each endpoint.

### GET /meta/elon — Public (No Key)

| Field | Anonymous | Pro |
|-------|:---------:|:---:|
| `event_id` | ✅ | ✅ |
| `event_title` | ✅ | ✅ |
| `start_ts` | ✅ | ✅ |
| `end_ts` | ✅ | ✅ |
| `polymarket_xtracker_counter` | ✅ | ✅ |
| `real_counter` | ✅ | ✅ |
| `polymarket_ui_counter` | ✅ | ✅ |
| `settlement_delta` | ✅ | ✅ |
| `display_delta` | ✅ | ✅ |
| `internal_delta` | ✅ | ✅ |

### GET /meta/elon/tweets — Public (Rate Limited)

| Field | Anonymous | Pro |
|-------|:---------:|:---:|
| `tweet_id` | ✅ | ✅ |
| `text` | ✅ | ✅ |
| `created_ts` | ✅ | ✅ |
| `referenced_text` | ✅ | ✅ |
| `referenced_author_id` | ✅ | ✅ |
| `is_reply` | ✅ | ✅ |
| `is_quote` | ✅ | ✅ |
| `is_retweet` | ✅ | ✅ |
| **`is_counted`** | **null** | ✅ |

### GET /prediction/elon — Public (Rate Limited)

| Field | Anonymous | Pro |
|-------|:---------:|:---:|
| `event_id` | ✅ | ✅ |
| `event_title` | ✅ | ✅ |
| `polymarket_xtracker_counter` | ✅ | ✅ |
| `polymarket_ui_counter` | ✅ | ✅ |
| `real_counter` | ✅ | ✅ |
| `settlement_delta` | ✅ | ✅ |
| `display_delta` | ✅ | ✅ |
| `internal_delta` | ✅ | ✅ |
| `seconds_remaining` | ✅ | ✅ |
| `sleep_probability` | ✅ | ✅ |
| `markets[].title` | ✅ | ✅ |
| `markets[].market_price` | ✅ | ✅ |
| **`markets[].model_prob`** | ❌ | ✅ |
| **`forecast.p5`** | ❌ | ✅ |
| **`forecast.p50`** | ❌ | ✅ |
| **`forecast.p95`** | ❌ | ✅ |
| **`markets[].edge`** | ❌ | ✅ |
| **`markets[].signal`** | ❌ | ✅ |

### GET /signals/elon — Pro Only (401 without key)

Optional query parameter: `?bankroll=100` — sizes `suggested_bet` to your bankroll via Kelly criterion.

| Field | Anonymous | Pro |
|-------|:---------:|:---:|
| `event_id` | ❌ 401 | ✅ |
| `event_title` | ❌ 401 | ✅ |
| `signals[].bucket` | ❌ 401 | ✅ |
| `signals[].action` | ❌ 401 | ✅ |
| `signals[].model_prob` | ❌ 401 | ✅ |
| `signals[].market_price` | ❌ 401 | ✅ |
| `signals[].edge` | ❌ 401 | ✅ |
| `signals[].ev` | ❌ 401 | ✅ |
| `signals[].kelly_fraction` | ❌ 401 | ✅ |
| `signals[].suggested_bet` | ❌ 401 | ✅ (sized to `?bankroll` if provided) |
| `signals[].confidence` | ❌ 401 | ✅ |
| `signals[].moneyness` | ❌ 401 | ✅ |
| `signals[].time_confidence` | ❌ 401 | ✅ |
| `signals[].asymmetry_edge` | ❌ 401 | ✅ |
| `signals[].reasons` | ❌ 401 | ✅ |
| `signals[].bankroll` | ❌ 401 | ✅ |

### GET /portfolio/elon?wallet=0x... — Pro Only (401 without key)

| Field | Anonymous | Pro |
|-------|:---------:|:---:|
| `wallet` | ❌ 401 | ✅ |
| `event.id` | ❌ 401 | ✅ |
| `event.title` | ❌ 401 | ✅ |
| `event.end_ts` | ❌ 401 | ✅ |
| `prediction.p5` / `p50` / `p95` | ❌ 401 | ✅ |
| `prediction.real_counter` | ❌ 401 | ✅ |
| `prediction.seconds_remaining` | ❌ 401 | ✅ |
| `positions[].event_id` | ❌ 401 | ✅ |
| `positions[].bucket` | ❌ 401 | ✅ |
| `positions[].tokens` | ❌ 401 | ✅ |
| `positions[].avg_price` | ❌ 401 | ✅ |
| `positions[].cost_basis` | ❌ 401 | ✅ |
| `positions[].current_price` | ❌ 401 | ✅ |
| `positions[].current_value` | ❌ 401 | ✅ |
| `positions[].pnl` | ❌ 401 | ✅ |
| `positions[].pnl_percent` | ❌ 401 | ✅ |
| `positions[].analysis.win_probability` | ❌ 401 | ✅ |
| `positions[].analysis.market_implied` | ❌ 401 | ✅ |
| `positions[].analysis.edge` | ❌ 401 | ✅ |
| `positions[].analysis.edge_percent` | ❌ 401 | ✅ |
| `positions[].analysis.signal` | ❌ 401 | ✅ |
| `positions[].analysis.recommendation` | ❌ 401 | ✅ |
| `portfolio.total_positions` | ❌ 401 | ✅ |
| `portfolio.total_cost` | ❌ 401 | ✅ |
| `portfolio.current_value` | ❌ 401 | ✅ |
| `portfolio.total_pnl` | ❌ 401 | ✅ |
| `portfolio.total_pnl_percent` | ❌ 401 | ✅ |




--- FILE: docs/api/system.md ---

---
title: System API
description: Operational endpoints for health checks and waitlist management.
---

## Health Check
`GET /health`

Used by load balancers and monitoring systems to verify API availability.

**Sample Response:**
```json
{
  "timestamp": 1770789357608,
  "status": "ok"
}
```

## Waitlist Registration
`POST /waitlist`

Register an agent or human user for early access to upcoming features.

### Parameters

| Field | Type | Required? | Description |
|-------|------|-----------|-------------|
| `type` | string | Yes | Must be `agent` or `human`. |
| `case` | string | Yes | Description of your intended use case. |
| `name` | string | If type=agent | Name of the bot/agent. |
| `wallet` | string | If type=agent | Base wallet address for whitelist |
| `email` | string | If type=human | Contact email address. |

### Example Request (Agent)

```bash
curl -X POST https://polystrike.xyz/api/v1/waitlist \
  -H "Content-Type: application/json" \
  -d '{
    "type": "agent",
    "name": "ArbBot-V1",
    "wallet": "0x123...",
    "case": "High-frequency arbitrage on Elon markets"
  }'
```

**Response:**
```json
{
  "status": "registered",
  "position": 42
}
```



--- FILE: docs/guides/concepts.md ---

---
title: Core Concepts
description: Understand the problem Polystrike solves and the data model behind it.
---

Polystrike is an oracle intelligence layer for Polymarket's Elon Musk tweet count markets. This page explains the core problem and how Polystrike gives you an information edge.

## The Problem: Two Counters, Both Wrong

Polymarket shows traders two tweet counters:

- **XTracker** (the settlement oracle): Updates every ~5 minutes. This is the number that actually determines who wins and loses.
- **UI Counter**: Displayed on the Polymarket trading interface. Frequently freezes or lags behind XTracker.

Most retail traders price their positions based on the UI counter. But the UI counter is often severely wrong — sometimes lagging by 5-10+ tweets. That lag is the exploitable inefficiency.

## The Solution: A Third Counter

Polystrike maintains its own counter — the **real counter** — by querying Twitter every 60 seconds and classifying each tweet against the exact settlement rules.

| Counter | Source | Update Frequency | Settlement Authority |
|---------|--------|-------------------|---------------------|
| **UI Counter** | Polymarket frontend | Irregular, often frozen | None |
| **XTracker** | Settlement oracle | Every ~5 minutes | Yes (determines payouts) |
| **Real Counter** | Polystrike | Every 60 seconds | None (but most accurate) |

The real counter is 5x faster than the settlement oracle and catches events the oracle never sees (deleted tweets).

## Deleted Tweets

Elon Musk deletes tweets. If a tweet existed when XTracker last scraped, it counts toward settlement — even if it's deleted by the time you check Twitter manually.

Polystrike captures tweets within seconds of posting. If a tweet is later deleted, we flag it with `is_deleted: true` but it remains in our count. This means:

- Our real counter may diverge from what you see on Twitter right now
- That divergence is correct — deleted tweets *did* count

## The is_counted Classification

Not every Elon tweet counts toward Polymarket settlement. The rules are specific:

| Tweet Type | Counts? |
|-----------|---------|
| Main feed post | Yes |
| Quote post | Yes |
| Repost (retweet) | Yes |
| Main-feed reply | Yes |
| Regular reply | No |
| Community repost | No |

XTracker doesn't expose this classification. Polystrike classifies every tweet in real time and exposes the `is_counted` field (Pro tier only).

## The Three Deltas

Polystrike tracks three independent lag signals. Each represents a different information asymmetry:

### settlement_delta
```
settlement_delta = real_counter - xtracker_counter
```
**What it means**: How far ahead of the settlement oracle we are. A positive value means Polystrike has counted tweets that XTracker hasn't picked up yet — including deleted tweets.

### display_delta
```
display_delta = real_counter - ui_counter
```
**What it means**: How wrong the Polymarket UI is. When this is large, most traders are looking at a stale number and may be mispricing their positions.

### internal_delta
```
internal_delta = ui_counter - xtracker_counter
```
**What it means**: The gap between what Polymarket shows and what will actually settle. Can be positive (UI ahead of oracle) or negative (UI behind oracle).

## Monte Carlo Predictions

Polystrike runs 1,000 Monte Carlo simulations per active event to produce bucket probability forecasts:

- **p5**: 5th percentile (optimistic low bound)
- **p50**: Median expected count
- **p95**: 95th percentile (pessimistic high bound)

The model is **sleep-aware** — it accounts for Elon's Texas timezone sleep schedule. Tweeting velocity drops to near-zero during sleep hours, which is deterministic, not random.

### Reliability Window

- **Final 16 hours**: Most reliable. The model has enough data to project accurately.
- **16-36 hours remaining**: Moderate reliability. Use with caution.
- **More than 36 hours**: Early predictions carry 15-20% overestimation risk. The model tends to extrapolate current velocity too aggressively.

## Tiers

| Feature | Free | Pro ($79/mo) |
|---------|------|-------------|
| Real-time counters & deltas | Yes | Yes |
| Recent tweets (last 15) | Yes | Yes |
| `is_counted` classification | Masked (null) | Yes |
| Full tweet history + pagination | No | Yes |
| Monte Carlo predictions | No | Yes |
| Trading signals (EV, Kelly) | No | Yes |
| Portfolio analysis | No | Yes |
| Rate limit | 100 req/hr | 10,000 req/hr |



--- FILE: docs/guides/example.md ---

---
title: FAQ
description: Frequently asked questions about Polystrike.
---

## Why is the real_counter higher than XTracker?

Two reasons:

1. **Speed**: Polystrike queries Twitter every 60 seconds. XTracker updates every ~5 minutes. So at any given moment, we've likely caught new tweets that XTracker hasn't processed yet.

2. **Deleted tweets**: If Elon posts and then deletes a tweet, our system captures it within seconds. If XTracker's next update runs *after* the deletion, it never sees that tweet — but it still counts if it existed during the window.

The `settlement_delta` field tells you exactly how large this gap is.

---

## Does is_counted track the same rules as Polymarket?

Yes. The classification is based on the public settlement rules:

- Main feed posts → **counted**
- Quote posts → **counted**
- Reposts (retweets) → **counted**
- Main-feed replies → **counted**
- Regular replies → **not counted**
- Community reposts → **not counted**

`is_counted` is a Pro-only field. Free tier returns `null`.

---

## Why does display_delta go negative sometimes?

The Polymarket UI sometimes *over-counts* — it shows a number higher than the real count. This can happen when the UI picks up a tweet that later gets deleted or that our system doesn't classify as counted.

A negative `display_delta` means the UI is ahead of our real count. This is unusual but not impossible.

---

## When are predictions most reliable?

The Monte Carlo model is most reliable in the **final 16 hours** of an event. At that point, the count trajectory and velocity are well established.

Early in an event (more than 36 hours remaining), predictions tend to overestimate by 15-20% because the model extrapolates current velocity too aggressively before sleep patterns emerge.

---

## What does sleep_probability mean?

Elon Musk is based in Texas (CT timezone). His sleep schedule is fairly consistent — there are specific overnight hours when his tweet velocity drops to near-zero.

The `sleep_probability` field gives the current probability that he's asleep right now, based on historical patterns. When this is high, the velocity model reduces its projection accordingly.

---

## How do I get a Pro API key?

Contact via Telegram ([@dizpers](https://t.me/dizpers)) or X ([@dizpers](https://x.com/dizpers)). Pro is $79/month and includes predictions, signals, `is_counted` classification, and full tweet history.

---

## What is x402 authentication?

x402 is a micropayment protocol for AI agents. Instead of a monthly subscription, agents can pay per-request using an `x402` header. This is designed for autonomous agents that need to call the API without a pre-arranged subscription. Contact us for details.



--- FILE: docs/guides/mcp-setup.md ---

---
title: MCP Server Setup
description: Connect Claude Desktop to Polystrike using the Model Context Protocol.
---

The Polystrike MCP server enables Claude Desktop to access trading signals, predictions, and portfolio analysis through natural language. No local installation required — the server runs on our infrastructure.

## What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI assistants like Claude connect to external data sources and tools. Instead of copying/pasting API responses, Claude can query Polystrike directly and reason about the data in real-time.

**Benefits:**
- Natural language queries: "What are the current Elon market predictions?"
- Automatic data refresh: Claude always sees live data
- Portfolio analysis: "Analyze my positions at 0x..."
- Trading signals: "Show me BUY signals with $100 bankroll"

## Prerequisites

- **Claude Desktop** (macOS, Windows, or Linux)
- **Polystrike API Key** (get one at [polystrike.xyz](https://polystrike.xyz))

## Setup

### 1. Get Your API Key

Visit [polystrike.xyz](https://polystrike.xyz) and sign up:
- **FREE**: 100 requests/hour, basic features
- **PRO**: 10,000 requests/hour, predictions and signals

### 2. Configure Claude Desktop

Open your Claude Desktop configuration file:

**macOS:**
```bash
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Windows:**
```bash
%APPDATA%\Claude\claude_desktop_config.json
```

**Linux:**
```bash
~/.config/Claude/claude_desktop_config.json
```

Add this configuration:

```json
{
  "mcpServers": {
    "polystrike": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://polystrike.xyz/mcp/sse",
        "--header",
        "x-api-key:${POLYSTRIKE_API_KEY}"
      ],
      "env": {
        "POLYSTRIKE_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Replace `your_api_key_here` with your actual API key.

:::note
The `mcp-remote` package bridges Claude Desktop's stdio transport to our HTTP/SSE server. It's automatically downloaded by `npx` — no manual installation needed.
:::

### 3. Restart Claude Desktop

**Important:** Completely quit Claude Desktop (Cmd+Q on macOS, not just close the window) and restart to load the configuration.

### 4. Test It

Try these prompts in Claude:

```
Check Polystrike API health
```

```
What are the current predictions for active Elon markets?
```

```
Get trading signals for Elon markets with $100 bankroll
```

If everything is working, Claude will respond with live data from Polystrike.

## Available Tools

### FREE Tier (No API Key Required)
- **get_market_metadata** - Active Elon tweet markets
- **get_crypto_metadata** - Crypto market information
- **get_recent_tweets** - Recent tweets (15 limit)
- **get_predictions** - Market predictions (limited)
- **check_health** - API health status
- **join_waitlist** - Registration

### PRO Tier (API Key Required)
- **get_trading_signals** - EV-based signals with Kelly sizing
- **analyze_portfolio** - Wallet position analysis
- **get_rebalancing_recommendations** - Position rebalancing

## Troubleshooting

### Tools Not Appearing

1. Check Claude Desktop logs for errors
2. Verify JSON syntax in config file (use [jsonlint.com](https://jsonlint.com))
3. Restart Claude Desktop completely (Cmd+Q, not just close window)
4. Verify API key is correct

### Connection Errors

Test server connectivity:

```bash
curl https://polystrike.xyz/mcp/health
```

Expected response:
```json
{"status":"ok","version":"1.0.0","server":"polystrike"}
```

If this fails, the server may be down. Check [status.polystrike.xyz](https://status.polystrike.xyz) or contact support.

### Authentication Errors

- Verify your API key is correct (check for extra spaces)
- Check API key tier (FREE vs PRO)
- Ensure key is not expired
- Try regenerating your key at [polystrike.xyz](https://polystrike.xyz)

### Tool Calls Timeout or Fail

If Claude can see the tools but calls fail:

1. Check your internet connection
2. Verify the MCP server is responding:
   ```bash
   curl -X POST https://polystrike.xyz/mcp/messages
   ```
   Should return: `"Invalid Content-Type header"` (not 404)

3. Check Claude Desktop logs for specific error messages

## Rate Limits

- **FREE Tier**: 100 requests/hour
- **PRO Tier**: 10,000 requests/hour

Rate limits are enforced server-side. If you hit the limit, Claude will receive an error message and you'll need to wait or upgrade.

## Why MCP vs Direct API?

| Approach | Setup | Updates | Natural Language |
|----------|-------|---------|------------------|
| **MCP Server** | 2 lines config | Automatic | Yes |
| **Direct API** | Manual curl/code | Manual | No |

MCP is the recommended approach for Claude Desktop users. It's simpler, automatically updated, and enables natural language queries.

## Support

- **Documentation**: [docs.polystrike.xyz](https://docs.polystrike.xyz)
- **Issues**: [github.com/dizpers/polystrike/issues](https://github.com/dizpers/polystrike/issues)
- **Contact**: [@dizpers](https://t.me/dizpers) on Telegram



--- FILE: docs/guides/quickstart.md ---

---
title: Quick Start
description: Get your first Polystrike response in under a minute.
---

No sign-up required. The core endpoint is public and free.

## 1. Get the live counters

```bash
curl https://polystrike.xyz/api/v1/meta/elon
```

You'll get back something like this:

```json
{
  "timestamp": 1771246725679,
  "data": [
    {
      "event_id": 206602,
      "event_title": "Elon Musk # tweets February 14 - February 16, 2026?",
      "start_ts": 1771088400000,
      "end_ts": 1771261200000,
      "polymarket_xtracker_counter": 65,
      "real_counter": 68,
      "polymarket_ui_counter": 65,
      "settlement_delta": 3,
      "display_delta": 3,
      "internal_delta": 0
    }
  ]
}
```

**What you're seeing**: The real count is 68 but the settlement oracle (XTracker) only shows 65. That `settlement_delta` of 3 means Polystrike has found 3 tweets the oracle hasn't counted yet. The UI is also showing 65 — so traders on Polymarket are looking at a number that's 3 behind reality.

The three delta fields are your edge signals:

| Field | Formula | What a positive value means |
|-------|---------|----------------------------|
| `settlement_delta` | `real − xtracker` | Polystrike is ahead of the oracle |
| `display_delta` | `real − ui` | The UI is showing a stale number |
| `internal_delta` | `ui − xtracker` | The UI is ahead of or behind the oracle |

## 2. See the tweet feed

```bash
curl https://polystrike.xyz/api/v1/meta/elon/tweets
```

Returns the 15 most recent tweets (free tier). Each tweet includes type flags (`is_reply`, `is_quote`, `is_retweet`) and a `is_counted` field that tells you whether it counts toward settlement.

:::note
`is_counted` is `null` on the free tier — it's only populated for Pro subscribers. This is the key field for understanding which tweets actually determine the outcome.
:::

## 3. Use with Claude Desktop (Recommended)

If you use Claude Desktop, skip the manual API calls and connect via MCP instead:

:::tip[Natural Language Access]
The [MCP Server Setup](/docs/guides/mcp-setup) lets Claude query Polystrike directly through natural language. Just ask "What are the current Elon market predictions?" and Claude fetches live data automatically.

**Setup time:** 2 minutes. **Installation:** Zero (runs on our servers).
:::

## 4. Upgrade to Pro

Pro unlocks the prediction model, `is_counted` classification, full tweet history (with pagination), and trading signals.

**$79/month. Contact to subscribe:**
- **Telegram**: [@dizpers](https://t.me/dizpers)
- **X**: [@dizpers](https://x.com/dizpers)

Once you have a key, pass it as a header:

```bash
curl -H "X-API-Key: ps_pro_..." \
  https://polystrike.xyz/api/v1/prediction/elon
```

## 5. For AI agents

Fetch the machine-readable API definition:

```bash
curl https://polystrike.xyz/SKILL.md
```

This single file contains the full API schema in a format optimized for LLM context injection. Your agent can discover, understand, and call the API autonomously from it.



--- FILE: docs/guides/strategies.md ---

---
title: Trading Strategies
description: How to use Polystrike's three delta signals to find trading edges on Polymarket Elon tweet markets.
---

Polystrike provides three independent lag signals that each represent a different trading opportunity. This guide explains how to use them.

:::caution
These strategies describe information edges, not guaranteed profits. Prediction markets involve risk. Always size positions appropriately and never risk more than you can afford to lose.
:::

## Strategy 1: Display Delta Front-Running

**Signal**: `display_delta` is large (e.g., > 5)

**What's happening**: The Polymarket UI counter is frozen or lagging. Most traders are looking at a stale number.

**The edge**: If the UI shows 240 tweets but the real count is 248, traders in the 240-259 bucket think they're safe. But the count is closer to busting that bucket than they realize.

**How to use it**:
1. Monitor `display_delta` via `GET /meta/elon`
2. When `display_delta > 5`, check which bucket the UI count suggests vs. where the real count is heading
3. If the real count is near a bucket boundary that the UI doesn't reflect, the market is likely mispriced

**When it fails**: The UI can catch up suddenly, and other sophisticated traders may already be exploiting the same lag.

## Strategy 2: Settlement Delta Arbitrage

**Signal**: `settlement_delta` is positive

**What's happening**: Polystrike has counted tweets (including deleted ones) that XTracker hasn't picked up yet.

**The edge**: The settlement oracle will eventually catch up to the real count. If that catch-up moves the count across a bucket boundary, the affected bucket's price should move.

**How to use it**:
1. Monitor `settlement_delta` via `GET /meta/elon`
2. Calculate where the count will land once XTracker updates
3. If the XTracker update would push the count into a different bucket, trade accordingly before the update

**Important caveat**: Deleted tweets create a persistent gap. If `settlement_delta` is driven by deletions (tweets we captured but XTracker never saw), the oracle may never "catch up" for those specific tweets. Check the tweet feed for `is_deleted` flags to distinguish real lag from deletion-driven divergence.

## Strategy 3: Prediction-Based Positioning

**Signal**: Monte Carlo predictions show high probability for a specific bucket

**What's happening**: The model projects where the final count will land based on current velocity and sleep patterns.

**The edge**: When the model assigns > 70% probability to a bucket but the Polymarket price for that bucket is only 50-60%, there's a potential expected value (EV) edge.

**How to use it**:
1. Call `GET /prediction/elon` (Pro tier) to get bucket probabilities
2. Compare `model_prob` to `market_price` for each bucket
3. The `edge` field gives you the raw difference: `model_prob - market_price`
4. The `signal` field provides a pre-computed recommendation (STRONG_BUY, BUY, HOLD, SELL)

**When to trust the model**:
- **Final 16 hours**: Highest reliability. The count trajectory is well-established.
- **16-36 hours**: Moderate. Check the `sleep_probability` field — if Elon is likely asleep, the model can project confidently.
- **More than 36 hours**: Low reliability. Early predictions overestimate by 15-20%.

## Position Sizing with Kelly Criterion

The `/signals/elon` endpoint (Pro tier) provides EV-based signals with Kelly Criterion sizing. Pass `?bankroll=100` to get `suggested_bet` sized to your bankroll:

| Field | What it tells you |
|-------|-------------------|
| `ev` | Expected value of a $1 bet. Positive = profitable in expectation. |
| `kelly_fraction` | Optimal fraction of bankroll to bet (Kelly Criterion). |
| `suggested_bet` | Dollar amount to bet, calculated as `kelly_fraction * bankroll`. Pass `?bankroll=` to customize. |
| `confidence` | HIGH, MEDIUM, or LOW based on time remaining and model certainty. |
| `moneyness` | How deep the p50 is inside the bucket. Higher = safer. |

:::tip
Kelly Criterion gives the mathematically optimal bet size, but most traders use "fractional Kelly" (betting 25-50% of the suggested amount) to reduce variance.
:::

## When NOT to Trade

Polystrike signals also help you avoid bad trades:

- **`confidence: LOW`**: Not enough data or too much time remaining. Wait.
- **`moneyness` near 0**: The p50 is right at a bucket boundary. High risk of the count landing on either side.
- **`ev` negative**: The market has already priced in the edge. No trade.
- **`signal: SKIP`**: The system explicitly recommends no action.
- **p5-p95 spans 3+ buckets**: Too much uncertainty to make a confident bet.



--- FILE: docs/index.mdx ---

---
title: Polystrike Docs
description: Official documentation for the Polystrike API.
template: splash
hero:
  tagline: Oracle intelligence layer for Polymarket Elon tweet markets. Real count. Deleted tweets. Triple lag signals. Monte Carlo predictions.
  image:
    file: ../../assets/houston.webp
  actions:
    - text: Get Started
      link: /docs/guides/quickstart/
      icon: right-arrow
    - text: API Reference
      link: /docs/api/overview/
      icon: external
      variant: minimal
---

import { Card, CardGrid } from '@astrojs/starlight/components';

## Quick Links

<CardGrid>
  <Card title="Quickstart" icon="rocket">
    [Get your first response](/docs/guides/quickstart) in under a minute. Free, no API key needed.
  </Card>
  <Card title="Core Concepts" icon="open-book">
    Understand [the problem Polystrike solves](/docs/guides/concepts) — counter lag, deleted tweets, and settlement rules.
  </Card>
  <Card title="MCP Server Setup" icon="setting">
    [Connect Claude Desktop](/docs/guides/mcp-setup) to Polystrike. Natural language queries, live data, zero installation.
  </Card>
  <Card title="Elon Tweet Markets API" icon="puzzle">
    Full endpoint reference for [tweet counts, predictions, and signals](/docs/api/elon).
  </Card>
  <Card title="Trading Strategies" icon="star">
    Learn the [three delta strategies](/docs/guides/strategies) that exploit counter lag.
  </Card>
</CardGrid>



--- FILE: docs/reference/example.md ---

---
title: Error Codes
description: HTTP error codes returned by the Polystrike API.
---

All errors return a JSON body with a `detail` field explaining the issue.

```json
{ "detail": "Invalid API key" }
```

## HTTP Status Codes

| Code | Meaning | Common Cause |
|------|---------|--------------|
| `200` | OK | Request succeeded |
| `400` | Bad Request | Missing required parameter, invalid wallet address |
| `401` | Unauthorized | Missing or invalid `X-API-Key` on a Pro-only endpoint |
| `422` | Unprocessable Entity | Parameter validation failed (e.g. `limit` out of range) |
| `429` | Too Many Requests | Rate limit exceeded |
| `500` | Internal Server Error | Upstream data source unavailable |
| `503` | Service Unavailable | Server overloaded or in maintenance |

---

## Rate Limit Errors (429)

When you exceed the rate limit, the response body will include:

```json
{ "detail": "Rate limit exceeded. Try again in 60 seconds." }
```

| Tier | Limit |
|------|-------|
| Free (Anonymous) | 100 requests / hour (per IP) |
| Pro | 10,000 requests / hour (per API key) |

Rate limits reset on a rolling 1-hour window.

---

## Authentication Errors (401)

Endpoints that require a Pro key return `401` if:

- The `X-API-Key` header is missing
- The key is invalid or expired
- The key doesn't have Pro tier access

**Affected endpoints**: `/prediction/elon`, `/signals/elon`, `/portfolio/elon`

---

## Validation Errors (422)

The `/meta/elon/tweets` endpoint accepts `limit` and `offset` query parameters for Pro users. Invalid values produce a `422`:

```bash
# This will 422 — limit max is 100
curl -H "X-API-Key: ps_pro_..." \
  "https://polystrike.xyz/api/v1/meta/elon/tweets?limit=500"
```

Valid ranges:
- `limit`: 1–100 (Pro only; free tier is fixed at 15)
- `offset`: 0 or any non-negative integer

---

## Empty Data (200)

A `200` response with `"data": []` means there are no active Elon tweet markets right now. This is normal between events. Check back when a new market opens on Polymarket.