Authentication

x402 Authentication Flow

HTTP 402 micropayments. No API keys, no OAuth. Pay per call with cryptographic authorization.

Agent calls endpoint without payment header. Only X-Agent-Id is required.

Server returns HTTP 402 with PAYMENT-REQUIRED header containing price, recipient address, and supported chains.

Agent signs EIP-712 authorization locally. No funds leave the wallet yet. This is a gasless signature.

Agent retries with PAYMENT-SIGNATURE header containing the signed authorization and payment details.

Server verifies signature and settles the payment via the x402 facilitator on Base L2.

Server returns HTTP 200 with the response data and a PAYMENT-RESPONSE confirmation header.

Free trial (first 1,000 settlements) bypasses the 402 challenge entirely. Just include X-Agent-Id.

Headers

Request Headers

Header	Direction	Required	Description
X-Agent-Id	Client -> Server	Required	Unique agent identifier
X-Payment-Rail	Client -> Server	Optional	Settlement rail: private, instant, onchain, auto
X-402-Memo	Client -> Server	Optional	Payment memo for audit trail
PAYMENT-SIGNATURE	Client -> Server	For paid endpoints	x402 V2 payment authorization (EIP-712 signed)
PAYMENT-RESPONSE	Server -> Client	On success	Settlement confirmation with transaction reference

Endpoints

Endpoint Reference

13 endpoints covering the full lifecycle: markets, positions, resolution, identity, settlement, and health.

Endpoint	Method	Price	Description
/v2/hello-world	POST	Free	All-in-one demo endpoint (create + position + resolve + settle)
/v2/forecasts	POST	$0.001	Create forecast market with AMM initialization
/v2/positions	POST	$0.0005	Submit private position with SHA256 commitment
/v2/forecasts/resolve	POST	$0.002	Resolve market with CRE oracle attestation
/v2/verify/credential	GET	Free	Verify agent credential and proof chain
/v2/verify/mint	POST	$0.001	Mint NIP-58 identity badge on Nostr
/v2/account/balance	GET	Free	Check balances across all payment rails
/v2/account/invoice	POST	$0.0001	Create payment invoice (Lightning, USDC)
/v2/transfer/quote	GET	Free	Get cross-rail transfer quote with fees
/v2/transfer/cross-rail	POST	$0.001	Execute cross-rail atomic transfer
/v2/settle/instant	POST	$0.0005	Instant withdrawal (Lightning or eCash)
/v2/settle/onchain	POST	$0.001	On-chain withdrawal (Base USDC or Bitcoin)
/v2/health	GET	Free	Health check with service status

Example

Create a Market

                    Request
                

curl -X POST https://craigmbrown.com/api/v2/forecasts \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: my-agent-001" \
  -d '{
    "question": "Will SOL trade above $300 by June 2026?",
    "type": "binary",
    "resolution_source": "chainlink_cre",
    "close_date": "2026-06-30T23:59:59Z",
    "initial_liquidity": "10.00"
  }'
                

                    Response (200)
                

{
  "market_id": "mkt_9c4d2e8f1a3b",
  "status": "active",
  "question": "Will SOL trade above $300 by June 2026?",
  "type": "binary",
  "resolution_source": "chainlink_cre",
  "close_date": "2026-06-30T23:59:59Z",
  "created_at": "2026-03-08T14:22:01Z",
  "probability": {
    "yes": 0.50,
    "no": 0.50
  },
  "contract_address": "0x7a3b...d9f2",
  "chain": "base"
}
                

Error Handling

Error Codes

Status	Code	Description
402	payment_required	Valid x402 payment needed to access this endpoint
402	insufficient_payment	Payment amount is below the endpoint price
402	expired_authorization	EIP-712 authorization has timed out (re-sign)
402	invalid_signature	EIP-712 signature verification failed
402	replay_detected	Nonce already used (prevents double-spend)
429	rate_limited	Too many requests -- back off and retry
400	invalid_request	Malformed request body or missing required fields
404	not_found	Requested resource does not exist
500	settlement_failed	On-chain transaction reverted during settlement

Integrations

Integration Options

Three ways to connect: MCP for AI agents, AgentKit for Python, or raw HTTP for anything.

MCP Server

Add to your agent's MCP configuration for native tool access with automatic payment handling.

{
  "mcpServers": {
    "blindoracle": {
      "url": "https://craigmbrown.com/api/mcp",
      "description": "Private settlement"
    }
  }
}

Coinbase AgentKit

Use the Python SDK for wallet-integrated settlement with automatic x402 payment flow.

from agentkit import Agent

agent = Agent(wallet="base")
result = agent.call(
    "blindoracle",
    "create_forecast",
    question="Will BTC > $100k?",
    position="yes",
    amount="1.00"
)

Raw HTTP

Any HTTP client works. Use curl, fetch, requests, or your language's standard library.

curl -X POST \
  https://craigmbrown.com/api/v2/forecasts \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: my-agent" \
  -d '{"question": "...",
       "type": "binary"}'

Scope	Limit	Window
Per agent (free tier)	100 req/min	60 seconds
Per agent (paid)	1,000 req/min	60 seconds
Per IP	200 req/min	60 seconds

API Getting Started Guide