Cara Menggunakan Coinbase API: Panduan Langkah demi Langkah

Coinbase, pemimpin global dalam lanskap pertukaran aset digital, menawarkan rangkaian lengkap Application Programming Interfaces (API). API ini adalah tulang punggung bagi pengembang, trader algoritmik, dan institusi keuangan yang ingin berintegrasi dengan layanan perdagangan dan data Coinbase secara terprogram. Panduan ini memberikan eksplorasi teknis mendetail tentang Coinbase Exchange API, berfokus pada implementasi praktis, fungsionalitas inti, dan praktik terbaik operasional.

💡

Ingin alat Pengujian API hebat yang menghasilkan Dokumentasi API yang indah?

Ingin platform Terintegrasi, All-in-One untuk Tim Pengembang Anda agar bekerja sama dengan produktivitas maksimum?

Apidog memenuhi semua kebutuhan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!

tombol

Pengaturan Awal dan Autentikasi

Berinteraksi dengan Coinbase Exchange API secara berhasil dimulai dengan persiapan akun, manajemen kunci API yang aman, dan pemahaman yang tepat tentang protokol autentikasi.

Prasyarat Akun dan Pembuatan Kunci API

Diperlukan akun Coinbase yang terverifikasi, biasanya akun Coinbase Advanced Trade atau institusional. Kunci API dibuat di dalam pengaturan akun Anda. Proses ini menghasilkan tiga informasi penting:

Kunci API: String alfanumerik publik (misalnya, k7b9f2d7e8h1g3j4) yang mengidentifikasi aplikasi Anda.
Rahasia API: String alfanumerik pribadi (misalnya, S9vP3rK2sLqR7xW1yZ0aB5cD6fE8gH9i). Rahasia ini hanya ditampilkan sekali saat pembuatan dan harus disimpan dengan aman.
Passphrase: Kredensial keamanan tambahan (misalnya, mySecureP@$$phr@se2024!) yang Anda buat selama pembuatan kunci.

Izin kunci API bersifat granular, memungkinkan Anda membatasi tindakan (misalnya, hanya melihat, eksekusi perdagangan, kemampuan penarikan). Selalu patuhi prinsip hak istimewa paling sedikit.

Autentikasi Permintaan API

Coinbase Exchange API menggunakan mekanisme autentikasi berbasis tanda tangan (HMAC-SHA256) untuk semua endpoint pribadi yang diautentikasi. Setiap permintaan memerlukan beberapa header HTTP kustom:

CB-ACCESS-KEY: Kunci API Anda.
CB-ACCESS-SIGN: Tanda tangan HMAC-SHA256 yang dikodekan base64.
CB-ACCESS-TIMESTAMP: Stempel waktu epoch Unix saat ini (detik).
CB-ACCESS-PASSPHRASE: Passphrase Kunci API Anda.

Tanda tangan (CB-ACCESS-SIGN) dibuat dengan membuat hash HMAC-SHA256 dari string prehash. String prehash adalah penggabungan dari:

Stempel waktu (sebagai string).
Metode HTTP dalam huruf besar (misalnya, GET, POST).
Jalur permintaan (misalnya, /orders, /products/BTC-USD/book).
Isi permintaan (untuk permintaan POST; string kosong jika tidak ada isi).

Contoh konstruksi string prehash (untuk permintaan POST):

timestamp = str(time.time())
method = "POST"
request_path = "/orders"
body_json_string = '{"product_id": "BTC-USD", "side": "buy", "type": "limit", "price": "50000.00", "size": "0.1"}' // JSON string, not Python dict
prehash_string = timestamp + method + request_path + body_json_string

// The API Secret needs to be base64-decoded before being used as the HMAC key.
// secret_decoded = base64.b64decode(api_secret)
// signature = hmac.new(secret_decoded, prehash_string.encode('utf-8'), hashlib.sha256).digest()
// CB_ACCESS_SIGN = base64.b64encode(signature)

