API Documentation

Polymarket Arbitrage API

Powerful RESTful API to integrate arbitrage detection and automated trading into your applications.

Titan Package Required

API access is exclusively available to Titan package subscribers. Upgrade to unlock unlimited API calls, real-time arbitrage data, and priority support.

Getting Started

The Polymarket Arbitrage API provides programmatic access to real-time arbitrage opportunities, automated trading execution, and comprehensive portfolio management. Built with REST principles, our API uses predictable resource-oriented URLs and returns JSON-encoded responses.

Base URL

https://api.arbitragebot.org/v1

JSON Responses

All API responses are JSON-encoded

HTTPS Only

All requests must be made over HTTPS

Authentication

Authenticate your API requests using your API key. Include it in the Authorization header of every request.

Obtaining Your API Key

Log in to your Polymarket Arbitrage Bot dashboard
Navigate to Settings → API Keys
Click "Generate New API Key"
Securely store your API key (it will only be shown once)

Authentication Header

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X GET "https://api.arbitragebot.org/v1/opportunities" \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -H "Content-Type: application/json"
                            

Example in JavaScript

const apiKey = 'sk_live_1234567890abcdef';
const baseUrl = 'https://api.arbitragebot.org/v1';

fetch(`${baseUrl}/opportunities`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));
                            

Example in Python

import requests

api_key = 'sk_live_1234567890abcdef'
base_url = 'https://api.arbitragebot.org/v1'

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.get(f'{base_url}/opportunities', headers=headers)
data = response.json()
print(data)
                            

Rate Limits

API rate limits ensure fair usage and system stability. Titan package subscribers enjoy higher limits.

Endpoint	Rate Limit	Window
/opportunities	1000 requests	Per minute
/trades	500 requests	Per minute
/portfolio	200 requests	Per minute

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000
                        

Arbitrage Opportunities

Access real-time arbitrage opportunities detected across Polymarket markets.

GET /opportunities

Retrieve a list of current arbitrage opportunities with profitability metrics.

Query Parameters

min_profit optional Minimum profit percentage (default: 0.5)

market_type optional Filter by market type (binary, categorical)

limit optional Number of results (default: 50, max: 100)

Example Request

curl -X GET "https://api.arbitragebot.org/v1/opportunities?min_profit=1.0&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
                        

Example Response

{
  "success": true,
  "data": {
    "opportunities": [
      {
        "id": "arb_7x9k2p4m",
        "market_id": "0x123abc...",
        "market_name": "Will Bitcoin reach $100k by 2024?",
        "market_type": "binary",
        "opportunity_type": "price_discrepancy",
        "profit_percentage": 2.34,
        "estimated_profit_usd": 47.82,
        "required_capital_usd": 2043.50,
        "confidence_score": 0.94,
        "execution_time_estimate": 12,
        "side_a": {
          "outcome": "Yes",
          "price": 0.52,
          "exchange": "clob"
        },
        "side_b": {
          "outcome": "No", 
          "price": 0.46,
          "exchange": "amm"
        },
        "detected_at": "2024-01-15T10:30:45Z",
        "expires_at": "2024-01-15T10:35:45Z",
        "status": "active"
      }
    ],
    "total_count": 23,
    "page": 1,
    "per_page": 10
  },
  "timestamp": "2024-01-15T10:30:47Z"
}
                        

GET /opportunities/:id

Retrieve detailed information about a specific arbitrage opportunity.

Example Request

curl -X GET "https://api.arbitragebot.org/v1/opportunities/arb_7x9k2p4m" \
  -H "Authorization: Bearer YOUR_API_KEY"
                        

Example Response

{
  "success": true,
  "data": {
    "id": "arb_7x9k2p4m",
    "market_id": "0x123abc...",
    "market_name": "Will Bitcoin reach $100k by 2024?",
    "profit_percentage": 2.34,
    "estimated_profit_usd": 47.82,
    "required_capital_usd": 2043.50,
    "execution_steps": [
      {
        "step": 1,
        "action": "buy",
        "outcome": "Yes",
        "price": 0.52,
        "amount": 100,
        "exchange": "clob"
      },
      {
        "step": 2,
        "action": "sell",
        "outcome": "No",
        "price": 0.46,
        "amount": 100,
        "exchange": "amm"
      }
    ],
    "risk_assessment": {
      "liquidity_risk": "low",
      "execution_risk": "medium",
      "market_volatility": 0.15
    },
    "historical_success_rate": 0.89
  }
}
                        

Trading Endpoints

Execute arbitrage trades programmatically with our automated trading API.

POST /trades/execute

Execute an arbitrage trade based on a detected opportunity.

Request Body

opportunity_id required ID of the arbitrage opportunity

amount_usd required Trading amount in USD

slippage_tolerance optional Max slippage percentage (default: 0.5)

auto_execute optional Execute immediately (default: true)

Example Request

curl -X POST "https://api.arbitragebot.org/v1/trades/execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "opportunity_id": "arb_7x9k2p4m",
    "amount_usd": 1000,
    "slippage_tolerance": 0.5,
    "auto_execute": true
  }'
                        

Example Response

