Public REST API Reference: Markets and Trades

The BlockForecast public REST API exposes prediction market data and trading functionality over standard HTTP. All endpoints live under https://blockforecast.io/api/v2/public/ and require an X-API-Key header. This page documents every endpoint with full parameter descriptions, response field definitions, and working code examples in curl, Python, and TypeScript. If you have not yet obtained an API key, start with Authentication.

All monetary values are returned as floating-point USD (e.g., 18420.50) in the REST API. On-chain, amounts are USDC with 6-decimal precision — keep this in mind if you are reconciling against on-chain data.

GET /public/markets

Returns a paginated, filterable list of prediction markets.

Query parameters

string

Filter by market status. One of open (trading), resolved (settled). Omit to return all statuses.

string

Filter by category slug. Common values: crypto, sports, politics, science, entertainment. Matched case-insensitively. Omit to return all categories.

integer

Number of markets to return per page. Maximum 100. Default 20.

integer

Pagination offset. Default 0.

string

Sort order. One of volume_desc (default), created_desc, resolve_asc.

Response fields

array

Array of market objects.

Show Market object fields

integer

Numeric market identifier (e.g., 781).

string

Human-readable ticker (e.g., BF-0781).

string

URL-friendly market slug (e.g., will-btc-close-above-150k-dec-2026).

string

The full market question text.

string

Category slug.

string

One of open (trading), resolving (closed, awaiting oracle), resolved (settled).

number

Current LSMR YES price as a probability (0–1).

number

Current LSMR NO price as a probability (0–1).

number

Total trade volume in USD.

number

Available liquidity in USD.

string

ISO 8601 resolution date.

string

ISO 8601 creation timestamp.

integer

Total number of markets matching the query (before pagination).

integer

The effective limit applied.

integer

The effective offset applied.

Examples

curl
Python
TypeScript

curl "https://blockforecast.io/api/v2/public/markets?status=open&category=crypto&limit=5" \
  -H "X-API-Key: $BLOCKFORECAST_API_KEY"

import os, requests

resp = requests.get(
    "https://blockforecast.io/api/v2/public/markets",
    headers={"X-API-Key": os.environ["BLOCKFORECAST_API_KEY"]},
    params={"status": "open", "category": "crypto", "limit": 5},
)
resp.raise_for_status()
data = resp.json()

for market in data["markets"]:
    print(f"{market['question']} — YES: {market['yesPrice']:.2f}")

const resp = await fetch(
  "https://blockforecast.io/api/v2/public/markets?status=open&category=crypto&limit=5",
  { headers: { "X-API-Key": process.env.BLOCKFORECAST_API_KEY! } }
);
if (!resp.ok) throw new Error(`API error: ${resp.status}`);
const data = await resp.json();

for (const market of data.markets) {
  console.log(`${market.question} — YES: ${market.yesPrice.toFixed(2)}`);
}

Example response:

{
  "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": 5,
  "offset": 0
}

GET /public/markets/:id

Fetches a single market by its numeric ID, ticker ID, or slug.

Path parameters

string

required

The market’s numeric id (e.g., 781), tickerId (e.g., BF-0781), or slug. All three are accepted.

Response fields

Returns a single market object with all the fields described in GET /markets, plus:

string

The plain-text criteria the AI oracle uses to resolve the market.

object

Creator metadata.

Show Creator fields

string

The Ethereum address of the market creator.

string

Creator display name, if set.

object

Present only on resolved markets.

Show Resolution fields

string

YES or NO.

string

ISO 8601 timestamp when the oracle resolved the market.

number

Oracle confidence score (0–1) at resolution time.

Examples

curl
Python
TypeScript

curl "https://blockforecast.io/api/v2/public/markets/781" \
  -H "X-API-Key: $BLOCKFORECAST_API_KEY"

import os, requests

market_id = 781
resp = requests.get(
    f"https://blockforecast.io/api/v2/public/markets/{market_id}",
    headers={"X-API-Key": os.environ["BLOCKFORECAST_API_KEY"]},
)
resp.raise_for_status()
market = resp.json()
print(f"YES: {market['yesPrice']}, NO: {market['noPrice']}")

