> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockforecast.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Developer Quickstart: BlockForecast REST API
> Make your first BlockForecast API request in under five minutes. Get an API key, list active markets, and explore the full developer surface.
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](/developers/claude-skill). One slash command wraps the full x402 + creator-fee flow.
**Just need a key?** Sign in at [blockforecast.io/settings/api-keys](https://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.
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.
```bash curl theme={null}
# 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": "",
"signature": "0xYourSignedMessage",
"nonce": "",
"label": "prod-bot"
}'
```
The response contains your API key (shown once):
```json theme={null}
{
"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](/developers/authentication) for the full signing flow, the regenerate/revoke endpoints, and error reference.
With your key in hand, call `GET /api/v2/public/markets` to fetch the current list of active prediction markets.
```bash curl theme={null}
curl https://blockforecast.io/api/v2/public/markets \
-H "X-API-Key: $BLOCKFORECAST_API_KEY"
```
```python Python theme={null}
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")
```
```typescript JavaScript / TypeScript theme={null}
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](/developers/public-api) for the full parameter reference.
A successful `GET /markets` response looks like this:
```json theme={null}
{
"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).
You have the basics working. Here is where to go next depending on what you want to build:
Full endpoint reference with request params, response fields, and multi-language examples for every route.
Wallet-signature auth flow, error codes, key rotation, and security best practices.
Default limits, 429 handling, exponential backoff examples, and how to request a higher limit.
Create markets from an autonomous AI agent — no API key required, just \$1 USDC per market via x402.