# Usage charges (upto)

> x402 upto — authorize a ceiling for one metered call, then settle the actual amount and refund the rest. For costs you only know after the work runs.

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](/docs/building-with-pay/payment-channels/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.

<Mermaid
  chart={`sequenceDiagram
  participant C as Client
  participant G as pay gateway (operator)
  participant Ch as Channel program
  C->>G: request
  G-->>C: 402 PAYMENT-REQUIRED (scheme upto, amount = ceiling)
  C->>G: retry + PAYMENT-SIGNATURE (open, deposit = ceiling)
  G->>Ch: co-sign + broadcast open (operator pays fees)
  G->>G: run handler, meter actual usage
  G->>Ch: settle_and_finalize (operator voucher = actual) + distribute
  Ch-->>C: refund unused deposit
  G-->>C: 200 + PAYMENT-RESPONSE (actual amount, settlement tx)`}
/>

## 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:

```yaml
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:

```sh
pay --sandbox server start provider.yml
```

<Callout type="info">
  `upto` settlement is **operator-signed**, so the gateway needs an operator signer (it co-signs the channel open as fee
  payer and signs the settlement voucher). On `--sandbox` this is provisioned for you; in production set
  `operator.signer` + `operator.fee_payer: true` in the spec.
</Callout>

## 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](https://github.com/solana-foundation/x402/blob/main/specs/schemes/upto/scheme_upto_svm.md).

## Next

- [Streaming sessions (MPP)](/docs/building-with-pay/payment-channels/sessions) — meter many deliveries over one channel.
- [upto vs sessions](/docs/building-with-pay/payment-channels/choosing) — when to pick which.
- [Defining pricing](/docs/building-with-pay/pricing) — the metering dimensions and tiers `upto` builds on.