Polymarket API Rehberi - 2026'da İlk Alım Satım Botunuzu Oluşturun

Kısa Özet

Polymarket size üç herkese açık API sunar (API, programların verileri otomatik olarak okumasını veya işlem yapmasını sağlayan bir yöntemdir): CLOB (alım satım), Gamma (pazar keşfi) ve Data (analitik). Resmî Python SDK’sı py-clob-client 0.34.6’dır. Kimlik doğrulamada API anahtarı + ECDSA imzası kullanılır; emirler ise Polygon proxy wallet üzerinden EIP-712 ile imzalanır. Hız sınırları, anahtar başına yaklaşık dakikada 60 emir ile sınırlıdır. Yeni geliştiriciler için en büyük tuzak, Gamma ile CLOB arasındaki condition_id → token_id eşleme problemidir. Önce bunu çözerseniz, geri kalan her şey çok daha sorunsuz ilerler. Polymarket’te likidite ödülleri ve botların yakaladığı spread üzerinden yaklaşık ayda 40 milyon dolar kazanılır; bunun neredeyse tamamı API kullanıcılarına gider.

Bölüm 1: Üç API

Polymarket, işleri üç ayrı servis arasında net şekilde paylaştırır. Her iş için doğru API’yi kullanmak botunuzu hızlı, sade ve hız sınırları içinde tutar.

Tipik bir bot döngüsünde pazarları bulmak için Gamma, emir defterlerini almak ve işlem yapmak için CLOB, strateji performansını çevrim dışı geriye dönük test etmek için ise Data kullanılır. Gamma’yı “katalog”, CLOB’u “borsa”, Data’yı ise “depo” gibi düşünebilirsiniz.

Bölüm 2: Kimlik Doğrulama & Proxy Wallet Modeli

Polymarket, işlemleri ana cüzdanınızın private key’i ile imzalamaz. Bunun yerine Gnosis Safe tarzı bir proxy wallet kullanır. Ana cüzdanınız bir proxy’yi yetkilendirir ve proxy, tüm işlemleri Polygon üzerinde yürütür. API botunuz bu proxy ile iletişim kurar.

Gerekenler

• API anahtarı - Polymarket Settings → Developer bölümünden oluşturun
• Private key - trading wallet anahtarınız (ana MetaMask seed phrase’iniz DEĞİL)
• Funder adresi - proxy wallet adresiniz (Settings → Wallet bölümünde gösterilir)
• Chain ID - 137 (Polygon mainnet)
• Signature type - 1 (POLY_PROXY, bireysel kullanıcılar için standart)

Bölüm 3: py-clob-client Kurulumu

Resmi Python SDK, sıfırdan ilk emrinize en hızlı şekilde ulaşmanızı sağlar. PyPI üzerindeki güncel sürüm olan 0.34.6 sürümünü kullanacağız (Şubat 2026); canlı botların neredeyse tamamı da bu sürümle çalışıyor.

# Create a virtual environment first
python3 -m venv venv
source venv/bin/activate   # macOS/Linux
venv\Scripts\activate      # Windows

# Install the SDK
pip install py-clob-client==0.34.6 requests websocket-client python-dotenv

Temel istemci yapılandırması

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"],
)

# One-time: derive and cache API credentials
client.set_api_creds(client.create_or_derive_api_creds())

create_or_derive_api_creds() çağrısı, özel anahtarınızla bir mesaj imzalar. Bunun karşılığında bir API anahtarı, secret ve passphrase alır. İlk çalıştırmadan sonra bunları .env dosyanızda önbelleğe alın; böylece her başlangıçta derive endpoint'ine istek göndermek zorunda kalmazsınız.

Bölüm 4: Gamma ile Piyasaları Keşfetme

İşlem yapmadan önce, işlem yapmaya değer piyasaları bulmanız gerekir. Gamma, Polymarket arayüzünde gördüğünüz her şeyi JSON olarak döndürür: soru, sonuçlar, fiyatlar, 24 saatlik hacim, vade, etiketler ve görseller.

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}")

Kullanışlı Gamma sorgu parametreleri

Bölüm 5: condition_id → token_id Eşlemesi

Bu, Polymarket bot geliştirirken karşılaşılan en büyük sorun noktasıdır. Gamma bir condition_id döndürür (piyasa başına bir tane). CLOB işlemleri ise token_id kullanır (sonuç başına bir tane). Her zaman ikisine de ihtiyacınız vardır.

