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

33'te 27. Bölüm

Kısa Versiyon

Polymarket, üç genel API sunar: CLOB (işlem yapma), Gamma (piyasa keşfi) ve Data (analitik). Resmi Python SDK'sı py-clob-client 0.34.6 sürümüdür. Kimlik doğrulama, bir API anahtarı + ECDSA imzası kullanır; emirler Polygon proxy cüzdanı üzerinden EIP-712 ile imzalanır. Hız sınırları, anahtar başına sizi yaklaşık dakikada 60 emir ile sınırlar. Yeni geliştiriciler için en büyük tuzak, Gamma ve CLOB arasındaki condition_id → token_id eşleme sorunudur - önce bunu çözün, gerisi kendiliğinden yerine oturur. Polymarket'te yaklaşık 40 milyon $/ay likidite ödülleri ve botların yakaladığı makas kazancı elde edilir ve bunun neredeyse tamamı API kullanıcıları tarafından kazanılır.

Bölüm 1: Üç API

Polymarket, sorumlulukları üç ayrı hizmet arasında temiz bir şekilde ayırır. Her iş için doğru API'yi kullanmak botunuzu hızlı, basit ve rate limitleri içinde tutar.

Tipik bir bot döngüsü, piyasaları bulmak için Gamma'yı, emir defterlerini çekmek ve işlem yapmak için CLOB'u, strateji performansını çevrimdışı geri test etmek için ise Data'yı kullanır. Gamma'yı bir "katalog", CLOB'u bir "borsa", Data'yı da bir "depo" olarak düşünün.

Bölüm 2: Kimlik Doğrulama ve Proxy Cüzdan Modeli

Polymarket işlemleri ana cüzdanınızın özel anahtarıyla imzalamaz. Bunun yerine, Gnosis Safe tarzı proxy cüzdan 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.

İhtiyacınız olanlar

• API key - Polymarket Ayarları → Developer bölümünde oluşturun
• Özel anahtar - işlem cüzdanınızın anahtarı (ANA MetaMask seed phrase'iniz DEĞİL)
• Funder address - proxy cüzdan adresiniz (Ayarlar → Wallet içinde gösterilir)
• Chain ID - 137 (Polygon ana ağı)
• Signature type - 1 (POLY_PROXY, bireysel kullanıcılar için standart)

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

Resmi Python SDK'sı sıfırdan ilk emre gitmenin en hızlı yoludur. Nisan 2026 itibarıyla geçerli olan 0.34.6 sürümünü kullanacağız.

# Önce bir sanal ortam oluşturun
python3 -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows

# SDK'yı kurun
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"],
)

# Bir defaya mahsus: API kimlik bilgilerini türet ve önbelleğe al
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 ve bunu bir API anahtarı, gizli anahtar ve parola ile değiştirir. İlk çalıştırmadan sonra bunları .env dosyanızda önbelleğe alın ki her başlangıçta türetme uç noktasına istek atmayın.

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

İşlem yapabilmeniz için önce işlem yapmaya değer piyasaları bulmanız gerekir. Gamma, Polymarket arayüzünde görünen her şeyi içeren JSON 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}")

Faydalı Gamma sorgu parametreleri

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

Bu, Polymarket bot geliştirmede #1 sorun noktasıdır. Gamma bir condition_id döndürür (piyasa başına bir tane). CLOB işlemleri bir token_id kullanır (sonuç başına bir tane). Her zaman ikisine de ihtiyacınız vardır.

# Her Gamma piyasa nesnesi 'clobTokenIds' içerir - bir JSON dizi dizesi
import json

market = markets[0]
token_ids = json.loads(market['clobTokenIds']) # ['7410...', '1120...']
yes_token = token_ids[0] # İlk sonuç
no_token = token_ids[1] # İkinci sonuç

# Alternatif: condition_id kullanarak doğrudan CLOB'a sorun
info = client.get_market(condition_id=market['conditionId'])
yes_token = info['tokens'][0]['token_id']

Sonuç sıralaması tuzağı

Gamma'nın outcomes dizisi ve clobTokenIds dizisi indeks eşleşmelidir. Her zaman 0. indeksin "Yes" olduğunu varsaymak yerine sonuç etiketini okuyun. Çok sonuçlu piyasalarda (NegRisk, Oscarlar, seçimler), 0. indeks "Kamala Harris" veya "Taylor Swift" olabilir - sıra deterministik ama 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"Alış {best_bid} Satış {best_ask} Orta {mid:.4f} Makas {spread:.4f}")

Emir defterleri sıralanmış diziler olarak döndürülür (alış emirleri azalan, satış emirleri artan). Her seviyede price ve size bulunur. Daha büyük bir emir için kaymayı tahmin etmek üzere, defter boyunca ilerleyin ve hedef büyüklüğünüze ulaşana kadar nominal değeri biriktirin.

Bölüm 7: Emir Verme

Limit emir (GTC - varsayılan)

from py_clob_client.clob_types import OrderArgs, OrderType