Konstruksi string prehash yang salah atau perbedaan stempel waktu (pastikan jam server Anda disinkronkan melalui NTP) adalah sumber umum kesalahan autentikasi (HTTP 401).

Pustaka Klien dan Lingkungan Pengembangan

Pustaka klien resmi dan yang dikembangkan komunitas untuk bahasa seperti Python (cbpro), Node.js (coinbase-pro-node), Java, dan Go mengabstraksi kompleksitas autentikasi ini. Alternatifnya, permintaan HTTP langsung dapat dibuat menggunakan alat seperti curl atau modul klien HTTP standar, yang memerlukan implementasi manual proses penandatanganan.

Lingkungan Sandbox untuk Pengujian

Coinbase menyediakan lingkungan Sandbox untuk pengembangan dan pengujian, sangat penting sebelum berinteraksi dengan pasar live.

Tujuan dan Fungsionalitas

Sandbox mencerminkan fungsionalitas API produksi tetapi menggunakan dana uji dan data pasar simulasi. Ini memungkinkan:

Pengujian algoritma perdagangan tanpa risiko.
Verifikasi logika integrasi API dan penanganan kesalahan.
Mengenal struktur permintaan/respons API.

Perbedaan Utama dari Produksi

Endpoint API: Sandbox menggunakan URL dasar yang berbeda.
Produksi: https://api.exchange.coinbase.com
Sandbox: https://api-public.sandbox.exchange.coinbase.com (Catatan: URL Sandbox yang tepat harus selalu dikonfirmasi dari dokumentasi resmi).
Kunci API: Kunci API terpisah harus dibuat untuk dan digunakan secara eksklusif dengan Sandbox.
Data Pasar & Likuiditas: Kedalaman order book, volume perdagangan, dan pergerakan harga disimulasikan. Simulasi pengisian order mungkin lebih sederhana dan mungkin tidak sepenuhnya mencerminkan selip atau skenario pengisian sebagian di dunia nyata.
Tidak Ada Dana Nyata: Semua aset dan perdagangan bersifat virtual. Saldo uji biasanya disediakan atau dapat diatur ulang.

Transisi ke Produksi

Strategi penerapan yang kuat mencakup konfigurasi yang berbeda untuk Sandbox dan Produksi, terutama berbeda dalam kredensial API dan URL dasar. Pengujian menyeluruh di Sandbox sangat penting untuk mencegah kesalahan dengan dana nyata.

Fungsionalitas Inti API: Endpoint dan Struktur Data

API secara luas dikategorikan menjadi manajemen akun, pengambilan data pasar, dan operasi perdagangan.

Manajemen Akun

Endpoint untuk menanyakan status dan riwayat akun.

Mengambil Saldo Akun (GET /accounts)
Mengambil daftar semua akun pengguna (fiat dan kripto) beserta saldonya.
Cuplikan Contoh Respons untuk akun BTC:

{
  "id": "7532b1f0-20f4-4ba7-96f0-303b592d130f",
  "currency": "BTC",
  "balance": "0.50123456",
  "available": "0.49123456",
  "hold": "0.01000000",
  "profile_id": "your-profile-id-string"
}

balance adalah jumlah total, available adalah apa yang dapat digunakan untuk perdagangan, dan hold adalah dana yang dicadangkan untuk order terbuka.

Riwayat Akun / Ledger (GET /accounts/{account_id}/ledger)
Menyediakan daftar transaksi berhalaman (perdagangan, biaya, transfer) untuk akun tertentu.
Parameter Kueri Umum: before (kursor untuk penomoran halaman), after (kursor), limit (maks 100, default 100), start_date, end_date.
Cuplikan Contoh Entri Ledger:

{
  "id": "1001874",
  "created_at": "2023-10-26T10:00:00.000Z",
  "amount": "-0.00005000",
  "balance": "0.50118456",
  "type": "fee",
  "details": {
    "order_id": "d0c5340b-6d6c-49d9-b567-48c4bfca13d2",
    "product_id": "BTC-USD",
    "trade_id": "7423736"
  }
}

