API Documentation

One unified API to access all prediction markets. Get started in minutes with our simple REST interface.

API Key for Testing

Enter your API key to test endpoints directly from the docs

Quick Start

1Get your API key from the dashboard or create one via the API.

2Include your API key in the Authorization header:

text

Authorization: Bearer YOUR_API_KEY

3Make your first request:

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.propheseer.com/v1/markets?limit=5"

Base URL

Production

text

https://api.propheseer.com/v1

Rate Limits

Plan	Daily Limit	Per-Minute Limit	Price
Free	100 req/day	10 req/min	$0/mo
Pro	10,000 req/day	100 req/min	$29/mo
Business	100,000 req/day	1,000 req/min	$99/mo

Rate limit headers are included in all authenticated responses: X-RateLimit-Remaining-Day, X-RateLimit-Remaining-Minute

Endpoints

GET/v1/markets

Retrieve a paginated list of prediction markets from all connected platforms. Filter by source, category, status, or search by question text.

Parameters

Name	Type	Description	Default
`source`	string	Filter by platform	all
`category`	string	Filter by topic category	-
`status`	string	Filter by market status	-
`q`	string	Search query to filter by question text	-
`limit`	number	Results per page (max: 200)	50
`offset`	number	Pagination offset for retrieving additional results	0

Example Request

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.propheseer.com/v1/markets?category=politics&limit=10"

Example Response

JSON

{
  "data": [
    {
      "id": "pm_abc123",
      "source": "polymarket",
      "question": "Will the Fed cut rates in January 2025?",
      "category": "finance",
      "status": "open",
      "outcomes": [
        { "name": "Yes", "probability": 0.35 },
        { "name": "No", "probability": 0.65 }
      ],
      "url": "https://polymarket.com/event/...",
      "imageUrl": "https://polymarket-upload.s3.amazonaws.com/..."
    }
  ],
  "meta": { "total": 1234, "limit": 50, "offset": 0 }
}

GET/v1/markets/:id

Retrieve detailed information about a specific market including historical data, trading volume, and resolution criteria.

Parameters

Name	Type	Description	Default
`id`*	string	Unique market identifier (e.g., pm_abc123 or ks_xyz789)	-

Example Request

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.propheseer.com/v1/markets/pm_abc123"

Example Response

JSON

{
  "data": {
    "id": "pm_abc123",
    "source": "polymarket",
    "question": "Will the Fed cut rates in January 2025?",
    "description": "This market resolves YES if...",
    "category": "finance",
    "status": "open",
    "outcomes": [
      { "name": "Yes", "probability": 0.35, "volume24h": 125000 },
      { "name": "No", "probability": 0.65, "volume24h": 98000 }
    ],
    "resolutionDate": "2025-01-30",
    "url": "https://polymarket.com/event/...",
    "imageUrl": "https://polymarket-upload.s3.amazonaws.com/..."
  }
}

GET/v1/categories

List all available market categories and their subcategories. Use these values to filter markets by topic.

Example Request

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.propheseer.com/v1/categories"

Example Response

JSON

{
  "data": [
    { "id": "politics", "name": "Politics", "subcategories": ["elections", "policy"] },
    { "id": "sports", "name": "Sports", "subcategories": ["nfl", "nba", "soccer"] },
    { "id": "finance", "name": "Finance", "subcategories": ["crypto", "stocks", "fed"] }
  ],
  "meta": { "total": 6 }
}

GET/v1/arbitrage

Discover cross-platform arbitrage opportunities where the same market trades at different prices. Perfect for building trading bots or alerts.

Parameters

Name	Type	Description	Default
`min_spread`	number	Minimum price spread to consider (0-1, e.g., 0.05 = 5%)	0.03
`category`	string	Filter opportunities by category	-

Example Request

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.propheseer.com/v1/arbitrage?min_spread=0.05"

Example Response

JSON

{
  "data": [
    {
      "question": "Will Trump win 2024 election?",
      "spread": 0.05,
      "potentialReturn": "5.3%",
      "markets": [
        { "source": "polymarket", "yesPrice": 0.52, "url": "..." },
        { "source": "kalshi", "yesPrice": 0.47, "url": "..." }
      ]
    }
  ],
  "meta": { "total": 3 }
}

GET/v1/unusual-trades

Detect unusual trading activity on Polymarket. Flags large trades, new wallet activity, and trades near market resolution. Pro+ plans only.

Parameters

Name	Type	Description	Default
`reason`	string	Filter by detection reason	-
`min_score`	number	Minimum anomaly score (0-1, e.g., 0.8 = high confidence)	0
`since`	string	ISO timestamp to fetch trades detected after (e.g., 2025-01-06T00:00:00Z)	-
`limit`	number	Results per page (max: 100)	50
`offset`	number	Pagination offset	0

Example Request

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.propheseer.com/v1/unusual-trades?min_score=0.8&limit=10"

Example Response

JSON

