Create a paywall

One POST /v1/paywalls names your upstream, sets the price, and says where the money lands (full reference). Prefer clicking? The dashboard's Machine payments page has a create drawer with the same fields.

curl -X POST https://api.codespar.dev/v1/paywalls \
  -H "authorization: Bearer $CODESPAR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "slug": "market-data",
    "name": "Market data API",
    "upstream_url": "https://api.yourservice.com/quote",
    "price": "0.01",
    "payto": { "kind": "provisioned" },
    "consumer_id": "you"
  }'

payto decides who gets paid, and settlement is non-custodial either way. provisioned settles into the CodeSpar-derived wallet of the consumer_id you pass, a governed wallet your own agent can later spend from. { "kind": "byo", "address": "0x..." } settles straight to an EVM address you already hold.

The 201 response carries the URL you share with the world:

{
  "id": "pw_9f81c2",
  "slug": "market-data",
  "price": "0.01",
  "currency": "USDC",
  "pricing_model": "flat",
  "gateway_url": "https://gw.codespar.dev/market-data",
  "active": true
}

Flat pricing is the default. Tiered price curves and dynamic per-request pricing are live too; post-paid metered pricing is in beta, see Meter. Slugs are a global namespace, and gw.codespar.dev/market-data/<path> forwards the trailing path to your upstream, so one paywall can front a whole API surface.

Curl it and read the 402

curl -i https://gw.codespar.dev/market-data

HTTP/2 402
payment-required: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJwYXltZW50IHJlcXVpcmVkIi...

The challenge arrives base64-encoded in the PAYMENT-REQUIRED response header; the JSON body of the 402 is only a human-readable hint. Decode the header and you get an x402 version 2 challenge:

curl -sD - -o /dev/null https://gw.codespar.dev/market-data \
  | awk 'tolower($1)=="payment-required:" {print $2}' | base64 -d

{
  "x402Version": 2,
  "error": "payment required",
  "resource": {
    "url": "https://gw.codespar.dev/market-data",
    "mimeType": "application/json",
    "description": "Market data API"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "10000",
      "payTo": "0x15cA...9E41",
      "maxTimeoutSeconds": 120,
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ]
}

amount is atomic USDC (6 decimals), so 10000 is your $0.01. network follows the paywall's environment: eip155:8453 (Base mainnet) on live, eip155:84532 (Base Sepolia) on test. Nothing has reached your upstream yet, and nothing will until a payment verifies.

Pay it

An x402-capable client reads the header, signs the payment, and retries the call.

npx @codespar/cli mandate create \
  --consumer you --agent smoke-test \
  --purpose "first paid call on my own paywall" \
  --payee https://gw.codespar.dev/market-data \
  --cap 10 --per-tx-cap 1

codespar spend --mandate cm_xxx --agent smoke-test \
  --payee https://gw.codespar.dev/market-data --amount 1

Either way, the gateway verifies the signature, settles the exact amount on-chain to your payTo, seals a hash-chained receipt, and only then proxies the request to your upstream.

Read the receipt and the earnings

curl https://api.codespar.dev/v1/paywalls/pw_9f81c2/stats \
  -H "authorization: Bearer $CODESPAR_API_KEY"

{
  "paywall_id": "pw_9f81c2",
  "slug": "market-data",
  "currency": "USDC",
  "settled_count": 1,
  "gross_atomic": "10000",
  "gross": "0.01",
  "refunded_atomic": "0",
  "refunded": "0",
  "net_atomic": "10000",
  "net": "0.01",
  "last_settled_at": "2026-08-06T18:22:41Z"
}

net is what landed and stayed. On flat, tiered, and dynamic paywalls gross equals net; on a metered paywall the gap is the on-chain refund of unused ceiling, which is the feature working, not revenue lost (Meter). The same figures show inline on each paywall in Machine payments, and every settlement seals a receipt in the audit chain.