Endpoint Data Pasar

Akses ke informasi pasar real-time dan historis.

Produk / Pasangan Perdagangan (GET /products)
Mencantumkan semua pasangan perdagangan yang tersedia dan propertinya.
Cuplikan Contoh Produk (BTC-USD):

{
  "id": "BTC-USD",
  "base_currency": "BTC",
  "quote_currency": "USD",
  "base_min_size": "0.0001", // Minimum order size in base currency
  "base_max_size": "200.0",  // Maximum order size in base currency
  "quote_increment": "0.01", // Smallest price change unit for quote currency
  "base_increment": "0.00000001", // Smallest size change unit for base currency
  "display_name": "BTC/USD",
  "min_market_funds": "1",    // Minimum funds for a market order in quote currency
  "max_market_funds": "1000000", // Maximum funds for a market order
  "status": "online",
  "status_message": "",
  "cancel_only": false,
  "limit_only": false,
  "post_only": false,
  "trading_disabled": false
}

Order Book (GET /products/{product_id}/book)
Mengambil order book saat ini untuk suatu produk.
Parameter Kueri: level (1, 2, atau 3).
* Level 1: Hanya bid dan ask terbaik.
* Level 2: Daftar bid dan ask yang dikumpulkan di setiap level harga. (Maks 50 entri per sisi).
* Level 3: Order book lengkap dengan order individual yang tidak dikumpulkan (memerlukan autentikasi dan mungkin memiliki batasan laju yang lebih ketat).
Cuplikan Contoh Order Book Level 2 (BTC-USD):

{
  "sequence": 1234567890,
  "bids": [
    ["49999.99", "0.75", 3], // [price, size, num-orders-at-this-price]
    ["49999.98", "1.20", 5]
  ],
  "asks": [
    ["50000.01", "0.50", 2],
    ["50000.02", "1.00", 4]
  ],
  "time": "2023-10-26T10:05:00.123Z"
}

Ticker Produk (GET /products/{product_id}/ticker)
Informasi snapshot tentang perdagangan terakhir (tick), bid/ask terbaik, dan volume 24 jam.
Cuplikan Contoh Ticker (BTC-USD):

{
  "trade_id": 7423739,
  "price": "50001.50", // Last trade price
  "size": "0.005",    // Last trade size
  "bid": "50001.49",
  "ask": "50001.51",
  "volume": "1250.75", // 24-hour trading volume in base currency
  "time": "2023-10-26T10:06:15.234Z"
}

Harga Historis / Lilin (GET /products/{product_id}/candles)
Mengambil data harga historis (OHLCV).
Parameter Kueri: start (stempel waktu ISO 8601), end (ISO 8601), granularity (dalam detik: 60, 300, 900, 3600, 21600, 86400). Maks 300 lilin per permintaan.
Contoh Data Lilin (granularitas 1 jam):

[
  // [time, low, high, open, close, volume]
  [1666771200, 49850.25, 50050.75, 49900.00, 50025.10, 15.2345], // time is Unix epoch
  [1666767600, 49700.00, 49950.50, 49750.20, 49850.25, 22.6789]
]

Operasi Perdagangan

Endpoint untuk menempatkan, mengelola, dan menanyakan order.

Menempatkan Order (POST /orders)
Mengirimkan order baru ke mesin pencocokan.
Parameter Isi Permintaan Umum:

