Skip to main content
All use cases
Usage-based API billingSaaS

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.

BeforeA flat price per call, padded for the worst case
AfterThe ceiling in the 402, the rest refunded
402 → refund
the unused ceiling goes back on-chain
Try it in the Sandbox
base × max
Ceiling in the 402
Base price times the maximum multiplier: the most the caller pays
X-Pages
Your API reports
The multiplier comes from a response header you choose, clamped between min and max
USDC
Refund on-chain
The difference goes back from the seller's wallet; dust below the gas cost is waived
off · on
Per deployment
Metered pricing is off until the operator enables it
Illustrative example · demo data

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.

Metered call · example
call_8f21 · /extract
Refunded · example
Ceiling in the 402US$ 0.80 · USDC
ReportedX-Pages: 17
ActualUS$ 0.34
RefundedUS$ 0.46 · on-chain
receipt-call8f21.json
✓ metered · refunded · examplecall_8f21
The pain

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

How the agent does it

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.

01
Create
POST /v1/paywalls

A metered paywall

02
402
Gate

The ceiling advertised

03
Call
Your API

Your API reports the multiplier

04
Meter
Gate

Actual = base × multiplier

05
Refund
Seller's wallet

Ceiling minus actual, on-chain

Architecture

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.

In code

The code, and what it assumes.

metered-api-access.ts
// 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.

Featured tools
POST /v1/paywalls

Creates the paywall; pricing_model metered takes metered_config and a provisioned payTo.

See the meta-tool reference

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.

Metered API access — CodeSpar | CodeSpar