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

status

string

Filter by market status. One of active, resolved, cancelled. Omit to return all statuses.

Response fields

markets

array

Array of market objects.

Show Market object fields

string

Unique market identifier with mkt_ prefix.

slug

string

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

question

string

The full market question text.

Examples

curl
Python
TypeScript

curl "https://blockforecast.io/api/v2/public/markets?status=active&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": "active", "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=active&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": "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": 5,
  "offset": 0
}

GET /public/markets/:id

Fetches a single market by its ID.

Path parameters

string

required

The market ID (with mkt_ prefix) or the market slug. Both are accepted.

Response fields

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

resolutionCriteria

string

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

creator

object

Creator metadata.

Show Creator fields

address

string

The Ethereum address of the market creator.

displayName

string

Creator display name, if set.

resolution

object

Present only on resolved markets.

Show Resolution fields

outcome

string

YES or NO.

resolvedAt

string

ISO 8601 timestamp when the oracle resolved the market.

oracleConsensus

number

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

Examples

curl
Python
TypeScript

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

import os, requests

market_id = "mkt_01hx9z3kqb8v2wyn4rfpje5d7t"
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 = "mkt_01hx9z3kqb8v2wyn4rfpje5d7t";
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

question

string

required

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

description

string

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

resolutionCriteria

string

required

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

resolveDate

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.

Response fields

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

string

The new market’s unique identifier.

slug

string

The URL slug generated from the question.

status

string

Always active 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

limit

integer

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

offset

integer

Pagination offset. Default 0.

side

string

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

Response fields

trades

array

Array of trade objects.

Show Trade object fields

string

Unique trade identifier with trd_ prefix.

marketId

string

The market this trade belongs to.

side

string

YES or NO.

number

Number of shares purchased.

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

totalCost

number

Total USDC cost of the trade.

traderAddress

string

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

createdAt

string

ISO 8601 timestamp of the trade.

total

integer

Total number of trades for this market.

Examples

curl
Python
TypeScript

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

import os, requests

market_id = "mkt_01hx9z3kqb8v2wyn4rfpje5d7t"
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 = "mkt_01hx9z3kqb8v2wyn4rfpje5d7t";
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": "trd_01hz4m7pqk9c3xbn6sgwre2f8v",
      "marketId": "mkt_01hx9z3kqb8v2wyn4rfpje5d7t",
      "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 separately in the authentication and trading documentation:

Method	Path	Description
`POST`	`/api/v2/auth/challenge`	Issue a single-use nonce for a wallet-signed action (`issue` / `revoke` / `regenerate`).
`POST`	`/api/v2/auth/token`	Exchange a wallet signature + nonce 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).

API

x402 Agent API

Skills & SDKs

​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