Usage charges (upto)

The x402 upto scheme charges for actual usage up to a ceiling. The buyer authorizes a maximum; your handler runs and meters real consumption; the operator settles only what was used and refunds the difference.

It exists because a plain signed transfer commits to an exact amount — once signed, the server can't lower it. upto breaks that: the buyer signs a ceiling, and the operator settles the actual amount against it afterward.

When to use it

Reach for upto when one call's cost is unknown until it runs:

• an LLM completion billed per output token,
• a request billed per byte returned or per second of compute,
• any single job where you can only price it once the work is done.

An upto authorization settles at most once. If you instead want to meter many deliveries over a reused channel (a token stream, a burst of cheap calls), use streaming sessions.

How it flows

The buyer signs the channel open (committing the ceiling). Unlike exact, they do not sign the charge — the operator settles a single voucher for the metered amount after serving, then closes the channel and refunds the unused deposit. The operator is the channel payee, the settlement signer, and the fee payer, so it can always settle without the buyer's help.

With the pay CLI

Declare a metering block with schemes: [x402-upto]. The metering tier's price_usd is the ceiling; min_usd is the amount settled on a successful serve (until your gateway wires a real per-unit meter), clamped to the ceiling:

endpoints:
  - method: POST
    path: 'api/v1/summarize'
    description: 'Summarize text, billed per token (x402 upto).'
    metering:
      schemes: [x402-upto]
      min_usd: 0.01 # default settled voucher (USD), clamped to the ceiling
      dimensions:
        - direction: usage
          unit: requests
          scale: 1
          tiers:
            - price_usd: 0.10 # the authorized ceiling — "up to $0.10"

Run it:

pay --sandbox server start provider.yml

On the wire

upto rides x402 v2 transport:

• PAYMENT-REQUIRED (402) — scheme: "upto", amount = the ceiling, extra.profiles: ["payment-channel"], extra.feePayer = the operator.
• PAYMENT-SIGNATURE (retry) — an UptoPayload with maxAmount (= the signed ceiling), channelId, deposit, authorizedSigner (the operator), and the channel open (broadcast signature or unsigned openTransaction).
• PAYMENT-RESPONSE — the settlement result: success, the actual amount charged, and the settlement transaction.

Full details: the x402 upto SVM scheme spec.

Next

• Streaming sessions (MPP) — meter many deliveries over one channel.
• upto vs sessions — when to pick which.
• Defining pricing — the metering dimensions and tiers upto builds on.