Pasar prediksi adalah salah satu domain yang paling menantang secara teknis untuk membangun API. Anda berhadapan dengan instrumen keuangan yang kedaluwarsa, probabilitas yang menentukan harga secara real-time, peristiwa multi-hasil dengan hubungan modal yang kompleks, dan basis pengguna yang mencakup manusia yang mengklik UI dan bot perdagangan otomatis yang menjalankan strategi arbitrase. Setiap keputusan desain langsung diuji ketahanannya.
Polymarket, yang saat ini merupakan platform pasar prediksi terbesar di dunia berdasarkan volume, telah membangun ekosistem API yang patut dipelajari persis karena alasan ini. Ini bukan sekadar API CRUD di atas basis data. Ini adalah arsitektur yang berlapis dengan hati-hati yang menangani ketegangan fundamental antara keterbukaan dan keamanan, antara data real-time dan historis, serta antara pola keuangan tradisional dan primitif asli kripto.
Berikut adalah delapan pola desain yang patut diekstraksi dari cara mereka melakukannya.
Pola 1: Lapisan API yang Terpisah Berdasarkan Domain
Polymarket mengekspos tiga API yang berbeda, masing-masing dengan domain yang jelas:
- Gamma API (
gamma-api.polymarket.com) — penemuan pasar, peristiwa, tag, pencarian - CLOB API (
clob.polymarket.com) — data buku pesanan, penetapan harga, penempatan pesanan - Data API (
data-api.polymarket.com) — posisi pengguna, perdagangan, analitik, papan peringkat
Ini bukan hanya konvensi penamaan — setiap API memiliki persyaratan otentikasi yang berbeda, irama pembaruan yang berbeda, dan profil konsumen yang berbeda. Gamma API sepenuhnya publik, dioptimalkan untuk penjelajahan dan penemuan. CLOB API memiliki endpoint publik (siapa pun dapat membaca buku pesanan) dan endpoint terotentikasi (perdagangan memerlukan kredensial). Data API bersifat publik tetapi dialamatkan ke dompet — Anda menanyakan posisi berdasarkan alamat pengguna.
Pelajaran desain di sini adalah bahwa pemisahan berdasarkan domain daripada berdasarkan entitas menghasilkan API yang lebih koheren. Pendekatan naïf akan memberi Anda /markets, /orders, /users semuanya dalam satu atap. Polymarket malah bertanya: "Untuk apa API ini digunakan?" dan kemudian membangun berdasarkan pertanyaan tersebut. Penemuan memiliki pola akses yang berbeda dari perdagangan. Perdagangan memiliki persyaratan latensi yang berbeda dari analitik. Memberikan setiap API URL dasar sendiri berarti masing-masing dapat berkembang, berskala, dan mengotentikasi secara independen.
Pola 2: Akses Data yang Mengutamakan Publik
Semua data pasar — harga, buku pesanan, metadata peristiwa, perdagangan historis — sepenuhnya publik:
curl "https://gamma-api.polymarket.com/events?limit=5"
Tanpa kunci API. Tanpa OAuth. Tanpa batasan laju pada endpoint baca. Anda mendapatkan datanya.
Ini adalah pilihan yang disengaja yang tidak dilakukan sebagian besar platform keuangan. Bursa tradisional menjaga data pasar sebagai sumber pendapatan. Polymarket memperlakukannya sebagai infrastruktur — semakin banyak orang dapat membaca dan membangun di atas data tersebut, semakin likuid dan berguna pasar tersebut. Ini adalah logika barang publik yang diterapkan pada API.
Konsekuensi praktis bagi perancang API patut dicatat: memisahkan akses baca dari akses tulis sebagai perhatian utama, daripada menerapkan otentikasi secara seragam, hampir selalu merupakan keputusan yang tepat untuk platform di mana konsumsi data jauh melebihi produksi data. Jika pengguna dapat membaca harga pasar tanpa kredensial, Anda telah menghilangkan gesekan dari 95% audiens potensial Anda. Anda hanya menambahkan gesekan pada titik yang benar-benar penting — ketika mereka ingin menempatkan pesanan nyata.
Pola 3: Otentikasi Dua Tingkat yang Mencerminkan Kepercayaan Nyata
Endpoint perdagangan memerlukan otentikasi, tetapi model otentikasi Polymarket memiliki struktur yang belum pernah dilihat sebagian besar perancang API: dua tingkat dengan tujuan yang berbeda.
Otentikasi L1 menggunakan tanda tangan EIP-712 dari kunci privat pengguna. Ini membuktikan kepemilikan dompet. Anda menggunakannya persis satu kali (atau jarang) untuk mendapatkan kredensial API:
// L1: Gunakan kunci privat Anda untuk mendapatkan kredensial API
const credentials = await client.createOrDeriveApiKey();
// → { key: "...", secret: "...", passphrase: "..." }
Otentikasi L2 menggunakan HMAC-SHA256 dengan kredensial yang didapatkan tersebut. Ini yang Anda lampirkan pada setiap permintaan perdagangan:
// Header L2 pada setiap permintaan perdagangan
{
"POLY_ADDRESS": "0x...",
"POLY_SIGNATURE": "<hmac-sha256>",
"POLY_TIMESTAMP": "1716000000",
"POLY_API_KEY": "550e8400-...",
"POLY_PASSPHRASE": "..."
}
Wawasan di sini adalah bahwa operasi yang berbeda membutuhkan upacara keamanan yang berbeda. Membuat kunci API memerlukan pembuktian kontrol dompet — itu adalah tindakan berisiko tinggi yang harus menuntut tanda tangan kriptografi dari kunci privat. Tetapi setelah Anda membangun kepercayaan itu, permintaan perdagangan rutin seharusnya tidak memerlukan penandatanganan ulang dengan kunci privat Anda pada setiap panggilan. Kredensial L2 cukup ringan untuk penggunaan frekuensi tinggi sementara tetap terikat pada identitas L1.
Pola ini berlaku jauh melampaui kripto: anggap saja sebagai perbedaan antara "buktikan Anda adalah orang ini" (L1, dilakukan jarang dengan kredensial terkuat yang tersedia) dan "buktikan permintaan ini berasal dari Anda" (L2, dilakukan terus-menerus dengan kredensial sesi). Sebagian besar aplikasi web menggabungkan ini menjadi satu alur otentikasi dan kehilangan nuansa keamanan.
Pola 4: Pesanan sebagai Pesan yang Ditandatangani, Bukan Panggilan API
Di sinilah pasar prediksi paling tajam menyimpang dari desain API konvensional. Ketika Anda menempatkan pesanan di Polymarket, Anda tidak hanya mengirim data ke server — Anda membuat pesan yang ditandatangani secara kriptografi yang merupakan komitmen finansial yang dapat ditegakkan:
const response = await client.createAndPostOrder(
{
tokenID: "71321045679...",
price: 0.65,
size: 100,
side: Side.BUY,
},
{
tickSize: "0.01",
negRisk: false,
},
OrderType.GTC
);
Di balik layar, SDK membangun struktur data bertipe EIP-712, menandatanganinya dengan kunci privat Anda, dan menyerahkan tanda tangan tersebut bersama dengan pesanan. Mesin pencocokan beroperasi di luar rantai, tetapi ketika perdagangan dicocokkan, mereka diselesaikan di rantai melalui Polygon menggunakan tanda tangan tersebut. Operator tidak dapat memalsukan perdagangan atau memindahkan dana — pesan yang ditandatangani adalah otorisasi.
Ini mengubah semantik dari apa arti "panggilan API". Biasanya, mengirim ke endpoint berarti "tolong lakukan ini atas nama saya." Di sini, mengirim pesanan berarti "ini adalah instrumen yang ditandatangani yang mengesahkan perdagangan ini." API bukanlah perantara yang membuat keputusan — ini adalah relai untuk pesan yang mengotorisasi diri secara kriptografi.
Bagi perancang API di luar ruang kripto, intinya adalah ini: ketika payload itu sendiri dapat membawa otorisasi daripada sepenuhnya mengandalkan kredensial lapisan transportasi, Anda mendapatkan non-penolakan dan verifiabilitas secara gratis. Sistem keuangan, dokumen hukum, dan operasi berisiko tinggi semuanya merupakan kandidat untuk pola ini.
Pola 5: Ontologi Eksplisit dalam Model Data
Polymarket menyusun datanya di sekitar dua objek: Peristiwa (Events) dan Pasar (Markets). Perbedaan ini penting.
Sebuah Peristiwa adalah pertanyaan: "Siapa yang akan memenangkan pemilihan Senat AS 2026 di Pennsylvania?" Ini memiliki judul, kategori, tanggal penyelesaian. Sebuah Pasar adalah hasil biner yang dapat diperdagangkan secara spesifik dalam peristiwa tersebut: "Apakah Bob Casey akan menang?" Satu peristiwa dapat berisi banyak pasar.
{
"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\"]" }
]
}
Ini adalah ontologi eksplisit — API tidak hanya menyimpan data, ia mengkodekan hubungan konseptual antara entitas. Harga direpresentasikan sebagai larik paralel di mana posisi indeks adalah konvensi pengikatan: outcomes[0] sesuai dengan outcomePrices[0]. Bendera negRisk di tingkat peristiwa menandakan bahwa pasar di dalamnya memiliki hubungan modal yang tidak ada di pasar independen.
Sebagian besar API meratakan hubungan ini. Polymarket menampilkannya karena mereka merupakan penopang beban bagaimana sistem bekerja. Jika Anda membangun pedagang otomatis dan Anda melewatkan negRisk: true, Anda akan membangun model posisi yang salah dan berpotensi kehilangan uang. Desain API membuat struktur konseptual terlihat sehingga menghilangkannya adalah pilihan sadar, bukan default yang tersembunyi.
Pola 6: NegRisk — Hubungan Modal sebagai Perhatian Kelas Satu
Bendera negRisk pada peristiwa menunjukkan salah satu pola desain API Polymarket yang paling menarik: membuat ekivalensi keuangan dapat diprogram.
Dalam peristiwa multi-hasil standar, setiap pasar bersifat independen. Tetapi dalam peristiwa NegRisk, di mana persis satu hasil dapat menang, ada hubungan matematis antara posisi:
1 token "Tidak" pada hasil A ≡ 1 token "Ya" pada setiap hasil lainnya
Ini bukan hanya matematika — ini diimplementasikan dalam smart contract dan ditampilkan melalui API. Ketika Anda memegang posisi "Tidak" pada "Lainnya" dalam pemilihan Senat Pennsylvania, Anda dapat mengkonversinya:
| Sebelum | Sesudah |
|---|---|
| 1× Tidak (Lainnya) | 1× Ya (Casey) + 1× Ya (McCormick) |
API membuat ini eksplisit: negRisk: true di objek pasar, dan negRisk: true diperlukan dalam opsi pesanan Anda saat memperdagangkan pasar ini. Jika salah, pesanan Anda akan ditolak atau diselesaikan dengan tidak benar.
Pola desain di sini adalah mengodekan invarian domain sebagai bidang API bertipe daripada membiarkannya sebagai catatan kaki dokumentasi. Bendera NegRisk tidak ada karena nyaman untuk dimiliki — ada karena menghilangkannya menyebabkan perilaku yang salah. Ketika domain Anda memiliki batasan keras (hanya satu hasil yang dapat menang, posisi memiliki ekivalensi konversi), batasan tersebut harus muncul di antarmuka API, bukan hanya di dokumen.
Pola 7: Ukuran Tick Dinamis sebagai Keadaan Pasar
Sebagian besar API keuangan memperlakukan ukuran tick sebagai konfigurasi statis. Polymarket melakukan sesuatu yang lebih menarik: ukuran tick berubah secara dinamis berdasarkan harga pasar, dan API mengekspos ini sebagai aliran peristiwa real-time.
Ketika harga pasar mendekati ekstrem (di atas 0.96 atau di bawah 0.04), ukuran tick minimum menyempit dari 0.01 menjadi 0.001:
{
"event_type": "tick_size_change",
"asset_id": "65818619657...",
"old_tick_size": "0.01",
"new_tick_size": "0.001",
"timestamp": "100000000"
}
Alasan ini intuitif: pada probabilitas ekstrem, tick 1 sen merepresentasikan pergerakan 25% (dari 0.04 menjadi 0.03). Itu terlalu kasar untuk penemuan harga yang berarti. Tick yang lebih halus di dekat ekstrem memungkinkan pasar untuk menyatakan probabilitas seperti 97.3% daripada membulatkannya menjadi 97%.
Apa yang membuat ini penting sebagai pilihan desain API adalah bahwa ukuran tick bukanlah parameter yang Anda ambil sekali — itu adalah keadaan yang berubah dan harus dilacak. WebSocket mengekspos peristiwa tick_size_change persis agar klien dapat menjaga logika konstruksi pesanan mereka konsisten dengan keadaan pasar saat ini. Jika Anda mengodekan ukuran tick secara manual dan melewatkan peristiwa ini, pesanan Anda akan ditolak.
Ini mencerminkan prinsip yang lebih luas: desain API untuk sistem keuangan harus merangkul keadaan sebagai konsep kelas satu. Parameter pasar tidak statis. Aturan resolusi berubah. Hasil diklarifikasi. API perlu mengkomunikasikan transisi keadaan ini secara eksplisit, tidak membiarkan klien menemukannya melalui permintaan yang ditolak.
Pola 8: Dua Lapisan WebSocket untuk Profil Konsumen yang Berbeda
Polymarket menjalankan dua sistem WebSocket terpisah, dan memahami alasannya mengungkapkan pola tentang segmentasi audiens.
Saluran Pasar (Market Channel) (wss://ws-subscriptions-clob.polymarket.com/ws/market) dibangun untuk konsumen perdagangan. Berlangganan berdasarkan ID token, menerima snapshot buku pesanan, perubahan harga, eksekusi perdagangan, dan perubahan ukuran tick. Semuanya dikunci ke ID aset dan dioptimalkan untuk konstruksi pesanan latensi rendah:
{
"assets_ids": ["65818619657568813474341868652308942079804919287380422192892211131408793125422"],
"type": "market"
}
Soket Data Real-Time (Real-Time Data Socket) (wss://ws-live-data.polymarket.com) dibangun untuk profil yang sama sekali berbeda. Ini mengalirkan komentar, harga kripto dari Binance dan Chainlink, harga ekuitas, dan peristiwa interaksi sosial. Berlangganan berdasarkan topik:
{
"action": "subscribe",
"subscriptions": [
{ "topic": "crypto_prices", "type": "update", "filters": "btcusdt,ethusd" }
]
}
Kedua sistem ini melayani audiens dengan kebutuhan yang secara fundamental berbeda. Pembuat pasar membutuhkan delta buku pesanan yang relevan dalam mikrosekon. UI yang menampilkan "apa yang sedang terjadi di Polymarket sekarang" membutuhkan umpan komentar dan aktivitas sosial. Menggabungkannya berarti entah terlalu merekayasa umpan sosial dengan persyaratan latensi tingkat perdagangan, atau kurang merekayasa umpan buku pesanan dengan asumsi keandalan tingkat sosial.
Pelajaran ini sederhana tetapi sering diabaikan: ketika konsumen real-time Anda memiliki toleransi latensi, volume data, dan mode kegagalan yang berbeda secara signifikan, berikan mereka infrastruktur terpisah. Endpoint WebSocket bersama yang mencoba melayani berbagai tujuan cenderung runtuh ke pembagi umum tertinggi untuk kompleksitas dan ke pembagi umum terendah untuk kinerja.
Apa Kesamaan Pola-Pola Ini
Desain API Polymarket mencerminkan filosofi tertentu: API harus membuat struktur domain yang sebenarnya terlihat, bukan mengabstraksikannya.
Arsitektur tiga lapis memetakan batas domain nyata. Akses yang mengutamakan publik mencerminkan cara kerja nilai pasar prediksi. Otentikasi dua tingkat mencerminkan perbedaan nyata antara membuktikan identitas dan mengotorisasi suatu tindakan. Pesanan sebagai pesan yang ditandatangani mengodekan jaminan non-penahanan. Hierarki Peristiwa/Pasar dan bendera NegRisk mengekspos hubungan yang jika tidak, tidak akan terlihat. Ukuran tick dinamis menjaga keadaan klien konsisten dengan keadaan pasar. Lapisan WebSocket terpisah melayani audiens yang berbeda.
Sebagian besar saran desain API berfokus pada ergonomi: membuatnya mudah dipanggil, konsisten dalam penamaan, dapat diprediksi dalam penanganan kesalahan. API Polymarket melakukan semua itu — tetapi pilihan yang lebih menarik adalah tentang kesetiaan pada domain. Ketika domain memiliki perbedaan yang berarti, API menampilkannya. Ketika domain memiliki batasan, API menegakkannya. Ketika domain memiliki keadaan yang berubah, API menyiarkannya.
Hasilnya adalah API yang menuntut lebih banyak dari konsumennya, tetapi API di mana melakukannya dengan benar berarti Anda benar-benar memahami sistem yang Anda perdagangkan. Itu bukan kebetulan — untuk pasar prediksi, di mana intinya adalah harga mencerminkan informasi, API yang memaksa Anda untuk memahami struktur pasar melakukan persis seperti yang seharusnya.