A terminal client for the BlackForge crypto market-data API. Discover the catalog, list a venue's pairs, pull the latest 5-minute bucket or a time series, and check your usage — as a table, JSON, or CSV, straight from your shell.

BlackForge is raw market-data intelligence: 9 spot venues (binance, bitget, bybit, coinbase, gate, kraken, kucoin, mexc, okx), ~13,800 pairs, up to 117 columns per (exchange, symbol) per closed 5-minute window. Every column is a measurement — for example, the median lifetime of a resting price level, or taker buy-vs-sell volume — not a trade call. The CLI is a thin HTTP wrapper over the same /v1 API the dashboard and MCP server use: one key, one meter, more surfaces.

Install

Run it without installing:

npx -y @blackforge-so/cli catalog

Or install it globally so blackforge is on your PATH:

npm i -g @blackforge-so/cli
blackforge --help

Requires Node.js 20 or newer.

Quickstart

# 1. Store your API key (get one at https://app.blackforge.so/keys)
blackforge login

# 2. Pull the most recent 5-minute bucket for a pair
blackforge latest --exchange binance --symbol BTCUSDT

# 3. Confirm what you've used
blackforge usage

catalog, venues, and metrics need no key — try blackforge catalog before you even have one.

Pull a market slice to CSV in one line

blackforge series \
  --exchange binance --symbol BTCUSDT \
  --metric upDepth30 --interval 5m \
  --from 2026-07-01T00:00:00Z --to 2026-07-02T00:00:00Z \
  --output csv > btc-book-depth.csv

That writes one measurement's time series straight to a CSV you can open in a spreadsheet or feed to pandas. Swap --metric for any key from blackforge metrics.

Commands

Command	What it does
`blackforge login`	Prompt for a key and store it (config file, mode `600`).
`blackforge auth set-key <key>`	Store a key non-interactively.
`blackforge auth status`	Show the resolved key (masked) + base URL, and ping the API.
`blackforge catalog`	List venues and metric definitions. No key required.
`blackforge venues`	Venues only. No key required.
`blackforge metrics`	Metric definitions only (`key`, `label`, `family`, `unit`, `minPlan`). No key required.
`blackforge symbols --exchange <v>`	List the pairs a venue trades.
`blackforge latest --exchange <v> --symbol <s> [--columns a,b,c]`	The latest 5-minute bucket.
`blackforge series --exchange <v> --symbol <s> --metric <k> [--interval 5m\|1h\|1d] [--from <iso>] [--to <iso>]`	A time series of one metric.
`blackforge usage`	Your recent request counts and remaining row quota.

Global options

Option	Meaning
`--output <table\|json\|csv>`	Output format. Defaults to `table` on a TTY, `json` when piped.
`--api-key <key>`	Override the stored/env key for this call.
`--base-url <url>`	Override the API base URL (defaults to `https://api.blackforge.so`).
`--verbose`	Print the `X-BlackForge-*` metering footer (rows served/remaining, columns omitted) to stderr.

Output formats

table — a bordered grid, the default in an interactive terminal.

json — the raw API payload, unmodified, so it pipes cleanly into jq:

blackforge latest -e binance -s BTCUSDT --output json | jq '.values.upDepth30'

csv — a header row plus one row per record, ready for a spreadsheet.

Configuration & auth

Key and base URL resolve in this order (first match wins):

--api-key / --base-url flags
BLACKFORGE_API_KEY / BLACKFORGE_BASE_URL environment variables
~/.blackforge/config.json (written by blackforge login, mode 600)
Base URL default: https://api.blackforge.so

Your key is only ever stored locally, in that 600-permission file. It is never printed in full — auth status shows a masked form.

Exit codes & errors

Any API error exits non-zero and prints the HTTP status plus the server's message to stderr:

400 — an unknown metric or malformed datetime.
402 — the row quota is exhausted.
403 — the venue or interval isn't in your plan; the message carries an upgrade URL.

A series request for a column outside your plan returns empty points with an X-BlackForge-Columns-Omitted header (not an error); the CLI prints a note explaining the emptiness so it never looks like missing data.