> developers

简体中文

English
日本語

简体中文

English
日本語

Oracle v2 API ​

这里记录当前 Oracle V2 API。OpenAPI 接口页覆盖 REST；WebSocket 格式见单独的说明。

通过 Oracle 行情看板 在浏览器中查看实时 K 线、行情和交易所状态。

Base URL ​

text
https://api.coinpost.ai/oracle

在该地址后添加 /v2/tickers?symbol=BTC 或 /v2/klines?symbol=BTC&quote=USD&interval=1m 等路径。本地服务使用 http://localhost:8083。

鉴权 ​

启用 CP Auth 时，向 /v2 REST 请求和 WebSocket 握手发送具有 oracle scope 的 Authorization: Bearer <token>。无法设置请求头的浏览器 WebSocket 客户端可使用 token 或 access_token 查询参数。

GET /v2/_hc 和兼容入口 GET /_hc 无需鉴权，只返回 status、server.status、worker.status。Bearer token 校验通过后返回健康详情；详情要求启用 CP Auth。关闭 CP Auth 时，即使带凭据也只返回简易响应。启用 CP Auth 时，鉴权格式错误返回 401；其他校验失败保留 CP Auth 的 HTTP 状态与错误码，错误消息经过脱敏。查询参数 token 不会开启健康详情。两个地址使用相同的 handler 和响应格式。详情权限按实际请求路径校验，因此同一个 token 可能被允许访问其中一个路径，而被另一个路径拒绝。可用性监控应省略 Authorization，以独立于 CP Auth 可用性和 token 权限读取公开状态。

REST 接口 ​

  • GET /v2/_hc：公开整体、server 和 worker 状态；Bearer token 校验通过后，还返回版本、API 与各资产聚合 ticker 和 1m K 线状态、已观察到的交易所 ticker 接收时间与原始报价时间，以及 worker 心跳。交易所 ticker 以 exchange:pair:quote 为键；报价时间较旧本身不会使服务降级。
  • GET /v2/market-overview: 缓存的全球总市值、24 小时成交额、比特币市值占比与恐惧贪婪指数。
  • GET /v2/assets：资产目录；filter 可为 listed（默认）、enabled、disabled 或 all。
  • GET /v2/klines：USD/JPY OHLCV，支持 1m、5m、15m、30m、1h、1d、1w、1M。
  • GET /v2/tickers：聚合价格和可用时的 24 小时基础资产成交量。
  • GET /v2/source-klines：查询交易所原生 K 线缓存及可用的未收盘 1m、1h、1d K 线，并返回未覆盖区间与补齐 K 线的时间戳。
  • GET /v2/source-tickers：各交易市场的最新价、bid、ask 和可用时的 24 小时成交量。
  • GET /v2/exchanges：交易所启用设置与已观测状态。
  • GET /v2/pairs：交易对启用设置与已观测状态；可用 exchange 筛选。
  • GET /v2/source-status：实时与历史的共享来源状态、历史隔离范围、closed Kline 是否仍在推进，以及按交易所的汇总。

行情价格和成交量以 JSON 字符串返回，行情时间戳使用 Unix 毫秒。K 线数组顺序为 [open_time_ms, open, high, low, close, volume, is_closed]。仅来自 CoinGecko 的历史 K 线成交量为 0。

symbol 使用 BTC 等基础资产。K 线、聚合行情和来源行情的 quote 可选 JPY（默认）或 USD。

市场启用设置 ​

启动 worker 或运行历史构建前，先运行 oracle markets sync。它只插入尚不存在的交易所和交易对，新增记录默认禁用；现有记录不会被修改，未发现的交易对也不会被删除或标记为 unavailable。可用 --assets BTC,XRP 和 --exchanges gmo_coin,sbi_vc_trade 限定发现范围。使用 oracle exchanges enable EXCHANGE 和 oracle pairs enable EXCHANGE PAIR 人工启用需要的数据；list 和 disable 命令可查看或调整设置。worker 每 30 秒检查设置，新交易对启用后重新发现市场；订阅切换时状态为 reconfiguring，并立即移除旧来源行情。历史构建使用相同设置。

WebSocket ​

wss://api.coinpost.ai/oracle/v2/ws 推送 K 线、聚合行情、来源行情和运行状态。订阅与消息格式见 WebSocket 文档。

使用 Docker 补齐历史 K 线 ​

在 Oracle 仓库根目录准备 config.yaml 和提供所需环境变量的 .env。下面以启用 GMO Coin 的 BTC_JPY 交易对并回填 BTC 为例。

运行前，v2_assets 中必须已有 BTC，且 enabled=true、coingecko_id 有效。新数据库应先用 oracle assets import --limit 500 导入资产，再在 PostgreSQL 中启用目标资产，同时更新 enabled 列和 asset.enabled JSON 字段。markets sync 只为已启用资产发现市场。

回填前先停止写入历史数据的 worker，命令结束后再启动。将 worker 使用的同一个数据卷挂载到 /app/data，以复用 FX 文件缓存。--network host 适用于 PostgreSQL 和 Redis 地址为 localhost 的 Linux 环境；其他环境应使用对应的 Docker 网络和服务名。

bash
docker build -t oracle:local .

oracle_run() {
  docker run --rm --network host \
    --env-file .env \
    -v "$PWD/config.yaml:/app/config.yaml:ro" \
    -v oracle-data:/app/data \
    oracle:local --config /app/config.yaml "$@"
}

oracle_run markets sync --assets BTC --exchanges gmo_coin
oracle_run pairs list gmo_coin
oracle_run exchanges enable gmo_coin
oracle_run pairs enable gmo_coin BTC_JPY
oracle_run klines --assets BTC

同步新增的交易所和交易对默认禁用，必须完成两个 enable 命令后再运行 klines。使用其他资产或交易所时，先同步目标资产，通过 pairs list 查看实际交易对，再逐一启用所选交易所和交易对，最后将目标资产加入 --assets。

普通 klines 会从检查点继续并补齐缺失历史。只有需要重建所选资产全部受支持的历史区间时才加 --rebuild。klines fix 只修复已存 K 线的精度和历史元数据，不会抓取缺失的交易所历史数据。

市场概览 ​

worker 每五分钟刷新市场概览。全球金额以 USD 计价，返回 JSON 数字；last_updated 为数据提供方的 RFC 3339 时间戳。没有可用指数时，fear_greed 为 null。指数抓取失败时保留旧值与原始时间戳：旧值不超过 48 小时且全球概览保存成功时保持健康，指数缺失或超过 48 小时时健康状态降级。缓存尚未建立或已过期时，GET /v2/market-overview 返回 503。概览缓存自最后一次成功写入起两小时后过期。上游数据不合理时（24 小时成交量超过市值的 3 倍、市值变化超过 +90%、成交量变化超过 +1000%）会被拒绝并保留上一份缓存；被拒绝的刷新在下一次成功之前会在 /v2/_hc 中计为失败。