# 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']

Sonuç sıralamasında dikkat edilmesi gereken nokta

Gamma'nın outcomes dizisi ile clobTokenIds dizisi indeks bazında eşleşir. Sonuç etiketini her zaman okuyun. 0 indeksinin "Yes" olduğunu varsaymayın. Çok sonuçlu piyasalarda (NegRisk, Oscar'lar, seçimler) 0 indeksi "Kamala Harris" veya "Taylor Swift" olabilir. Sıralama sabittir, ancak her piyasaya özeldir.

Bölüm 6: Emir Defterlerini Okuma

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}")

Emir defterleri sıralı diziler olarak döner (alış emirleri azalan, satış emirleri artan sırada). Her kademede bir price ve bir size bulunur. Daha büyük bir emirde kaymayı tahmin etmek için defterde ilerleyin ve hedef büyüklüğünüz dolana kadar nominal tutarı toplayın.

Bölüm 6b: CLOB v2 REST Endpoint'leri (ham, SDK olmadan)

SDK bunları sarmalar; ancak ham endpoint'leri bilmek hata ayıklamanıza, başka bir dil kullanmanıza veya ince bir istemci oluşturmanıza olanak tanır. Temel URL: https://clob.polymarket.com. Aşağıdaki tüm okuma işlemleri herkese açıktır - kimlik doğrulama gerekmez. Bunlar Haziran 2026'da canlı olarak doğrulanmıştır.

Canlı API'den doğrudan alınmış doğrulanmış yanıtlar:

$ curl "https://clob.polymarket.com/price?token_id=7347...&side=buy"
{"price":"0.14"}

$ curl "https://clob.polymarket.com/midpoint?token_id=7347..."
{"mid":"0.21"}

$ curl "https://clob.polymarket.com/spread?token_id=7347..."
{"spread":"0.14"}

$ curl "https://clob.polymarket.com/tick-size?token_id=7347..."
{"minimum_tick_size":0.01}

L2 kimlik doğrulama başlıkları (SDK olmadan ham REST için)

Okuma endpoint'leri herkese açıktır. Ham REST üzerinden emir göndermek veya iptal etmek için her isteği API kimlik bilgilerinizle imzalarsınız. SDK bunu sizin yerinize yapar; arka planda oluşturduğu yapı şöyledir:

Bölüm 7: Emir Gönderme - Alış ve Satış

Limit emri (GTC - varsayılan)

from py_clob_client.clob_types import OrderArgs, OrderType

args = OrderArgs(
    token_id=yes_token,
    price=0.45,
    size=100,           # Shares, not dollars. 100 shares @ $0.45 = $45 max cost.
    side="BUY",
)
signed_order = client.create_order(args)
response = client.post_order(signed_order, OrderType.GTC)
print(response)

create_order çağrısı, özel anahtarınızla EIP-712 yapısal mesajını imzalar. Ardından post_order bunu CLOB'a gönderir. Ham özel anahtarları ağ üzerinden asla göndermezsiniz; yalnızca imzalı emirler gönderilir.

Önce fiyatı tick'e hizalayın

