راهنمای Polymarket API: CLOB، REST و ربات‌های معاملاتی (2026)

فصل 27 از 33

نسخه کوتاه

Polymarket سه API عمومی ارائه می‌دهد: CLOB (معامله)، Gamma (کشف بازار) و Data (تحلیل). SDK رسمی پایتون py-clob-client 0.34.6 است. احراز هویت از کلید API + امضای ECDSA استفاده می‌کند و سفارش‌ها از طریق EIP-712 با یک کیف پول پروکسی Polygon امضا می‌شوند. محدودیت نرخ شما را به حدود 60 سفارش در دقیقه برای هر کلید محدود می‌کند. بزرگ‌ترین مشکل برای توسعه‌دهندگان جدید مسئله نگاشت condition_id → token_id بین Gamma و CLOB است - اول آن را حل کنید، و بقیه چیزها سر جای خود قرار می‌گیرند. حدود 40 میلیون دلار در ماه در پاداش‌های نقدشوندگی و اسپردی که توسط بات‌ها جذب می‌شود در Polymarket به دست می‌آید، که تقریباً همه آن توسط کاربران API کسب می‌شود.

سه سرویس جداگانه: CLOB (احراز هویت 9000/10 ثانیه) برای معامله، Gamma (عمومی 4000/10 ثانیه) برای کشف، Data (عمومی 1000/10 ثانیه) برای تحلیل تاریخی.

بخش 1: سه API

Polymarket وظایف را به‌طور شفاف بین سه سرویس مجزا تفکیک می‌کند. استفاده از API مناسب برای هر کار، ربات شما را سریع، ساده و در محدوده نرخ مجاز نگه می‌دارد.

یک حلقه معمولی ربات از Gamma برای پیدا کردن بازارها، از CLOB برای دریافت دفتر سفارش و ثبت معاملات، و از Data برای بک‌تست عملکرد استراتژی به‌صورت آفلاین استفاده می‌کند. Gamma را مثل «کاتالوگ»، CLOB را مثل «صرافی» و Data را مثل «انبار» در نظر بگیرید.

L1 ساختار EIP-712 «ClobAuthDomain» را با chainId 137 امضا می‌کند تا اعتبارنامه‌ها را استخراج کند. L2 HMAC-SHA256 هر درخواست بعدی را با هدرهای POLY_SIGNATURE امضا می‌کند.

بخش ۲: احراز هویت و مدل کیف پول پروکسی

Polymarket تراکنش‌ها را با کلید خصوصی کیف پول اصلی شما امضا نمی‌کند. در عوض، از یک کیف پول پروکسی به سبک Gnosis Safe استفاده می‌کند: کیف پول اصلی شما یک پروکسی را مجاز می‌کند و پروکسی همه تراکنش‌ها را روی Polygon اجرا می‌کند. ربات API شما با آن پروکسی صحبت می‌کند.

آنچه نیاز دارید

• کلید API - در Polymarket Settings → Developer ایجاد کنید
• کلید خصوصی - کلید کیف پول معاملاتی شماست (نه عبارت بازیابی MetaMask اصلی شما)
• آدرس Funder - آدرس کیف پول پروکسی شما (در Settings → Wallet نمایش داده می‌شود)
• Chain ID - 137 (شبکه اصلی Polygon)
• نوع امضا - 1 (POLY_PROXY، استاندارد برای کاربران خرد)

نوع امضا 1 (POLY_PROXY) برای حساب‌های Magic-link، نوع 2 (GNOSIS_SAFE) برای پروکسی‌های کیف پول مرورگر، نوع 0 (EOA) برای کلیدهای مستقیم. Funder برای نوع‌های 1 و 2 لازم است.

بخش ۳: نصب py-clob-client

SDK رسمی پایتون سریع‌ترین راه برای رسیدن از صفر به اولین سفارش است. ما از نسخه 0.34.6 استفاده می‌کنیم که تا آوریل ۲۰۲۶ به‌روز است.

# ابتدا یک محیط مجازی ایجاد کنید
python3 -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows

# SDK را نصب کنید
pip install py-clob-client==0.34.6 requests websocket-client python-dotenv

پیکربندی پایه کلاینت

import os
from dotenv import load_dotenv
from py_clob_client.client import ClobClient
from py_clob_client.constants import POLYGON

load_dotenv()

