Polymarket Bot Eğitimi · Bölüm 8 / 32
Botlar için Polymarket CLOB API: order book snapshot’ları için REST endpoints, gerçek zamanlı güncellemeler için WebSocket subscriptions, bids/asks ayrıştırma, mid-price ve depth hesaplama, code samples.
Bu bölüm neleri kapsıyor
CLOB API, orders’ın imzalandığı, gönderildiği, match edildiği ve order book’un bulunduğu yerdir. Polymarket’in iki SDK nesli vardır - deprecated v1 ve mevcut v2. Bu bölüm yalnızca v2’yi kapsar; 2026’da yayınlayacağınız hiçbir botta v1 yer almamalıdır. REST snapshot yolunu, WebSocket update kanalını, yeni geliştiricileri sıkıntıya sokan parsing ayrıntılarını ve uzun süre çalışan bir botun saatler içinde senkronizasyondan çıkmasını engelleyen reconnect mantığını ele alıyoruz.
- CLOB v1 vs v2 (v2 kullanın]
- Order book REST snapshot
- WebSocket subscriptions: market ve user channels
- Bids/asks/depth parsing
- Mid-price ve best-bid/ask hesaplama
- Maker fees, taker fees, rebates
- Code: WS’ye bağlanma ve price-change events işleme
- Reconnect ve gap-handling
CLOB v1 vs v2 (v2 kullanın]
Polymarket iki SDK neslini destekler. v1 (@polymarket/clob-client npm üzerinde, py-clob-client <0.30) deprecated durumdadır ve 2024’te eklenen birkaç order type’ı içermez. v2 (@polymarket/clob-client-v2 Node’da v1.0.2, Python’da py-clob-client 0.34.6+ ) mevcut standarttır.
Üç somut fark vardır. v2, çoklu outcome market’ler için negRisk flag’ini destekler - NegRisk exchange 2024 sonlarında başlatıldığından beri zorunludur. v2, WebSocket message shape’leri için TypeScript types ile gelir; v1 ise any döndürür. v2, Ağustos 2025 Gnosis Safe signature akışını yerleşik olarak işler; v1 ise özel signing glue gerektirir.
Bu bölümün geri kalanı boyunca v2 varsayılmıştır. Daha eski bir tutorial’da v1 code görürseniz, aksi kanıtlanana kadar onu bozuk sayın - özellikle NegRisk market’lere order placement, v1 altında sessizce yanlış exchange contract’ına yönlenebilir.
Order book REST snapshot
REST snapshot endpoint’i, belirli bir token için book’un o andaki tam halini döndürür.
GET https://clob.polymarket.com/book?token_id=<ERC1155_TOKEN_ID>Response shape:
{
"market": "0x...",
"asset_id": "5413...",
"timestamp": "1715600000000",
"hash": "0x...",
"bids": [{"price":"0.45","size":"120"}, {"price":"0.44","size":"380"}, ...],
"asks": [{"price":"0.47","size":"85"}, {"price":"0.48","size":"210"}, ...]
}Prices 2-3 ondalık basamaklı string’lerdir; sizes ise share sayısını temsil eden string’lerdir (dolar değil). Bids yüksekten düşüğe, asks düşükten yükseğe sıralanır. hash bir deduplication işaretçisidir - değişmemiş bir book için tekrarlanan polls aynı hash’i döndürür ve bot’unuz işlemeyi atlayabilir.
REST snapshot, tek seferlik bakışlar için doğru seçenektir (giriş kararı sırasında price check gibi). Sürekli izleme için aşağıdaki WebSocket kanalını kullanın.
WebSocket subscriptions: market ve user channels
İki WebSocket channel önemlidir.
Market channel: wss://ws-subscriptions-clob.polymarket.com/ws/market. Bir veya birden fazla token’a subscribe olun; order-book updates geldikçe alın.
{"type":"Market","markets":["0xCondId1","0xCondId2"]}Mesajlar her değişiklikte gelir. Türler arasında book (tam snapshot), price_change (delta), tick_size_change (nadir) ve last_trade_price (en son fill) bulunur.
User channel: wss://ws-subscriptions-clob.polymarket.com/ws/user. Authenticated’dır; kendi order event’lerinizi alırsınız - fills, partial fills, cancellations.
{"type":"User","auth":{"apiKey":"...","secret":"...","passphrase":"..."}}User channel, bir fill’i tespit etmenin en temiz yoludur. Orders REST endpoint’ini poll etmek daha maliyetlidir ve poll’lar arasındaki state changes’i kaçırabilir; WebSocket, matcher bunu onayladığı anda event’i iter.
Bids/asks/depth parsing
Order book, toplanmış size’a sahip price level’ların bir listesidir. Doğru yapılması gereken iki parsing kuralı vardır.
Order direction: bids buy order’larıdır (birileri bu fiyattan BUY yapmak istiyor). SİZİN bot’unuz satarken bir bid’e isabet edersiniz. Bot’unuz alırken bir ask’i kaldırırsınız. Polymarket UI aynı yönü gösterir; bazı diğer exchange’ler tersini kullanır.
Sorting: bids azalan şekilde gelir (en iyi bid önce). asks artan şekilde gelir (en iyi ask önce). En iyi bid bids[0]; en iyi ask asks[0]’dır. Dikkat: public WebSocket bazen önceden sıralanmamış kısmi book updates gönderir - herhangi bir merge’den sonra daima savunmacı şekilde yeniden sıralayın.
Bir level’daki depth, işlem yapılabilir dolar değeridir: price * size. Top-5-level depth yaygın bir liquidity metriğidir: sum(b.price * b.size for b in bids[:5]). Top-5 depth $100’ün altındaysa book illiquid’dir ve çoğu strategy varsayımı bozulur.
Mid-price ve best-bid/ask hesaplama
Bot’unuzun ihtiyaç duyduğu üç türetilmiş price point vardır.
- Best bid / best ask:
bids[0].priceveasks[0].price. Gerçekten trade edebileceğiniz fiyatlar, bir share için. - Mid-price:
(best_bid + best_ask) / 2. Spread’in matematiksel merkezi. Valuation için kullanışlıdır; mid’den işlem yapmazsınız. - Size N için VWAP price: cumulative size N’e ulaşana kadar book boyunca ilerleyin, size-weighted average price’ı döndürün. Daha derin level’lara süpürmeyi hesaba katarak, şu anda N share BUY etmenin gerçek maliyeti.
Edge case: boş bir bid veya ask tarafı (kimse satmıyor ya da kimse almıyor) book’un tek taraflı olduğu anlamına gelir. Polymarket’in market yapısında bu, resolved veya near-resolved market’lerde görülür; bir taraf 0.999’dadır ve kaybeden tarafta kimse liquidity sunmaz. Best-bid = 0 veya best-ask = 1 değerlerini "do not trade" sinyali olarak değerlendirin.
Maker fees, taker fees, rebates
Polymarket maker-taker fee modelini kullanır. Mayıs 2026 itibarıyla rakamlar:
- Taker fee: 0 (sıfır) - mevcut book liquidity’sini alan order’lar fee ödemez. Proxy operations için gas / network costs uygulandığını unutmayın.
- Maker rebate: küçük pozitif, programatik olarak ödenir, uygun reward-program market’lerinde rested order fill oldukça dağıtılır. Tüm market’lerde rewards yoktur.
- NegRisk markets: aynı fee yapısı, ancak ayrı bir exchange contract’ında; rewards ayrı tahakkuk eder.
Sıfır taker fee, Polymarket’i geleneksel CFD venue’lerinden anlamlı biçimde farklı kılar - trading "cost"unun çoğu açık fee değil, bid-ask spread’in kendisidir. Her trade’de spread’i aşan bir strategy için gerçek maliyet spread tax’tır; tipik book’larda round-trip başına 1-3 cent varsayın, illiquid olanlarda daha fazla.
Maker rebate peşine düşmek ancak liquidity-rewards-eligible market’ler strategy fikirleriyle örtüştüğünde anlamlıdır. Bölüm 19, liquidity-rewards farming’i özel bir yaklaşım olarak ele alır.
Code: WS’ye bağlanma ve price-change events işleme
Minimal Node örneği: bağlan, subscribe ol, tek bir token için gelen her price-change event’ini logla.
import WebSocket from "ws";
const ws = new WebSocket("wss://ws-subscriptions-clob.polymarket.com/ws/market");
ws.on("open", () => {
ws.send(JSON.stringify({ type: "Market", markets: ["<CONDITION_ID>"] }));
});
ws.on("message", (data) => {
const msg = JSON.parse(data.toString());
if (msg.event_type === "price_change") {
console.log("price_change", msg.asset_id, msg.changes);
} else if (msg.event_type === "book") {
console.log("book snapshot", msg.bids?.[0], msg.asks?.[0]);
}
});
ws.on("close", () => console.log("closed"));
ws.on("error", (e) => console.error("err", e.message));Bir WebSocket connection üzerinden rahatça yaklaşık 30 token’a kadar subscribe olabilirsiniz. Bunun ötesinde, birden fazla connection’a bölün - server bazen büyük subscriptions’ları hata vermeden düşürür; bu da sessizce eski book okuması üretir.
Reconnect ve gap-handling
Uzun süre çalışan bir WebSocket connection düşecektir. Cloudflare her birkaç saatte bir connection’ları döngüye sokar; network’ler kısa kesilir; Polymarket bazen deploy eder. Buna hazır olun.
Reconnect stratejisi: close veya error durumunda, jitter ile birlikte min(2^attempt, 30) saniye bekleyin, sonra yeniden subscribe olun. Reconnect sonrası ilk başarılı mesajda attempt sayacını sıfırlayın.
Gap-handling, reconnect hızından daha önemlidir. WebSocket bağlantısı kesikken book hareket etti. Her reconnect’te, subscribe olduğunuz her token’ın REST snapshot’ını yeniden alın ve reconcile edin: book’u anlamlı ölçüde hareket eden açık pozisyonların state check’i gerekir, çıkışlar tetiklenebilir, alarmlar stale olabilir. "30 saniyelik book update’lerini kaçırdım" durumu, uzun süre çalışan bot’ların sessiz katilidir - stale state üzerinde çalışmaya devam eder ve artık var olmayan fiyatlara order yerleştirirler.
Defensive pattern: WebSocket state’inden bağımsız olarak, subscribe olduğunuz her book’un snapshot’ını dakikada bir alın ve WS’yi snapshot poll’unun üzerinde çalışan bir fast-path optimization olarak değerlendirin.
