Referensi API

Kelola API key · Unduh kontrak OpenAPI

Autentikasi dan scope

Kirim key melalui header x-api-key atau Bearer. Simpan key di server. Portal memerlukan sesi wallet; key tidak dapat membuat key baru. Pembacaan publik juga tersedia tanpa key, dengan rate limit IP.

curl "$API_BASE_URL/v1/chains" -H "x-api-key: $DEFI_API_KEY"

data:read untuk data; quotes:create untuk quote; plans:create untuk rencana unsigned dan tracking transaksi milik wallet pemilik key. Signature wallet tetap diperlukan. strategies:read membaca aturan otomatisasi milik wallet pemilik key (GET /v1/strategies); strategies:write membuat, mengubah, menjeda, melanjutkan, dan mencabut aturan (eksekusi live tetap butuh izin keeper on-chain yang ditandatangani wallet). webhooks:manage mengelola subscription webhook (GET/POST /v1/developer/webhooks, DELETE /v1/developer/webhooks/{id}, GET …/deliveries). Pengelolaan API key tetap hanya lewat sesi wallet.

Login wallet untuk klien non-browser

Endpoint transaksi juga menerima sesi wallet. Buat challenge, tandatangani pesannya apa adanya dengan personal_sign, lalu verifikasi. Respons berisi token sesi 7 hari untuk header Authorization: Bearer (opsi sessionToken di SDK). Browser menerima cookie HttpOnly saja. Tanda tangan login tidak memberi izin transaksi apa pun.

POST /v1/auth/challenges  {"address":"0x…","chainId":8453}   → {id, message, expiresAt}
POST /v1/auth/verify      {"challengeId":"…","signature":"0x…"} → {token, actor, expiresAt}
GET  /v1/auth/session     (Authorization: Bearer <token>)      → {actor}
DELETE /v1/auth/session   → logout

SDK TypeScript

Workspace @defi/api-client menyediakan client yang dibuat dari OpenAPI. Jalankan di server.

import { createDefiClient } from '@defi/api-client';
const client = createDefiClient({
  baseUrl: process.env.API_BASE_URL!,
  apiKey: process.env.DEFI_API_KEY!,
});
const { data, error, response } = await client.GET('/v1/pools', {
  params: { query: { chain: 'base', limit: 50 } },
});
if (!response.ok) throw new Error(JSON.stringify(error));
console.log(data?.data, data?.meta.nextCursor);

Pagination dan presisi

Daftar pool, token, dan riwayat transaksi (GET /v1/transactions) memakai limit 1–200 (default 50) dan cursor dari meta.nextCursor. Pertahankan filter dan sort saat mengambil halaman berikutnya. Nominal token dan nilai keuangan dikirim sebagai string; metrik yang tidak tersedia bernilai null. Periksa meta.partial, dataStatus, dan timestamp sebelum menggunakan data.

Kuota, error, dan idempotency

Biaya: baca biasa 1 unit, histori/saldo/posisi akun 5, quote/plan 10, tracking 5. Kuota harian per key ditentukan operator; lihat X-Quota-Limit dan X-Quota-Remaining. HTTP 429 menyertakan Retry-After. Batas IP tetap berlaku. Baca publik membawa ETag: kirim If-None-Match untuk mendapat 304 tanpa body bila data tidak berubah. Response sukses berbentuk data/meta; error memuat code, message, retryable, details, dan requestId.

POST /v1/quotes memerlukan Idempotency-Key 8–128 karakter; POST /v1/developer/api-keys dan /webhooks menerimanya secara opsional (ulangan payload sama mengembalikan resource yang sama dengan replayed: true dan secret null). Gunakan key yang sama untuk payload yang sama. Client tidak mengulangi mutasi otomatis. Plan tidak menandatangani atau menyiarkan transaksi.

Webhook

Endpoint wajib HTTPS publik port 443. Secret ditampilkan sekali. Header: x-webhook-id, x-webhook-timestamp, x-webhook-signature. Verifikasi HMAC SHA-256 atas timestamp + titik + raw body dengan secret, bandingkan secara constant-time, tolak timestamp di luar ±5 menit, dan deduplikasi event ID. Body: id, type, data, createdAt.

