Pay per request (HTTP 402)

402 Payment Required is the HTTP status code the web reserved for machine payments — and Foresight API uses it exactly that way. Call a paid endpoint with no API key and the response is a 402 carrying everything needed to pay: no signup, no dashboard, no stored card. Pay, retry, get the data.

Two payment rails are supported, and the same 402 advertises both:

• x402 — a few cents of USDC on Base, settled on-chain.
• L402 — the same price in bitcoin over the Lightning Network, settled instantly.

Use whichever your wallet or agent stack speaks. Catalog endpoints stay free; only observation, insight, and signal endpoints are payable. Payment only happens on a 2xx — a 400/404/5xx never charges the buyer.

The 402 response

curl -i "https://api.creativeforesight.io/v1/observations/latest?indicator=unemployment_rate&region=47187"

The response carries the x402 payment requirements twice: as JSON in the body, and base64-encoded in the PAYMENT-REQUIRED header. The Lightning challenge is in WWW-Authenticate:

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6Mi…
WWW-Authenticate: L402 macaroon="AgEEbHNhdC…", invoice="lnbc100n1p4x…"

{
  "x402Version": 2,
  "error": "PAYMENT-SIGNATURE header is required",
  "resource": {
    "url": "https://api.creativeforesight.io/v1/observations/latest",
    "description": "Foresight API latest observations",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "10000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x9eDB521A5aD936Ef5D7054Ed94252D4d7978cf90",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ],
  "extensions": { "bazaar": { "info": { "input": { "type": "http", "method": "GET" } } } }
}

amount is in USDC base units (6 decimals), so 10000 = $0.01. eip155:8453 is Base mainnet. The Lightning invoice is the same price converted to sats at the current BTC-USD rate.

Pay with x402 (USDC on Base)

x402  settles in USDC on Base. The buyer pays gaslessly (EIP-3009); Creative Foresight settles on-chain through the Coinbase CDP facilitator and returns the data.

1. Call a payable endpoint without an API key.
2. Read the accepts array from the 402 (amount, asset, network, payTo).
3. Sign a USDC transferWithAuthorization and retry with a PAYMENT-SIGNATURE header (the legacy X-PAYMENT name is also accepted).
4. The facilitator verifies and settles; the API returns 200 with the data and a PAYMENT-RESPONSE header (the on-chain settlement receipt).

The x402 client

The simplest path is the official x402 client, @x402/fetch. It turns any fetch into one that pays automatically: it catches the 402, signs the payment, retries, and returns the 200 with a decoded on-chain receipt. Fund a wallet with a little USDC on Base, then:

import { decodePaymentResponseHeader, wrapFetchWithPaymentFromConfig } from "@x402/fetch"
import { ExactEvmScheme } from "@x402/evm/exact/client"
import { privateKeyToAccount } from "viem/accounts"
 
const account = privateKeyToAccount(process.env.BUYER_PRIVATE_KEY)
const fetchWithPay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
})
 
const res = await fetchWithPay(
  "https://api.creativeforesight.io/v1/observations/latest?indicator=unemployment_rate&region=47187",
)
console.log(await res.json())
 
// The settlement receipt (tx hash, network, payer).
console.log(decodePaymentResponseHeader(res.headers.get("PAYMENT-RESPONSE")))

End to end: an agent discovers, gets a 402, pays, gets the data

This script covers the whole loop with no account and no API key. It reads the discovery manifest, calls a paid endpoint unauthenticated, reads the 402, pays per call with the x402 client, and prints the data and the on-chain receipt. It needs Node 20+ and a wallet holding a little USDC on Base.

npm install @x402/fetch @x402/evm viem

// agent-demo.mjs — run with: BUYER_PRIVATE_KEY=0x… node agent-demo.mjs
import { decodePaymentResponseHeader, wrapFetchWithPaymentFromConfig } from "@x402/fetch"
import { ExactEvmScheme } from "@x402/evm/exact/client"
import { privateKeyToAccount } from "viem/accounts"
 
const api = "https://api.creativeforesight.io"
const maxAmount = 50_000n // refuse anything above $0.05 (USDC has 6 decimals)
 
