docs - polydictions api

Getting Started

Authentication

All endpoints require an API key passed in the X-API-Key header. Get your key at /dashboard with an active subscription.

curl -H "X-API-Key: pd_your_key" https://polydictions.xyz/api/v1/arbitrage

Base URL: https://polydictions.xyz/api/v1

Rate Limits

60 requests per minute per API key, sliding window.

Response headers on every request:

Header	Description
X-RateLimit-Limit	Max requests per window (60)
X-RateLimit-Remaining	Requests left in current window
Retry-After	Seconds until limit resets (only on 429)

Errors

All errors follow this format:

{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing X-API-Key header"
  }
}

Code	HTTP	Description
UNAUTHORIZED	401	Missing, invalid, or revoked API key
NO_SUBSCRIPTION	403	Subscription expired or inactive
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Server error

Endpoints

GET/arbitrage

Cross-platform price discrepancies between Polymarket and Kalshi. Refreshes every 20 seconds.

Param	Type	Default	Description
sport	string	all	Filter: all, nba, nhl, nfl, mlb, epl, cbb, etc.
min_spread	number	0	Minimum raw spread %

curl -H "X-API-Key: pd_xxx" \
  "https://polydictions.xyz/api/v1/arbitrage?sport=nba&min_spread=1"

// Response
{
  "ok": true,
  "data": {
    "opportunities": [
      {
        "slug": "nba-lal-det-2026-03-23",
        "game": "Lakers vs Pistons",
        "poly_price": 0.54,
        "kalshi_price": 0.55,
        "spread_pct": 1.0,
        "net_pct": -2.9,
        "direction": "YES Poly + NO Kalshi"
      }
    ],
    "count": 1
  }
}

GET/markets

Trending prediction markets sorted by 24h volume.

Param	Type	Default	Description
limit	integer	10	Max results (1-100)

curl -H "X-API-Key: pd_xxx" "https://polydictions.xyz/api/v1/markets?limit=5"

GET/markets/search

Search markets by keyword.

Param	Type	Default	Description
q	string	required	Search query
limit	integer	10	Max results (1-100)

curl -H "X-API-Key: pd_xxx" "https://polydictions.xyz/api/v1/markets/search?q=bitcoin&limit=5"

GET/events

Paginated list of active Polymarket events.

Param	Type	Default	Description
limit	integer	100	Max results (1-500)
offset	integer	0	Pagination offset

curl -H "X-API-Key: pd_xxx" "https://polydictions.xyz/api/v1/events?limit=50"

GET/whales

Large trades on Polymarket from today.

Param	Type	Default	Description
min_amount	integer	5000	Minimum trade size in USD
limit	integer	100	Max results (1-500)

curl -H "X-API-Key: pd_xxx" "https://polydictions.xyz/api/v1/whales?min_amount=10000"

GET/leaderboard

Top prediction market traders.

Param	Type	Default	Description
period	string	all	all, 1d, 7d, 30d

curl -H "X-API-Key: pd_xxx" "https://polydictions.xyz/api/v1/leaderboard?period=7d"

GET/wallets/top

Top wallets by PnL.

Param	Type	Default	Description
period	string	all	all, 1d, 7d, 30d
limit	integer	10	Max results (1-100)

curl -H "X-API-Key: pd_xxx" "https://polydictions.xyz/api/v1/wallets/top?period=7d&limit=20"

GET/wallets/search

Look up a wallet by address.

Param	Type	Default	Description
q	string	required	Wallet address

curl -H "X-API-Key: pd_xxx" "https://polydictions.xyz/api/v1/wallets/search?q=0x1234..."

GET/wallets/{address}/profile

Trader profile with PnL and stats.

curl -H "X-API-Key: pd_xxx" "https://polydictions.xyz/api/v1/wallets/0x1234.../profile"

GET/wallets/{address}/positions

Current open positions for a wallet.

curl -H "X-API-Key: pd_xxx" "https://polydictions.xyz/api/v1/wallets/0x1234.../positions"

GET/wallets/{address}/history

Trade history for a wallet.

Param	Type	Default	Description
limit	integer	50	Max results (1-500)

curl -H "X-API-Key: pd_xxx" "https://polydictions.xyz/api/v1/wallets/0x1234.../history?limit=100"

Key Management

POST/keys

Create a new API key. Max 3 per wallet. Uses wallet session auth (X-Wallet-Address + X-Session-Token).

// Request body
{ "label": "my-trading-bot" }

// Response
{
  "ok": true,
  "data": {
    "key": "pd_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
    "prefix": "pd_a1b2c3d4"
  }
}

The full key is shown only once. Save it immediately.

GET/keys

List your API keys (prefix only). Uses wallet session auth.

// Response
{
  "ok": true,
  "data": {
    "keys": [
      {
        "prefix": "pd_a1b2c3d4",
        "label": "my-trading-bot",
        "request_count": 142,
        "active": true
      }
    ]
  }
}

DELETE/keys/{prefix}

Delete an API key permanently. Uses wallet session auth.

curl -X DELETE \
  -H "X-Wallet-Address: ..." \
  -H "X-Session-Token: ..." \
  "https://polydictions.xyz/api/v1/keys/pd_a1b2c3d4"

Code Examples

Python

import requests

API_KEY = "pd_your_key"
BASE = "https://polydictions.xyz/api/v1"

# Get arbitrage opportunities
r = requests.get(f"{BASE}/arbitrage",
    headers={"X-API-Key": API_KEY},
    params={"sport": "nba", "min_spread": 2}
)
data = r.json()

for opp in data["data"]["opportunities"]:
    print(f"{opp['game']}: {opp['net_pct']:+.1f}%")

JavaScript

const API_KEY = "pd_your_key";
const BASE = "https://polydictions.xyz/api/v1";

const res = await fetch(`${BASE}/arbitrage?sport=nba`, {
  headers: { "X-API-Key": API_KEY }
});
const { ok, data } = await res.json();

data.opportunities.forEach(opp =>
  console.log(`${opp.game}: ${opp.net_pct}%`)
);

cURL

# Arbitrage opportunities
curl -s -H "X-API-Key: pd_xxx" \
  https://polydictions.xyz/api/v1/arbitrage | jq '.data.opportunities'

# Search markets
curl -s -H "X-API-Key: pd_xxx" \
  "https://polydictions.xyz/api/v1/markets/search?q=bitcoin" | jq

# Whale trades
curl -s -H "X-API-Key: pd_xxx" \
  "https://polydictions.xyz/api/v1/whales?min_amount=10000" | jq