/coinapi-openapi-skill

name: coinapi-openapi-skill
description: Operate CoinAPI market data reads through UXC with a curated OpenAPI schema, API-key auth, and read-first guardrails.

CoinAPI REST Skill

Use this skill to run CoinAPI REST market data operations through `uxc` + OpenAPI.

Reuse the `uxc` skill for shared execution, auth, and error-handling guidance.

Prerequisites

• `uxc` is installed and available in `PATH`.
• Network access to `https://rest.coinapi.io`.
• Access to the curated OpenAPI schema URL:
• `https://raw.githubusercontent.com/holon-run/uxc/main/skills/coinapi-openapi-skill/references/coinapi-market.openapi.json`
• A CoinAPI key.

Scope

This skill covers a read-first market data surface:

• current exchange rates
• current quote snapshots
• latest OHLCV candles
• latest trades
• latest order books

This skill does **not** cover:

• FIX, WebSocket, or MCP transport surfaces
• write operations
• the broader CoinAPI catalog

Authentication

CoinAPI uses `X-CoinAPI-Key` header auth.

Configure one API-key credential and bind it to `rest.coinapi.io`:

uxc auth credential set coinapi \
  --auth-type api_key \
  --api-key-header X-CoinAPI-Key \
  --secret-env COINAPI_KEY

uxc auth binding add \
  --id coinapi \
  --host rest.coinapi.io \
  --scheme https \
  --credential coinapi \
  --priority 100

Validate the active mapping when auth looks wrong:

uxc auth binding match https://rest.coinapi.io

Core Workflow

1. Use the fixed link command by default:

• `command -v coinapi-openapi-cli`
• If missing, create it:

`uxc link coinapi-openapi-cli https://rest.coinapi.io --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/coinapi-openapi-skill/references/coinapi-market.openapi.json`

• `coinapi-openapi-cli -h`

2. Inspect operation schema first:

• `coinapi-openapi-cli get:/v1/exchangerate/{asset_id_base}/{asset_id_quote} -h`
• `coinapi-openapi-cli get:/v1/ohlcv/{symbol_id}/latest -h`
• `coinapi-openapi-cli get:/v1/trades/{symbol_id}/latest -h`

3. Prefer narrow spot and latest reads before broader crawls:

• `coinapi-openapi-cli get:/v1/exchangerate/{asset_id_base}/{asset_id_quote} asset_id_base=BTC asset_id_quote=USD`
• `coinapi-openapi-cli get:/v1/quotes/current filter_symbol_id=BINANCE_SPOT_BTC_USDT`

4. Execute with key/value parameters:

• `coinapi-openapi-cli get:/v1/ohlcv/{symbol_id}/latest symbol_id=BINANCE_SPOT_BTC_USDT period_id=1DAY limit=10`
• `coinapi-openapi-cli get:/v1/orderbooks/{symbol_id}/latest symbol_id=BINANCE_SPOT_BTC_USDT limit_levels=20`

Operations

• `get:/v1/exchangerate/{asset_id_base}/{asset_id_quote}`
• `get:/v1/quotes/current`
• `get:/v1/ohlcv/{symbol_id}/latest`
• `get:/v1/trades/{symbol_id}/latest`
• `get:/v1/orderbooks/{symbol_id}/latest`

Guardrails

• Keep automation on the JSON output envelope; do not use `--text`.
• Parse stable fields first: `ok`, `kind`, `protocol`, `data`, `error`.
• Treat this v1 skill as read-only. Do not imply order entry or market connectivity support.
• Keep `filter_symbol_id`, `period_id`, `limit`, and `limit_levels` narrow unless the user explicitly wants larger pulls.
• `coinapi-openapi-cli <operation> ...` is equivalent to `uxc https://rest.coinapi.io --schema-url <coinapi_openapi_schema> <operation> ...`.

References

• Usage patterns: `references/usage-patterns.md`
• Curated OpenAPI schema: `references/coinapi-market.openapi.json`
• CoinAPI REST docs: https://docs.coinapi.io/market-data/rest-api