x402-hedera-upto

The x402 upto scheme for Hedera. The client authorises a maximum; the server settles the actual amount consumed.

x402 defines upto for usage-based pricing — the scheme you need whenever the price is only knowable after the work is done: LLM tokens, bandwidth, compute. Until now it existed only for EVM, on Permit2. Hedera had exact and nothing else.

This is upto for Hedera. It settles any HTS fungible token (USDC), and the client never sends a transaction or pays a network fee — not once.

exact:  "this costs $0.05."  →  pay $0.05.          the price must be known up front
upto:   "this costs at most $0.50."  →  charged $0.0731.   the price is discovered by doing the work

How it works

The client grants X402UptoProxy an HTS token allowance once (AccountAllowanceApproveTransaction, HIP-336). After that, paying costs the client a single off-chain EIP-712 signature — no transaction, no gas, no HBAR.

The facilitator submits capture() with the metered amount and pays the network fee. The contract enforces the scheme's four MUSTs, so neither a malicious facilitator nor a malicious resource server can take more than the client signed for, take it twice, take it late, or send it anywhere the client did not name:

| MUST | Enforced by | | --- | --- | | single-use | nonceUsed[from][nonce] — burned even on a zero charge | | time-bound | validAfter <= block.timestamp <= deadline | | recipient binding | payTo is inside the signed struct; editing it invalidates the signature | | max amount | amount <= maxAmount; the amount may be 0 |

Plus facilitator binding: only the facilitator the client named in the signature may settle it.

The proxy has no owner, no admin, no pause and no upgrade path. It never custodies the token and holds no balance.

Under the hood this is the Hedera counterpart of Permit2. HIP-376 makes an HTS token's ERC-20 facade spend transferFrom against the caller's allowance, and HIP-336 lets that allowance be granted to a contract — so an allowance granted with the SDK is spendable by the proxy. Verified on testnet.

Install

npm i x402-hedera-upto @x402/core @hiero-ledger/sdk

Client — sign a ceiling, pay nothing

import { x402Client } from '@x402/core/client';
import { createUptoClientSigner } from 'x402-hedera-upto';
import { UptoHederaScheme } from 'x402-hedera-upto/upto/client';
import { PrivateKey } from '@hiero-ledger/sdk';

const signer = createUptoClientSigner('0.0.CLIENT', PrivateKey.fromStringECDSA(KEY), {
  network: 'hedera:testnet',
});

const client = new x402Client().register('hedera:*', new UptoHederaScheme(signer));
// 402s are now answered with a signed authorisation, automatically.

Resource server — advertise a maximum, settle the actual

import { x402ResourceServer } from '@x402/core/server';
import { UptoHederaScheme } from 'x402-hedera-upto/upto/server';

server.register('hedera:*', new UptoHederaScheme({
  defaultAssets: { 'hedera:testnet': { asset: '0.0.429274', decimals: 6 } }, // USDC
}));

// ...do the work, then charge for exactly what it consumed:
const actual = String(outputTokens * unitPrice);
await server.settlePayment(payload, requirements, undefined, undefined, { amount: actual });
//                                                                       ^^^^ the 5th argument

SettleResponse.amount comes back as the amount actually taken.

Facilitator — verify and settle

import { createUptoFacilitatorSigner, accountEvmAddress } from 'x402-hedera-upto';
import { UptoHederaScheme } from 'x402-hedera-upto/upto/facilitator';

const scheme = new UptoHederaScheme(
  createUptoFacilitatorSigner('0.0.FAC', key, { proxyContractId: '0.0.PROXY' }),
  {
    proxyContractId: '0.0.PROXY',
    chainId: 296,
    facilitatorEvm: await accountEvmAddress('0.0.FAC', 'hedera:testnet'),
  },
);

No public Hedera facilitator supports upto today, so you must run your own — which x402 explicitly encourages, and Hedera's docs ask for.

Requirements

• The client account must be ECDSA with an EVM alias. ecrecover returns the alias, and it is the only address form HTS resolves. An ED25519 account cannot sign an upto authorisation.
• payTo must be associated with the asset, or have an auto-association slot.
• The client's allowance to the proxy must cover the ceiling it signs, not just today's charge.
• Native HBAR (0.0.0) is not supported. An HBAR allowance is unreachable from a contract through the ERC-20 facade; it needs the Hedera Account Service path (HIP-906). upto here is a stablecoin-metering scheme. Contributions welcome.

Spec

Implements scheme_upto.md for Hedera. The network-specific spec is scheme_upto_hedera.md.

License

Apache-2.0