Oracle v2 API

This reference describes the current Oracle V2 API. The OpenAPI operation pages cover REST; WebSocket messages have a separate guide.

Use Oracle Market View to explore live Klines, tickers, and exchange status in your browser.

Base URL

https://api.coinpost.ai/oracle

Append paths such as /v2/tickers?symbol=BTC or /v2/klines?symbol=BTC&quote=USD&interval=1m to this base URL. Local Oracle servers use http://localhost:8083.

Authentication

When CP Auth is enabled, send Authorization: Bearer <token> with the oracle scope to /v2 REST requests and the WebSocket upgrade. Browser WebSocket clients may use token or access_token query parameters if they cannot set an Authorization header.

GET /v2/_hc and its compatibility alias GET /_hc return only status, server.status, and worker.status without authentication. A valid Bearer token enables the detailed health response. When CP Auth is disabled, always returns the summary, including requests carrying credentials. With CP Auth enabled, malformed credentials return 401. Other validation failures retain the CP Auth HTTP status and error code, with sanitized error messages. Query-string tokens do not enable health details. Both paths use the same handler and response formats. Detail authorization is checked against the actual request path, so the same token may be allowed on one path and denied on the other. Uptime monitors should omit Authorization to read public health independently of CP Auth availability and token permissions.

REST resources

• GET /v2/_hc: Public overall, server, and worker status. With a validated Bearer token, also returns build information, API and per-asset aggregate ticker and 1m Kline health, observed source ticker delivery and exchange quote times, and worker heartbeat. Source ticker entries are keyed by exchange:pair:quote; old quote times alone do not degrade service health.
• GET /v2/market-overview: Cached global market capitalization, 24-hour volume, Bitcoin market share, and the Fear & Greed index.
• GET /v2/assets: asset catalog; filter can be listed (default), enabled, disabled, or all.
• GET /v2/klines: USD or JPY OHLCV for 1m, 5m, 15m, 30m, 1h, 1d, 1w, or 1M.
• GET /v2/tickers: aggregate USD or JPY prices and optional 24-hour base-asset volume.
• GET /v2/source-klines: cached native exchange OHLCV, including available active 1m, 1h, and 1d bars, with uncovered ranges and carried-bar timestamps.
• GET /v2/source-tickers: per-market last, bid, ask, and optional 24-hour base-asset volume.
• GET /v2/exchanges: persisted exchange inclusion and observed status.
• GET /v2/pairs: persisted pair inclusion and observed status; optional exchange filter.
• GET /v2/source-status: shared realtime and history source states, history isolation scopes, whether closed Klines keep advancing, and the per-exchange summary.

Market price and volume values are JSON strings; market timestamps are Unix milliseconds. Klines are arrays in [open_time_ms, open, high, low, close, volume, is_closed] order. A historical candle sourced only from CoinGecko has volume 0.

Use a base asset such as BTC for symbol. The optional quote selects JPY (default) or USD on Klines, tickers, and source tickers.

Market inclusion

Run oracle markets sync before starting the worker or a historical build. It inserts missing exchanges and pairs as disabled and leaves every existing record unchanged; a missing pair is not deleted or marked unavailable. Use --assets BTC,XRP and --exchanges gmo_coin,sbi_vc_trade to limit discovery. Explicitly enable the desired exchange and pairs with oracle exchanges enable EXCHANGE and oracle pairs enable EXCHANGE PAIR; use the corresponding list and disable commands to inspect or change choices. The worker checks choices every 30 seconds and rediscovers markets when a newly added pair is enabled. During a subscription change, source status is reconfiguring and old source tickers are removed immediately. Historical builds use the same choices.

WebSocket

Use wss://api.coinpost.ai/oracle/v2/ws for Kline, aggregate ticker, source ticker, and operational status events. See the WebSocket guide for subscriptions and message formats.

Backfill historical Klines with Docker

From the Oracle repository root, prepare config.yaml and an .env file supplying its environment variables. The following example enables GMO Coin's BTC_JPY market and backfills BTC.

Before running it, BTC must already exist in v2_assets with enabled=true and a valid coingecko_id. For a new database, first import assets with oracle assets import --limit 500, then enable the intended asset in PostgreSQL, updating both the enabled column and asset.enabled JSON field. markets sync only discovers markets for enabled assets.

Stop the running history worker before backfilling and restart it after completion. Use the same /app/data volume as the worker so the FX file cache is reused. --network host is for Linux setups whose PostgreSQL and Redis addresses are localhost; use your Docker network and service names otherwise.

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

Sync inserts new exchanges and pairs as disabled. Both enable commands must complete before running klines. For other assets or exchanges, sync the desired assets, inspect pairs list, and enable each selected exchange and pair before adding those assets to --assets.

The normal klines run resumes from checkpoints and fills missing history. Add --rebuild to regenerate the requested assets' supported historical ranges. klines fix repairs precision and history metadata in already stored Klines; it does not fetch missing exchange history.

Market overview

The worker refreshes the overview every five minutes. Global amounts are USD JSON numbers; last_updated values are RFC 3339 provider timestamps. fear_greed is null when no index is available. On an index fetch failure, the last known value and its original timestamp are retained: health stays healthy while the value is at most 48 hours old and the global overview saves successfully; missing or older values degrade health. GET /v2/market-overview returns 503 before the cache is populated or after it expires. The overview cache expires after two hours without a successful write. Implausible upstream data (24-hour volume above three times market cap, a market cap change above +90%, or a volume change above +1000%) is rejected and the previous cache is retained; the rejected refresh counts as a failed refresh for /v2/_hc until the next success.