# Rekko AI

> Prediction market intelligence API — deep AI research, causal analysis, and trading signals for Kalshi and Polymarket.

Rekko AI is the intelligence layer for prediction market trading bots, apps, and agents. It runs multi-stage AI research pipelines that produce probability estimates, Bayesian causal decomposition of price drivers, portfolio-aware trading signals, cross-platform arbitrage detection, and execution guidance. Covers Kalshi (CFTC-regulated) and Polymarket (crypto). Clean flat JSON designed for developers and autonomous trading agents.

Base URL: `https://api.rekko.ai/v1`
Auth: Bearer token (`Authorization: Bearer rk_free_...` or `rk_pro_...`)
OpenAPI spec: `https://api.rekko.ai/openapi.json`

---

## Quickstart

### 1. Sign up for a free API key

```bash
curl -X POST https://api.rekko.ai/v1/customers/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "name": "Your Name"}'
```

```python
import httpx

resp = httpx.post("https://api.rekko.ai/v1/customers/signup", json={
    "email": "you@example.com",
    "name": "Your Name",
})
data = resp.json()
print(data["api_key"])  # Save this — it's shown only once
```

Your API key is shown only once in the signup response. Store it securely — you cannot retrieve it later.

### 2. List prediction markets

```bash
curl https://api.rekko.ai/v1/markets \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import httpx

client = httpx.Client(
    base_url="https://api.rekko.ai/v1",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
markets = client.get("/markets").json()
for m in markets[:5]:
    print(f"{m['platform']} | {m['title']} | YES: {m['yes_price']}")
```

```javascript
// Node.js / TypeScript
const resp = await fetch("https://api.rekko.ai/v1/markets", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
const markets = await resp.json();
markets.slice(0, 5).forEach((m) =>
  console.log(`${m.platform} | ${m.title} | YES: ${m.yes_price}`)
);
```

### 3. Get an AI analysis

Analysis runs a deep research pipeline (30-90 seconds). Trigger it, then poll for completion.

```python
import time
import httpx

client = httpx.Client(
    base_url="https://api.rekko.ai/v1",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

# 1. Trigger analysis
resp = client.post("/markets/kalshi/KXFED-26MAR19/analyze")
analysis_id = resp.json()["analysis_id"]

# 2. Poll until complete
while True:
    status = client.get(
        f"/markets/kalshi/KXFED-26MAR19/analyze/{analysis_id}/status"
    ).json()
    if status["status"] == "complete":
        break
    time.sleep(5)

# 3. Get the analysis
analysis = client.get("/markets/kalshi/KXFED-26MAR19/analysis").json()
print(f"Probability: {analysis['probability']}")
print(f"Edge: {analysis['edge']}")
print(f"Recommendation: {analysis['recommendation']}")
```

---

## Authentication

All API requests require authentication. Pass your API key as a Bearer token in the `Authorization` header.

```http
Authorization: Bearer rk_free_your_key_here
```

### Key prefixes

| Prefix | Plan |
|--------|------|
| `rk_free_` | Free tier |
| `rk_pro_` | Pro subscription |

### Getting a key

