Skip to main content
The BlockForecast REST API gives you programmatic access to prediction markets — list and filter markets, stream trade data, place trades, and create your own markets with creator approval. The base URL for all v2 endpoints is https://blockforecast.io/api/v2. Authentication uses a long-lived API key (bf_<32 hex>) that you obtain by signing a one-time challenge with your wallet. This guide walks you through every step from zero to your first successful response.
Building an AI agent that creates markets? Skip the manual setup — install the /bf-create-market Claude Code skill. One slash command wraps the full x402 + creator-fee flow.
Just need a key? Sign in at blockforecast.io/settings/api-keys and tap Generate key — Privy pops the wallet signature, the key is shown once. No curl needed for the happy path.
1

Get an API key (programmatic)

Keys are issued in a two-step nonce-bound flow: request a challenge, sign the exact message it returns, post both back. No account required — your wallet address is your identity. Each nonce is single-use, so the same signature can’t be replayed for any other action.
curl
# 1. Request a challenge
curl -X POST https://blockforecast.io/api/v2/auth/challenge \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xYourWalletAddress",
    "action":  "issue"
  }'

# response → { "success": true, "data": {
#   "nonce":     "<48-hex-chars>",
#   "message":   "BlockForecast API Key\nAction: issue\nAddress: 0x...\nNonce: ...\nTimestamp: 1777408738",
#   "expiresAt": "2026-04-28T20:43:58.000Z"
# } }

# 2. Sign data.message with your wallet (any EVM tool: viem, ethers, MetaMask…)
# 3. Post the signature + nonce back
curl -X POST https://blockforecast.io/api/v2/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "address":   "0xYourWalletAddress",
    "message":   "<exact message from step 1>",
    "signature": "0xYourSignedMessage",
    "nonce":     "<nonce from step 1>",
    "label":     "prod-bot"
  }'
The response contains your API key (shown once):
{
  "success": true,
  "data": {
    "id":        7,
    "apiKey":    "bf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "prefix":    "bf_xxxxxxxx...",
    "label":     "prod-bot",
    "rateLimit": 60,
    "createdAt": "2026-04-28T20:43:00.000Z",
    "note":      "Store this key securely. It cannot be retrieved again."
  }
}
Store the apiKey value as a secret in your deployment platform — the server only stores its SHA-256 hash, so a leaked DB doesn’t leak keys, but the raw key cannot be re-fetched. See Authentication for the full signing flow, the regenerate/revoke endpoints, and error reference.
2

Make your first request

With your key in hand, call GET /api/v2/public/markets to fetch the current list of active prediction markets.
curl https://blockforecast.io/api/v2/public/markets \
  -H "X-API-Key: $BLOCKFORECAST_API_KEY"
You can filter results with query parameters: ?status=active&category=crypto&limit=10. See Public API for the full parameter reference.
3

Parse the response

A successful GET /markets response looks like this:
{
  "markets": [
    {
      "id": "mkt_01hx9z3kqb8v2wyn4rfpje5d7t",
      "slug": "btc-above-150k-dec-2026",
      "question": "Will BTC close above $150k on Dec 31, 2026?",
      "category": "crypto",
      "status": "active",
      "yesPrice": 0.34,
      "noPrice": 0.66,
      "volume": 18420.50,
      "liquidity": 4100.00,
      "resolveDate": "2026-12-31T23:59:59Z",
      "createdAt": "2026-01-15T10:22:00Z"
    }
  ],
  "total": 142,
  "limit": 20,
  "offset": 0
}
Each market object includes the current LSMR prices (yesPrice, noPrice), aggregate volume, available liquidity, and the resolution date. Prices are expressed as probabilities between 0 and 1 — a yesPrice of 0.34 means the market currently prices the YES outcome at 34 cents per share.
All monetary values in the API are denominated in USDC (6-decimal precision on-chain, returned as floating-point USD in the REST API).
4

Next steps

You have the basics working. Here is where to go next depending on what you want to build:

Public API reference

Full endpoint reference with request params, response fields, and multi-language examples for every route.

Authentication

Wallet-signature auth flow, error codes, key rotation, and security best practices.

Rate limits

Default limits, 429 handling, exponential backoff examples, and how to request a higher limit.

x402 Agent API

Create markets from an autonomous AI agent — no API key required, just $1 USDC per market via x402.