نحوه استفاده از API Polymarket: راهنمای کامل توسعه‌دهنده (۲۰۲۶)

Polymarket بزرگترین پلتفرم بازار پیش‌بینی است که به کاربران اجازه می‌دهد روی نتایج رویدادهای دنیای واقعی معامله کنند. چه بخواهید یک dashboard بسازید، استراتژی‌های معاملاتی را خودکار کنید، یا داده بازار را در برنامه خود بکشید، API Polymarket دسترسی برنامه‌نویسی به همه چیز در پلتفرم را به شما می‌دهد.

این راهنما کامل ترین راه‌اندازی API Polymarket را طی می‌کند، از احراز هویت تا اولین معامله، با مثال‌های کد کارآمد در Python و JavaScript.

بررسی اجمالی API Polymarket

Polymarket دو API اصلی را در معرض نمایش می‌گذارد:

API	هدف	احراز هویت	محدودیت نرخ
CLOB API	معامله، ثبت سفارش، داده بازار	کلید API + secret	100 req/min
Gamma API	داده بازار عمومی، رویدادها، metadata	هیچ (عمومی)	300 req/min

CLOB API (دفتر سفارش مرکزی) چیزی است که برای معامله نیاز دارید. Gamma API یک REST API فقط-خواندنی برای واکشی اطلاعات بازار، جزئیات رویداد و داده تاریخی بدون احراز هویت است.

مرحله ۱: دریافت کلید API Polymarket

برای استفاده از CLOB API، به یک کلید API مرتبط با کیف پول Polymarket خود نیاز دارید.

به polymarket.com بروید و کیف پول خود را متصل کنید یا یک حساب ایجاد کنید.
به تنظیمات حساب بروید و بخش API را پیدا کنید.
یک کلید API و secret جدید تولید کنید. اینها را به امنیت ذخیره کنید — دیگر secret را نخواهید دید.

برای Gamma API، هیچ احراز هویتی لازم نیست. می‌توانید بلافاصله شروع به ارسال درخواست کنید.

مرحله ۲: واکشی داده بازار با Gamma API

Gamma API ساده‌ترین راه برای شروع است. داده ساختاریافته درباره تمام بازارهای فعال برمی‌گرداند.

فهرست تمام بازارهای فعال

import requests

# واکشی بازارهای فعال از Polymarket Gamma API
response = requests.get(
    "https://gamma-api.polymarket.com/markets",
    params={
        "active": "true",
        "limit": 10,
        "order": "volume24hr",
        "ascending": "false"
    }
)

markets = response.json()

for market in markets:
    print(f"Question: {market['question']}")
    print(f"Volume (24h): ${market.get('volume24hr', 0):,.2f}")
    print(f"Liquidity: ${market.get('liquidity', 0):,.2f}")
    print("---")

// مثال Node.js / fetch
const response = await fetch(
  "https://gamma-api.polymarket.com/markets?" +
  new URLSearchParams({
    active: "true",
    limit: "10",
    order: "volume24hr",
    ascending: "false"
  })
);

const markets = await response.json();

markets.forEach(market => {
  console.log(`Question: ${market.question}`);
  console.log(`Volume (24h): $${Number(market.volume24hr || 0).toLocaleString()}`);
  console.log(`Liquidity: $${Number(market.liquidity || 0).toLocaleString()}`);
  console.log("---");
});

دریافت یک بازار خاص با ID

import requests

market_id = "0x1234..."  # با condition ID واقعی جایگزین کنید

response = requests.get(
    f"https://gamma-api.polymarket.com/markets/{market_id}"
)

market = response.json()
print(f"Question: {market['question']}")
print(f"Description: {market['description']}")
print(f"End Date: {market['endDate']}")

جستجوی بازارها با کلید واژه

import requests

response = requests.get(
    "https://gamma-api.polymarket.com/markets",
    params={
        "tag": "politics",
        "active": "true",
        "limit": 5
    }
)

markets = response.json()
for m in markets:
    print(f"{m['question']} — Volume: ${m.get('volume24hr', 0):,.0f}")

مرحله ۳: اتصال به CLOB API برای معامله

