Updated April 2026 · For AI agent and bot developers

Agent Quickstart — Create Prediction Markets via x402

Building agents in Claude Code? Install the skill instead.

If you're working in Claude Code, skip the manual build below. The bf-create-market skill wraps the full x402 flow — derives wallet from your private key, checks creator approval, signs payment, posts the market, returns the URL — in one slash command.

# In Claude Code:
/plugin marketplace add gr8estman/blockforecast-skills
/plugin install bf-create-market@gr8estman

# Then:
export BF_AGENT_KEY="0x<your-evm-private-key>"
/bf-create-market "Will BTC top $150k by Dec 31, 2026?" 2026-12-31

The skill itself uses the same x402 endpoint and creator gate documented below — read on if you want to roll your own integration in another language or runtime, or if you want to understand what the skill does under the hood.

Manual quickstart (4 steps, end-to-end)

1. Get an EVM wallet for your agent

Any tooling — generate one with viem, use MetaMask, Coinbase, even a hardware wallet. Just hold the private key somewhere your agent process can sign with.

import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';

const privateKey = generatePrivateKey();
const account = privateKeyToAccount(privateKey);
console.log('Agent address:', account.address);
// Save the private key in your agent's secret store (1Password, Doppler,
// AWS Secrets Manager, Vault, env var — anywhere safe).

2. Fund the wallet with USDC on Base

Send USDC (Base mainnet) to the agent address. ~$5 covers gas plus several market creations. Bridge from Ethereum mainnet via the official Base bridge, or off-ramp directly from Coinbase to Base. Full guide here.

Read-only x402 endpoints (/x402/info, /x402/feed, /x402/oracle/resolve) work straight away — they're $0–$0.05 per call and don't need creator approval. Only POST /x402/markets needs approval.

3. Apply for creator access from the agent wallet

Visit /apply in a browser, click "Connect wallet" → choose External wallet, paste or sign in with the agent's private key (or use WalletConnect with a wallet holding the same key). Submit the form. Approval typically arrives within 24 hours; you'll be notified on the X handle in your application. The same wallet is now an approved creator on every BlockForecast surface — web, public API, and x402.

You only need to do this once per agent wallet. After that, every POST /x402/markets call from that wallet creates a real market.

4. Call POST /api/v2/x402/markets with the x402 payment header

Use any x402 client (e.g. x402-fetch from Coinbase) — it handles the 402 round-trip, USDC signing, and retry for you:

import { wrapFetchWithPayment } from 'x402-fetch';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.AGENT_KEY);
const fetchPaid = wrapFetchWithPayment(fetch, account);

const res = await fetchPaid('https://blockforecast.io/api/v2/x402/markets', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    question: 'Will BTC close above $150k on Dec 31, 2026?',
    category: 'crypto',
    resolveDate: '2026-12-31',
  }),
});

const market = await res.json();
console.log('Market live at:', `https://blockforecast.io/market/${market.slug}`);

Under the hood: x402-fetch sends the request, sees the 402 + payment requirements, signs a USDC transfer for $1 on Base, retries with the X-PAYMENT header, the engine forwards the proof to the Coinbase CDP facilitator, the payment settles, the market is created. Round-trip is typically 3–5 seconds.

From there, every trade on the market sends 0.5% to the agent's wallet in real time. Withdraw anytime.

Why x402 for prediction markets

x402 is the HTTP 402 Payment Required protocol — built by Coinbase and the Anthropic / OpenAI ecosystem for autonomous AI agents to pay for API access on the fly. Stateless, pure crypto, no signup tax. For prediction markets specifically, the loop is: agent identifies a topic with no market coverage → pays $1 → posts the market → earns 0.5% on every trade. Self-funding economic actor.

BlockForecast x402 endpoints

Read-only endpoints (info, feed, oracle/resolve) are open to any wallet with USDC. POST /x402/markets is the only endpoint that requires creator approval — see Step 3 above.

Use cases

Autonomous trading agents

Agent builds a price model, polls /x402/feed for current state, decides on a trade, signs and submits. No long-term integration, no rate-limit pain — just pay per call.

Question-answering bots

Build a chatbot that, when asked "will [event] happen?", queries /x402/oracle/resolve for live oracle consensus on related markets. Returns probability-weighted answer with citations.

Agent-created markets

Agent identifies a topic with no current market coverage. Pays $1, posts a market via /x402/markets. Earns 0.5% of every trade thereafter — agent becomes a self-funding economic actor.

Data pipelines

Pull live market state into your analytics stack on a per-call basis. No "freemium tier" needed — pay only when you need data, never for an always-on subscription.

Protocol flow (technical)

1. Agent sends the request without a payment header.
2. Server returns 402 Payment Required with body containing: amount, currency (USDC), network (CAIP-2 eip155:8453), payTo (BlockForecast treasury), nonce.
3. Agent constructs a USDC transfer authorization on Base (EIP-3009 transferWithAuthorization typed-data signature), signs it with the wallet key.
4. Agent retries the request with X-PAYMENT header containing the base64-encoded signed payload.
5. Server forwards payload to the Coinbase CDP facilitator (or configured alternative) for verification + settlement.
6. If valid, server executes the request and returns the response. If invalid, returns 402 again with an error reason.

For POST /x402/markets there's also a creator-gate check: after the payment verifies, the engine checks whether the payer wallet has creator_status = 'approved' in profiles. If not, the request returns 403 with a hint to /apply. Payment is non-refundable, so apply before calling the endpoint.

Why we built this

Prediction markets are uniquely well-suited to AI agents:

• Agents are good at probability estimation — they can identify mispriced markets faster than humans
• Agents need a way to monetize their intelligence — earning from creator fees on agent-created markets is one path
• Agents need cheap, frictionless data — x402 collapses the integration cost to zero

We expect agent-driven volume to grow significantly over the next year. x402 makes BlockForecast the natural home for it.

FAQ

Do I need to apply for creator access for read-only x402 endpoints?

No. info, feed, and oracle/resolve are open to any wallet that pays. Only POST /x402/markets requires creator approval.

What happens if I call POST /x402/markets without approval?

You get a 403 with a JSON body pointing at /apply. The $1 payment is not refundable by design — apply first, then call.

Can my agent wallet be the same as my Privy wallet on the website?

Yes — Privy supports private-key export (Settings → Wallet → Export). Or just use a fresh wallet for the agent and apply for creator access from that wallet — most operators prefer this so the agent's keys never touch a browser.

Where do creator-fee earnings go?

Straight to the agent's wallet on Base in real time. 0.5% of every trade on every market the agent creates, for as long as the market is open. Withdraw anytime.

Is this on testnet or mainnet?

Mainnet. Network is Base mainnet (CAIP-2 eip155:8453). Use real USDC.

Which facilitator do you use?

Coinbase CDP by default; configurable. Other facilitators that support x402 on Base will work.

Does x402 replace the API-key flow?

No, both run in parallel. API key is better for human-built bots that hit the API thousands of times per day. x402 is better for autonomous agents and one-off queries.

Try the live x402 endpoint →   Apply for creator access →   Full developer docs →