Skip to main content
This guide walks you through the complete end-to-end flow for creating a BlockForecast prediction market from an autonomous agent using the x402 payment protocol. When you finish, your agent will hold a Base L2 wallet, pay $1 USDC to create a market with a single HTTP call, and begin earning 0.5% of every trade on that market in real time. The implementation language is TypeScript, but the flow maps directly to any language with an EIP-3009 signing library.
Building in Claude Code? Skip the manual EIP-3009 signing — the /bf-create-market skill wraps this entire flow into one slash command. Install once with /plugin marketplace add gr8estman/blockforecast-skills then /plugin install bf-create-market@gr8estman, set BF_AGENT_KEY, run the slash command. This page is for non-Claude-Code agents or developers who want to roll their own integration.
POST /api/v2/x402/markets only succeeds if the paying wallet has approved creator status. The $1 payment is non-refundable by design — apply for creator access in Step 3 before calling the endpoint. If your wallet is not approved, you receive 403 Forbidden and the payment is not returned.

Prerequisites

  • Node.js 18+ with TypeScript support
  • An Ethereum wallet (or you will generate one in Step 1)
  • USDC on Base mainnet (~$5 to cover gas and several market creations)
Install the required packages:

Step 1: Set up a Base L2 wallet

Your agent needs a dedicated EVM wallet whose private key it can access at runtime for signing. You can generate a fresh wallet programmatically:
Store the private key in a secrets manager — AWS Secrets Manager, Doppler, 1Password, or a .env file that is never committed to source control. Anyone with access to this key can spend the wallet’s funds.
If you already have a wallet (MetaMask, Coinbase Wallet), you can export the private key from Settings and use it directly. For production agents, a dedicated wallet that is separate from any browser wallet is strongly recommended. Load the key from your environment at runtime:

Step 2: Fund the wallet with USDC on Base

The x402 endpoints use USDC on Base mainnet (CAIP-2 identifier: eip155:8453). Your wallet needs:
  • $1.00 USDC minimum per market creation call
  • A small amount of ETH on Base for gas (typically $0.01–$0.05 per transaction)
  • A buffer for other x402 endpoints if you plan to use them (feed, oracle/resolve)
Option A — Bridge from Ethereum mainnet: Use the official Base bridge. Connect your agent wallet (or a funding wallet), select USDC, and bridge to Base. Bridging takes ~1 minute. Option B — Send directly from Coinbase: In Coinbase, select “Send” → choose USDC → select “Base” as the network → enter the agent address. Funds arrive in seconds. Option C — Programmatic funding (for CI/testing):
Verify the balance before proceeding:

Step 3: Apply for creator access

Creator approval is a one-time, per-wallet step. Without it, POST /x402/markets returns 403 after charging you $1 — apply first.
  1. Visit blockforecast.io/apply.
  2. Click Connect wallet and choose External wallet.
  3. Connect using the agent wallet’s address (use WalletConnect with any wallet holding the key, or paste the address and sign manually).
  4. Complete the application form — describe your use case and confirm the wallet address.
  5. You will hear back within 24 hours. Creator approval covers the web UI, POST /public/markets, and POST /x402/markets from the same wallet.
You only do this once per agent wallet. After approval, the wallet can create markets indefinitely across all BlockForecast surfaces.
To check approval status programmatically before paying for a market — /x402/info does not include per-wallet status. Use the public creator-status endpoint:
Always poll this before calling POST /x402/markets. The $1 payment is not refundable if the call fails the creator gate (returns 403).

Step 4: POST /x402/markets

With a funded, approved wallet, you are ready to create a market. The x402-fetch library handles the entire 402 round-trip for you — it sends the initial request, parses the payment requirements, constructs and signs the EIP-3009 transferWithAuthorization, and retries with the X-PAYMENT header automatically.

Full working example

What x402-fetch does under the hood

If you prefer to implement the protocol directly (for a different language or a custom client), here is the manual flow:

Response: the created market object

A successful 201 Created response returns the new market:
The market is immediately live and tradeable at https://blockforecast.io/market/{slug}. Creator fee earnings (0.5% of every trade) flow to account.address in real time.

Error handling

Full error handling example:
To monitor your agent’s market performance and creator earnings, use GET /api/v2/public/balance (with your standard API key) or query the on-chain USDC balance of the agent address directly via any Base L2 RPC.