Her emir fiyatı, marketin minimum_tick_size değerinin tam katı olmalıdır (çoğu markette 0,01; dar spread'li marketlerde 0,001). Tick'e uymayan fiyat reddedilir. Tick değerini bir kez alın ve fiyatı buna yuvarlayın:

from py_clob_client.clob_types import OrderArgs, OrderType

tick = float(client.get_tick_size(token_id=yes_token))   # e.g. 0.01
def to_tick(p, tick): return round(round(p / tick) * tick, 4)

price = to_tick(0.453, tick)   # -> 0.45 on a 0.01 market

Buy

side="BUY", size hisse cinsindendir (dolar değil). 0,45 ABD dolarından 100 hisse en fazla 45 ABD dolarına mal olur ve sonuç kazanırsa 100 ABD doları öder. Minimum emir değeri yaklaşık 1 ABD dolarıdır.

buy = OrderArgs(token_id=yes_token, price=to_tick(0.45, tick), size=100, side="BUY")
resp = client.post_order(client.create_order(buy), OrderType.GTC)
print(resp)   # {'success': True, 'orderID': '0x...', 'status': 'live', ...}

Sell

Satış için aynı çağrıyı side="SELL" ile yaparsınız. Yalnızca zaten elinizde bulunan payları satabilirsiniz; pozisyonunuzdan fazlasını satmaya çalışırsanız işlem "insufficient balance" hatasıyla reddedilir. Bir pozisyonu kapatmak için, satın aldığınız aynı token_id değerini satın.

sell = OrderArgs(token_id=yes_token, price=to_tick(0.62, tick), size=100, side="SELL")
resp = client.post_order(client.create_order(sell), OrderType.GTC)

Emir parametrelerine hızlı bakış

Hepsini birleştirelim: ilk API işleminiz (çalıştırılabilir tek betik)

Uçtan uca tüm akış budur: bağlanın, likit bir piyasa bulun, emir defterini okuyun, fiyatı tik boyutuna hizalayın, küçük bir gerçek emir verin ve ardından iptal edin. İki gizli bilginizi girip çalıştırın. İlk çalıştırmanızda çok küçük bir büyüklükle (birkaç dolar) başlayın.

import os, json, requests
from dotenv import load_dotenv
from py_clob_client.client import ClobClient
from py_clob_client.constants import POLYGON
from py_clob_client.clob_types import OrderArgs, OrderType

load_dotenv()

# 1) Connect (signing key in your EOA, funds in your proxy/funder)
client = ClobClient(
    "https://clob.polymarket.com",
    key=os.environ["POLY_PRIVATE_KEY"],
    chain_id=POLYGON,            # 137
    signature_type=1,            # 1 = email/Magic proxy, 2 = browser-wallet proxy
    funder=os.environ["POLY_FUNDER"],
)
client.set_api_creds(client.create_or_derive_api_creds())   # cache these after first run

# 2) Find the most-traded open market (Gamma, no auth)
m = requests.get(
    "https://gamma-api.polymarket.com/markets",
    params={"active": "true", "closed": "false", "order": "volume24hr",
            "ascending": "false", "limit": 1}, timeout=10,
).json()[0]
token_id = json.loads(m["clobTokenIds"])[0]   # index 0 = first outcome (read the label!)
print("Trading:", m["question"])

# 3) Read the book + the tick size
tick = float(client.get_tick_size(token_id))
book = client.get_order_book(token_id)
best_ask = float(book.asks[0].price)
print("best ask", best_ask, "| tick", tick)

# 4) Place a small BUY at the ask (tiny size to start)
price = round(round(best_ask / tick) * tick, 4)      # snap to tick
order = OrderArgs(token_id=token_id, price=price, size=5, side="BUY")  # 5 shares
resp = client.post_order(client.create_order(order), OrderType.GTC)
print(resp)                                          # {'success': True, 'orderID': '0x...', ...}

# 5) Cancel it (clean up)
# client.cancel(order_id=resp["orderID"])

Emir türleri

İptal etme

# Single order
client.cancel(order_id="0xabc...")

# Cancel all orders on a specific market
client.cancel_market_orders(market=market['conditionId'])

# Nuclear option: cancel everything
client.cancel_all()

Bölüm 8: WebSocket Akışı

Gamma’yı her saniye sorgulamak verimsizdir ve hız sınırlarına hızla takılırsınız. WebSocket akışı, gerçek zamanlı emir defteri ve işlem güncellemelerini saniyenin altında gecikmeyle iletir.

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)

İki akış vardır. /market akışı herkese açık emir defterini ve işlemleri taşır. /user akışı ise kendi emir ve gerçekleşme olaylarınızı taşır (kimlik doğrulamalı). Üretim botları ikisine de bağlanır, bağlantı koparsa otomatik olarak yeniden bağlanır ve mevcut emir defteri için WebSocket’i doğruluk kaynağı olarak kabul eder.

Bölüm 9: Hız Sınırları ve Backoff

HTTP 429 ile karşılaştığınızda sunucu bir Retry-After başlığı döndürür. Jitter ile üstel backoff kullanın:

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")

Bölüm 10: Referans Bot Mimarisi

Her güvenilir Polymarket botu aynı altı bileşene sahiptir. Her birini ayrı bir modül olarak oluşturun ve aralarındaki bağımlılığı düşük tutun.

Bölüm 11: Yaygın Hata Modları

