Developer Quickstart: BlockForecast REST API

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.

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.

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"

import os
import requests

resp = requests.get(
    "https://blockforecast.io/api/v2/public/markets",
    headers={"X-API-Key": os.environ["BLOCKFORECAST_API_KEY"]},
)
resp.raise_for_status()
body = resp.json()
# Every v2 endpoint wraps results: { success: true, data: {...} }
markets = body["data"]["markets"]
total   = body["data"]["total"]
print(f"Found {total} markets")

const resp = await fetch("https://blockforecast.io/api/v2/public/markets", {
  headers: {
    "X-API-Key": process.env.BLOCKFORECAST_API_KEY!,
  },
});

if (!resp.ok) throw new Error(`API error: ${resp.status}`);
const body = await resp.json();
// Every v2 endpoint wraps results: { success: true, data: {...} }
const { markets, total } = body.data;
console.log(`Found ${total} markets`);

You can filter results with query parameters: ?status=active&category=crypto&limit=10. See Public API for the full parameter reference.

Parse the response

A successful GET /markets response looks like this:

{
  "markets": [
    {
      "id": 781,
      "tickerId": "BF-0781",
      "slug": "will-btc-close-above-150k-dec-2026",
      "question": "Will BTC close above $150k on Dec 31, 2026?",
      "category": "crypto",
      "status": "open",
      "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. The status field is open while trading is live, resolving after close, and resolved once the oracle settles.

All monetary values in the API are denominated in USDC (6-decimal precision on-chain, returned as floating-point USD in the REST API).

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.