External API 使用文档

概览

External API 用于读取钱包发现、画像、综合分析、持仓、成交、订单、PnL、风险、 行为时间序列和当前 key 的用量信息。所有业务数据来自已生成的 facts/read model， 不会在请求路径中触发数据生产。

• 覆盖核心钱包分析数据 围绕钱包维度提供 discovery、context、detail、analysis、positions、fills、orders、PnL、risk 和 activity 数据。
• 统一的只读 RESTful 访问模式 接口使用一致的路径结构、Bearer API key、分页参数、字段投影和错误响应，便于服务端与数据系统集成。
• 面向研究、看板和外部 Agent 适合构建钱包筛选、交易复盘、风险监控、自动化研究流程和工具调用层。
• 清晰的数据生产边界 API 只读取 data-plane 已生成的 facts/read models，不暴露写入、ingest、刷新任务或内部 Agent 私有 payload。

快速开始

1. 1 打开订阅服务 在 Onmine 左侧栏进入 订阅服务 > API 密钥。
2. 2 创建 API key 填写 label 创建 API key。创建成功后，完整 key 会显示在当前页面。
3. 3 保存 key 复制完整 key。后续列表页只展示 key prefix，不会展示完整 key。
4. 4 调用 health 接口 使用下面的 curl 验证鉴权与服务状态。

复制示例curl http://127.0.0.1:8010/v1/health \
  -H "Authorization: Bearer $EXTERNAL_API_KEY"

获取 API key

API key 通过 Onmine 前端创建。当前入口在 订阅服务 > API 密钥，创建、撤销和列表查看都在同一个页面完成。

鉴权

每个请求都需要携带 API key。支持 Authorization: Bearer 和 X-API-Key 两种方式。

复制示例curl http://127.0.0.1:8010/v1/health \
  -H "Authorization: Bearer sa_xxx"

复制示例curl http://127.0.0.1:8010/v1/usage \
  -H "X-API-Key: sa_xxx"

明文 key 只在创建后展示。请避免在日志、截图、文档或公开渠道中暴露完整 key。

接口速览

当前 `/v1` 共 72 个 endpoint，全部需要 API key。`/health` 和 `/usage` 是鉴权与用量接口，其余 70 个按 7 个钱包业务模块组织。

参数说明

响应示例

复制示例{
  "key_prefix": "sa_xxx",
  "scopes": ["read"],
  "rate_limit_per_minute": 60,
  "monthly_quota": 1000,
  "used_this_month": 42,
  "remaining_this_month": 958
}

复制示例{
  "address": "0x004edcd40360e293e4cf260d2ebdf8c7076c1bb8",
  "timeframe": "30D",
  "sections": ["context", "positions", "trading", "pnl", "risk", "activity"],
  "missing_sections": [],
  "data_freshness": {
    "context_snapshot_time": "2026-05-15T00:00:00+00:00",
    "latest_position_captured_at": "2026-05-15T00:00:00+00:00",
    "latest_fill_time": "2026-05-15T00:00:00+00:00"
  },
  "context": {
    "rank": 7,
    "account_value": "1500000.000000000000000000",
    "roi": "0.12000000",
    "risk_score": "0.20000000"
  },
  "positions": {
    "position_count": 3,
    "coin_count": 3,
    "total_position_value": "500000.000000000000000000"
  }
}

复制示例{
  "timeframe": "30D",
  "limit": 20,
  "offset": 0,
  "total": 128,
  "items": [
    {
      "address": "0x004edcd40360e293e4cf260d2ebdf8c7076c1bb8",
      "rank": 1,
      "account_value": "1500000.000000000000000000",
      "pnl": "25000.000000000000000000",
      "roi": "0.12000000",
      "risk_score": "0.20000000"
    }
  ]
}

配额与用量

已鉴权请求会写入用量审计事件。成功请求会更新 key 的 last_used_at。

调用示例

发现钱包

复制示例curl "http://127.0.0.1:8010/v1/wallets/search?timeframe=30D&min_account_value=100000&limit=20" \
  -H "Authorization: Bearer $EXTERNAL_API_KEY"

查询综合分析

复制示例curl "http://127.0.0.1:8010/v1/wallets/0x004edcd40360e293e4cf260d2ebdf8c7076c1bb8/analysis?timeframe=30D&sections=context,positions,pnl,risk,activity" \
  -H "Authorization: Bearer $EXTERNAL_API_KEY"

查询当前持仓

复制示例curl "http://127.0.0.1:8010/v1/wallets/0x004edcd40360e293e4cf260d2ebdf8c7076c1bb8/positions?fields=coin,direction,position_value,unrealized_pnl" \
  -H "Authorization: Bearer $EXTERNAL_API_KEY"

查询成交记录

复制示例curl "http://127.0.0.1:8010/v1/wallets/0x004edcd40360e293e4cf260d2ebdf8c7076c1bb8/fills?coin=BTC&limit=20" \
  -H "Authorization: Bearer $EXTERNAL_API_KEY"

查询交易员排行榜

复制示例curl "http://127.0.0.1:8010/v1/leaderboards/traders?timeframe=30D&limit=20" \
  -H "Authorization: Bearer $EXTERNAL_API_KEY"

查询当前 key 用量

复制示例curl "http://127.0.0.1:8010/v1/usage" \
  -H "Authorization: Bearer $EXTERNAL_API_KEY"

常见错误

错误响应通常包含机器可读的 error code 和可展示/记录的 message。

复制示例{
  "detail": {
    "code": "API_KEY_REVOKED",
    "message": "api key has been revoked"
  }
}

复制示例{
  "detail": {
    "code": "INVALID_FIELDS",
    "message": "Invalid fields."
  }
}

• 400: 参数不在白名单中，例如 timeframe、fields、coin、side、pagination、analysis section。
• 401: 缺少 key、key 格式错误或 key 不存在。
• 403: key 已撤销、已过期或 scope 不足。
• 404: 请求的钱包、read model、持仓、成交、订单或榜单数据不存在。
• 429: rate limit 或月度 quota 已达到上限。