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.
• 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.