Sign up at the dashboard (https://rekko.ai/dashboard) or via the API:

```bash
curl -X POST https://api.rekko.ai/v1/customers/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "name": "Your Name"}'
```

### Key rotation

Rotate your key from the dashboard. The old key is revoked immediately.

### Error responses

| Status | Meaning |
|--------|---------|
| `401 Unauthorized` | Missing or invalid API key |
| `403 Forbidden` | Valid key but insufficient tier for this endpoint |
| `429 Too Many Requests` | Rate limit or monthly quota exceeded |

All errors return JSON:

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

### Alternative auth methods

**RapidAPI**: If you subscribe via RapidAPI, use RapidAPI's standard headers (`x-rapidapi-key`, `x-rapidapi-host: rekko-ai.p.rapidapi.com`) instead of a Bearer token.

**x402 Micropayments**: For crypto-native agents, pay per-request with USDC on Base L2. Make a request without an API key — Rekko returns `402 Payment Required` with a payment envelope — an x402 client pays USDC on Base — retry succeeds.

---

## Pricing

### Endpoint tiers

Every endpoint belongs to a tier. Higher tiers unlock deeper intelligence.

| Tier | Per-call cost | What it covers |
|------|--------------|----------------|
| LISTING | $0.01 | Market listings, prices, history |
| INSIGHT | $0.10 | AI analysis, screening, resolution intelligence |
| STRATEGY | $2.00 | Trading signals, execution guidance, portfolio strategy |
| DEEP | $5.00 | Arbitrage, correlation, webhooks, SSE streaming |

The `/v1/calibration` endpoint is free and unauthenticated — use it to evaluate Rekko's accuracy before committing.

### Subscription plans

| | Free | Pro | Enterprise |
|---|---|---|---|
| Price | $0/mo | $49/mo | Custom |
| LISTING calls | 100/mo | 10,000/mo | Custom |
| INSIGHT calls | 10/mo | 500/mo | Custom |
| STRATEGY calls | — | 50/mo | Custom |
| DEEP calls | — | 10/mo | Custom |
| Rate limit | 30 req/min | 120 req/min | Custom |
| Strategy rate limit | — | 5 req/min | Custom |

Free tier quotas reset on the 1st of each month (UTC). When exceeded, the API returns `429 Too Many Requests` with a `Retry-After` header containing the reset date.

Check your current usage:

```bash
curl https://api.rekko.ai/v1/customers/me \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

## Core Concepts

### Markets

Markets are identified by a `platform` + `market_id` pair. Platform is `kalshi` or `polymarket`.

**Market object:**

| Field | Type | Description |
|-------|------|-------------|
| platform | string | `kalshi` or `polymarket` |
| market_id | string | Platform-specific identifier (e.g., `KXFED-26MAR19`) |
| title | string | Market question |
| url | string | Direct link to the market page |
| category | string | Market category (e.g., `economics`, `crypto`, `politics`) |
| yes_price | number | Current YES price (0-1, represents implied probability) |
| volume_24h | number | 24-hour trading volume in USD |
| liquidity | number | Available liquidity |
| open_interest | number | Total open contracts |
| resolution_date | datetime | When the market resolves |
| updated_at | datetime | Last data refresh |

**Price interpretation**: A `yes_price` of 0.62 means the market implies a 62% probability of YES resolution.

**Market lifecycle**: active → closed → determined → finalized.

**Platforms**:
- Kalshi: CFTC-regulated US exchange. Market IDs are ticker-style (e.g., `KXFED-26MAR19`).
- Polymarket: Crypto-native on Polygon. Market IDs are hex addresses.

### Analysis Pipeline

Analysis endpoints use an async 3-step pattern because research pipelines run 30-90 seconds:

1. **Trigger**: `POST /v1/markets/{platform}/{market_id}/analyze` returns `202 Accepted` with `analysis_id` and `poll_url`
2. **Poll**: `GET /v1/markets/{platform}/{market_id}/analyze/{analysis_id}/status` every 5 seconds until `status` is `"complete"`
3. **Retrieve**: `GET /v1/markets/{platform}/{market_id}/analysis` with optional `?expand=scenarios,causal,meta`

**Analysis object fields:**

| Field | Type | Description |
|-------|------|-------------|
| probability | number (0-1) | Rekko's estimated true probability |
| confidence | number (0-1) | Confidence in the estimate |
| edge | number | estimated_prob - market_price (positive = underpriced YES) |
| recommendation | string | `BUY_YES`, `BUY_NO`, or `NO_TRADE` |
| risk_rating | string | `low`, `medium`, or `high` |
| summary | string | Executive summary |
| key_factors | string[] | Top probability drivers |
| risks | string[] | Ways the analysis could be wrong |
| source_count | integer | Number of sources analyzed |
| freshness | string | `fresh` (<24h), `stale` (24-72h), `expired` (>72h) |
| analyzed_at | datetime | When produced |
| expires_at | datetime | Signal staleness window |

**Caching**: Analyses are cached. `fresh` means <24h old. Use `?force=true` to force a new analysis.

**Example response:**

```json
{
  "platform": "kalshi",
  "market_id": "KXFED-26MAR19",
  "title": "Will the Fed cut rates at the March 2026 meeting?",
  "probability": 0.71,
  "confidence": 0.82,
  "edge": 0.09,
  "recommendation": "BUY_YES",
  "risk_rating": "low",
  "summary": "Fed futures imply 68% probability of a March cut. PCE inflation at 2.1% is within the Fed's comfort zone, and three FOMC members have signaled openness to easing. Our research across 14 sources estimates 71% true probability — a 9-point edge over the current market price of 62c.",
  "key_factors": [
    "PCE inflation at 2.1% — within Fed target range",
    "Three FOMC members signaled openness to cuts in recent speeches",
    "Jobless claims trending upward (225K → 238K over 4 weeks)"
  ],
  "risks": [
    "Strong March employment report could reverse dovish signals",
    "Tariff escalation could reignite inflation expectations"
  ],
  "source_count": 14,
  "analyzed_at": "2026-03-21T12:00:00Z",
  "expires_at": "2026-03-22T12:00:00Z"
}
```

### Signals

Signals are actionable trading recommendations derived from analyses.

**Signal object:**

| Field | Type | Description |
|-------|------|-------------|
| platform | string | `kalshi` or `polymarket` |
| market_id | string | Market identifier |
| title | string | Market question |
| recommendation | string | `BUY_YES`, `BUY_NO`, or `NO_TRADE` |
| target_price | number | Rekko's estimated true probability |
| edge | number | estimated_probability - market_price |
| confidence | number (0-1) | Analysis confidence |
| risk_rating | string | `low`, `medium`, `high` |
| size_pct | number (0-1) | Kelly-derived position size as fraction of bankroll |
| time_horizon | string | `hours`, `days`, `weeks` |
| hedge | string | Hedge recommendation |
| freshness | string | Data freshness |
| generated_at | datetime | When generated |
| expires_at | datetime | When the signal becomes stale |

**Edge calculation**: `edge = estimated_probability - market_price`. Positive edge on YES means the market underprices the event.

**Position sizing**: `size_pct` is a Kelly Criterion-derived fraction of bankroll. A value of 0.05 means "risk 5% of bankroll."

### Causal Decomposition

Access via `?expand=causal` on analysis and signal endpoints. Breaks a probability estimate into 3-7 evidence-backed causal factors with Bayesian prior/posterior updates.

**CausalDecomposition object:**

| Field | Type | Description |
|-------|------|-------------|
| overall_probability | number (0-1) | Aggregated probability from factor weights |
| overall_confidence | number (0-1) | Weighted confidence across all factors |
| factors | CausalFactor[] | 3-7 causal factors |
| method | string | `weighted_bayesian`, `linear`, or `log_odds` |

**CausalFactor object:**

| Field | Type | Description |
|-------|------|-------------|
| claim | string | The factor statement |
| direction | string | `supports_yes`, `supports_no`, or `neutral` |
| weight | number (0-1) | Relative importance (top-level factors sum to ~1.0) |
| confidence | number (0-1) | Confidence in this factor |
| prior | number (0-1) | Base rate probability before evidence |
| posterior | number (0-1) | Updated probability after evidence |
| evidence | string[] | Key evidence supporting this factor |

**Example:**

```json
{
  "overall_probability": 0.71,
  "overall_confidence": 0.82,
  "method": "weighted_bayesian",
  "factors": [
    {
      "claim": "Inflation is within Fed's comfort zone",
      "direction": "supports_yes",
      "weight": 0.35,
      "confidence": 0.9,
      "prior": 0.6,
      "posterior": 0.82,
      "evidence": ["PCE Feb 2026: 2.1%", "Core CPI declining 3 months"]
    },
    {
      "claim": "Fed rhetoric is dovish",
      "direction": "supports_yes",
      "weight": 0.3,
      "confidence": 0.75,
      "prior": 0.5,
      "posterior": 0.68,
      "evidence": ["Waller speech March 12", "Bostic: 'open to adjustment'"]
    },
    {
      "claim": "Tariff uncertainty creates headwinds",
      "direction": "supports_no",
      "weight": 0.2,
      "confidence": 0.6,
      "prior": 0.4,
      "posterior": 0.45,
      "evidence": ["New tariffs announced March 5", "Trade deficit widening"]
    }
  ]
}
```

### Expand Parameter

Use `?expand=` (comma-separated) to include additional nested data:

| Expansion | Available on | Description |
|-----------|-------------|-------------|
| `causal` | Analysis, signals | Causal factor decomposition with Bayesian updates |
| `scenarios` | Analysis | Bull/base/bear scenario breakdown with probabilities and triggers |
| `meta` | Analysis | Pipeline metadata: what_would_change_mind, edge_assessment, models_used, duration_ms |
| `history` | Analysis, markets | Price history data points |
| `analysis` | Market listings | Include latest analysis inline in market listing |
| `scoring` | Arbitrage | Scoring breakdown: spread_score (40% weight), liquidity_score (20%), match_confidence_score (20%), execution_score (20%) |

By default, expandable fields are omitted. Request only what you need to minimize response size.

---

## API Reference

Base URL: `https://api.rekko.ai/v1`

All request bodies are JSON. Query parameters use standard URL encoding. Market identifiers follow `{platform}/{market_id}` where platform is `kalshi` or `polymarket`.

### Events

#### GET /v1/events

List prediction market events grouped with aggregate stats. Events group related individual markets (e.g., "Who will leave the Trump administration?" groups 32 individual outcome markets). Sorted by aggregate 24h volume descending.

**Tier**: LISTING ($0.01)

**Query parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| source | string | (all) | Filter by platform: `kalshi` or `polymarket` |
| category | string | (all) | Filter by category (e.g., `politics`, `crypto`) |
| featured | boolean | (all) | Only featured events (true) or all (omit) |
| limit | integer | 20 | Maximum events to return (1-100) |

**Response**: Array of EventSummary objects.

#### GET /v1/events/trending

Top prediction market events by trending score. Combines featured status, volume, and recency. Designed for AI agents that want a quick overview of what's hot in prediction markets.

**Tier**: LISTING ($0.01)

**Query parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| limit | integer | 20 | Maximum events to return (1-50) |

**Response**: Array of EventSummary objects.

#### GET /v1/events/search

Search events using hybrid full-text + semantic vector search. Finds events matching by keyword ("Iran") and by meaning ("US military Middle East" matches "US forces enter Iran"). Uses Reciprocal Rank Fusion to combine both signals.

**Tier**: LISTING ($0.01)

**Query parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| q | string | (required) | Search query (supports semantic + keyword matching) |
| limit | integer | 20 | Maximum results (1-50) |

**Response**: Array of EventSummary objects.

#### GET /v1/events/{slug}

Get a single event with aggregate stats and optionally all its markets. Use ?expand=markets to include individual outcome markets in the response.

**Tier**: LISTING ($0.01)

**Path parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| slug | string | Event slug (e.g., `kalshi:kxtrumpadminleave-26dec31`) |

**Query parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| expand | string | Comma-separated expansions: `markets` |

**Response**: Event object.

#### GET /v1/events/{slug}/markets

List all individual outcome markets within an event. Returns markets sorted by 24h volume descending.

**Tier**: LISTING ($0.01)

**Path parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| slug | string | Event slug (e.g., `kalshi:kxtrumpadminleave-26dec31`) |

**Response**: Array of EventMarketSummary objects.

### Markets

#### GET /v1/markets

List current prediction markets with pricing data.

**Tier**: LISTING ($0.01)

**Query parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| source | string | (all) | Filter by platform: `kalshi` or `polymarket` |
| limit | integer | 30 | Maximum markets to return (1-100) |

**Response**: Array of Market objects.

#### GET /v1/markets/{platform}/{market_id}

Get a single market by platform and ID.

**Tier**: LISTING ($0.01)

**Path parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| platform | string | `kalshi` or `polymarket` |
| market_id | string | Platform-specific identifier |

**Query parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| expand | string | Comma-separated expansions (e.g., `analysis,history`) |

**Response**: Market object.

#### GET /v1/markets/{platform}/{market_id}/history

Historical price and volume data for backtesting.

**Tier**: LISTING ($0.01)

**Query parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| period | string | `7d` | Time period: `48h`, `7d`, or `30d` |
| max_points | integer | 48 | Maximum data points (10-200) |

### Insights

#### POST /v1/markets/{platform}/{market_id}/analyze

Start an async AI analysis for a specific market. Returns `202 Accepted`.

**Tier**: INSIGHT ($0.10)

**Response** (202):

```json
{
  "analysis_id": "rk-a1b2c3d4e5f6",
  "status": "running",
  "poll_url": "/v1/markets/kalshi/KXFED-26MAR19/analyze/rk-a1b2c3d4e5f6/status",
  "estimated_seconds": 60
}
```

#### GET /v1/markets/{platform}/{market_id}/analyze/{analysis_id}/status

Check the status of an async analysis.

**Tier**: INSIGHT (no additional charge)

**Response**: AnalysisStatus with `status` field: `running`, `complete`, or `error`.

#### GET /v1/markets/{platform}/{market_id}/analysis

Get the latest AI analysis for a market.

**Tier**: INSIGHT ($0.10)

**Query parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| expand | string | Comma-separated: `causal`, `scenarios`, `meta` |

**Response**: Analysis object (see Core Concepts > Analysis Pipeline for full schema).

#### GET /v1/analyses

List recent analysis summaries.

**Tier**: INSIGHT ($0.10)

**Query parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| limit | integer | 20 | Maximum analyses (1-50) |

**Response**: Array of AnalysisSummary objects (compact: platform, market_id, title, probability, confidence, recommendation, analyzed_at, freshness).

#### POST /v1/screen

Batch screen markets with lightweight scoring (no LLM pipeline).

**Tier**: INSIGHT ($0.10)

**Request body:**

```json
{
  "market_ids": ["KXFED-26MAR19", "KXBITCOIN-26MAR23"],
  "platform": "kalshi",
  "min_volume_24h": 10000,
  "min_score": 50,
  "limit": 10
}
```

**Response**: Array of ScreenResult objects with scores.

### Strategy

#### POST /v1/signals

Generate an actionable AI strategy signal for a market.

**Tier**: STRATEGY ($2.00)

Default: returns `202` with `analysis_id` for polling. With `?wait=true`: blocks until pipeline completes (30-90 seconds). If a cached analysis exists (<24h): returns immediately. Use `"force": true` to bypass cache.

**Query parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| wait | boolean | false | Block until analysis completes (up to 5 min) |
| expand | string | (none) | Comma-separated expansions |

**Request body:**

```json
{
  "market": "kalshi/KXFED-26MAR19",
  "risk_limit": "medium"
}
```

**Response**: Signal object (see Core Concepts > Signals for full schema).

#### POST /v1/signals/portfolio

Portfolio-aware strategy signal with correlation analysis and hedge recommendations.

**Tier**: STRATEGY ($2.00)

**Request body:**

```json
{
  "market": "kalshi/KXFED-26MAR19",
  "portfolio": [
    {"market_id": "KXBITCOIN-26MAR23", "platform": "kalshi", "side": "yes", "size_usd": 500}
  ],
  "bankroll_usd": 10000
}
```

**Response**: PortfolioSignal with correlation matrix, concentration warnings, and hedge suggestions.

#### GET /v1/markets/{platform}/{market_id}/execution

Optimal trade execution analysis from bid/ask spread patterns.

**Tier**: STRATEGY ($2.00)

**Response**: ExecutionGuidance object.

### Deep Intelligence

#### GET /v1/arbitrage

Cached cross-platform arbitrage opportunities with composite scoring.

**Tier**: DEEP ($5.00)

**Query parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| min_spread | number | 0.02 | Minimum spread filter (0.0-0.5) |
| expand | string | (none) | Use `scoring` for score breakdown |

**Response:**

```json
{
  "scanned_at": "2026-03-21T14:30:00Z",
  "count": 1,
  "opportunities": [
    {
      "event": "Fed rate cut March 2026",
      "kalshi": {"market_id": "KXFED-26MAR19", "yes_price": 0.62, "url": "..."},
      "polymarket": {"market_id": "0x1234abcd", "yes_price": 0.68, "url": "..."},
      "spread": 0.06,
      "spread_pct": 6.0,
      "cheaper_on": "kalshi",
      "score": 78,
      "match_confidence": 0.92,
      "scanned_at": "2026-03-21T14:30:00Z"
    }
  ]
}
```

**Scoring breakdown** (via `?expand=scoring`): `spread_score` (40% weight), `liquidity_score` (20%), `match_confidence_score` (20%), `execution_score` (20%). All sub-scores 0-100.

#### GET /v1/arbitrage/live

Run a fresh arbitrage scan. Takes 10-30 seconds.

**Tier**: DEEP ($5.00)

Same parameters and response format as `/v1/arbitrage`.

#### POST /v1/correlation

Cross-market correlation analysis for portfolio diversification.

**Tier**: DEEP ($5.00)

**Request body:**

```json
{
  "market_ids": ["KXFED-26MAR19", "KXBITCOIN-26MAR23", "KXINFLATION-26APR"],
  "platform": "kalshi",
  "period": "30d"
}
```

**Response**: CorrelationGraph with pairwise correlation coefficients, clusters (groups with correlation > 0.5), and concentration warnings.

#### GET /v1/markets/{platform}/{market_id}/resolution

Resolution timing, mechanism, and time-value analysis.

**Tier**: DEEP ($5.00)

**Response**: ResolutionIntelligence object.

### Analytics

#### GET /v1/calibration

Signal accuracy and calibration metrics. **Free, no auth required.**

**Query parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| category | string | (all) | Filter by category (e.g., `crypto`, `politics`) |
| period | string | `all` | Time period: `7d`, `30d`, `90d`, or `all` |
| mode | string | `shadow` | Trading mode: `shadow` or `live` |

#### GET /v1/sentiment

Aggregate market sentiment from price momentum and volume trends.

**Tier**: LISTING ($0.01)

**Response**: SentimentSnapshot object.

#### GET /v1/performance

Trading track record — win rate, P&L, ROI, and edge metrics.

**Tier**: LISTING ($0.01)

**Query parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| mode | string | `shadow` | Trading mode: `shadow` or `live` |

**Response**: PerformanceSummary object.

#### GET /v1/performance/history

Daily P&L time series for equity curve charting.

**Tier**: LISTING ($0.01)

Same parameters as `/v1/performance`.

### Consensus

#### GET /v1/markets/{platform}/{market_id}/consensus

Consensus probability from aggregated agent trades.

**Tier**: INSIGHT ($0.10)

**Query parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| period | string | `7d` | Lookback: `24h`, `7d`, `30d` |

**Response:**

```json
{
  "market_id": "KXFED-26MAR19",
  "platform": "kalshi",
  "consensus_probability": 0.69,
  "sample_size": 23,
  "unique_agents": 8,
  "rekko_probability": 0.71,
  "divergence": -0.02,
  "divergence_signal": "crowd_agrees",
  "yes_volume_usd": 3200.0,
  "no_volume_usd": 1450.0,
  "period": "7d"
}
```

**Divergence signals**: `crowd_agrees`, `crowd_disagrees`, `strong_divergence`, `neutral`, `insufficient_data`.

#### POST /v1/trades/report

Report a trade for consensus probability aggregation.

**Tier**: INSIGHT ($0.10)

**Request body:**

```json
{
  "market_id": "KXFED-26MAR19",
  "platform": "kalshi",
  "side": "yes",
  "size_usd": 100,
  "price": 0.62
}
```

### Streaming & Webhooks

#### GET /v1/stream

Server-Sent Events stream for real-time market signals.

**Tier**: DEEP ($5.00)

**Query parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| events | string | Comma-separated event types: `price_shift`, `whale_alert`, `analysis_complete` |

#### POST /v1/webhooks

Register a webhook for real-time event notifications.

**Tier**: DEEP ($5.00)

**Request body:**

```json
{
  "url": "https://your-server.com/webhook",
  "events": ["price_shift", "analysis_complete"],
  "secret": "your_hmac_secret"
}
```

**Response**: WebhookInfo with `webhook_id`.

#### GET /v1/webhooks

List your registered webhooks.

**Tier**: DEEP (no additional charge)

#### DELETE /v1/webhooks/{webhook_id}

Remove a webhook.

**Tier**: DEEP (no additional charge)

### Customers

#### POST /v1/customers/signup

Create a free-tier account. Returns a one-time API key.

**Request body:**

```json
{
  "email": "you@example.com",
  "name": "Your Name"
}
```

**Response:**

```json
{
  "customer_id": "cus_...",
  "email": "you@example.com",
  "plan": "free",
  "api_key": "rk_free_..."
}
```

The `api_key` is shown only once. Store it securely.

#### GET /v1/customers/me

Get the authenticated customer's profile and usage stats.

**Response:**

```json
{
  "customer_id": "cus_...",
  "email": "you@example.com",
  "plan": "free",
  "status": "active",
  "key_prefix": "rk_free_abc",
  "usage": {
    "listing": 42,
    "insight": 3,
    "strategy": 0,
    "deep": 0
  },
  "quotas": {
    "listing": 100,
    "insight": 10,
    "strategy": 0,
    "deep": 0
  },
  "resets_on": "2026-04-01T00:00:00Z"
}
```

### Error Responses

All errors return JSON:

```json
{
  "detail": "Human-readable error message"
}
```

| Status | Meaning |
|--------|---------|
| 400 | Bad request — invalid parameters |
| 401 | Unauthorized — missing or invalid API key |
| 403 | Forbidden — tier too low for this endpoint |
| 404 | Not found — market or resource doesn't exist |
| 429 | Too many requests — rate limit or quota exceeded |
| 502 | Bad gateway — upstream platform unavailable |

---

## Integrations

### Browser WebMCP (in-page tools)

Every page on rekko.ai registers a W3C WebMCP tool surface via `navigator.modelContext`. Agents running inside a WebMCP-capable browser (Chrome 146+ with the `chrome://flags/#enable-webmcp-testing` flag, or any client loading a polyfill such as `@mcp-b/webmcp-polyfill`) can call these tools directly — no API key, no screen-scraping.

**Discovery:**
- `<meta name="webmcp" content="enabled">` is present in every page's `<head>`.
- `/.well-known/mcp.json` lists the full browser + remote + HTTP surface in machine-readable form.
- `rekko_site_info` tool returns the full tool catalog at runtime.

**Available WebMCP tools (19):**

Read-only market & content:
- `rekko_search_analyses(query?, category?, platform?, signal?, sort?, limit?)`
- `rekko_get_analysis(slug)`
- `rekko_list_categories()`
- `rekko_list_markets(platform?, category?, sort?, limit?)`
- `rekko_get_market(platform, market_id)`
- `rekko_market_history(platform, market_id, window?)`
- `rekko_list_events(platform?, category?, limit?)`
- `rekko_trending_events(limit?)`
- `rekko_get_event(slug, expand?)`

Metadata & navigation:
- `rekko_site_info()`
- `rekko_get_pricing()`
- `rekko_api_docs()`
- `rekko_navigate(target)`

Session-aware (authenticated):
- `rekko_get_dashboard()` — plan, usage, quotas, key prefix

Interactive (user confirmation via `client.requestUserInteraction`):
- `rekko_signup(email?)` — opens `/signup?email=…` for Turnstile-gated form completion
- `rekko_reveal_api_key()` — reveal the current user's key
- `rekko_rotate_api_key()` — revoke + reissue the current key
- `rekko_upgrade_to_pro(email?)` — start Stripe Checkout for Pro ($49/mo)
- `rekko_open_billing_portal()` — manage subscription, cards, invoices

All destructive tools gate on `client.requestUserInteraction(() => confirm(...))` — the browser always shows a confirmation prompt before any state change. Account creation via WebMCP is intentionally not supported (Cloudflare Turnstile captcha is required); `rekko_signup` navigates the user to the signup form instead.

### MCP Server (Model Context Protocol)

**GitHub:** https://github.com/Rekko-AI/rekko-mcp

The `rekko-mcp` package exposes 25+ tools to AI coding assistants (Claude Code, Cursor, Windsurf). Install and configure, then use natural language to interact with prediction markets.

**Install:**

```bash
uvx rekko-mcp
# or
pip install rekko-mcp
```

Requires Python 3.10+ and a Rekko API key (`REKKO_API_KEY` env var).

**Claude Code setup** (Option 1 — plugin):

```bash
claude plugin install rekko
```

**Claude Code setup** (Option 2 — manual .mcp.json):

```json
{
  "mcpServers": {
    "rekko": {
      "command": "uvx",
      "args": ["rekko-mcp"],
      "env": {
        "REKKO_API_KEY": "rk_free_your_key_here"
      }
    }
  }
}
```

**Cursor setup** (.cursor/mcp.json):

```json
{
  "mcpServers": {
    "rekko": {
      "command": "uvx",
      "args": ["rekko-mcp"],
      "env": {
        "REKKO_API_KEY": "rk_free_your_key_here"
      }
    }
  }
}
```

**Available MCP tools** (25+):

Market Intelligence:
- `list_markets(source?, limit?)` — Browse active markets
- `get_market(market_id, source?)` — Get a single market
- `search_markets(query, limit?)` — Search markets by text
- `get_market_history(platform, market_id, period?, max_points?)` — Price history
- `get_resolution(platform, market_id)` — Resolution intelligence
- `get_execution_guidance(platform, market_id)` — Execution analysis

Screening & Discovery:
- `screen_markets(market_ids[], platform?, min_volume_24h?, min_score?, limit?)` — Batch score
- `get_calibration(category?, period?)` — Accuracy metrics (free)

Deep Research (async):
- `analyze_market(bet_text, platform?)` — Trigger analysis
- `check_analysis_status(analysis_id)` — Poll status
- `get_analysis(analysis_id? | market_id+platform?)` — Get result
- `list_analyses()` — Recent analyses

Strategy & Portfolio:
- `get_strategy(market_query, risk_limit?)` — Trading signal (blocking)
- `get_portfolio_strategy(market_query, portfolio[], bankroll_usd?)` — Portfolio-aware
- `get_consensus(market_id, platform?)` — Agent consensus

Arbitrage:
- `get_arbitrage(min_spread?)` — Cached opportunities
- `get_arbitrage_live(min_spread?)` — Fresh scan

Correlation:
- `get_correlation(market_ids[], platform?, period?)` — Cross-market analysis

Trading:
- `place_shadow_trade(ticker, side, size_usd)` — Paper trade
- `report_trade(market_id, platform, side, size_usd, price)` — Report trade for consensus
- `get_portfolio(mode?)` — Portfolio positions
- `get_performance(mode?)` — Track record
- `check_resolutions(mode?)` — Resolve settled markets

Data Refresh:
- `run_scraper(platform)` — Refresh market data (`kalshi`, `polymarket`, `arbitrage`)

Webhooks:
- `create_webhook(url, events[], secret?)` — Register webhook
- `list_webhooks()` — List webhooks
- `delete_webhook(webhook_id)` — Remove webhook

### RapidAPI

Rekko is available on the RapidAPI marketplace. RapidAPI acts as a proxy to `api.rekko.ai` — endpoints and responses are identical, with different auth headers.

**Auth headers:**

```http
x-rapidapi-key: YOUR_RAPIDAPI_KEY
x-rapidapi-host: rekko-ai.p.rapidapi.com
```

**When to use Direct API instead**: Lower latency, webhook/SSE support, MCP plugin, x402 micropayments.

### OpenClaw (AI Agent Skills)

**GitHub:** https://github.com/Rekko-AI/rekko-skill

Rekko is available as a SKILL.md in the OpenClaw ecosystem — a composable skill for autonomous AI trading agents.

**Three-skill architecture:**
- Rekko (Brain): Research + signals
- PolyClaw (Hands): Polymarket execution
- Kalshi Trader (Hands): Kalshi execution

**Install:**

```bash
npx skills add Rekko-AI/rekko-skill
```

**Python client** (`rekko_tools.py`): Async HTTP client with x402 autopay support. See [Python client docs](https://rekko.ai/docs/integrations/openclaw/python-client).

### x402 Micropayments

HTTP 402 payment protocol for crypto-native agents. Pay per-request with USDC on Base L2 — no subscription, no API key.

**Flow:**
1. Make a request without an API key
2. Rekko returns `402 Payment Required` with a payment envelope
3. Your x402 client pays USDC on Base L2
4. Retry the request — it succeeds

**Per-call pricing** matches the tier table: LISTING=$0.01, INSIGHT=$0.10, STRATEGY=$2.00, DEEP=$5.00.

**When subscriptions are cheaper**: If you make more than ~100 LISTING calls/month, a subscription is more cost-effective.

---

## Rate Limits

| Plan | General | Strategy endpoints |
|------|---------|-------------------|
| Free | 30 req/min | — |
| Pro | 120 req/min | 5 req/min |

When rate-limited, the API returns `429 Too Many Requests` with a `Retry-After` header. Use exponential backoff.

### Always-free endpoints (no auth, no quota)

- `GET /v1/health` — Health check
- `GET /v1/pricing` — Tier pricing
- `GET /v1/calibration` — Signal accuracy metrics

---

## Tutorials

- [Prediction Market API Comparison](https://rekko.ai/docs/guides/prediction-market-api-comparison): Kalshi vs Polymarket vs Robinhood — authentication, endpoints, rate limits, Python SDKs, fees, and the unified Rekko layer
- [Build a Trading Bot with Python](https://rekko.ai/docs/guides/build-trading-bot-python): Step-by-step tutorial — screen markets, get AI analysis, generate signals with Kelly sizing, execute trades, track performance
- [Kalshi API Guide](https://rekko.ai/docs/guides/kalshi-api-guide): RSA-PSS authentication, REST endpoints, ticker format, order placement, market data, and adding AI analysis on top
- [Polymarket API Guide](https://rekko.ai/docs/guides/polymarket-api-guide): CLOB API, Gamma Markets API, py-clob-client SDK, condition IDs, HMAC auth, and AI-powered analysis
- [Cross-Platform Arbitrage](https://rekko.ai/docs/guides/prediction-market-arbitrage): Find price gaps between Kalshi and Polymarket, spread calculation, fee accounting, automated scanning, real-time alerts
- [MCP Trading Workflow](https://rekko.ai/docs/guides/mcp-trading-workflow): Use Rekko's 25+ MCP tools from Claude Code or Cursor — market screening, deep analysis, arbitrage, portfolio management via natural language
- [Kelly Criterion Position Sizing](https://rekko.ai/docs/guides/kelly-criterion-position-sizing): Full Kelly, half Kelly, portfolio Kelly with correlation adjustment, automated sizing via signals API
- [PredictIt Alternatives](https://rekko.ai/docs/guides/predictit-alternatives): PredictIt is winding down — where to trade prediction markets in 2026 (Kalshi, Polymarket, Robinhood)
- [Manifold Markets API](https://rekko.ai/docs/guides/manifold-markets-api-guide): Play-money prediction market API and when to use real-money platforms instead
- [Bayesian Analysis](https://rekko.ai/docs/guides/bayesian-analysis-prediction-markets): Prior estimation, evidence updating, causal factor decomposition, and automated Bayesian analysis via API
- [Webhooks and SSE Streaming](https://rekko.ai/docs/guides/webhooks-streaming): Real-time price shifts, whale alerts, analysis completions via Server-Sent Events and webhook push notifications

---

## Disclaimer

All content and signals from Rekko AI are for educational and informational purposes only. Nothing constitutes financial advice, investment advice, or a recommendation to participate in any prediction market.

## Contact

- Email: contact@rekko.ai
- Dashboard: https://rekko.ai/dashboard
- Discord: https://discord.gg/qTPEk9aAZg
- X / Twitter: https://x.com/RekkoAI
- GitHub: https://github.com/Rekko-AI