API 参考
开放平台 v1 的完整接入规范。所有接口都遵循这里描述的统一约定,未来的业务接口也会以同样的方式挂载在 /api/v1 之下。
| 接口 | 鉴权 | 用途 |
|---|---|---|
GET /api/v1/health |
不需要 | 确认服务可达。 |
GET /api/v1/me |
需要 | 查看当前凭证所属的账号与密钥。 |
GET /api/v1/strategies |
需要 | 列出公开可见的交易策略。查看详情 |
GET /api/v1/lives |
需要 | 列出公开可见的圈子直播。查看详情 |
基础地址与版本
Section titled “基础地址与版本”- 基础地址:
https://ohmy.xin/api/v1—— 开发者 API 页面底部的「快速接入指引」会显示你当前所在环境的基础地址。 - 生产环境强制 HTTPS。
- 路径带版本前缀
/v1;未来若有不兼容变更会引入新的版本前缀,旧版本按公告逐步退役。
除健康检查外,所有接口都需要在请求头携带 Bearer 密钥:
Authorization: Bearer omx_live_<8 位标识>_<32 位密文>- 密钥在开发者 API 页面的账号详情里生成,形如
omx_live_xxxxxxxx_yyyyyyyy…。 - 平台只保存密钥的单向摘要;任何页面、响应与日志都不会再出现完整明文。
- 密钥被禁用或吊销、所属账号被停用或冻结后,下一次请求立即返回
401。
统一响应结构
Section titled “统一响应结构”成功时返回 data,失败时返回 error,两者都附带 meta.request_id:
{ "data": { "...": "..." }, "meta": { "request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f" }}{ "error": { "code": "unauthorized", "message": "Invalid or inactive API credentials." }, "meta": { "request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f" }}meta.request_id 是本次请求的唯一追踪编号,同时出现在响应头 X-Request-Id 里;联系平台排查问题时请提供它。
| 响应头 | 出现时机 | 说明 |
|---|---|---|
X-Request-Id |
所有响应 | 与 meta.request_id 一致 |
X-RateLimit-Limit |
鉴权通过后 | 当前账号每分钟请求上限 |
X-RateLimit-Remaining |
鉴权通过后及 429 |
当前窗口剩余次数(限流时为 0) |
X-RateLimit-Reset |
鉴权通过后及 429 |
窗口重置时间的 Unix 时间戳(秒) |
Retry-After |
429 |
建议等待的秒数 |
- 每个 API 账号默认每分钟 60 次;平台可为个别账号调整上限 —— 开发者 API 页面的账号信息里显示的是当前生效值。
- 额度按账号计算:同一账号下的多把密钥共享同一个额度。
- 此外还有一层按来源 IP 计数的兜底限制(默认每分钟 300 次),对同一 IP 的全部
/api/流量生效,不区分凭证是否有效。 - 触发限流时返回
429与Retry-After;请按提示等待后重试,而不是并发重试。被 IP 级限制拦下的429没有X-RateLimit-*头,文案为 “Too many requests. Please retry later.”,也不会出现在调用记录里。
| HTTP 状态 | error.code |
含义 |
|---|---|---|
400 |
invalid_parameter |
查询参数不合法。error.details 会逐条列出出错的参数,形如 { "param": "...", "reason": "..." }。 |
401 |
unauthorized |
凭证缺失、格式非法、密钥被禁用/吊销,或所属账号被停用/冻结(对外统一文案,不区分具体原因)。 |
404 |
not_found |
接口路径不存在。 |
429 |
rate_limit_exceeded |
超出速率限制。 |
503 |
service_unavailable |
平台临时关闭了外部 API 服务。 |
500 |
internal_error |
服务端内部异常,请携带 meta.request_id 联系平台。 |
连通性健康检查
Section titled “连通性健康检查”GET /api/v1/health不需要鉴权,用于确认服务可达:
{ "data": { "status": "ok", "version": "v1", "timestamp": "2026-11-15T22:15:00+08:00" }, "meta": { "request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f" }}凭证与账号自检
Section titled “凭证与账号自检”GET /api/v1/me需要鉴权,返回当前密钥所属的账号与密钥信息:
{ "data": { "account": { "number": "8392014", "name": "Production Integration", "state": "active", "rate_limit_per_minute": 60 }, "key": { "name": "Primary Key", "masked_token": "omx_live_a1b2c3d4••••••••x9y0", "state": "active", "last_used_at": "2026-11-15T22:14:12+08:00" } }, "meta": { "request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f" }}account.state 取值:active(启用中)、disabled(已停用)、frozen(已冻结);key.state 取值:active(启用中)、disabled(已禁用)、revoked(已吊销)。
任何未注册的 /api/* 路径都返回统一的 404 信封,而不是内部错误页:
{ "error": { "code": "not_found", "message": "API endpoint not found." }, "meta": { "request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f" }}返回列表的接口共用同一套约定,针对其中一个写好的集成代码可以直接复用到下一个。
通用查询参数
Section titled “通用查询参数”| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
limit |
整数 | 20 |
每页条数,取值范围 1–100。 |
cursor |
字符串 | — | 上一页返回的 meta.pagination.next_cursor。不透明字符串,请原样回传。 |
sort |
字符串 | 由接口决定 | 该接口自己支持的排序方式;游标与上一页使用的排序绑定。 |
circle_number |
字符串 | — | 只返回某个圈子的数据(最长 32 字符)。 |
state |
字符串 | 由接口决定 | 该接口允许的状态值,逗号分隔多个。 |
updated_after |
ISO 8601 时间 | — | 更新时间下界(含)。 |
接口还可以在此基础上追加自己的筛选参数:策略接口有 symbol、side、published_after、published_before,直播接口有 scheduled_after、scheduled_before。
所有集合接口的响应都带同样的 meta.pagination 结构:
{ "meta": { "pagination": { "limit": 20, "has_more": true, "next_cursor": "eyJzIjoi..." }, "request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f" }}| 字段 | 类型 | 可为 null | 说明 |
|---|---|---|---|
limit |
整数 | 否 | 本次实际生效的每页条数。 |
has_more |
布尔 | 否 | 是否还有下一页。 |
next_cursor |
字符串 | 是 | 下一页游标;has_more 为 false 时为 null。 |
取下一页时,把 next_cursor 原样作为 cursor 传回,其余参数保持不变。换一种 sort 会让旧游标失效并返回 400。
- 策略列表 ——
GET /api/v1/strategies - 直播列表 ——
GET /api/v1/lives - 快速开始
- 开放平台概览
- OpenAPI 规范 —— 所有接口的机器可读描述