coal
coal

Proxy Mode

Wrap any existing REST API with x402 + USDC settlement without touching its code. You give Coal your origin URL; Coal returns a public proxy URL.

When to use proxy mode

  • Your API runs somewhere you do not want to modify (RapidAPI listing, third-party hosted service, internal API you have read access to but not deploy access).
  • You want to ship in minutes, not days.
  • You are fine with Coal sitting on the request path.

If you can drop code into your API server, see SDK mode instead — it has slightly lower latency and no third party on the request path.

Five-step walkthrough

1. Sign in to the console. If you have no payout address yet, Settings → Payout Address.

2. Open the Paywalls page, click New Paywall ▾ → Proxy to upstream API, and enter:

  • Bundle name — e.g. "Twitter AIO"
  • Origin URL — https://twitter-aio.example.com (no trailing slash, no path)
  • Origin auth header (optional) — key + value pair, encrypted at rest

3. Add your first endpoint:

  • Endpoint name — "User lookup"
  • Method — GET
  • Path template — /user/{username} (brace-wrapped segments match any value)
  • Price — 0.05 (USDC; $0.05 is the recommended minimum on Base)

4. Submit. The wizard shows your public URL:

text
1https://api.usecoal.xyz/p/twitter-aio/user/{username}

5. Test with curl:

bash
1curl -i https://api.usecoal.xyz/p/twitter-aio/user/jack

Expected response: 402 Payment Required with x402 PaymentRequirements in the X-PAYMENT header and the JSON body. Any x402-capable agent can now sign an EIP-3009 USDC authorization, post it back as X-Payment, and receive your origin's response.

What happens on a paid call

  1. Agent POSTs the same URL with X-Payment: <base64-encoded signed auth>.
  2. Coal decodes and validates the payload (signature recovery off-chain to reject garbage cheaply).
  3. Coal submits transferWithAuthorization on Base — operator wallet pays gas; payer's USDC moves to the recipient.
  4. If the merchant has a 0xSplits Push Split deployed (fee-tier merchants), recipient is the split address; otherwise it is the merchant's payout address.
  5. Coal forwards the request to your origin URL with any stored auth headers decrypted and attached.
  6. Origin response streams back to the agent with x-payment-response: 0x<txHash> stamped on.

Cost model

  • $0.05/call → operator pays ~$0.003 gas → merchant nets ~$0.0475 → Coal takes 5% ($0.0025) → break-even-ish for Coal.
  • For design partners, the fee is 0% (set via the admin endpoint; see Pricing).
  • Public-beta merchants get 0% until announcement.

See Pricing and the Roadmap for the official fee schedule.

Limitations

  • No streaming responses today — origin must return a complete response.
  • No multi-step / stateful flows (sessions, cookies, retained auth).
  • One bundle = one origin. If your API spans multiple origins, create multiple bundles.
  • Path templates support brace-wrapped segments ({username}) but not regex or wildcards.

If you hit a wall, reach out — most limitations are scheduled, not architectural.