• Tick dışı fiyat reddi - fiyat, piyasanın minimum_tick_size değerinin tam katı olmalıdır. İmzalamadan önce /tick-size?token_id= üzerinden alın ve yuvarlayın; aksi halde emir reddedilir.
• 404 "No orderbook exists" - kapalı/sonuçlanmış bir token üzerinde /book, /price veya /midpoint sorguladınız. Canlı defteri olan token’ları bulmak için /sampling-markets kullanın.
• Eski WebSocket verisi - Her varlık için son mesaj zamanını izleyin; aktif bir piyasada >30s boyunca güncelleme gelmezse REST yenilemeyi zorunlu kılın.
• Nonce çakışmaları - py-clob-client emir nonce değerlerini sizin için yönetir; ancak kendi imzalayıcınızı yazıyorsanız her emirde nonce değerini artırın.
• Yetersiz bakiye - Emir vermeden önce her zaman USDC bakiyesini kontrol edin; defter emrinizi gösterebilir, ancak eşleştirme bunu reddeder.
• Piyasa duraklatılmış veya sonuçlanıyor - İşlem yapmadan önce market.active && !market.closed koşulunu kontrol edin. Sonuçlanma anlarında Gamma güncellemeleri CLOB’nin birkaç saniye gerisinde kalır.
• NegRisk adaptör uyuşmazlığı - Çok sonuçlu piyasalar ayrı bir NegRisk adaptörü üzerinden yönlendirilir. SDK bunu yönetir, ancak emrinizin doğru işlem yerine gittiğini doğrulayın.

Bölüm 12: API Üzerinden Likidite Ödülleri

Polymarket, genel likidite ödüllerinde ayda yaklaşık 5 milyon ABD doları ve spora özel ödüllerde ayda 5 milyon ABD dolarından fazla dağıtır (bkz. Likidite Ödülleri). Bunun büyük kısmı API ile çalışan piyasa yapıcılara gider. Bu kişiler binlerce piyasada dar spread’li çift taraflı kotasyonlar tutar.

Ödül formülü; büyüklük ve defterde kalma süresiyle birlikte orta fiyata yakın emirleri destekler. En basit piyasa yapıcılık döngüsü şöyledir:

1. Hedef piyasanın emir defterini okuyun
2. Adil bir orta fiyat hesaplayın (ör. her iki tarafta ilk 3 seviyenin VWAP’i)
3. mid − spread_target/2 seviyesinde alış ve mid + spread_target/2 seviyesinde satış kotasyonu girin
4. Her WebSocket güncellemesinde kotasyonunuz hedeften bir tick’ten fazla saparsa yeniden fiyatlayın
5. Defter sığlaşırsa veya önemli haber çıkarsa iptal edin ve çıkın

Bölüm 13: Üretime Geçiş

• Barındırma: Avrupa veya US-East bölgesinde ayda 6 ABD doları tutarında bir VPS (Hetzner, DigitalOcean) çoğu bot için yeterlidir. 10 ms altı gecikmeye ihtiyacınız varsa Polygon RPC ile aynı konuma yerleştirin.
• RPC: güvenilir Polygon RPC için Alchemy, Infura veya QuickNode kullanın. Dakikada yüzlerce emir göndermediğiniz sürece ücretsiz katmanlar yeterlidir.
• İzleme: metrikler için Prometheus + Grafana; uyarılar için bir Telegram botu kullanın. Gönderdiğiniz her emir kimliğini ve aldığınız her gerçekleşmeyi günlüğe yazın.
• Yedekler: durumu her dakika kalıcı olarak kaydedin. VPS bir gerçekleşmenin ortasında çökerse elle mutabakat yapmak yerine saniyeler içinde devam edebilmelisiniz.
• Vergi: günlükleyiciniz aynı zamanda denetim kaydınızdır - bkz. Vergi Rehberi.

Bölüm 14 - Polymarket API İçin Doğrulanmış Profesyonel İpuçları

Durum → Eylem Kısa Başvuru Tablosu

Sırada ne var?

• Araçlar ve Kaynaklar - API'yi tamamlayan üçüncü taraf panoları, analiz araçları ve veri akışları
• İleri Düzey Stratejiler - botlara uygun çok bacaklı arbitraj ve opsiyon benzeri yapılar
• Likidite Ödülleri - piyasa yapıcılık iadeleri kazanmak için kesin formüller
• Emir Defteri Rehberi - emir defteriyle entegrasyon kodlamadan önce defteri okumaya yönelik daha derin bir bakış
• Sözlük - bu rehberdeki her terimin sade dille tanımı

Hızlı kontrol