Polymarket Bot Tutorial · 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.6, 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, tarihinin büyük bölümünde hiç trading fee almadı. Bu 2026’da değişti: fee’ler yıl başında 15 dakikalık crypto market’lerinde devreye girdi, 30 Mart 2026’da Sports’a genişletildi ve o zamandan beri çoğu kategoriye yayıldı. Polymarket’in fee’siz olduğunu hâlâ söyleyen her tutorial eskimiştir - ve bunu yüksek frekanslı bir strategy’de gözden kaçıran sessizce yenir. İşte modelin 2026 ortası itibarıyla gerçekte nasıl işlediği.
Önce her trade’in iki tarafı. Maker, book’a bekleyen dinlenen bir limit order koyan kişidir; taker, mevcut likiditeye karşı hemen yürütülen bir order gönderen kişidir. Maker’lar hâlâ sıfır fee öder ve üstüne bir rebate alır; fee’yi yalnızca taker’lar öder.
Taker fee sabit bir yüzde değildir. Hem order büyüklüğüne hem de fiyata bağlı bir eğri izler:
fee = shares × feeRate × price × (1 - price)price × (1 - price) terimi 0,50 fiyatında (gerçek bir yazı-tura market’i) maksimumdur ve 0 ya da 1’e doğru küçülür. Başka bir deyişle, en belirsiz market’lerde en yüksek fee’yi, neredeyse kesinleşmişlerde ise neredeyse hiç fee ödemezsiniz. feeRate kategori bazında belirlenir:
- Crypto: feeRate 0,07 (en yüksek, efektif tepe yaklaşık %1,8), maker rebate %20.
- Sports: feeRate 0,03 (tepe yaklaşık %0,75), maker rebate %25.
- Finance, Politics, Tech, Mentions: feeRate 0,04, maker rebate %25.
- Economics, Culture, Weather, genel: feeRate 0,05, maker rebate %25.
- Geopolitics ve büyük dünya olayları: 0, hâlâ fee’siz.
Bir hesap örneği. Diyelim ki bot’unuz bir crypto market’inden 0,50 fiyatla 100 shares alıyor. Fee 100 × 0,07 × 0,50 × (1 - 0,50) = 100 × 0,07 × 0,25 = $1,75 olur. Aynı 100 shares’i 0,90’dan alırsanız fee 100 × 0,07 × 0,90 × 0,10 = $0,63’e düşer, çünkü fiyat belirsiz ortadan uzaktır. Bir bot için ders açıktır: oynak, neredeyse dengeli crypto ve sports market’lerinde likidite almak en yüksek fee’ye mal olur - dolayısıyla tam orada maker olarak quote verip rebate kapmak, fee ödemekten çok daha kârlıdır.
Açık fee’ye ek olarak, bid-ask spread’i her aştığınızda onu da ödersiniz. Spread, en iyi alış fiyatı ile en iyi satış fiyatı arasındaki farktır ve taker olarak girip çıkan bir strategy için bu fark, fee’nin üstüne gelen gerçek bir maliyettir. Tipik book’larda round-trip başına 1-3 cent, illiquid olanlarda daha fazla varsayın. NegRisk market’leri (multi-outcome exchange) aynı fee modelini kullanır ama ayrı bir contract’ta settle olur, bu yüzden rewards’ları ayrı tahakkuk eder. Bölüm 19, maker rebate kapmanın yan etki değil bizzat strategy olduğu liquidity-rewards farming’i 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.