client = ClobClient(
 host="https://clob.polymarket.com",
 key=os.environ["POLY_PRIVATE_KEY"],
 chain_id=POLYGON, # 137
 signature_type=1, # POLY_PROXY
 funder=os.environ["POLY_FUNDER"],
)

# یک‌بار: اطلاعات API را استخراج و ذخیره کنید
client.set_api_creds(client.create_or_derive_api_creds())

فراخوانی create_or_derive_api_creds() با کلید خصوصی شما یک پیام را امضا می‌کند و آن را با یک کلید API، secret و passphrase معاوضه می‌کند. این‌ها را بعد از اولین اجرا در .env خود ذخیره کنید تا در هر راه‌اندازی به endpoint استخراج مراجعه نکنید.

Gamma /markets مقدارهای outcomePrices، clobTokenIds، volume24hr و tags را برمی‌گرداند. از tag_slug + order=volume24hr به‌عنوان کوئری پیش‌فرض اسکنر بات استفاده کنید.

بخش 4: کشف بازارها از طریق Gamma

قبل از اینکه بتوانید معامله کنید، باید بازارهایی را پیدا کنید که ارزش معامله داشته باشند. Gamma یک JSON برمی‌گرداند که همه چیزهایی را که رابط کاربری Polymarket نشان می‌دهد شامل می‌شود: پرسش، نتایج، قیمت‌ها، حجم 24 ساعته، تاریخ انقضا، برچسب‌ها و تصاویر.

import requests

resp = requests.get(
 "https://gamma-api.polymarket.com/markets",
 params={
 "active": "true",
 "closed": "false",
 "tag_slug": "politics",
 "limit": 20,
 "order": "volume24hr",
 "ascending": "false",
 },
 timeout=10,
)
resp.raise_for_status()
markets = resp.json()

for m in markets:
 print(f"{m['slug']:50} Yes ${float(m['outcomePrices'][0]):.3f} Vol24h ${m.get('volume24hr', 0):,.0f}")

پارامترهای مفید کوئری Gamma

Gamma conditionId را افشا می‌کند (یکی برای هر بازار)؛ CLOB بر token_id معامله می‌کند (یکی برای هر نتیجه). clobTokenIds یک آرایه رشته‌ای کدگذاری‌شده با JSON است که ایندکس‌های آن با نتایج هم‌تراز است.

بخش 5: نگاشت condition_id → token_id

این مشکل شماره 1 در توسعه ربات Polymarket است. Gamma یک condition_id برمی‌گرداند (یکی برای هر بازار). معاملات CLOB از یک token_id استفاده می‌کنند (یکی برای هر نتیجه). شما همیشه به هر دو نیاز دارید.

# Each Gamma market object contains 'clobTokenIds' - a JSON string array
import json

market = markets[0]
token_ids = json.loads(market['clobTokenIds']) # ['7410...', '1120...']
yes_token = token_ids[0] # First outcome
no_token = token_ids[1] # Second outcome

# Alternative: ask CLOB directly using condition_id
info = client.get_market(condition_id=market['conditionId'])
yes_token = info['tokens'][0]['token_id']

نکته‌ی دردسرسازِ ترتیب نتایج

آرایه outcomes در Gamma و آرایه clobTokenIds از نظر اندیسی با هم منطبق هستند. همیشه برچسب نتیجه را بخوانید و فرض نکنید که اندیس 0 یعنی "Yes." در بازارهای چندنتیجه‌ای (NegRisk، Oscars، انتخابات)، اندیس 0 می‌تواند "Kamala Harris" یا "Taylor Swift" باشد - ترتیب قطعی است اما به خود بازار وابسته است.

دفتر به‌صورت bidهای نزولی و askهای صعودی برگردانده می‌شود. سطوح را بررسی کنید تا پیش از ارسال یک FAK شبیه سفارش بازار، قیمت پرشدن را برای هر ارزش اسمی هدف برآورد کنید.

بخش 6: خواندن دفتر سفارش

book = client.get_order_book(token_id=yes_token)

best_bid = float(book.bids[0].price) if book.bids else None
best_ask = float(book.asks[0].price) if book.asks else None
mid = (best_bid + best_ask) / 2 if best_bid and best_ask else None
spread = best_ask - best_bid if best_bid and best_ask else None