args = OrderArgs(
 token_id=yes_token,
 price=0.45,
 size=100, # Hisse, dolar değil. 0.45 $'dan 100 hisse = 45 $ azami maliyet.
 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 bir EIP-712 yapılandırılmış mesajı imzalar. post_order bunu CLOB'a gönderir. Ham özel anahtarları asla ağ üzerinden göndermezsiniz - yalnızca imzalanmış emirler.

Emir türleri

İptal etme

# Tek emir
client.cancel(order_id="0xabc...")

# Belirli bir piyasadaki tüm emirleri iptal et
client.cancel_market_orders(market=market['conditionId'])

# Nükleer seçenek: her şeyi iptal et
client.cancel_all()

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

Gamma'yı her saniye sorgulamak boşa harcamadır ve hız limitlerine hızlıca takılırsınız. WebSocket akışı, gerçek zamanlı emir defteri ve işlem güncellemelerini alt saniye 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 defteri + işlemler) ve /user akışı (kendi emir ve gerçekleşme olaylarınız, kimlik doğrulamalı). Üretim botları genellikle ikisine de bağlanır, bağlantı kopunca otomatik yeniden bağlanır ve mevcut emir defteri durumunun tek doğruluk kaynağı olarak WebSocket'i kabul eder.

Bölüm 9: Hız Sınırları & Geri Çekilme

Bir HTTP 429 aldığınızda, sunucu bir Retry-After başlığı döndürür. Jitter ile üstel geri çekilme uygulayı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: Bir Referans Bot Mimarisi

Her sağlam Polymarket botunun aynı altı bileşeni vardır. Her birini ayrı bir modül olarak oluşturun; gevşek bağlı tutun.

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

• Eski WebSocket verisi - Her varlık için son mesajın zamanını takip edin; aktif bir piyasada 30 saniyeden uzun süre güncelleme yoksa REST yenilemesini zorlayın.
• Nonce çakışmaları - py-clob-client emir nonce'larını sizin için yönetir, ancak kendi imzalayıcınızı yazıyorsanız, her emir için nonce'u artırın.
• Yetersiz bakiye - Emir vermeden önce her zaman pUSD bakiyesini kontrol edin; emir defteri emrinizi gösterebilir ama eşleştirme bunu reddeder.
• Piyasa duraklatıldı veya sonuçlanıyor - İşlem yapmadan önce market.active && !market.closed kontrol edin. Gamma güncellemeleri, sonuçlanma çevresinde CLOB'un birkaç saniye gerisinde kalır.
• NegRisk adaptör uyumsuzluğu - Çok sonuçlu piyasalar ayrı bir NegRisk adaptöründen geçer. SDK bunu halleder, ancak emrinizin doğru mekana gittiğini doğrulayın.

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

Polymarket genel likidite ödülleri için aylık yaklaşık $5M ve spor odaklı ödüller için aylık $5M+ çalıştırır (bkz. Likidite Ödülleri). Bunun çok büyük kısmı, binlerce piyasa boyunca sıkı iki taraflı kotasyonları koruyabilen API odaklı piyasa yapıcılara gider.

Ödül formülü, orta noktaya yakın emirleri, boyutu ve emir defterinde kalma süresini ödüllendirir. Minimal bir piyasa yapıcılığı döngüsü:

1. Hedef piyasa için emir defterini oku
2. Adil bir orta nokta hesapla (ör. her iki tarafta ilk 3 seviyenin VWAP'i)
3. mid - spread_target/2 seviyesinde bir alış ve mid + spread_target/2 seviyesinde bir satış ver
4. Her WebSocket güncellemesinde, kotasyonun hedeften bir tick'ten fazla sapması halinde fiyatı yeniden ayarla
5. Defter incelirse veya haber çıkarsa iptal et ve çık

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

• Barındırma: Avrupa veya US-East'te aylık $6'lık bir VPS (Hetzner, DigitalOcean) çoğu bot için yeterlidir. 10 ms altı gecikmeye ihtiyacınız varsa Polygon RPC ile aynı yerde konumlandırın.
• RPC: güvenilir Polygon RPC için Alchemy, Infura veya QuickNode kullanın. Saatte yüzlerce emir verene kadar ücretsiz katmanlar yeterlidir.
• İzleme: metrikler için Prometheus + Grafana; uyarılar için bir Telegram botu. Gönderdiğiniz her emir kimliğini ve aldığınız her gerçekleşmeyi kaydedin.
• Yedekler: durumu her dakika kalıcılaştırın. VPS bir gerçekleşme sırasında çökerse, saniyeler içinde devam etmek istersiniz, elle uzlaştırmak değil.
• Vergi: günlük kaydınız aynı zamanda denetim izinizdir - bkz. Vergi Rehberi.

Bölüm 14 - Polymarket API için Doğrulanmış İleri Düzey İpuçları

Durum → Eylem Kısa Rehberi

Sırada Ne Var?

• Araçlar ve Kaynaklar - API’yi tamamlayan üçüncü taraf panolar, analitik ve veri akışları
• İleri Seviye Stratejiler - botlar için uygun çok ayaklı arbitraj ve opsiyon benzeri yapılar
• Likidite Ödülleri - piyasa yapıcılığı iadeleri kazanmak için kesin formüller
• Emir Defteri Rehberi - ona karşı kod yazmadan önce defteri okumaya dair daha derin bir sezgi
• Sözlük - bu rehberdeki her terimin sade İngilizce tanımları