API reference

Manage API keys · Download the OpenAPI contract

Authentication & scopes

Send the key through x-api-key or Bearer headers. Store keys on the server. The portal requires a wallet session; keys cannot create new keys. Public reads are also available without a key, subject to IP rate limits.

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

data:read for data; quotes:create for quotes; plans:create for unsigned plans and tracking transactions of the key owner's wallet. A wallet signature is still required. strategies:read reads the automation rules of the key owner's wallet (GET /v1/strategies); strategies:write creates, edits, pauses, resumes and revokes rules (live execution still needs the on-chain keeper permission signed by the wallet). webhooks:manage manages webhook subscriptions (GET/POST /v1/developer/webhooks, DELETE /v1/developer/webhooks/{id}, GET …/deliveries). API keys themselves can only be managed through a wallet session.

Wallet sign-in for non-browser clients

Transaction endpoints also accept wallet sessions. Create a challenge, sign its unmodified message with personal_sign, and verify it. The response contains a 7-day session token for Authorization: Bearer (sessionToken in the SDK). Browsers receive only an HttpOnly cookie. Signing in does not authorize any transactions.

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

TypeScript SDK

The @defi/api-client workspace provides an OpenAPI-generated client. Run it on the 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 & precision

Pool lists, token lists, and transaction history (GET /v1/transactions) use limit 1–200 (default 50) and the cursor from meta.nextCursor. Keep filters and sorting when fetching the next page. Token amounts and financial values are strings; unavailable metrics are null. Check meta.partial, dataStatus, and timestamps before using data.

Quotas, errors, and idempotency

Costs: standard reads 1 unit, account history/balances/positions 5, quotes/plans 10, tracking 5. Daily key quotas are set by the operator; see X-Quota-Limit and X-Quota-Remaining. HTTP 429 includes Retry-After. IP limits still apply. Public reads include ETag: send If-None-Match for a bodyless 304 when data is unchanged. Success responses contain data/meta; errors contain code, message, retryable, details, and requestId.

POST /v1/quotes requires an 8–128 character Idempotency-Key; POST /v1/developer/api-keys and /webhooks accept it optionally (repeating the same payload returns the same resource with replayed: true and secret null). Use the same key for the same payload. The client does not automatically retry mutations. Plans do not sign or broadcast transactions.

Webhook

Endpoints require public HTTPS on port 443. Secrets are shown once. Headers: x-webhook-id, x-webhook-timestamp, x-webhook-signature. Verify HMAC SHA-256 over timestamp + dot + raw body using the secret; compare in constant time, reject timestamps outside ±5 minutes, and deduplicate event IDs. Body: id, type, data, createdAt.

Up to 8 attempts with backoff/jitter; after that the status is dead. A 2xx response means received; redirects are not followed. Subscribable events: transaction.finalized, transaction.failed, public data.degraded (once per network head outage episode), position.out_of_range, strategy.executed (paper/notified, or executed by the live keeper) and strategy.execution_failed (live keeper execution failed; the rule is paused). Transaction events are produced automatically by background reconciliation (about 30 seconds after a transaction is final/failed), no polling needed; position/strategy events come from the automation worker and the keeper. The positionOutOfRange preference controls position events; strategy audit events stay available.

Realtime (SSE)

GET /v1/events/stream streams the same events as webhooks (owned by the session/key owner, plus public data.degraded) as text/event-stream. Each event carries an id cursor; reconnect with Last-Event-ID (automatic with EventSource) or ?after=. Connections close after about 100 seconds for browsers or 15 minutes for API keys. revoked means the key was revoked/expired or the session ended. reset means the cursor is outside retention: fetch a new snapshot (e.g. GET /v1/transactions). Browsers should use same-origin sessions; never put API keys in URLs — use x-api-key (data:read, 1 unit per connection).

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 */ });

User data (/v1/me)

Wallet sessions only (API keys receive 403). GET/POST /v1/me/watchlist and DELETE /v1/me/watchlist/ {itemId} : pool (internal ID), token (CAIP-19), or watch-only account (CAIP-10), up to 200 items; adding an existing item returns 200 with created: false. GET/PUT /v1/me/settings: version-guarded notification preferences (send the latest version; mismatch → 409). GET /v1/me/portfolio: session wallet on active networks + up to 20 watch-only accounts; unreadable accounts have error status and meta.partial true, not zero balances. DELETE /v1/me/data removes watchlists and preferences (security audit logs remain).

Paper and notification strategies

GET/POST /v1/strategies, GET/PATCH /v1/strategies/ {id} , POST preview/pause/resume/revoke, GET executions. All are private to the session/key owner. Mutations require strategies:write (5 units); reads require strategies:read (1 unit). PATCH and status changes require the latest version; conflicts return 409. Paper mode records triggers, not trade simulations; notify mode is only for notify type. Compound/rebalance/exit do not execute funds yet. The worker enforces time buffers, cooldowns, UTC daily limits, and expiry. Revoke removes the off-chain rule, not on-chain allowances.Manage rules.

Sandbox, changelog, and deprecation

Version 1.4.0: paper/notification strategies, strategy API scopes, position/strategy events. Version 1.3.0: /v1/me endpoints (watchlists, preferences, combined portfolio, data deletion). Version 1.0.0 added the portal, keys, quotas, SDK, and webhooks. Version 1.2.0: complete transaction/quote/balance/status schemas (internal columns no longer sent), transaction history pagination, ETag, optional portal Idempotency-Key, 15-minute/1-unit API-key SSE. Version 1.1.0 added wallet sign-in to OpenAPI and GET /v1/tokens/ {tokenId} in the SDK (URL-encoded CAIP-19 IDs), SSE /v1/events/stream, and automatic transaction events. For a sandbox, run a local database and fixture-based integration tests; the API does not invent mainnet data. The registry shows actual deployment capabilities. Breaking changes use a new major version and an announced migration period before the old version is disabled. No endpoints are deprecated yet.