CLOB API به شما اجازه می‌دهد سفارش‌ها را ثبت و مدیریت کنید. نیاز به احراز هویت رمزنگاری با اعتبارنامه‌های API شما دارد.

نصب کلاینت Python

pip install py-clob-client

مقداردهی اولیه کلاینت

from py_clob_client.client import ClobClient
from py_clob_client.clob_types import ApiCreds

# اعتبارنامه‌های شما
host = "https://clob.polymarket.com"
chain_id = 137  # شبکه اصلی Polygon
private_key = "0xYOUR_PRIVATE_KEY"

# مقداردهی اولیه کلاینت
client = ClobClient(
    host,
    key=private_key,
    chain_id=chain_id
)

# اعتبارنامه‌های API را استخراج کنید
api_creds = client.create_or_derive_api_creds()
client.set_api_creds(api_creds)

print("Connected to Polymarket CLOB API")

واکشی داده دفتر سفارش

# دفتر سفارش یک بازار خاص را بگیرید
token_id = "71321045..."  # شناسه توکن برای یک نتیجه خاص

order_book = client.get_order_book(token_id)

print("Bids:")
for bid in order_book.bids[:5]:
    print(f"  Price: {bid.price} | Size: {bid.size}")

print("Asks:")
for ask in order_book.asks[:5]:
    print(f"  Price: {ask.price} | Size: {ask.size}")

ثبت سفارش محدود

from py_clob_client.order_builder.constants import BUY

# یک سفارش محدود ایجاد و امضا کنید
order_args = {
    "token_id": "71321045...",
    "price": 0.55,        # قیمت در USDC (0.55 = 55 سنت = احتمال 55%)
    "size": 100,           # تعداد سهام
    "side": BUY,
    "fee_rate_bps": 0,     # کارمزد در واحد basis point
}

signed_order = client.create_and_post_order(order_args)
print(f"Order placed: {signed_order}")

لغو سفارش

# یک سفارش خاص را لغو کنید
order_id = "0xABC123..."
result = client.cancel(order_id)
print(f"Order cancelled: {result}")

# همه سفارش‌های باز را لغو کنید
result = client.cancel_all()
print(f"All orders cancelled: {result}")

مرحله ۴: جریان داده real-time با WebSocket

Polymarket اتصالات WebSocket برای به‌روزرسانی‌های قیمت real-time و تغییرات دفتر سفارش ارائه می‌دهد.

import asyncio
import websockets
import json

async def stream_market_data():
    uri = "wss://ws-subscriptions-clob.polymarket.com/ws/market"

    async with websockets.connect(uri) as ws:
        # اشتراک در یک بازار
        subscribe_msg = {
            "type": "subscribe",
            "market": "71321045...",  # شناسه توکن
            "channel": "price"
        }
        await ws.send(json.dumps(subscribe_msg))
        print("Subscribed to price updates")

        async for message in ws:
            data = json.loads(message)
            print(f"Price update: {data}")

asyncio.run(stream_market_data())

مرحله ۵: ساخت یک dashboard بازار ساده

در اینجا یک مثال عملی آمده است که بازارهای برتر را می‌کشد و آن‌ها را در یک جدول فرمت‌بندی شده نمایش می‌دهد.

import requests
from tabulate import tabulate

def get_top_markets(limit=10):
    response = requests.get(
        "https://gamma-api.polymarket.com/markets",
        params={
            "active": "true",
            "limit": limit,
            "order": "volume24hr",
            "ascending": "false"
        }
    )
    return response.json()

def format_market_table(markets):
    rows = []
    for m in markets:
        rows.append([
            m["question"][:60],
            f"${float(m.get('volume24hr', 0)):,.0f}",
            f"${float(m.get('liquidity', 0)):,.0f}",
            m.get("endDate", "N/A")[:10]
        ])

    headers = ["Market", "24h Volume", "Liquidity", "End Date"]
    return tabulate(rows, headers=headers, tablefmt="grid")

markets = get_top_markets()
print(format_market_table(markets))

محدودیت‌های نرخ API Polymarket و بهترین روش‌ها