{
  "client_oid": "my-unique-client-order-id-001", // Optional: UUID for idempotency
  "product_id": "BTC-USD",
  "side": "buy", // "buy" or "sell"
  "type": "limit", // "limit", "market", or "stop" (stop orders are more complex)
  "price": "49500.00", // Required for limit orders
  "size": "0.0125", // Amount of base currency to buy/sell
  // "funds": "500.00", // For market buy orders: amount of quote currency to spend
  "time_in_force": "GTC", // GTC (Good 'Til Canceled), GTT (Good 'Til Time), IOC (Immediate Or Cancel), FOK (Fill Or Kill)
  // "cancel_after": "min" / "hour" / "day" (used with GTT)
  "post_only": false, // If true, order is rejected if it would immediately match (ensures maker)
  "stp": "dc" // Self-trade prevention: "dc" (Decrease and Cancel), "co" (Cancel Oldest), "cn" (Cancel Newest), "cb" (Cancel Both)
}

Penempatan order yang berhasil mengembalikan detail order termasuk id yang ditetapkan server.

Mengelola Order

Mendapatkan Status Order (GET /orders/{order_id_or_client_oid}): Mengambil satu order berdasarkan ID servernya atau client_oid Anda (beri awalan client: untuk client_oid, misalnya, GET /orders/client:my-unique-client-order-id-001).
Mencantumkan Order Terbuka (GET /orders): Mengembalikan daftar berhalaman order aktif Anda. Parameter seperti status (open, pending, active) dan product_id dapat digunakan untuk penyaringan.
Membatalkan Order (DELETE /orders/{order_id_or_client_oid}): Membatalkan order terbuka tertentu. Mengembalikan ID order setelah permintaan pembatalan berhasil.
Membatalkan Semua Order (DELETE /orders): Membatalkan semua order terbuka, secara opsional untuk product_id tertentu.

Pengisian (Fills) (GET /fills)
Mengambil daftar berhalaman perdagangan yang telah dieksekusi (pengisian).
Parameter Kueri: order_id, product_id, before, after, limit.
Cuplikan Contoh Pengisian:

{
  "trade_id": 7423800,
  "product_id": "BTC-USD",
  "price": "49500.00",
  "size": "0.00500000",
  "order_id": "e4f2c1a0-f3d8-4b9b-8b7e-1f2a3c4d5e6f",
  "created_at": "2023-10-26T10:15:30.123Z",
  "liquidity": "T", // "M" for Maker, "T" for Taker
  "fee": "0.00000250", // Fee in quote currency (USD for BTC-USD) or base currency depending on API.
  "settled": true,
  "side": "buy"
}

Mesin Pencocokan

Mesin pencocokan memasangkan order beli dan jual berdasarkan algoritma Prioritas Harga-Waktu:

Prioritas Harga: Order dengan harga yang lebih menguntungkan diprioritaskan (harga lebih tinggi untuk bid, harga lebih rendah untuk ask).
Prioritas Waktu: Di antara order dengan harga yang sama, order yang paling awal diajukan diprioritaskan.

Order Maker vs. Taker:
Maker: Order yang menambahkan likuiditas ke order book (misalnya, order limit yang tidak langsung terisi). Biasanya mendapat manfaat dari biaya perdagangan yang lebih rendah (misalnya, 0,00% - 0,40%). Flag post_only membantu memastikan order adalah maker.
Taker: Order yang menghilangkan likuiditas (misalnya, order pasar, atau order limit yang langsung terisi). Menimbulkan biaya yang sedikit lebih tinggi (misalnya, 0,05% - 0,60%). Tingkat biaya seringkali didasarkan pada volume 30 hari sebelumnya.

Memahami logika ini sangat penting untuk strategi penempatan order, mengelola selip, dan optimasi biaya.

Batasan Laju dan Throttling

Akses API tunduk pada batasan laju untuk memastikan stabilitas platform dan penggunaan yang adil.

Jenis dan Identifikasi

Batasan biasanya diterapkan per kunci API, per alamat IP, dan dapat bervariasi per endpoint (misalnya, endpoint pribadi yang ditandatangani vs. endpoint publik yang tidak ditandatangani). Endpoint publik mungkin memiliki batasan seperti 3-10 permintaan/detik per IP. Endpoint pribadi (yang ditandatangani) seringkali memiliki batasan yang lebih tinggi, juga per kunci API.

