Integrate with REST, Python, or Claude MCP

# Python — pip install requests
import requests

API_BASE = 'https://api.falconai.pro/api/v1/external/polymarket'
API_KEY  = 'aif_your_key_here'

session = requests.Session()
session.headers['Authorization'] = f'Bearer {API_KEY}'

# Health check
resp = session.get(f'{API_BASE}/health')
resp.raise_for_status()
print(resp.json())  # {'success': True, 'data': {'status': 'ok'}}

# Health check
curl https://api.falconai.pro/api/v1/external/polymarket/health \
  -H "Authorization: Bearer aif_your_key_here"

# List top 10 active markets by volume
markets = session.get(
  f'{API_BASE}/markets',
  params={'status': 'active', 'sort': 'volume', 'limit': 10}
).json()['data']

# Single market
market = session.get(f'{API_BASE}/markets/{market_id}').json()['data']

# Hourly OHLCV
candles = session.get(
  f'{API_BASE}/markets/{market_id}/ohlcv',
  params={'interval': '1h', 'limit': 168}
).json()['data']

# ── Cursor pagination ─────────────────────────────────────────
def get_all_markets():
    all_markets, cursor = [], None
    while True:
        params = {'status': 'active', 'limit': 50}
        if cursor:
            params['cursor'] = cursor
        resp = session.get(f'{API_BASE}/markets', params=params).json()
        all_markets.extend(resp['data'])
        if not resp['pagination']['has_more']:
            break
        cursor = resp['pagination']['next_cursor']
    return all_markets

# List top 10 active markets sorted by volume
curl "https://api.falconai.pro/api/v1/external/polymarket/markets?status=active&sort=volume&limit=10" \
  -H "Authorization: Bearer aif_your_key"

# Single market detail
curl "https://api.falconai.pro/api/v1/external/polymarket/markets/0xabc123..." \
  -H "Authorization: Bearer aif_your_key"

# Hourly OHLCV
curl "https://api.falconai.pro/api/v1/external/polymarket/markets/0xabc123.../ohlcv?interval=1h&limit=168" \
  -H "Authorization: Bearer aif_your_key"

# Categories + platform volume
curl "https://api.falconai.pro/api/v1/external/polymarket/markets/categories" \
  -H "Authorization: Bearer aif_your_key"
curl "https://api.falconai.pro/api/v1/external/polymarket/volume/timeseries?range_days=30" \
  -H "Authorization: Bearer aif_your_key"

# Next page using cursor
curl "https://api.falconai.pro/api/v1/external/polymarket/markets?status=active&limit=50&cursor=eyJ0cyI6..." \
  -H "Authorization: Bearer aif_your_key"

# Recent trades (global)
trades = session.get(f'{API_BASE}/trades', params={'limit': 50}).json()['data']

# Trades for a specific wallet
wallet_trades = session.get(f'{API_BASE}/trades', params={
    'wallet': '0xba4ac793e68eacb93b41566137f25757656a9fa6', 'limit': 100
}).json()['data']

# Trader profile (30-day stats + realized PnL)
trader = session.get(
    f"{API_BASE}/traders/0xba4ac793e68eacb93b41566137f25757656a9fa6"
).json()['data']
print(trader['total_realized_pnl'], trader['win_rate_pct'])

# Daily PnL + holders (Tier 2)
pnl = session.get(f'{API_BASE}/traders/{wallet}/pnl', params={'days': 90}).json()['data']
holders = session.get(f'{API_BASE}/markets/{market_id}/holders').json()['data']

# Recent trades
curl "https://api.falconai.pro/api/v1/external/polymarket/trades?limit=50" \
  -H "Authorization: Bearer aif_your_key"

# Trades for a wallet
curl "https://api.falconai.pro/api/v1/external/polymarket/trades?wallet=0xba4ac...&limit=100" \
  -H "Authorization: Bearer aif_your_key"

# Trader profile + daily PnL + holders
curl "https://api.falconai.pro/api/v1/external/polymarket/traders/0xba4ac..." \
  -H "Authorization: Bearer aif_your_key"
curl "https://api.falconai.pro/api/v1/external/polymarket/traders/browse?sort_by=total_realized_pnl&limit=25" \
  -H "Authorization: Bearer aif_your_key"
curl "https://api.falconai.pro/api/v1/external/polymarket/markets/0xabc.../holders" \
  -H "Authorization: Bearer aif_your_key"

# Flask webhook receiver — pip install flask
import hmac, hashlib, time
from flask import Flask, request, abort

app   = Flask(__name__)
SECRET = 'whsec_your_secret'  # set from env

@app.post('/webhook')
def receive_webhook():
    sig = request.headers.get('X-Falcon-Signature', '')
    ts  = request.headers.get('X-Falcon-Timestamp', '0')

    # Replay-attack guard — reject events older than 5 minutes
    if abs(time.time() - int(ts)) > 300:
        abort(400, 'Timestamp too old')

    raw_body = request.get_data()
    msg = ts.encode() + b'.' + raw_body
    expected = 'sha256=' + hmac.new(
        SECRET.encode(), msg, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(sig, expected):
        abort(401, 'Bad signature')

    event = request.get_json()
    print(f"Received {event['event']} for {event.get('market_id','?')}")
    return 'OK', 200

# HMAC-SHA256 algorithm (language-agnostic)
#
# 1. Concatenate:   message = timestamp + "." + raw_body_string
# 2. Compute HMAC:  digest  = HMAC-SHA256(key=webhook_secret, data=message)
# 3. Format:        expected = "sha256=" + hex(digest)
# 4. Compare:       use constant-time comparison to avoid timing attacks
#
# Reject if: sig != expected OR abs(now - timestamp) > 300 seconds
#
# Example values:
timestamp  = "1743600000"
raw_body   = '{"event":"trade.executed","market_id":"0xabc..."}'
secret     = "whsec_8c027e334813cbafe38895ca0281f992..."

message    = timestamp + "." + raw_body
# → "1743600000.{"event":"trade.executed",...}"

signature  = "sha256=" + HMAC_SHA256_HEX(key=secret, data=message)
# → "sha256=a3f7e2c8d1..."

def safe_get(path, **params):
    resp = session.get(f'{API_BASE}{path}', params=params).json()
    if not resp.get('success'):
        code = resp.get('code', 'UNKNOWN')
        msg  = resp.get('error',  'Unknown error')
        error_map = {
            'UNAUTHORIZED':   'Invalid API key',
            'FORBIDDEN':       'Tier too low for this endpoint',
            'NOT_FOUND':       f'Not found: {path}',
            'PAYMENT_REQUIRED': 'Insufficient credits',
        }
        raise Exception(error_map.get(code, f'API error [{code}]: {msg}'))
    return resp