{
  "success": true,
  "data": {
    "trade_id": "trade_9m2k4x7p",
    "opportunity_id": "arb_7x9k2p4m",
    "status": "executed",
    "executed_at": "2024-01-15T10:31:22Z",
    "transactions": [
      {
        "tx_hash": "0xabc123...",
        "type": "buy",
        "outcome": "Yes",
        "amount": 100,
        "price": 0.52,
        "total_usd": 1000,
        "gas_fee_usd": 2.34
      },
      {
        "tx_hash": "0xdef456...",
        "type": "sell",
        "outcome": "No",
        "amount": 100,
        "price": 0.46,
        "total_usd": 1023.40,
        "gas_fee_usd": 1.89
      }
    ],
    "profit": {
      "gross_usd": 23.40,
      "fees_usd": 4.23,
      "net_usd": 19.17,
      "roi_percentage": 1.92
    }
  }
}
                        

GET /trades/history

Retrieve your trading history with detailed performance metrics.

Query Parameters

start_date optional Filter from date (ISO 8601)

end_date optional Filter to date (ISO 8601)

status optional Filter by status (executed, pending, failed)

Example Request

curl -X GET "https://api.arbitragebot.org/v1/trades/history?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
                        

Portfolio Management

Monitor your portfolio performance and active positions.

GET /portfolio/summary

Get a comprehensive overview of your portfolio performance.

Example Response

{
  "success": true,
  "data": {
    "total_value_usd": 15234.67,
    "available_balance_usd": 8500.00,
    "locked_in_trades_usd": 6734.67,
    "total_profit_usd": 1234.67,
    "total_profit_percentage": 8.82,
    "active_positions": 5,
    "total_trades": 127,
    "win_rate": 0.94,
    "daily_performance": {
      "profit_usd": 123.45,
      "trades": 8,
      "win_rate": 1.0
    },
    "monthly_performance": {
      "profit_usd": 2345.67,
      "trades": 234,
      "win_rate": 0.93
    }
  }
}
                        

GET /portfolio/positions

List all your active trading positions.

Example Response

{
  "success": true,
  "data": {
    "positions": [
      {
        "position_id": "pos_3k7m9x2p",
        "market_name": "Will Bitcoin reach $100k by 2024?",
        "outcome": "Yes",
        "entry_price": 0.52,
        "current_price": 0.54,
        "amount": 100,
        "value_usd": 1000,
        "unrealized_pnl_usd": 38.46,
        "unrealized_pnl_percentage": 3.85,
        "opened_at": "2024-01-15T09:00:00Z"
      }
    ],
    "total_positions": 5
  }
}
                        

Webhooks

Receive real-time notifications when arbitrage opportunities are detected or trades are executed.

Setting Up Webhooks

Navigate to Settings → Webhooks in your dashboard
Click "Create Webhook"
Enter your endpoint URL (must use HTTPS)
Select the events you want to receive
Save your webhook configuration

Available Events

opportunity.detected

Triggered when a new arbitrage opportunity is found

trade.executed

Triggered when a trade is successfully executed

trade.failed

Triggered when a trade execution fails

portfolio.update

Triggered when your portfolio value changes significantly

Webhook Payload Example

{
  "event": "opportunity.detected",
  "timestamp": "2024-01-15T10:30:45Z",
  "data": {
    "id": "arb_7x9k2p4m",
    "market_name": "Will Bitcoin reach $100k by 2024?",
    "profit_percentage": 2.34,
    "estimated_profit_usd": 47.82,
    "expires_at": "2024-01-15T10:35:45Z"
  }
}
                    

Verifying Webhook Signatures

Each webhook request includes a signature in the X-Webhook-Signature header. Verify this signature to ensure the request came from our servers.

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}
                    

Error Codes

Our API uses standard HTTP status codes and returns detailed error messages.

Code	Status	Description
200	OK	Request successful
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing API key
403	Forbidden	Titan package required
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error occurred

Error Response Format

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked",
    "details": {
      "key_prefix": "sk_live_1234"
    }
  },
  "timestamp": "2024-01-15T10:30:45Z"
}
                    

SDKs & Libraries

Official SDKs to integrate our API into your applications quickly.

JavaScript/Node.js

npm install @arbitragebot/api

const ArbitrageBot = require('@arbitragebot/api');

const client = new ArbitrageBot({
  apiKey: 'YOUR_API_KEY'
});

const opportunities = await client
  .opportunities
  .list({ min_profit: 1.0 });
                            

Python

pip install arbitragebot-python

from arbitragebot import Client

client = Client(
  api_key='YOUR_API_KEY'
)

opportunities = client.opportunities.list(
  min_profit=1.0
)
                            

Support Team

Currently Offline

Avg. response time: 84 minutes

Hi there! We're currently offline, but leave us a message and we'll get back to you as soon as possible.

Polymarket Arbitrage API

Titan Package Required

Getting Started

Base URL

JSON Responses

HTTPS Only

Authentication

Obtaining Your API Key

Authentication Header

Example Request

Example in JavaScript

Example in Python

Rate Limits

Rate Limit Headers

Arbitrage Opportunities

Query Parameters

Example Request

Example Response

Example Request

Example Response

Trading Endpoints

Request Body

Example Request

Example Response

Query Parameters

Example Request

Portfolio Management

Example Response

Example Response

Webhooks

Setting Up Webhooks

Available Events

Webhook Payload Example

Verifying Webhook Signatures

Error Codes

Error Response Format

SDKs & Libraries

JavaScript/Node.js

Python

Support Team

Message Sent!