Tahmin piyasaları, API'ler oluşturmak için teknik olarak en zorlu alanlar arasındadır. Süresi dolan finansal enstrümanlarla, gerçek zamanlı fiyatlanan olasılıklarla, karmaşık sermaye ilişkilerine sahip çok sonuçlu olaylarla ve hem bir kullanıcı arayüzüne tıklayan insanları hem de arbitraj stratejileri yürüten otomatik ticaret botlarını içeren bir kullanıcı tabanıyla uğraşırsınız. Her tasarım kararı anında strese tabi tutulur.
Hacim açısından şu anda dünyanın en büyük tahmin piyasası platformu olan Polymarket, tam da bu nedenle incelenmeye değer bir API ekosistemi kurmuştur. Bu sadece bir veri tabanı üzerinde çalışan bir CRUD API değildir. Açıklık ve güvenlik, gerçek zamanlı ve geçmiş veriler ile geleneksel finans modelleri ve kripto-yerel temel öğeler arasındaki temel gerilimi ele alan dikkatlice katmanlı bir mimaridir.
İşte bunu nasıl başardıklarından çıkarılmaya değer sekiz tasarım modeli.
Model 1: Alan Adına Göre Ayrılmış API Katmanları
Polymarket, her biri net bir alana sahip üç farklı API sunar:
- Gamma API (
gamma-api.polymarket.com) — piyasa keşfi, olaylar, etiketler, arama - CLOB API (
clob.polymarket.com) — emir defteri verileri, fiyatlandırma, emir yerleştirme - Veri API'si (
data-api.polymarket.com) — kullanıcı pozisyonları, işlemler, analizler, liderlik tabloları
Bu sadece bir adlandırma kuralı değil; her API'nin farklı kimlik doğrulama gereksinimleri, farklı güncelleme sıklıkları ve farklı tüketici profilleri vardır. Gamma API tamamen halka açık olup, göz atma ve keşif için optimize edilmiştir. CLOB API hem genel uç noktalara (herkes emir defterini okuyabilir) hem de kimlik doğrulaması gerektiren uç noktalara (ticaret için kimlik bilgileri gerekir) sahiptir. Veri API'si herkese açık ancak cüzdan adreslidir — pozisyonları kullanıcı adresine göre sorgularsınız.
Buradaki tasarım dersi şudur: varlığa göre değil, alan adına göre ayırmak daha tutarlı API'ler üretir. Acemi bir yaklaşım size /markets, /orders, /users gibi tümünü tek bir çatı altında sunardı. Bunun yerine Polymarket şunu sorar: "Bu API ne için?" ve sonra bu soru etrafında inşa eder. Keşfin, ticaretten farklı erişim modelleri vardır. Ticaretin, analizlerden farklı gecikme gereksinimleri vardır. Her birine kendi temel URL'sini vermek, her birinin bağımsız olarak gelişebileceği, ölçeklenebileceği ve kimlik doğrulaması yapabileceği anlamına gelir.
Model 2: Önce-Genel Veri Erişimi
Piyasa verileriyle ilgili her şey — fiyatlar, emir defterleri, olay meta verileri, geçmiş işlemler — tamamen halka açıktır:
curl "https://gamma-api.polymarket.com/events?limit=5"
API anahtarı yok. OAuth yok. Okuma uç noktalarında hız sınırı engelleri yok. Veriyi alırsınız.
Bu, çoğu finansal platformun yapmadığı kasıtlı bir seçimdir. Geleneksel borsalar piyasa verilerini bir gelir kaynağı olarak korur. Polymarket bunu altyapı olarak görür — ne kadar çok kişi verileri okuyabilir ve üzerinde inşa edebilirse, piyasa o kadar likit ve kullanışlı hale gelir. Bu, bir API'ye uygulanan kamu malı mantığıdır.
API tasarımcıları için pratik sonuç dikkat çekicidir: kimlik doğrulamayı tekdüze uygulamak yerine, *okuma* erişimini *yazma* erişiminden birincil bir endişe olarak ayırmak, veri tüketiminin veri üretiminden çok daha fazla olduğu platformlar için neredeyse her zaman doğru yaklaşımdır. Bir kullanıcı piyasa fiyatlarını kimlik bilgisi olmadan okuyabiliyorsa, potansiyel kitlenizin %95'inden sürtünmeyi (engeli) kaldırmış olursunuz. Sürtünmeyi yalnızca gerçekten önemli olduğu noktada eklersiniz — gerçek bir emir vermek istediklerinde.
Model 3: Gerçek Güveni Yansıtan İki Seviyeli Kimlik Doğrulama
Ticaret uç noktaları kimlik doğrulama gerektirir, ancak Polymarket'in kimlik doğrulama modeli, çoğu API tasarımcısının daha önce görmediği bir yapıya sahiptir: farklı amaçları olan iki seviye.
L1 Kimlik Doğrulama kullanıcının özel anahtarından bir EIP-712 imzası kullanır. Cüzdan sahipliğini kanıtlar. API kimlik bilgilerini türetmek için bunu tam olarak bir kez (veya nadiren) kullanırsınız:
// L1: API kimlik bilgilerini türetmek için özel anahtarınızı kullanın
const credentials = await client.createOrDeriveApiKey();
// → { key: "...", secret: "...", passphrase: "..." }
L2 Kimlik Doğrulama, türetilmiş bu kimlik bilgileriyle HMAC-SHA256 kullanır. Her ticaret isteğine eklediğiniz şey budur:
// Her ticaret isteğindeki L2 başlıkları
{
"POLY_ADDRESS": "0x...",
"POLY_SIGNATURE": "<hmac-sha256>",
"POLY_TIMESTAMP": "1716000000",
"POLY_API_KEY": "550e8400-...",
"POLY_PASSPHRASE": "..."
}
Buradaki içgörü, farklı işlemlerin farklı güvenlik törenlerini hak ettiğidir. API anahtarları oluşturmak, cüzdan kontrolünü kanıtlamayı gerektirir — bu, özel anahtardan bir kriptografik imza talep etmesi gereken yüksek riskli bir eylemdir. Ancak bu güveni bir kez kurduktan sonra, rutin ticaret istekleri her çağrıda özel anahtarınızla yeniden imzalama gerektirmemelidir. L2 kimlik bilgileri, L1 kimliğine bağlı kalırken yüksek frekanslı kullanım için yeterince hafiftir.
Bu model kripto alanının çok ötesine uzanır: bunu "bu kişi olduğunuzu kanıtlayın" (L1, en güçlü mevcut kimlik bilgisiyle nadiren yapılır) ve "bu isteğin sizden geldiğini kanıtlayın" (L2, bir oturum kimlik bilgisiyle sürekli yapılır) arasındaki fark olarak düşünün. Çoğu web uygulaması bunları tek bir kimlik doğrulama akışında birleştirir ve güvenlik nüansını kaybeder.
Model 4: İmzalı Mesajlar Olarak Emirler, API Çağrıları Değil
Tahmin piyasalarının geleneksel API tasarımından en keskin şekilde ayrıldığı yer burasıdır. Polymarket'te bir emir verdiğinizde, sadece bir sunucuya veri göndermekle kalmazsınız — *uygulanabilir bir finansal taahhüt* olan kriptografik olarak imzalı bir mesaj oluşturursunuz:
const response = await client.createAndPostOrder(
{
tokenID: "71321045679...",
price: 0.65,
size: 100,
side: Side.BUY,
},
{
tickSize: "0.01",
negRisk: false,
},
OrderType.GTC
);
Temelde, SDK bir EIP-712 tipi veri yapısı oluşturur, özel anahtarınızla imzalar ve imzayı emirle birlikte gönderir. Eşleştirme motoru zincir dışı çalışır, ancak işlemler eşleştirildiğinde, bu imzaları kullanarak Polygon aracılığıyla zincir üzerinde sonuçlandırılır. Operatör işlem uyduramaz veya fonları taşıyamaz — imzalı mesaj yetkilendirmedir.
Bu, bir "API çağrısı"nın ne anlama geldiğinin anlambilimini değiştirir. Normalde, bir uç noktaya gönderme "lütfen bunu benim adıma yapın" anlamına gelir. Burada, bir emir göndermek "işbu ticareti yetkilendiren imzalı bir belge buradadır" anlamına gelir. API karar veren bir aracı değildir — kriptografik olarak kendi kendini yetkilendiren mesajlar için bir aktarıcıdır.
Kripto alanı dışındaki API tasarımcıları için çıkarım şudur: *yükün kendisi* yetkilendirmeyi taşıyabiliyorken, tamamen taşıma katmanı kimlik bilgilerine güvenmek yerine, reddedilemezlik ve doğrulanabilirlik bedelsiz olarak elde edersiniz. Finansal sistemler, yasal belgeler ve yüksek riskli operasyonlar bu model için adaydır.
Model 5: Veri Modelinde Açık Ontoloji
Polymarket verilerini iki nesne etrafında yapılandırır: Olaylar ve Piyasalar. Ayrım önemlidir.
Bir Olay bir sorudur: "2026 ABD Pennsylvania Senato yarışını kim kazanacak?" Bir başlığı, bir kategorisi, bir çözüm tarihi vardır. Bir Piyasa, o olay içindeki belirli, alınıp satılabilir ikili bir sonuçtur: "Bob Casey kazanacak mı?" Bir olay birçok piyasa içerebilir.
{
"id": "501",
"title": "2026 Pennsylvania Senate Race",
"negRisk": true,
"markets": [
{ "id": "2301", "question": "Will Bob Casey win?", "outcomePrices": "[\"0.42\", \"0.58\"]" },
{ "id": "2302", "question": "Will Dave McCormick win?", "outcomePrices": "[\"0.35\", \"0.65\"]" },
{ "id": "2303", "question": "Will a third candidate win?", "outcomePrices": "[\"0.23\", \"0.77\"]" }
]
}
Bu açık ontolojidir — API sadece veri depolamakla kalmaz, varlıklar arasındaki *kavramsal ilişkileri* kodlar. Fiyatlar, dizin pozisyonunun bağlama kuralı olduğu paralel diziler olarak temsil edilir: outcomes[0], outcomePrices[0]'a karşılık gelir. Olay seviyesindeki negRisk bayrağı, içindeki piyasaların bağımsız piyasalarda bulunmayan sermaye ilişkilerine sahip olduğunu belirtir.
Çoğu API bu ilişkileri düzleştirir. Polymarket bunları yüzeye çıkarır çünkü sistemin çalışma şekli için yük taşıyıcıdırlar. Otomatik bir ticaret botu oluşturuyorsanız ve negRisk: true değerini atlarsanız, yanlış bir pozisyon modeli oluşturur ve potansiyel olarak para kaybedersiniz. API tasarımı, kavramsal yapıyı görünür kılar, böylece onu atlamak bilinçli bir seçim olur, sessiz bir varsayılan değil.
Model 6: NegRisk — Birincil Endişe Olarak Sermaye İlişkileri
Olaylardaki negRisk bayrağı, Polymarket'in en ilginç API tasarım modellerinden birine işaret eder: finansal denkliklerin programlanabilir hale getirilmesi.
Standart çok sonuçlu bir olayda, her piyasa bağımsızdır. Ancak, tam olarak bir sonucun kazanabileceği bir NegRisk olayında, pozisyonlar arasında matematiksel bir ilişki mevcuttur:
A sonucunda 1 "Hayır" token'ı ≡ diğer her sonuçta 1 "Evet" token'ı
Bu sadece matematik değil — akıllı sözleşmelerde uygulanır ve API aracılığıyla yüzeye çıkarılır. Pennsylvania Senato yarışında "Diğer" için bir "Hayır" pozisyonuna sahip olduğunuzda, bunu dönüştürebilirsiniz:
| Önce | Sonra |
|---|---|
| 1× Hayır (Diğer) | 1× Evet (Casey) + 1× Evet (McCormick) |
API bunu açıkça belirtir: piyasa nesnesinde negRisk: true ve bu piyasalarda işlem yaparken emir seçeneklerinizde negRisk: true gereklidir. Yanlış yaparsanız emriniz reddedilir veya yanlış sonuçlandırılır.
Buradaki tasarım modeli, **alan değişmezlerini dokümantasyon dipnotları olarak bırakmak yerine, yazılı API alanları olarak kodlamaktır**. NegRisk bayrağı, sahip olması uygun olduğu için var değildir — var çünkü onu atlamak yanlış davranışa neden olur. Alanınızda katı kısıtlamalar olduğunda (yalnızca bir sonuç kazanabilir, pozisyonların dönüşüm denklikleri vardır), bu kısıtlamalar yalnızca belgelerde değil, API yüzeyinde de görünmelidir.
Model 7: Piyasa Durumu Olarak Dinamik Tick Boyutu
Çoğu finansal API, tick boyutunu statik bir yapılandırma olarak ele alır. Polymarket'inki daha ilginç bir şey yapar: tick boyutu piyasa fiyatına göre dinamik olarak değişir ve API bunu gerçek zamanlı bir olay akışı olarak sunar.
Bir piyasanın fiyatı aşırı uçlara (0.96'nın üzeri veya 0.04'ün altı) yaklaştığında, minimum tick boyutu 0.01'den 0.001'e daralır:
{
"event_type": "tick_size_change",
"asset_id": "65818619657...",
"old_tick_size": "0.01",
"new_tick_size": "0.001",
"timestamp": "100000000"
}
Mantık sezgiseldir: aşırı olasılıklarda, 1 sentlik bir tick %25'lik bir hareketi temsil eder (0.04'ten 0.03'e gitmek). Bu, anlamlı fiyat keşfi için çok kabadır. Aşırı uçlara yakın daha ince tick'ler, piyasanın %97'ye yuvarlamak yerine %97,3 gibi olasılıkları ifade etmesine olanak tanır.
Bunu bir API tasarım tercihi olarak dikkat çekici kılan şey, tick boyutunun bir kez alıp bitirdiğiniz bir parametre olmaması — değişen ve takip edilmesi gereken bir *durum* olmasıdır. WebSocket, istemcilerin emir oluşturma mantıklarını mevcut piyasa durumuyla tutarlı tutabilmeleri için tick_size_change olaylarını tam olarak bu nedenle açığa çıkarır. Tick boyutunu sabit kodlar ve bu olayı kaçırırsanız, emirleriniz reddedilecektir.
Bu, daha geniş bir prensibi yansıtır: **finansal sistemler için API tasarımı, durumu birinci sınıf bir kavram olarak benimsemelidir.** Piyasa parametreleri statik değildir. Çözüm kuralları değişir. Sonuçlar netleşir. API'nin bu durum geçişlerini açıkça iletmesi gerekir, istemcilerin reddedilen istekler aracılığıyla bunları keşfetmesini beklememelidir.
Model 8: Farklı Tüketici Profilleri İçin İki WebSocket Katmanı
Polymarket iki ayrı WebSocket sistemi çalıştırır ve nedenini anlamak, kitle segmentasyonu hakkında bir modeli ortaya koyar.
Piyasa Kanalı (wss://ws-subscriptions-clob.polymarket.com/ws/market), ticaret tüketicileri için oluşturulmuştur. Token kimliğine göre abone olun, emir defteri anlık görüntülerini, fiyat değişikliklerini, işlem gerçekleşmelerini ve tick boyutu değişikliklerini alın. Her şey varlık kimliklerine göre anahtarlanır ve düşük gecikmeli emir oluşturma için optimize edilmiştir:
{
"assets_ids": ["65818619657568813474341868652308942079804919287380422192892211131408793125422"],
"type": "market"
}
Gerçek Zamanlı Veri Soketi (wss://ws-live-data.polymarket.com) tamamen farklı bir profil için oluşturulmuştur. Yorumları, Binance ve Chainlink'ten kripto fiyatlarını, hisse senedi fiyatlarını ve sosyal etkileşim olaylarını yayınlar. Konuya göre abone olun:
{
"action": "subscribe",
"subscriptions": [
{ "topic": "crypto_prices", "type": "update", "filters": "btcusdt,ethusd" }
]
}
Bu iki sistem, temelde farklı ihtiyaçları olan kitlelere hizmet eder. Bir piyasa yapıcı, mikrosaniye hassasiyetinde emir defteri değişimlerine ihtiyaç duyar. "Polymarket'te şu anda neler oluyor"u gösteren bir kullanıcı arayüzü, yorum akışlarına ve sosyal aktiviteye ihtiyaç duyar. Bunları birleştirmek, ya sosyal akışı ticaret düzeyinde gecikme gereksinimleriyle aşırı tasarlamak ya da emir defteri akışını sosyal düzeyde güvenilirlik varsayımlarıyla yetersiz tasarlamak anlamına gelirdi.
Ders basit ama genellikle göz ardı edilir: **gerçek zamanlı tüketicileriniz anlamlı derecede farklı gecikme toleransına, veri hacimlerine ve hata modlarına sahip olduğunda, onlara ayrı altyapı sağlayın.** Birden fazla amaca hizmet etmeye çalışan paylaşılan WebSocket uç noktaları, karmaşıklık için en yüksek ortak paydaya ve performans için en düşük ortak paydaya çökme eğilimindedir.
Bu Modellerin Ortak Noktaları Nelerdir?
Polymarket'in API tasarımı belirli bir felsefeyi yansıtır: API, alanın gerçek yapısını görünür kılmalı, onu soyutlamamalıdır.
Üç katmanlı mimari, gerçek alan sınırlarına karşılık gelir. Önce-genel erişim, tahmin piyasası değerinin nasıl çalıştığını yansıtır. İki seviyeli kimlik doğrulama, kimliği kanıtlama ve bir eylemi yetkilendirme arasındaki gerçek farkı yansıtır. İmzalı mesajlar olarak emirler, emanet dışı garantiyi kodlar. Olay/Piyasa hiyerarşisi ve NegRisk bayrağı, aksi takdirde görünmez olacak ilişkileri ortaya çıkarır. Dinamik tick boyutları, istemci durumunu piyasa durumuyla tutarlı tutar. Ayrı WebSocket katmanları ayrı kitlelere hizmet eder.
Çoğu API tasarım tavsiyesi ergonomiye odaklanır: çağrılmasını kolaylaştırmak, adlandırmada tutarlı olmak, hata işlemede öngörülebilir olmak. Polymarket'in API'si tüm bunları yapar — ancak daha ilginç seçimler *alana sadakat* hakkındadır. Alanın anlamlı bir ayrımı olduğunda, API bunu yüzeye çıkarır. Alanın bir kısıtlaması olduğunda, API bunu uygular. Alanın değişen bir durumu olduğunda, API bunu yayınlar.
Sonuç, tüketicilerinden daha fazlasını talep eden, ancak doğru yapmanın, işlem yaptığınız sistemi gerçekten anladığınız anlamına geldiği bir API'dir. Bu bir tesadüf değil — tahmin piyasaları için, fiyatların bilgiyi yansıtması temel amaçken, piyasanın yapısını anlamanızı zorlayan bir API tam da yapması gerekeni yapıyor demektir.