Respons API mencakup header yang menunjukkan status batasan laju saat ini:

CB-RATELIMIT-LIMIT: Batas total permintaan untuk jendela saat ini.
CB-RATELIMIT-REMAINING: Sisa permintaan dalam jendela.
CB-RATELIMIT-RESET: Stempel waktu Unix kapan jendela batasan diatur ulang.

Melebihi batasan akan menghasilkan kesalahan HTTP 429 Too Many Requests.

Strategi Penanganan

Pemantauan Proaktif: Periksa CB-RATELIMIT-REMAINING sebelum membuat permintaan.
Penggunaan API yang Efisien:

Ambil hanya data yang diperlukan.
Gunakan feed WebSocket untuk data real-time alih-alih melakukan polling endpoint REST.
Cache data statis atau yang jarang berubah (misalnya, detail produk dari /products).

Backoff Eksponensial: Setelah menerima kesalahan 429, tunggu sebelum mencoba lagi. Implementasikan backoff eksponensial (misalnya, tunggu 1 detik, lalu 2 detik, 4 detik, 8 detik, dll., dengan jitter) untuk menghindari membebani server.
WebSockets untuk Data Real-Time: Untuk pembaruan order book, perdagangan langsung, dan ticker, koneksi WebSocket jauh lebih efisien daripada polling REST.

Keunggulan Operasional: Prinsip Runbook

Praktik operasional yang kuat sangat penting untuk integrasi API perdagangan apa pun.

Pemantauan dan Peringatan

Konektivitas & Latensi API: Pantau waktu ping dan tingkat keberhasilan ke endpoint API.
Konsumsi Batasan Laju: Lacak CB-RATELIMIT-REMAINING dan beri peringatan saat mendekati nol.
Eksekusi Order: Beri peringatan pada penempatan order yang gagal, order yang macet dalam status pending melebihi durasi yang diharapkan, atau perbedaan pengisian yang signifikan.
Perbedaan Saldo: Pantau saldo akun utama untuk penyimpangan yang tidak terduga.
Tingkat Kesalahan: Lacak persentase kesalahan HTTP 4xx dan 5xx; selidiki lonjakan. Alat seperti Prometheus/Grafana atau Datadog umum digunakan.
Status Sistem Coinbase: Berlangganan atau periksa secara berkala halaman status resmi Coinbase (misalnya, status.coinbase.com) untuk insiden atau pemeliharaan di seluruh platform.

Pencatatan (Logging)

Catat informasi penting untuk debugging dan audit:

Stempel waktu (UTC).
Permintaan: metode, jalur, header (kunci API disunting), isi (data sensitif disunting).
Respons: kode status, header (terutama batasan laju dan ID permintaan seperti CB-TRACE-ID), isi.
ID Korelasi: Jika sistem Anda menggunakannya, atau gunakan CB-TRACE-ID dari header respons.

Praktik Terbaik Keamanan

Keamanan Kunci API: Simpan kunci di brankas aman (misalnya, HashiCorp Vault, AWS Secrets Manager) atau variabel lingkungan. Jangan pernah menuliskannya secara langsung (hardcode) atau melakukan commit ke kontrol versi.
Daftar Putih IP (IP Whitelisting): Jika tersedia, batasi akses kunci API ke alamat IP tertentu.
Prinsip Hak Istimewa Paling Sedikit: Berikan kunci API hanya izin yang benar-benar mereka butuhkan.
Audit Reguler: Tinjau penggunaan dan izin kunci API secara berkala.
Versi API: Perhatikan perubahan versi API (misalnya, /v2/products, /v3/products). Pantau pengumuman pengembang untuk jadwal penghentian dan jalur migrasi.

Topik dan Teknik Lanjutan

Feed WebSocket untuk Data Real-Time

Coinbase Exchange menyediakan feed WebSocket untuk data real-time dengan latensi rendah.