print(f"Bid {best_bid} Ask {best_ask} Mid {mid:.4f} Spread {spread:.4f}")

دفترهای سفارش به‌صورت آرایه‌های مرتب‌شده برگردانده می‌شوند (bidها به‌صورت نزولی، askها به‌صورت صعودی). هر سطح دارای price و size است. برای برآورد لغزش قیمت برای یک سفارش بزرگ‌تر، دفتر را پیمایش کنید و ارزش اسمی را انباشته کنید تا زمانی که اندازه هدف خود را مصرف کرده باشید.

GTC روی دفتر باقی می‌ماند، GTD در timestamp به‌طور خودکار لغو می‌شود، FOK به پر شدن کامل اندازه یا لغو شدن نیاز دارد، FAK هرچه را بتواند با حد سفارش می‌گیرد و بقیه را لغو می‌کند.

بخش ۷: ثبت سفارش‌ها

سفارش محدود (GTC - پیش‌فرض)

from py_clob_client.clob_types import OrderArgs, OrderType

args = OrderArgs(
 token_id=yes_token,
 price=0.45,
 size=100, # تعداد سهم، نه دلار. 100 سهم @ $0.45 = حداکثر هزینه $45.
 side="BUY",
)
signed_order = client.create_order(args)
response = client.post_order(signed_order, OrderType.GTC)
print(response)

فراخوانی create_order یک پیام ساختاریافته EIP-712 را با کلید خصوصی شما امضا می‌کند. post_order آن را به CLOB ارسال می‌کند. شما هرگز کلیدهای خصوصی خام را از طریق شبکه ارسال نمی‌کنید - فقط سفارش‌های امضاشده.

انواع سفارش

لغو کردن

# سفارش واحد
client.cancel(order_id="0xabc...")

# لغو همه سفارش‌ها در یک بازار مشخص
client.cancel_market_orders(market=market['conditionId'])

# گزینه نهایی: همه‌چیز را لغو کن
client.cancel_all()

بخش 8: استریم WebSocket

پول‌کردن Gamma هر ثانیه اتلافی است و خیلی زود به محدودیت نرخ می‌رسید. فید WebSocket به‌روزرسانی‌های لحظه‌ای دفتر سفارش و معاملات را با تأخیر کمتر از یک ثانیه پخش می‌کند.

import json, websocket

WS_URL = "wss://ws-subscriptions-clob.polymarket.com/ws/market"

def on_open(ws):
 ws.send(json.dumps({
 "type": "market",
 "assets_ids": [yes_token, no_token],
 }))

def on_message(ws, message):
 event = json.loads(message)
 if event.get("event_type") == "price_change":
 print(f"{event['market']} {event['side']} {event['price']} size={event['size']}")

ws = websocket.WebSocketApp(
 WS_URL,
 on_open=on_open,
 on_message=on_message,
)
ws.run_forever(ping_interval=20)

دو فید وجود دارد: فید /market (دفتر سفارش عمومی + معاملات) و فید /user (رویدادهای سفارش و پرشدنِ خودتان، احراز هویت‌شده). ربات‌های تولیدی معمولاً به هر دو متصل می‌شوند، در صورت قطع اتصال به‌طور خودکار دوباره وصل می‌شوند، و WebSocket را به‌عنوان منبع حقیقت برای وضعیت فعلی دفتر در نظر می‌گیرند.

بخش 9: محدودیت نرخ و backoff

وقتی به HTTP 429 می‌رسید، سرور یک هدر Retry-After برمی‌گرداند. backoff نمایی همراه با jitter را پیاده‌سازی کنید:

import random, time

def post_with_backoff(fn, *args, max_retries=6):
 for attempt in range(max_retries):
 try:
 return fn(*args)
 except Exception as e:
 if "429" in str(e):
 sleep = (2 ** attempt) + random.random()
 time.sleep(min(sleep, 30))
 continue
 raise
 raise RuntimeError("Too many retries")

بخش 10: یک معماری مرجع برای بات

هر بات مقاوم Polymarket همان شش مؤلفه را دارد. هرکدام را به‌صورت ماژول جداگانه بسازید؛ آن‌ها را با اتصال سست نگه دارید.

بخش 11: حالت‌های خرابی رایج