const marketId = 781;
const resp = await fetch(
  `https://blockforecast.io/api/v2/public/markets/${marketId}`,
  { headers: { "X-API-Key": process.env.BLOCKFORECAST_API_KEY! } }
);
if (!resp.ok) throw new Error(`API error: ${resp.status}`);
const market = await resp.json();
console.log(`YES: ${market.yesPrice}, NO: ${market.noPrice}`);

POST /public/markets

Creates a new prediction market. Requires your wallet to have approved creator status. Apply for creator access — applications are reviewed within 24 hours.

Request body

string

required

The market question. Should be phrased as a binary yes/no question. Maximum 280 characters.

string

Additional context about the market. Markdown supported. Maximum 2000 characters.

string

required

Clear, unambiguous criteria that define how the market resolves. The AI oracle uses this text. Maximum 1000 characters.

string

required

ISO 8601 date-time for when the market is eligible for resolution (e.g., 2026-12-31T23:59:59Z). Must be at least 1 hour in the future.

string

required

Category slug. One of: crypto, sports, politics, science, entertainment, other.

Response fields

Returns the newly created market object with all fields from GET /markets/:id.

integer

The new market’s numeric identifier.

string

The URL slug generated from the question.

string

Always open on creation.

Examples

curl
Python
TypeScript

curl -X POST "https://blockforecast.io/api/v2/public/markets" \
  -H "X-API-Key: $BLOCKFORECAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Will ETH surpass $10,000 before July 2027?",
    "description": "Tracks ETH/USD price on Coinbase Pro at any point before the resolution date.",
    "resolutionCriteria": "Resolves YES if ETH/USD closes above $10,000 on Coinbase Pro on any day before July 1, 2027. Resolves NO otherwise.",
    "resolveDate": "2027-07-01T00:00:00Z",
    "category": "crypto"
  }'

import os, requests

resp = requests.post(
    "https://blockforecast.io/api/v2/public/markets",
    headers={
        "X-API-Key": os.environ["BLOCKFORECAST_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "question": "Will ETH surpass $10,000 before July 2027?",
        "description": "Tracks ETH/USD price on Coinbase Pro at any point before the resolution date.",
        "resolutionCriteria": "Resolves YES if ETH/USD closes above $10,000 on Coinbase Pro on any day before July 1, 2027. Resolves NO otherwise.",
        "resolveDate": "2027-07-01T00:00:00Z",
        "category": "crypto",
    },
)
resp.raise_for_status()
market = resp.json()
print(f"Created market: https://blockforecast.io/market/{market['slug']}")

const resp = await fetch("https://blockforecast.io/api/v2/public/markets", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.BLOCKFORECAST_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    question: "Will ETH surpass $10,000 before July 2027?",
    description: "Tracks ETH/USD price on Coinbase Pro at any point before the resolution date.",
    resolutionCriteria:
      "Resolves YES if ETH/USD closes above $10,000 on Coinbase Pro on any day before July 1, 2027. Resolves NO otherwise.",
    resolveDate: "2027-07-01T00:00:00Z",
    category: "crypto",
  }),
});
if (!resp.ok) throw new Error(`API error: ${resp.status}`);
const market = await resp.json();
console.log(`Created: https://blockforecast.io/market/${market.slug}`);

If your API key’s wallet does not have creator status, this endpoint returns 403 Forbidden with code INSUFFICIENT_PERMISSIONS. Apply at blockforecast.io/apply — the same approval covers both the public API and the x402 Agent API.

GET /public/markets/:id/trades

Returns a paginated list of trades for a specific market, ordered from most recent to oldest.

Path parameters

string

required

The market ID or slug.

Query parameters

integer

Number of trades to return. Maximum 100. Default 20.

integer

Pagination offset. Default 0.

string

Filter by trade side. One of YES, NO. Omit to return both.

Response fields

array

Array of trade objects.

Show Trade object fields

integer

Numeric trade identifier.

