Gamma API پلی‌مارکت: بازارها، رویدادها و Token IDها (۲۰۲۶)

API · مرجع

Gamma API در آدرس gamma-api.polymarket.com نقش «کاتالوگ» را دارد - با آن بازارها و رویدادها را کشف می‌کنید و token IDهایی را می‌گیرید که CLOB برای معامله به آن‌ها نیاز دارد. این API عمومی و بدون احراز هویت است، بنابراین همین حالا می‌توانید هر endpoint را از مرورگر یا با curl کاوش کنید؛ ابزارهای زندهٔ این صفحه هم همین کار را می‌کنند.

Endpointهایی که واقعاً استفاده می‌کنید

query parameterهای رایج روی /markets و /events: active=true، closed=false، slug=، tag_slug=، order=volume24hr، ascending=false، و limit= و offset= برای صفحه‌بندی.

GET /markets - درخواست و پاسخ

یک بازار را با slug درخواست کنید. یک آرایه دریافت می‌کنید (حتی برای یک بازار)، پس عنصر [0] را بردارید:

curl -s "https://gamma-api.polymarket.com/markets?slug=will-it-rain-in-nyc-today" | jq '.[0]'

import requests, json
m = requests.get("https://gamma-api.polymarket.com/markets",
                 params={"slug": "will-it-rain-in-nyc-today"}).json()[0]

یک پاسخ خلاصه و حاشیه‌نویسی‌شده (فیلدهایی که برای یک بات مهم‌اند):

{
  "id": "519284",
  "question": "Will it rain in NYC today?",
  "slug": "will-it-rain-in-nyc-today",
  "conditionId": "0x1f2e...c0",      // the market id (NOT what you trade on)
  "active": true,                    // listed and live
  "closed": false,                   // not yet resolved
  "acceptingOrders": true,           // the CLOB is currently taking orders
  "outcomes": "[\"Yes\", \"No\"]",          // JSON string -> parse it
  "clobTokenIds": "[\"7142...\", \"1098...\"]", // JSON string, aligned with outcomes
  "outcomePrices": "[\"0.62\", \"0.38\"]",     // JSON string, last prices
  "bestBid": 0.61,
  "bestAsk": 0.63,
  "lastTradePrice": 0.62,
  "volume24hr": 48213.5,
  "endDate": "2026-06-16T00:00:00Z"
}

دو token ID مربوط به نتایج درون clobTokenIds قرار دارند. همین‌ها هستند که CLOB روی آن‌ها معامله می‌کند - آن‌ها را بخوانید و می‌توانید یک سفارش ثبت کنید.

مهم‌ترین نکتهٔ گیج‌کننده: فیلدهای رشته‌ایِ JSON-encoded

Gamma فیلدهای clobTokenIds، outcomes و outcomePrices را به‌صورت رشته‌های JSON-encoded داخل خودِ JSON برمی‌گرداند، پس باید بار دوم آن‌ها را decode کنید. و هرگز هاردکد نکنید که کدام token همان «Yes» است: آرایهٔ parse‌شدهٔ outcomes را بخوانید و بر اساس نام نگاشت کنید، چون ترتیب تضمین‌شده نیست.

import requests, json
m = requests.get("https://gamma-api.polymarket.com/markets",
                 params={"slug": SLUG}).json()[0]
outcomes   = json.loads(m["outcomes"])        # e.g. ["Yes", "No"]
token_ids  = json.loads(m["clobTokenIds"])    # aligned with outcomes
prices     = json.loads(m["outcomePrices"])   # aligned with outcomes
yes_token  = token_ids[outcomes.index("Yes")]
print(yes_token, prices[outcomes.index("Yes")])

const r = await fetch(`https://gamma-api.polymarket.com/markets?slug=${SLUG}`);
const m = (await r.json())[0];
const outcomes  = JSON.parse(m.outcomes);
const tokenIds  = JSON.parse(m.clobTokenIds);
const yesToken  = tokenIds[outcomes.indexOf("Yes")];

curl -s "https://gamma-api.polymarket.com/markets?slug=$SLUG" | jq -r '.[0].clobTokenIds | fromjson | .[0]'

روی یک بازار واقعی امتحان کنید - یک slug بچسبانید و token IDهای آن را به‌صورت زنده بگیرید:

اسکن بازارهای قابل‌معامله

پرس‌وجوی کشف در یک بات معمول، بازارهای فعال و باز را می‌خواهد، پرمعامله‌ترین‌ها اول، در یک دسته:

GET https://gamma-api.polymarket.com/markets
    ?active=true&closed=false&order=volume24hr&ascending=false&limit=20&tag_slug=politics

پیش از اقدام، نتیجه را سمت client فیلتر کنید تا فقط بازارهایی بمانند که واقعاً قابل‌معامله‌اند:

# keep only markets the CLOB will accept orders on right now
tradeable = [m for m in markets
             if m.get("active") and not m.get("closed") and m.get("acceptingOrders")]

به‌صورت زنده جستجو کنید (این /public-search را صدا می‌زند، سپس token IDها را برای هر بازار بارگذاری می‌کند):

صفحه‌بندی و تازگی داده

• صفحه‌بندی: limit و offset را اضافه کنید و پیش بروید تا وقتی یک صفحهٔ کوتاه بگیرید. limit را روی /events کوچک‌تر یا مساوی ۵۰۰ و روی /markets کوچک‌تر یا مساوی ۳۰۰ نگه دارید.
• تازگی: قیمت‌ها (bestBid، bestAsk، lastTradePrice) دائماً حرکت می‌کنند. Gamma برای کشف و یک قیمت تقریبی خوب است، اما quote و معامله را از دفتر سفارشات زندهٔ CLOB انجام دهید، نه از یک قیمت کش‌شدهٔ Gamma.
• کش: نگاشت slug به token_id را کش کنید (پایدار است)، نه قیمت‌ها را.

GET /events - گروه‌های چندنتیجه‌ای

یک رویداد، بازارهای مرتبط را دسته‌بندی می‌کند (مثلاً «انتخابات شهرداری NYC» یک بازار به‌ازای هر نامزد دارد). از آن برای رندر کارت‌های چندنتیجه‌ای یا برای یافتن هر بازار روی یک موضوع استفاده کنید:

curl -s "https://gamma-api.polymarket.com/events?slug=nyc-mayor-2025" | jq '.[0].markets | length'

هر رویداد یک آرایهٔ markets دارد؛ هر ورودی همان فیلدهای رشته‌ایِ clobTokenIds / outcomes را دارد که یک بازار سطح‌بالا دارد، پس همان parse کردن اعمال می‌شود.

مرجع فیلدها (آن‌هایی که دردسر می‌سازند)

بعدی: CLOB API (معامله روی یک token_id) · Data API (تاریخچه و PnL) · رفع یک خطا.