Retry maksimal 8 attempt dengan backoff/jitter; setelahnya status dead. Respons 2xx menandakan diterima; redirect tidak diikuti. Event yang dapat dilanggan: transaction.finalized, transaction.failed, data.degraded publik (sekali per episode gangguan head jaringan), position.out_of_range, strategy.executed (paper/notified, atau executed oleh keeper live) dan strategy.execution_failed (eksekusi keeper live gagal; aturan dijeda). Event transaksi diproduksi otomatis oleh reconcile latar belakang (±30 detik setelah transaksi final/gagal), tanpa perlu polling; event posisi/strategi dari worker automation dan keeper. Preferensi positionOutOfRange mengendalikan event posisi; event audit strategi tetap tersedia.

Realtime (SSE)

GET /v1/events/stream mengalirkan event yang sama dengan webhook (milik pemilik sesi/key, plus data.degraded publik) sebagai text/event-stream. Setiap event membawa id sebagai cursor; sambung ulang dengan header Last-Event-ID (EventSource melakukannya otomatis) atau ?after=. Server menutup koneksi sekitar 100 detik untuk browser dan 15 menit untuk API key. Event revoked berarti key dicabut/kedaluwarsa atau sesi berakhir. Event reset berarti cursor sudah lewat retensi: ambil snapshot baru (mis. GET /v1/transactions). Di browser gunakan sesi same-origin; jangan menaruh API key di URL — kirim lewat header x-api-key (scope data:read, 1 unit per koneksi).

const es = new EventSource('/api/v1/events/stream');
es.addEventListener('transaction.finalized', (e) => console.log(e.lastEventId, JSON.parse(e.data)));
es.addEventListener('reset', () => { /* sinkron ulang */ });

Data pengguna (/v1/me)

Hanya sesi wallet (API key ditolak 403). GET/POST /v1/me/watchlist dan DELETE /v1/me/watchlist/ {itemId} : pool (ID internal), token (CAIP-19) atau akun watch-only (CAIP-10), maks. 200 item; menambah item yang sudah ada mengembalikan 200 dengan created: false. GET/PUT /v1/me/settings: preferensi notifikasi dengan version guard (kirim version terakhir; berbeda → 409). GET /v1/me/portfolio: wallet sesi di jaringan aktif + maks. 20 akun watch-only; akun yang gagal dibaca berstatus error dan meta.partial true, tidak dihitung nol. DELETE /v1/me/data menghapus watchlist dan preferensi (audit log keamanan tetap).

Strategi paper dan pemberitahuan

GET/POST /v1/strategies, GET/PATCH /v1/strategies/ {id} , POST preview/pause/resume/revoke, GET executions. Semua privat untuk pemilik sesi/key. Mutasi membutuhkan strategies:write (5 unit); pembacaan strategies:read (1 unit). PATCH dan perubahan status membutuhkan version terbaru; konflik 409. Mode paper mencatat pemicu, bukan simulasi trade; mode notify hanya untuk type notify. Compound/rebalance/exit belum mengeksekusi dana. Worker menerapkan time buffer, cooldown, batas harian UTC dan expiry. Revoke mencabut aturan off-chain, bukan allowance on-chain.Kelola aturan.

Sandbox, changelog, dan deprecation

Versi 1.4.0: strategi paper/pemberitahuan, API scope strategi, event posisi/strategi. Versi 1.3.0: endpoint /v1/me (watchlist, preferensi, portofolio gabungan, hapus data). Versi 1.0.0 menambahkan portal, key, kuota, SDK, dan webhook. Versi 1.2.0: schema respons transaksi/quote/saldo/status lengkap (kolom internal tidak lagi dikirim), pagination riwayat transaksi, ETag, Idempotency-Key opsional di portal, SSE API key 15 menit/1 unit. Versi 1.1.0 menambahkan login wallet di kontrak OpenAPI, GET /v1/tokens/ {tokenId} di SDK (ID CAIP-19 di-URL-encode), SSE /v1/events/stream, dan event transaksi otomatis. Untuk sandbox, jalankan database lokal serta integration test berbasis fixture; API tidak mengarang data mainnet. Registry menunjukkan capability nyata setiap deployment. Breaking change memakai versi major baru dan pengumuman periode migrasi sebelum versi lama dinonaktifkan. Belum ada endpoint deprecated.