• داده قدیمی WebSocket - زمان آخرین پیام برای هر دارایی را پیگیری کنید؛ اگر روی یک بازار فعال تا بیش از 30 ثانیه به‌روزرسانی نبود، یک تازه‌سازی REST را اجباری کنید.
• برخورد nonce - py-clob-client nonceهای سفارش را برای شما مدیریت می‌کند، اما اگر signer خودتان را نوشته‌اید، در هر سفارش nonce را افزایش دهید.
• موجودی ناکافی - همیشه پیش از ثبت، موجودی USDC را بررسی کنید؛ دفتر ممکن است سفارش شما را نشان دهد اما matching آن را رد خواهد کرد.
• بازار متوقف یا در حال تسویه - پیش از معامله، market.active && !market.closed را بررسی کنید. به‌روزرسانی‌های Gamma در اطراف تسویه چند ثانیه از CLOB عقب می‌مانند.
• عدم تطابق adapter مربوط به NegRisk - بازارهای چندنتیجه‌ای از طریق یک adapter جداگانه NegRisk مسیریابی می‌شوند. SDK آن را مدیریت می‌کند، اما مطمئن شوید سفارش شما به مکان درست رفته است.

بخش 12: پاداش‌های نقدشوندگی از طریق API

Polymarket حدود $5M در ماه پاداش نقدشوندگی عمومی و بیش از $5M در ماه پاداش‌های مخصوص اسپرت اجرا می‌کند (ببینید پاداش‌های نقدشوندگی). بخش بسیار بزرگی از این پاداش به market makerهای مبتنی بر API می‌رسد که می‌توانند در هزاران بازار، دوطرفه و با فاصله کم قیمت‌گذاری کنند.

فرمول پاداش، سفارش‌های نزدیک به midpoint، اندازه، و مدت‌زمان حضور در دفتر را پاداش می‌دهد. یک حلقه حداقلی market-making:

1. دفتر سفارش بازار هدف را بخوانید
2. یک midpoint منصفانه محاسبه کنید (مثلاً VWAP سه سطح برتر هر سمت)
3. یک bid در mid - spread_target/2 و یک ask در mid + spread_target/2 ثبت کنید
4. در هر به‌روزرسانی WebSocket، اگر quote شما بیش از یک tick از هدف منحرف شد، قیمت را دوباره تنظیم کنید
5. اگر دفتر نازک شد یا خبری منتشر شد، لغو کنید و خارج شوید

بخش 13: رفتن به Production

• میزبانی: یک VPS ماهی 6 دلار (Hetzner، DigitalOcean) در اروپا یا US-East برای بیشتر بات‌ها کافی است. اگر به latency زیر 10 میلی‌ثانیه نیاز دارید، نزدیک Polygon RPC مستقر شوید.
• RPC: برای Polygon RPC قابل‌اعتماد از Alchemy، Infura یا QuickNode استفاده کنید. پلن‌های رایگان تا زمانی که صدها سفارش در دقیقه ثبت نکنید کافی‌اند.
• پایش: Prometheus + Grafana برای متریک‌ها؛ یک بات Telegram برای هشدارها. شناسه هر سفارشی را که می‌فرستید و هر پرشدنی را که دریافت می‌کنید ثبت کنید.
• پشتیبان‌گیری: هر دقیقه وضعیت را ذخیره کنید. اگر VPS وسط پرشدن بمیرد، می‌خواهید ظرف چند ثانیه ادامه دهید، نه اینکه دستی تطبیق دهید.
• مالیات: logger شما در حکم ردپای حسابرسی شما هم هست - ببینید راهنمای مالیات.

بخش 14 - نکات حرفه‌ای تأییدشده برای Polymarket API

برگه تقلب وضعیت -> اقدام

بعدش چی؟

• ابزارها و منابع - داشبوردها، تحلیل‌ها، و فیدهای داده شخص ثالث که API را تکمیل می‌کنند
• استراتژی‌های پیشرفته - آربیتراژ چندمرحله‌ای و ساختارهای شبیه آپشن که برای بات‌ها مناسب‌اند
• پاداش‌های نقدشوندگی - فرمول‌های دقیق برای کسب ریبیت‌های بازارسازی
• راهنمای دفتر سفارش - درک عمیق‌تر برای خواندن دفتر قبل از اینکه روی آن کدنویسی کنید
• واژه‌نامه - تعریف‌های ساده و روان برای هر اصطلاح در این راهنما