BlackForge API documentation

Updated August 2026

What does the BlackForge API return?

BlackForge is a crypto market-data API. Every request returns measurements of the spot order book and trade tape, computed per pair per closed five-minute window across nine venues. This is the public reference: the authentication model, the plan ladder, and one page per endpoint with a real captured response.

Authentication

Authenticate with an API key in the x-api-key header, obtained from your dashboard. Autonomous agents can skip the key entirely and pay per call over the x402 rail. The catalog endpoint answers without either, so a client can read the schema before it authenticates.

Set $BF to the API base and put your key in $BLACKFORGE_API_KEY. Every example on these pages uses that convention.

The plan ladder

Every plan reaches the same endpoints; the plan sets which venues, which columns and how far back you can read. Columns outside your plan are omitted from a response and named in the X-BlackForge-Columns-Omitted header, never silently dropped. History windows are entitlements, not retention: the archive is kept forever.

Plans, columns and coverage (~11,800 pairs across 9 venues)
Plan	Columns	Venues	Granularity and window
Free	39	Binance, MEXC, Gate	Daily granularity, 2-week window
Pro ($29)	73	All 9	Hourly granularity, 3-month window
Max ($99)	120	All 9	Native 5-minute granularity, 1-year window
Ultra ($399)	120	All 9	Full archive, larger quota and rate
x402 pay-per-call	120	All 9	No key, up to 100 rows a call, 90-day window

Derived from the live plan configuration; see the metric reference for every column.

Sixty-second quickstart

# 1. Read the schema (no key needed)
curl "$BF/v1/catalog"

# 2. Pull the latest window for a pair (key in the header)
curl -H "x-api-key: $BLACKFORGE_API_KEY" \
  "$BF/v1/latest?exchange=binance&symbol=BTCUSDT&columns=price,buyTradeVol,sellTradeVol"

# 3. Chart one metric over the last hour
curl -H "x-api-key: $BLACKFORGE_API_KEY" \
  "$BF/v1/series?exchange=binance&symbol=BTCUSDT&metric=price&interval=5m&from=2026-08-13T00:00:00Z&to=2026-08-13T01:00:00Z"

Endpoints

One page each, with the parameters, a real example request and a real captured response.

Pay-per-call over x402

A metered endpoint called with no key and no payment answers HTTP 402 with a machine-readable challenge: the price per call, the asset, the chain, and the row cap. An agent that understands x402 pays the micropayment and retries, no account required.

A metered endpoint called with no key and no payment answers HTTP 402 with this challenge:

HTTP 402 challenge from GET /v1/latest with no credentials

{
  "error": "Payment Required",
  "message": "This endpoint is metered for autonomous agents: each call is paid per-request in USDC via the x402 flow, or authenticated with an API key. Obtain an API key from your BlackForge dashboard and send it in the x-api-key header.",
  "price": 0.005,
  "asset": "USDC",
  "network": "eip155:8453",
  "recipient": "0x9723b022cebb47bA2af605144EF0B2cD8D85d832",
  "rowsPerCall": 100,
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "5000",
      "resource": "$BF/v1/latest?exchange=binance&symbol=BTCUSDT",
      "description": "BlackForge market data — up to 100 rows, all 9 venues, all 120 columns, computed 5-minute to daily buckets (your choice; finer resolution and Max-tier columns bill proportionally more rows), 90-day history window.",
      "mimeType": "application/json",
      "payTo": "0x9723b022cebb47bA2af605144EF0B2cD8D85d832",
      "maxTimeoutSeconds": 25,
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ]
}

Every column, by family · Coverage by venue · How the data is measured · Pricing