// 1. Discover: the manifest lists every payable endpoint, its price, and an
//    example input that returns real data (here: Williamson County, TN's BLS
//    unemployment rate, indicator=unemployment_rate&region=47187).
const manifest = await (await fetch(`${api}/.well-known/x402.json`)).json()
const entry = manifest.resources.find((r) => r.resource.url.endsWith("/v1/observations/latest"))
const example = entry.extensions.bazaar.info.input.queryParams
const url = `${entry.resource.url}?${new URLSearchParams(example)}`
 
// 2. Challenge: an unauthenticated call returns 402 with the requirements.
const challenge = await fetch(url)
const required = JSON.parse(atob(challenge.headers.get("PAYMENT-REQUIRED")))
console.log(challenge.status, required.accepts[0]) // 402 { amount: "10000", network: "eip155:8453", … }
 
// 3. Pay: the x402 client signs a USDC transferWithAuthorization and retries.
const account = privateKeyToAccount(process.env.BUYER_PRIVATE_KEY)
const paidFetch = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
  policies: [(_version, reqs) => reqs.filter((r) => BigInt(r.amount) <= maxAmount)],
})
const res = await paidFetch(url)
const receipt = decodePaymentResponseHeader(res.headers.get("PAYMENT-RESPONSE"))
 
console.log(res.status, await res.json())
console.log(`settled: https://basescan.org/tx/${receipt.transaction}`)

The payment is gasless for the buyer: it signs an EIP-3009 authorization, and the facilitator submits the transfer and pays the gas. The policies cap is the agent’s spending guard. The client refuses any requirement priced above it, so a price change can never drain the wallet. Each run spends one call’s price ($0.01 here).

Doing it by hand

If you build the PAYMENT-SIGNATURE header yourself, sign an exact-scheme USDC transferWithAuthorization for the payTo/asset/network in accepts, base64-encode the x402 payload, and retry:

curl "https://api.creativeforesight.io/v1/observations/latest?indicator=unemployment_rate&region=47187" \
  -H "PAYMENT-SIGNATURE: <base64 x402 payment payload>"

x402 payment configuration

Settlement is non-custodial — funds move directly to the Creative Foresight wallet; the facilitator only verifies signatures and submits the transfer.

Pay with Lightning (L402)

L402  settles the same prices over the Lightning Network — useful when your agent holds sats instead of stablecoins, and the cheapest rail at sub-cent amounts.

1. Call a payable endpoint without an API key.
2. Read the WWW-Authenticate: L402 header from the 402. It carries two values: a macaroon (your access token, held until payment completes) and a bolt11 invoice.
3. Pay the invoice with any Lightning wallet. Paying reveals the preimage — the proof of payment.
4. Retry with both joined by a colon:

curl "https://api.creativeforesight.io/v1/observations/latest?indicator=unemployment_rate&region=47187" \
  -H 'Authorization: L402 <macaroon>:<preimage>'

The API verifies the proof and returns 200 with the data. No account is created; nothing persists but your receipt.

Details worth knowing:

• The invoice is priced in sats from the USD price at the moment of the 402 (e.g. $0.01 ≈ 10 sats).
• A paid credential is valid for 10 minutes and scoped to the endpoint and indicator it was issued for — re-reads within that window are free; a new request scope means a new 402.
• /v1/ask is stricter, on either rail: a payment buys one answer to the exact question, depth and hints it was priced for. Change any of them and you pay again. If you lost the response, repeat the same request within 15 minutes to get the same answer with no second charge.
• Invoices expire with the credential; if one lapses unpaid, just request again for a fresh challenge.

Lightning tooling that understands L402 (such as Aperture-compatible clients  or agent frameworks with L402 fetch wrappers) can drive the whole loop automatically, the same way @x402/fetch does for USDC.

Payable endpoints & prices

Prices are the same on both rails. free and premium are the indicator access_tier values. Premium includes Creative Foresight derived series. See Pricing for the full table. Batch latest requests using indicators= are flat-priced at $0.01 per request no matter how many indicators are included.

Discovery

Payable resources are advertised so agents can find them:

• GET /.well-known/x402.json — a machine-readable manifest of every payable endpoint with its price and payment details.
• The x402 Bazaar  — the CDP facilitator catalogs the resource after its first settlement.
• Every 402 response itself — both rails, self-describing, no prior knowledge needed.