endpoint	محدودیت نرخ	فاصله توصیه‌شده
Gamma API (عمومی)	300 req/min	200ms بین درخواست‌ها
CLOB REST API	100 req/min	600ms بین درخواست‌ها
WebSocket	بدون محدودیت سخت	هر 30 ثانیه ping heartbeat بفرستید
ثبت سفارش	10 سفارش در ثانیه	در صورت امکان دسته‌بندی کنید

بهترین روش‌ها

داده بازار را کش کنید. metadata بازار به ندرت تغییر می‌کند. آن را به صورت محلی کش کنید و هر ۵ تا ۱۰ دقیقه تازه کنید.
از WebSocket برای داده real-time استفاده کنید. polling REST API محدودیت‌های نرخ را هدر می‌دهد. برای فیدهای قیمت زنده از اشتراک WebSocket استفاده کنید.
خطاهای 429 را به خوبی مدیریت کنید. هنگامی که به محدودیت‌های نرخ برمی‌خورید، backoff نمایی پیاده‌سازی کنید.
کلیدهای API را در متغیرهای محیطی ذخیره کنید. هرگز کلیدهای خصوصی یا API secret ها را در کد hardcode نکنید.

import os

# از متغیرهای محیطی بارگذاری کنید
api_key = os.environ.get("POLYMARKET_API_KEY")
api_secret = os.environ.get("POLYMARKET_API_SECRET")
private_key = os.environ.get("POLYMARKET_PRIVATE_KEY")

کدهای پاسخ رایج API

کد	معنی	اقدام
200	موفق	پردازش پاسخ
400	درخواست بد	بررسی پارامترها
401	غیرمجاز	تأیید اعتبارنامه‌های API
404	پیدا نشد	بررسی شناسه بازار/سفارش
429	محدودیت نرخ	عقب‌نشینی و تلاش مجدد
500	خطای سرور	تلاش مجدد پس از تأخیر

سوالات متداول

آیا API Polymarket رایگان است؟ بله. Gamma API کاملاً رایگان است و به احراز هویت نیاز ندارد. CLOB API برای استفاده رایگان است اما برای ثبت معاملات به یک حساب Polymarket با موجودی نیاز دارد.

Polymarket از کدام بلاکچین استفاده می‌کند؟ Polymarket روی Polygon (chain ID 137) فعالیت می‌کند. برای معامله به USDC روی Polygon نیاز دارید.

آیا می‌توانم از API برای ربات‌های معاملاتی خودکار استفاده کنم؟ بله. CLOB API برای معاملات برنامه‌نویسی طراحی شده است. بسیاری از کاربران استراتژی‌های خودکار اجرا می‌کنند. از شرایط خدمات مربوط به دستکاری بازار آگاه باشید.

آیا محیط sandbox یا testnet وجود دارد؟ Polymarket گاهی محیط‌های testnet برای توسعه‌دهندگان ارائه داده است. برای در دسترس بودن فعلی Discord و مستندات آن‌ها را بررسی کنید.

چه زبان‌های برنامه‌نویسی پشتیبانی می‌شوند؟ کتابخانه کلاینت رسمی در Python است (py-clob-client). APIهای REST و WebSocket با هر زبانی که از درخواست‌های HTTP پشتیبانی می‌کند کار می‌کنند.

جمع‌بندی

API Polymarket یکی از قابل‌دسترس‌ترین APIهای بازار پیش‌بینی موجود است. Gamma API عمومی به صفر راه‌اندازی برای خواندن داده بازار نیاز دارد، و CLOB API قابلیت‌های معاملاتی کامل با پشتیبانی کلاینت Python ارائه می‌دهد.

اگر برنامه‌های مبتنی بر هوش مصنوعی می‌سازید که داده بازار پیش‌بینی یا هر نوع تولید رسانه را در بر می‌گیرند، Hypereal AI را رایگان امتحان کنید — ۳۵ کردیت، بدون نیاز به کارت اعتباری. Hypereal APIهای ساده برای تولید تصویر، ویدیو و آواتار ارائه می‌دهد که به خوبی با برنامه‌های داده‌محور جفت می‌شوند و برای توسعه‌دهندگان ایرانی بدون موانع جغرافیایی در دسترس است.