Gate

A paywall is a thin x402 seller in front of one of your endpoints. You declare a price and where the money should land; CodeSpar issues an HTTP 402 challenge on every unpaid call, verifies the agent's signed payment, settles it on-chain, seals a receipt, and only then proxies the request to your upstream. Private headers stay private; there is no order, no session, and no account for the caller to create.

The flow

agent ──GET──▶ gw.codespar.dev/<slug> ──▶ 402 (price, payTo, network)
      ◀────────────────────────────────────┘
agent ──GET + X-PAYMENT──▶ gw.codespar.dev/<slug>
                            │ verify signature
                            │ settle USDC on Base  ──▶ your payTo
                            │ seal receipt
                            └──▶ proxy to your upstream ──▶ 200 + data

Every paid call settles USDC to the address you chose and closes with a hash-chained receipt. A caller that does not pay gets the 402 back; nothing reaches your upstream until the payment verifies.

Create a paywall

Admin auth required. See Authentication.

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": "your-consumer"
  }'

The response carries the gateway URL you share with agents:

{
  "id": "pw_...",
  "slug": "market-data",
  "price": "0.01",
  "currency": "USDC",
  "gateway_url": "https://gw.codespar.dev/market-data",
  "payto_kind": "provisioned",
  "active": true
}

Who gets paid: payto

Pricing

price is a decimal string of USDC per call, minimum "0.01". Endpoint-level pricing: one paywall, one price. Charge different prices by creating more paywalls in front of different upstream paths.

Gate's flat, tiered, and dynamic pricing models are live. If a call's cost depends on how much work it actually did, Meter prices it after the fact and refunds the difference on-chain. Meter is in beta while final mainnet validation completes.

Path passthrough

gw.codespar.dev/<slug> and gw.codespar.dev/<slug>/<path> both dispatch to the paywall; the trailing path is forwarded to your upstream_url. So a single paywall can front a whole API surface, charging the same price per call.

Earnings

Read what a paywall has earned, an aggregate over its settled payments:

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

{ "settled_count": 128, "gross": "1.28", "last_settled_at": "2026-07-10T21:04:11Z" }

The dashboard's Machine payments page shows the same figure inline on each paywall.

Manage

• GET /v1/paywalls: list your project's paywalls.
• PATCH /v1/paywalls/:id: change name, upstream_url, price, or active (pause/resume).
• DELETE /v1/paywalls/:id: remove it.

Full field and error reference: Paywalls API.

Monetized MCP servers

A paywall fronts one endpoint at one price. A monetized MCP server is the same runtime applied to a whole MCP surface: wrap an MCP server you already run, price each tool individually, and point clients at the gateway URL:

https://gw.codespar.dev/mcp/<slug>

Any MCP client connects to that URL instead of your upstream. The gateway only charges a tools/call for a tool you priced: initialize, tools/list, pings, notifications, and calls to unpriced tools proxy through free, so a client can connect and browse the tool catalog without paying. The gateway covers request/response JSON-RPC; a GET SSE stream proxies through, with full streaming fidelity still being completed.

A priced call can be paid two ways at the same interception point:

• Any x402 agent pays exactly as on a paywall. An unpaid priced call gets a 402 with the challenge in the PAYMENT-REQUIRED header; the signed payment goes back in PAYMENT-SIGNATURE (or X-PAYMENT), and the settlement result returns in PAYMENT-RESPONSE.
• A CodeSpar-native agent sends a signed wallet mandate in the X-CODESPAR-PAYMENT header: base64-encoded JSON {"mandate": ..., "signature": "...", "agent_id": "..."} (agent_id optional). The charge verifies against the mandate's cap and allowlist, debits the paying agent's governed wallet, and seals a receipt; the receipt id returns in the x-codespar-receipt response header.

Either way, settlement lands in the provisioned wallet of the consumer_id you named at create time; BYO addresses are not offered for MCP servers. The Idempotency-Key header from the gateway protocol works on paid tool calls too, scoped per tool.

Manage MCP servers

Admin auth required, on /v1/mcp-servers:

• POST /v1/mcp-servers/validate: connect to an upstream_url (optionally with one auth header) and get back the tools it advertises ({ valid, count, tools }), so you can price them before creating anything.
• POST /v1/mcp-servers: create with slug, name, upstream_url, consumer_id, and tools: [{ "tool_name": "...", "price": "0.05" }] (at least one). Returns 201 with the object, including gateway_url.
• GET /v1/mcp-servers and GET /v1/mcp-servers/:id: list, and read one with its priced tools.
• PATCH /v1/mcp-servers/:id: update listing metadata (name, description, category) or active.
• PATCH /v1/mcp-servers/:id/tools/:tool: change one tool's price or active without touching the rest.
• DELETE /v1/mcp-servers/:id: remove the server and its tools.

Tool prices are USDC decimal strings with up to 6 decimals. Slugs are global, one namespace across all MCP servers. If your upstream needs an auth header, pass upstream_auth: { "header": "...", "value": "..." } on create; it is stored encrypted and never returned by the API.

Getting discovered

Every project has a public, machine-readable manifest of its active paywalls:

GET https://gw.codespar.dev/.well-known/x402?project=<projectId>&env=live

No auth; it is meant to be crawled. x402 indexes and buying agents read it to find and price your resources without a single 402 round-trip. env is live or test (default test).

{
  "x402Version": 2,
  "resources": [
    {
      "url": "https://gw.codespar.dev/market-data",
      "description": "Market data API",
      "pricing_model": "flat",
      "accepts": [
        {
          "scheme": "exact",
          "network": "eip155:8453",
          "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "amount": "10000",
          "payTo": "0x...",
          "maxTimeoutSeconds": 120,
          "extra": { "name": "USD Coin", "version": "2" }
        }
      ]
    }
  ]
}

Each entry mirrors the live 402 challenge of its gateway URL, so what a crawler reads here equals what the endpoint actually charges. A tiered paywall advertises its current tier. A dynamic or metered paywall carries "variable_price": true because the advertised amount is not the exact charge: the fallback price for dynamic, the ceiling for metered.

Only active paywalls appear. Pause one and it leaves the manifest; there is nothing to submit or refresh. To preview your own manifest, call GET https://api.codespar.dev/v1/discovery/manifest with your API key: it returns { "manifest": ..., "project_id": ..., "environment": ... } scoped to your authenticated project and environment.

Need Pix too?

Paywalls settle in USDC. When the payer might be a person in Brazil rather than an agent, use a Collect payment link: the same gateway serves one shareable URL where an agent pays over x402/USDC and a person pays via Pix, under the same receipt model. Early access.

Related

• Meter: post-paid metered pricing on a Gate paywall (beta).
• Pay to Agent: the other direction: an agent pays another agent by Agent ID.
• Facilitator: how x402 verification and settlement work.
• Audit chain: the receipt every settlement seals.