x402 specification

We didn’t build on the standard. We extended it.

x402 defines upto for EVM only. scheme_upto_hedera.md is the first non-EVM one — written from scratch, shipped in three npm packages, and destined for the upstream repo.

The one rule that separates it from exact

The amount means two different things. Drag it.

Under exact the charge must equal the signed amount. Under upto it may be anything from $0 up to the ceiling — but the signature is always verified against the maximum, never the settle amount. Get that wrong and you charge the full ceiling every time.

the metered charge$0.130
ceiling $0.50
✓ settles $0.130 — the signature still verifies against the $0.50 you authorised. The unspent $0.370 never moves.
facilitator logic
// verify(): against the MAXIMUM — what the client signed
maxAmount    = 500000      // $0.50 ceiling

// settle(): the ACTUAL metered charge
settleAmount = 130000  // ← you set this

require(settleAmount <= maxAmount)  // ✓

// re-verify signature against maxAmount,
// NEVER against settleAmount.
Scheme properties
Protocol versionx402Version: 2
Networkshedera:mainnet · hedera:testnet (CAIP-2)
Assetsany HTS fungible token · HBAR is not supported
Amountssmallest unit per the token’s decimals
Fee modela facilitator submits capture() and pays the fee
EnforcementX402UptoProxy — the Hedera analogue of Permit2
Facilitator verification rules (MUST)
ARequirements parity

accepted.amount is the signed maximum; the settle-time amount is the actual charge. The facilitator asserts actual ≤ maximum — and, unlike exact, must NOT require them equal.

BAuthorization integrity

ecrecover(digest) == authorization.from; from resolves to a real ECDSA-alias account; maxAmount matches the advertised ceiling; within the time bounds.

COn-chain state

nonce unused (read from a consensus node, never a lagging relay); allowance covers the ceiling; balance covers the charge; payTo can receive the asset.

DSettlement

Re-run A–C at settle time, re-verifying the signature against the maximum. The amount may be 0 — the nonce still burns.

A gap in the standard

The spec also names a hole in every chain, not just Hedera.

The canonical offer-receipt payloads carry no meter reading — the offer commits an amount, the receipt a payer and a transaction id. Neither commits the unit price or the units consumed. So an upto receipt is unverifiable as written, on any network. Tally documents this and fixes it with a signed price schedule and meter reading.

AUTHORISE A CEILING · PAY THE ACTUAL ✦ FIRST NON-EVM UPTO IN X402 ✦ SOFTWARE PAYS SOFTWARE · NO HUMAN IN THE LOOP ✦ AN OVERCHARGE IS ARITHMETIC ANYONE CAN CHECK ✦ RECEIPTS ON HCS · $0.0001 EACH ✦ AUTHORISE A CEILING · PAY THE ACTUAL ✦ FIRST NON-EVM UPTO IN X402 ✦ SOFTWARE PAYS SOFTWARE · NO HUMAN IN THE LOOP ✦ AN OVERCHARGE IS ARITHMETIC ANYONE CAN CHECK ✦ RECEIPTS ON HCS · $0.0001 EACH ✦