API 参考

管理 API 密钥 · 下载 OpenAPI 契约

认证与权限范围

通过 x-api-key 或 Bearer 请求头发送密钥。密钥应保存在服务器。门户需要钱包会话；密钥不能创建新密钥。无需密钥也可读取公开数据，但受 IP 速率限制。

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

data:read 用于读取数据；quotes:create 用于报价；plans:create 用于未签名计划及追踪密钥所属钱包的交易。仍需钱包签名。strategies:read 读取密钥所属钱包的自动化规则（GET /v1/strategies）；strategies:write 创建、修改、暂停、恢复和撤销规则（实盘执行仍需钱包签署的链上 keeper 授权）。webhooks:manage 管理 webhook 订阅（GET/POST /v1/developer/webhooks、DELETE /v1/developer/webhooks/{id}、GET …/deliveries）。API 密钥本身只能通过钱包会话管理。

非浏览器客户端的钱包登录

交易端点也接受钱包会话。创建挑战，使用 personal_sign 对未经修改的消息签名，再进行验证。响应包含有效期 7 天的会话令牌，用于 Authorization: Bearer（SDK 中为 sessionToken）。浏览器仅接收 HttpOnly cookie。登录签名不会授权任何交易。

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

@defi/api-client 工作区提供由 OpenAPI 生成的客户端，请在服务器上运行。

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);

分页与精度

资金池列表、代币列表和交易历史（GET /v1/transactions）使用 limit 1–200（默认 50）及 meta.nextCursor 中的游标。获取下一页时保留筛选与排序。代币数量与财务数值以字符串发送；不可用指标为 null。使用数据前请检查 meta.partial、dataStatus 与时间戳。

配额、错误与幂等性

费用：普通读取 1 单位，账户历史 / 余额 / 仓位 5，报价 / 计划 10，追踪 5。每日密钥配额由运营方设置，请查看 X-Quota-Limit 和 X-Quota-Remaining。HTTP 429 包含 Retry-After。IP 限制仍然适用。公开读取包含 ETag：数据未变时，发送 If-None-Match 可获得无响应体的 304。成功响应含 data/meta；错误含 code、message、retryable、details 和 requestId。

POST /v1/quotes 需要 8–128 字符的 Idempotency-Key；POST /v1/developer/api-keys 和 /webhooks 可选提供（重复相同请求数据会返回同一资源，replayed: true 且 secret 为 null）。相同数据使用相同密钥。客户端不会自动重试修改操作。计划不会签名或广播交易。

Webhook

端点须为 443 端口的公共 HTTPS。密钥仅显示一次。请求头：x-webhook-id、x-webhook-timestamp、x-webhook-signature。使用密钥对 timestamp + 点号 + 原始响应体校验 HMAC SHA-256，以恒定时间比较，拒绝超过 ±5 分钟的时间戳，并按事件 ID 去重。响应体：id、type、data、createdAt。

最多重试 8 次（退避+抖动），之后状态为 dead。2xx 响应表示已接收；不跟随重定向。可订阅事件：transaction.finalized、transaction.failed、公开的 data.degraded（每次网络 head 故障期间一次）、position.out_of_range、strategy.executed（模拟/通知，或实盘 keeper 已执行）以及 strategy.execution_failed（实盘 keeper 执行失败；规则被暂停）。交易事件由后台对账自动产生（交易最终确认/失败后约 30 秒），无需轮询；仓位/策略事件来自 automation worker 与 keeper。positionOutOfRange 偏好控制仓位事件；策略审计事件始终可用。

实时事件（SSE）

GET /v1/events/stream 以 text/event-stream 发送与 webhook 相同的事件（属于会话 / 密钥所有者，加上公开的 data.degraded）。每个事件带 id 游标；使用 Last-Event-ID（EventSource 自动处理）或 ?after= 重新连接。浏览器连接约 100 秒后关闭，API 密钥连接约 15 分钟后关闭。revoked 表示密钥已撤销 / 到期或会话结束。reset 表示游标超出保留期：获取新快照（例如 GET /v1/transactions）。浏览器应使用同源会话；切勿将 API 密钥放入 URL，使用 x-api-key（data:read，每连接 1 单位）。

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

用户数据（/v1/me）

仅限钱包会话（API 密钥返回 403）。GET/POST /v1/me/watchlist 和 DELETE /v1/me/watchlist/ {itemId} ：资金池（内部 ID）、代币（CAIP-19）或仅观察账户（CAIP-10），最多 200 项；添加已存在项目返回 200 和 created: false。GET/PUT /v1/me/settings：带版本校验的通知偏好（发送最新 version；不匹配 → 409）。GET /v1/me/portfolio：活跃网络中的会话钱包 + 最多 20 个仅观察账户；读取失败账户状态为 error 且 meta.partial 为 true，不视为零余额。DELETE /v1/me/data 删除关注列表与偏好设置（安全审计日志保留）。

纸上与通知策略

GET/POST /v1/strategies, GET/PATCH /v1/strategies/ {id} ，POST preview/pause/resume/revoke、GET executions。均为会话 / 密钥所有者私有。修改需 strategies:write（5 单位）；读取需 strategies:read（1 单位）。PATCH 与状态修改需最新 version；冲突返回 409。纸上模式记录触发条件，而非模拟交易；notify 模式仅用于 notify 类型。复投 / 再平衡 / 退出尚不执行资金操作。工作进程执行时间缓冲、冷却、UTC 每日限制与到期规则。撤销移除的是链下规则，而非链上授权额度。管理规则.

沙盒、变更日志与弃用

版本 1.4.0：纸上 / 通知策略、策略 API 权限、仓位 / 策略事件。版本 1.3.0：/v1/me 端点（关注列表、偏好、合并资产组合、删除数据）。版本 1.0.0 新增门户、密钥、配额、SDK 和 webhook。版本 1.2.0：完整的交易 / 报价 / 余额 / 状态架构（不再发送内部列）、交易历史分页、ETag、门户可选 Idempotency-Key、15 分钟 / 1 单位的 API 密钥 SSE。版本 1.1.0 在 OpenAPI 中新增钱包登录以及 GET /v1/tokens/ {tokenId} 在 SDK 中（CAIP-19 ID 进行 URL 编码）、SSE /v1/events/stream 以及自动交易事件。沙盒可运行本地数据库与基于固定数据的集成测试；API 不会伪造主网数据。注册表显示各部署的真实功能。破坏性变更使用新的主版本，并在禁用旧版本前公布迁移期。目前没有已弃用端点。