Endpoint: Biasanya satu URL WebSocket (misalnya, wss://ws-feed.exchange.coinbase.com).
Langganan: Setelah terhubung, kirim pesan JSON untuk berlangganan ke saluran dan ID produk.
Contoh Pesan Langganan:

{
    "type": "subscribe",
    "product_ids": ["ETH-USD", "BTC-USD"],
    "channels": [
        "level2", // Untuk pembaruan order book Level 2
        "heartbeat", // Untuk menjaga koneksi tetap hidup dan memantau status
        {
            "name": "ticker", // Saluran ticker untuk produk tertentu
            "product_ids": ["ETH-USD", "BTC-USD"]
        },
        "status" // Untuk pembaruan status perdagangan produk
    ],
    // Untuk pembaruan spesifik pengguna (order, saldo), autentikasi diperlukan dalam handshake WebSocket atau pesan awal.
    // "signature": "...", "key": "...", "passphrase": "...", "timestamp": "..." (jika auth diperlukan untuk saluran tertentu)
}

Jenis Pesan:

heartbeat: Pesan berkala untuk mengonfirmasi kesehatan koneksi dan menyediakan status produk saat ini.
snapshot: Status awal data yang dilanggan (misalnya, snapshot order book lengkap untuk level2).
l2update: Perubahan inkremental pada order book Level 2 (bid/ask ditambahkan, diubah, atau dihapus).
ticker: Pembaruan harga, volume, dan bid/ask real-time.
matches (atau trade): Perdagangan yang dieksekusi real-time untuk produk yang dilanggan.
error: Menunjukkan masalah dengan langganan atau koneksi.
Mengelola koneksi WebSocket melibatkan penanganan logika penyambungan kembali, pengurutan pesan (jika berlaku, melalui nomor urut dalam pesan), dan pemeliharaan status lokal (misalnya, merekonstruksi order book dari pesan snapshot dan l2update).

Idempotensi dan `client_oid`

Untuk mencegah pengiriman order ganda karena masalah jaringan atau percobaan ulang, permintaan POST /orders dapat menyertakan bidang client_oid. Ini harus berupa pengenal unik (misalnya, UUID v4) yang dihasilkan oleh klien Anda.

Jika order dengan client_oid tertentu diterima dan diproses, permintaan identik berikutnya dengan client_oid yang sama dalam jangka waktu tertentu (misalnya, 24 jam) tidak akan membuat order baru tetapi akan mengembalikan status order asli.
Ini memastikan bahwa mencoba kembali permintaan "tempatkan order" aman.

Pencegahan Perdagangan Sendiri (STP)

Parameter stp dalam penempatan order (POST /orders) membantu mencegah order suatu akun saling cocok. Opsi biasanya meliputi:

dc (Kurangi dan Batalkan): Order agresif (taker) dibatalkan, dan ukuran order diam (maker) dikurangi sebesar ukuran order agresif.
co (Batalkan Terlama): Order yang lebih lama dibatalkan.
cn (Batalkan Terbaru): Order yang lebih baru (agresif) dibatalkan.
cb (Batalkan Keduanya): Kedua order dibatalkan.

Kesimpulan

Coinbase Exchange API menyediakan toolkit komprehensif bagi pengembang untuk membangun aplikasi dan integrasi perdagangan yang canggih. Menguasai autentikasinya, memahami struktur datanya, menghormati batasan laju, dan menerapkan praktik operasional yang kuat adalah kunci untuk memanfaatkan potensi penuhnya. Pergeseran ke feed WebSocket untuk data real-time dan fitur seperti client_oid untuk idempotensi semakin memberdayakan pengembang untuk menciptakan sistem yang tangguh dan efisien dalam dunia perdagangan mata uang kripto yang bergerak cepat. Perhatian terus-menerus pada dokumentasi pengembang resmi Coinbase sangat penting untuk tetap mendapatkan informasi terbaru tentang fitur baru, perubahan endpoint, dan praktik terbaik.