Charge the ceiling. Refund what the call did not use.
Extracta, in this example, sells document extraction as an API, and a one-page receipt costs less to process than a forty-page contract. With a metered paywall on Gate, the 402 advertises a ceiling: a base price times a maximum multiplier. The caller pays the ceiling; after the call, the multiplier Extracta reports in a response header sets the actual price, clamped between the minimum and the maximum, and the difference is refunded on-chain from Extracta's wallet. Metered pricing is off on a deployment until the operator enables it.
One extraction, priced by its pages.
An example with demo data: a contract through a metered paywall with a base of US$ 0.02 per page and a maximum of 40. The 402 asks for the ceiling, US$ 0.80; the API reports 17 pages, so the actual is US$ 0.34 and US$ 0.46 goes back on-chain.
- The caller pays the ceiling the 402 advertises
- Your API reports the multiplier in a response header
- The difference is refunded on-chain from the seller's wallet
Extract the line items from this vendor contract.
The extraction endpoint asks at most US$ 0.80 in its 402: paying the ceiling; the actual comes from the pages it reports.
The conversation is the easy part.
Usage-based APIs guess. A flat per-call price overcharges the easy jobs or eats the loss on the hard ones, and nobody finds out which until the invoice runs.
Price every call flat, padded for the worst case
The 402 advertises a ceiling; the actual follows what the call used
Chase a shortfall on the hard jobs
The multiplier your API reports prices the call, up to the ceiling
Let callers overpay on easy jobs
The difference between ceiling and actual is refunded on-chain
Refund by hand and argue over it
The refund is sent once per settlement and confirmed on-chain
A metered paywall, on the seller's side.
The seller creates a paywall with pricing_model metered: a base price, a minimum and maximum multiplier, and the response header that carries the multiplier. The 402 advertises the ceiling, the base times the maximum. After the call, the gateway reads the header, clamps it, charges the actual and refunds the rest on-chain from the seller's provisioned wallet. A deployment answers metered_not_enabled until the operator enables metered pricing.
A metered paywall
The ceiling advertised
Your API reports the multiplier
Actual = base × multiplier
Ceiling minus actual, on-chain
The metered paywall stores a base price in USDC atomic units, a minimum and maximum multiplier and the response header to read. The 402 advertises base × maximum; the caller pays it. After the upstream call, the gateway reads the header (a missing or invalid value counts as the minimum), clamps it, and the refund of ceiling minus actual is claimed once per settlement before it is sent from the seller's provisioned wallet, then confirmed against the chain. Creating or settling a metered paywall is refused until the operator enables metered pricing.
The code, and what it assumes.
// Prerequisites: CODESPAR_API_KEY with the admin role, a deployment where the // operator enabled metered pricing (otherwise the API answers // metered_not_enabled), and a consumer whose provisioned wallet receives the // payments and sends the refunds. import { CodeSpar } from "@codespar/sdk"; const cs = new CodeSpar(); // the seller's paywall: US$ 0.02 per page, up to 40 pages; the 402 asks for the // ceiling (US$ 0.80) and the X-Pages header of the response sets the actual const res = await cs.api.response("post", "/v1/paywalls", { body: { slug: "extract", name: "Document extraction", upstream_url: "https://api.extracta.example/extract", price: "0.02", pricing_model: "metered", metered_config: { basis: "units", base_atomic: "20000", min_mult: 1, max_mult: 40, units_header: "X-Pages" }, payto: { kind: "provisioned" }, consumer_id: "user_0000", }, }); console.log(res.status, res.ok ? res.data : null);
Example with the published SDK (@codespar/sdk 0.16.11). Its prerequisites are in the comments. Compiling does not prove the integration: run it in test mode first.
POST /v1/paywallsCreates the paywall; pricing_model metered takes metered_config and a provisioned payTo.
Start with a test key.
Test keys are free. Open the sandbox, connect the providers your project uses and see which tools it can call before you build.