{
  "data": [
    {
      "id": "ut_abc123",
      "market": {
        "id": "pm_xyz789",
        "question": "Will Bitcoin exceed $150,000 by end of 2025?",
        "source": "polymarket",
        "end_date": "2025-12-31T23:59:59Z"
      },
      "trade": {
        "wallet_address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "side": "BUY",
        "size": 25000,
        "price": 0.42,
        "usdc_value": 10500,
        "timestamp": "2025-01-06T14:30:00Z",
        "transaction_hash": "0x1234..."
      },
      "detection": {
        "reason": "high_amount",
        "anomaly_score": 0.92,
        "context": { "market_avg_size": 280, "market_std_dev": 195 }
      },
      "detected_at": "2025-01-06T14:35:00Z"
    }
  ],
  "meta": { "total": 127, "limit": 50, "offset": 0 }
}

POST/v1/keys

Create a new API key for your application. Keys start on the free tier and are generated immediately. Upgrade your plan from the dashboard after signing up.

Parameters

Name	Type	Description	Default
`name`	string	A friendly name to identify this key (e.g., 'Production App')	Unnamed Key

Example Request

bash

curl -X POST -H "Content-Type: application/json" \
  -d '{"name": "My App"}' \
  "https://api.propheseer.com/v1/keys"

Example Response

JSON

{
  "message": "API key created successfully",
  "data": {
    "key": "pk_test_abc123xyz...",
    "name": "My App",
    "plan": "free",
    "limits": { "requestsPerDay": 100, "requestsPerMinute": 10 }
  }
}

GET/v1/keys/me

Retrieve information about your API key including current usage statistics, rate limits, and plan details.

Example Request

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.propheseer.com/v1/keys/me"

Example Response

JSON

{
  "data": {
    "id": "key_abc123",
    "name": "My App",
    "plan": "free",
    "limits": { "requestsPerDay": 100, "requestsPerMinute": 10 },
    "usage": { "daily": 45, "minute": 3, "total": 1250 },
    "createdAt": "2025-01-15T10:30:00Z"
  }
}

WebSocket API

Get real-time market updates via WebSocket streaming. Perfect for building live dashboards, trading bots, and alerts without polling.

Connection

Connect to the WebSocket endpoint with your API key as a query parameter:

text

wss://api.propheseer.com/ws?api_key=YOUR_API_KEY

For local development, use: ws://localhost:3000/ws?api_key=YOUR_API_KEY

Message Types

Client Messages (Send)

Type	Description	Example
`subscribe`	Subscribe to a market	`{"type":"subscribe","market_id":"pm_abc123"}`
`unsubscribe`	Unsubscribe from a market	`{"type":"unsubscribe","market_id":"pm_abc123"}`
`list_subscriptions`	List active subscriptions	`{"type":"list_subscriptions"}`
`ping`	Keep connection alive	`{"type":"ping"}`

Server Messages (Receive)

Type	Description
`connected`	Connection established with session info
`subscribed`	Successfully subscribed to a market
`market_update`	Real-time price/probability update
`market_resolved`	Market has been settled
`pong`	Response to ping message
`error`	Error message (rate limit, invalid subscription, etc.)

Tier Limits

Plan	Connections	Subscriptions	Monthly Data
Free	1	5 markets	10 MB
Pro	5	50 markets	500 MB
Business	25	Unlimited	10 GB

Code Examples

JavaScript / Node.js

JavaScript

const ws = new WebSocket('wss://api.propheseer.com/ws?api_key=YOUR_API_KEY');

ws.onopen = () => {
  console.log('Connected to Propheseer WebSocket');
  // Subscribe to a market
  ws.send(JSON.stringify({
    type: 'subscribe',
    market_id: 'pm_abc123'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'market_update':
      console.log('Price update:', data.market_id, data.outcomes);
      break;
    case 'market_resolved':
      console.log('Market resolved:', data.market_id, data.resolution);
      break;
    case 'error':
      console.error('Error:', data.message);
      break;
  }
};

// Keep connection alive
setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ type: 'ping' }));
  }
}, 30000);

Python

import asyncio
import websockets
import json

async def connect():
    uri = "wss://api.propheseer.com/ws?api_key=YOUR_API_KEY"

    async with websockets.connect(uri) as ws:
        # Subscribe to a market
        await ws.send(json.dumps({
            "type": "subscribe",
            "market_id": "pm_abc123"
        }))

        async for message in ws:
            data = json.loads(message)

            if data["type"] == "market_update":
                print(f"Price update: {data['market_id']}")
                for outcome in data["outcomes"]:
                    print(f"  {outcome['name']}: {outcome['probability']:.2%}")

            elif data["type"] == "market_resolved":
                print(f"Market resolved: {data['market_id']} -> {data['resolution']}")

            elif data["type"] == "error":
                print(f"Error: {data['message']}")

asyncio.run(connect())

Error Codes

Code	Status	Description
`UNAUTHORIZED`	401	Missing or invalid API key in Authorization header
`NOT_FOUND`	404	The requested resource does not exist
`RATE_LIMITED`	429	You have exceeded your rate limit. Upgrade your plan or wait.
`INTERNAL_ERROR`	500	An unexpected server error occurred. Please try again.

Data Sources

Polymarket

Crypto-native prediction market with high liquidity, particularly on political and current events.

Market IDs prefixed with pm_

Kalshi

CFTC-regulated exchange, legal for US residents. Diverse categories including economics and weather.

Market IDs prefixed with ks_

Gemini

Gemini prediction markets offering events across politics, economics, sports, and entertainment.

Market IDs prefixed with gm_