integer

The numeric ID of the market this trade belongs to.

string

YES or NO.

number

Number of shares purchased.

Effective price per share at execution (0–1).

number

Total USDC cost of the trade.

string

Ethereum address of the trader (may be partial for privacy).

string

ISO 8601 timestamp of the trade.

integer

Total number of trades for this market.

Examples

curl
Python
TypeScript

curl "https://blockforecast.io/api/v2/public/markets/781/trades?limit=10" \
  -H "X-API-Key: $BLOCKFORECAST_API_KEY"

import os, requests

market_id = "781"
resp = requests.get(
    f"https://blockforecast.io/api/v2/public/markets/{market_id}/trades",
    headers={"X-API-Key": os.environ["BLOCKFORECAST_API_KEY"]},
    params={"limit": 10},
)
resp.raise_for_status()
data = resp.json()

for trade in data["trades"]:
    print(f"{trade['side']} | {trade['shares']} shares @ {trade['pricePerShare']:.3f}")

const marketId = "781";
const resp = await fetch(
  `https://blockforecast.io/api/v2/public/markets/${marketId}/trades?limit=10`,
  { headers: { "X-API-Key": process.env.BLOCKFORECAST_API_KEY! } }
);
if (!resp.ok) throw new Error(`API error: ${resp.status}`);
const data = await resp.json();

for (const trade of data.trades) {
  console.log(`${trade.side} | ${trade.shares} shares @ ${trade.pricePerShare.toFixed(3)}`);
}

Example response:

{
  "trades": [
    {
      "id": 31487,
      "marketId": 781,
      "side": "YES",
      "shares": 50.0,
      "pricePerShare": 0.341,
      "totalCost": 17.05,
      "traderAddress": "0x1a2b...f9e0",
      "createdAt": "2026-04-27T14:35:12Z"
    }
  ],
  "total": 1204,
  "limit": 10,
  "offset": 0
}

Additional endpoints

The following endpoints are available but covered in detail in Authentication. The auth flow is two-step — /auth/challenge must be called before /auth/token:

Method	Path	Description
`POST`	`/api/v2/auth/challenge`	Step 1 — required prerequisite for `/auth/token`. Issues a single-use nonce for a wallet-signed action (`issue` / `revoke` / `regenerate`).
`POST`	`/api/v2/auth/token`	Step 2. Exchange a wallet signature + the nonce from step 1 for a `bf_…` API key.
`GET`	`/api/v2/auth/keys?address=`	List active keys (prefixes only) for a wallet.
`POST`	`/api/v2/auth/keys/:id/revoke`	Revoke a specific key by id.
`POST`	`/api/v2/auth/keys/:id/regenerate`	Atomically rotate — old revoked, new issued.
`GET`	`/api/v2/public/markets/:id/price`	Current LSMR price and price impact for a given quote size.
`GET`	`/api/v2/public/markets/:id/history`	OHLC price history.
`POST`	`/api/v2/public/markets/:id/trade`	Place a trade on a market.
`GET`	`/api/v2/public/positions`	Open positions for your wallet.
`GET`	`/api/v2/public/positions/history`	Trade history for your wallet.
`GET`	`/api/v2/public/balance`	Your USDC balance on BlockForecast.

To create markets programmatically without the manual creator approval flow, see the x402 Agent API — autonomous agents can pay $1 USDC per market with no signup required (creator approval still needed, but the flow is fully programmatic).

​GET /public/markets

​Query parameters

​Response fields

​Examples

​GET /public/markets/:id

​Path parameters

​Response fields

​Examples

​POST /public/markets

​Request body

​Response fields

​Examples

​GET /public/markets/:id/trades

​Path parameters

​Query parameters

​Response fields

​Examples

​Additional endpoints

GET /public/markets

Query parameters

Response fields

Examples

GET /public/markets/:id

Path parameters

Response fields

Examples

POST /public/markets

Request body

Response fields

Examples

GET /public/markets/:id/trades

Path parameters

Query parameters

Response fields

Examples

Additional endpoints