Upto

The upto scheme lets a seller advertise a maximum price for one request, then settle for the actual amount used. The buyer signs once for the maximum, and the server chooses a final amount that is less than or equal to that maximum. Use upto for one-request usage metering, such as LLM token generation, bandwidth, compute time, or dynamic data queries.

Server Setup

Set the route price to the maximum authorized amount. In the handler, use settlement overrides to charge the actual amount.

TypeScript (EVM)
TypeScript (SVM)
Go (EVM)
Go (SVM)
Python

import { paymentMiddleware, setSettlementOverrides, x402ResourceServer } from "@x402/express";
import { UptoEvmScheme } from "@x402/evm/upto/server";

const resourceServer = new x402ResourceServer(facilitatorClient)
  .register("eip155:84532", new UptoEvmScheme());

app.use(paymentMiddleware({
  "GET /api/generate": {
    accepts: {
      scheme: "upto",
      price: "$0.10",
      network: "eip155:84532",
      payTo: "0xYourAddress",
    },
    description: "AI text generation billed by usage",
  },
}, resourceServer));

app.get("/api/generate", (req, res) => {
  const actualUsage = computeActualCost();
  setSettlementOverrides(res, { amount: String(actualUsage) });
  res.json({ result: "..." });
});

import { base58 } from "@scure/base";
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { paymentMiddleware, setSettlementOverrides, x402ResourceServer } from "@x402/express";
import { UptoSvmScheme } from "@x402/svm/upto/server";
import { HTTPFacilitatorClient } from "@x402/core/server";

const receiverAuthorizerSigner = await createKeyPairSignerFromBytes(
  base58.decode(process.env.SVM_RECEIVER_AUTHORIZER_PRIVATE_KEY),
);

const resourceServer = new x402ResourceServer(facilitatorClient)
  .register(
    "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
    new UptoSvmScheme({
      receiverAuthorizerSigner, // omit for facilitator-delegated mode
      rpcUrl: process.env.SVM_RPC_URL, // optional: embeds recentBlockhash in 402
    }),
  );

app.use(paymentMiddleware({
  "GET /api/generate": {
    accepts: {
      scheme: "upto",
      price: "$0.10",
      network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
      payTo: "YourSolanaAddress",
    },
    description: "AI text generation billed by usage",
  },
}, resourceServer));

app.get("/api/generate", (req, res) => {
  const actualUsage = computeActualCost();
  setSettlementOverrides(res, { amount: String(actualUsage) });
  res.json({ result: "..." });
});

routes := x402http.RoutesConfig{
    "GET /api/generate": {
        Accepts: x402http.PaymentOptions{
            {
                Scheme:  "upto",
                Price:   "$0.10",
                Network: "eip155:84532",
                PayTo:   "0xYourAddress",
            },
        },
        Description: "AI text generation billed by usage",
    },
}

mux.HandleFunc("GET /api/generate", func(w http.ResponseWriter, r *http.Request) {
    actualUsage := computeActualCost()
    nethttpmw.SetSettlementOverrides(w, &x402.SettlementOverrides{
        Amount: fmt.Sprintf("%d", actualUsage),
    })
    _ = json.NewEncoder(w).Encode(map[string]string{"result": "..."})
})

import (
    x402 "github.com/x402-foundation/x402/go/v2"
    x402http "github.com/x402-foundation/x402/go/v2/http"
    ginmw "github.com/x402-foundation/x402/go/v2/http/gin"
    uptosvm "github.com/x402-foundation/x402/go/v2/mechanisms/svm/upto/server"
    svmsigners "github.com/x402-foundation/x402/go/v2/signers/svm"
)

authorizer, err := svmsigners.NewReceiverAuthorizerSignerFromPrivateKey(
    os.Getenv("SVM_RECEIVER_AUTHORIZER_PRIVATE_KEY"),
)
if err != nil {
    log.Fatal(err)
}

r.Use(ginmw.X402Payment(ginmw.Config{
    Routes: x402http.RoutesConfig{
        "GET /api/generate": {
            Accepts: x402http.PaymentOptions{
                {
                    Scheme:  "upto",
                    Price:   "$0.10",
                    Network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
                    PayTo:   "YourSolanaAddress",
                },
            },
            Description: "AI text generation billed by usage",
        },
    },
    Facilitator: facilitatorClient,
    Schemes: []ginmw.SchemeConfig{
        {
            Network: x402.Network("solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"),
            Server: uptosvm.NewUptoSvmScheme(&uptosvm.Config{
                ReceiverAuthorizerSigner: authorizer,
                RPCURL:                   os.Getenv("SVM_RPC_URL"),
            }),
        },
    },
}))

r.GET("/api/generate", func(c *gin.Context) {
    actualUsage := computeActualCost()
    ginmw.SetSettlementOverrides(c, &x402.SettlementOverrides{
        Amount: fmt.Sprintf("%d", actualUsage),
    })
    c.JSON(http.StatusOK, gin.H{"result": "..."})
})

from fastapi import FastAPI, Response

from x402.http import FacilitatorConfig, HTTPFacilitatorClient, PaymentOption
from x402.http.middleware.fastapi import PaymentMiddlewareASGI, set_settlement_overrides
from x402.http.types import RouteConfig
from x402.mechanisms.evm.upto import UptoEvmServerScheme
from x402.server import x402ResourceServer

app = FastAPI()
facilitator = HTTPFacilitatorClient(FacilitatorConfig(url="https://x402.org/facilitator"))

server = x402ResourceServer(facilitator)
server.register("eip155:84532", UptoEvmServerScheme())

routes = {
    "GET /api/generate": RouteConfig(
        accepts=[
            PaymentOption(
                scheme="upto",
                price="$0.10",
                network="eip155:84532",
                pay_to="0xYourAddress",
            )
        ],
        description="AI text generation billed by usage",
    )
}

app.add_middleware(PaymentMiddlewareASGI, routes=routes, server=server)

@app.get("/api/generate")
async def generate(response: Response) -> dict[str, str]:
    actual_usage = compute_actual_cost()
    set_settlement_overrides(response, {"amount": str(actual_usage)})
    return {"result": "..."}

Client Setup

TypeScript (EVM)
TypeScript (SVM)
Go (EVM)
Go (SVM)
Python

import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { UptoEvmScheme } from "@x402/evm/upto/client";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(signer));
client.register("eip155:*", new UptoEvmScheme(signer));

import { x402Client } from "@x402/core/client";
import { ExactSvmScheme } from "@x402/svm/exact/client";
import { UptoSvmScheme } from "@x402/svm/upto/client";
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";

const signer = await createKeyPairSignerFromBytes(
  base58.decode(process.env.SVM_PRIVATE_KEY),
);

const client = new x402Client();
client.register("solana:*", new ExactSvmScheme(signer)); // fixed-price services
client.register("solana:*", new UptoSvmScheme(signer));  // usage-based services

import (
    x402 "github.com/x402-foundation/x402/go/v2"
    exactevm "github.com/x402-foundation/x402/go/v2/mechanisms/evm/exact/client"
    uptoevm "github.com/x402-foundation/x402/go/v2/mechanisms/evm/upto/client"
    evmsigners "github.com/x402-foundation/x402/go/v2/signers/evm"
)

evmSigner, err := evmsigners.NewClientSignerFromPrivateKey(os.Getenv("EVM_PRIVATE_KEY"))
if err != nil {
    log.Fatal(err)
}

x402Client := x402.Newx402Client().
    Register("eip155:*", exactevm.NewExactEvmScheme(evmSigner, nil)).
    Register("eip155:*", uptoevm.NewUptoEvmScheme(evmSigner, nil))

import (
    x402 "github.com/x402-foundation/x402/go/v2"
    exactsvm "github.com/x402-foundation/x402/go/v2/mechanisms/svm/exact/client"
    uptosvm "github.com/x402-foundation/x402/go/v2/mechanisms/svm/upto/client"
    svmsigners "github.com/x402-foundation/x402/go/v2/signers/svm"
)

svmSigner, err := svmsigners.NewClientSignerFromPrivateKey(os.Getenv("SVM_PRIVATE_KEY"))
if err != nil {
    log.Fatal(err)
}

x402Client := x402.Newx402Client().
    Register("solana:*", exactsvm.NewExactSvmScheme(svmSigner)).      // fixed-price services
    Register("solana:*", uptosvm.NewUptoSvmScheme(svmSigner, nil))    // usage-based services

import os

from eth_account import Account

from x402 import x402Client
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client
from x402.mechanisms.evm.upto import UptoEvmScheme

account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
signer = EthAccountSigner(account)

client = x402Client()
register_exact_evm_client(client, signer)
client.register("eip155:*", UptoEvmScheme(signer))

Settlement Override Formats

amount can be expressed as:

Format	Example	Meaning
Raw atomic units	`"50000"`	Settle exactly 50,000 token base units
Percentage	`"50%"`	Settle 50% of the route maximum
Dollar price	`"$0.05"`	Convert a dollar-denominated route price to base units

Setting the amount to "0" means no charge for that request. On SVM, a zero-amount close still lands a transaction to release the escrowed deposit and channel rent.

EVM Implementation

upto on EVM uses Permit2 because the settled amount is not known when the buyer signs. The facilitator advertises a facilitatorAddress in the payment requirements, and the client binds the authorization to that facilitator.

SVM Implementation

upto on Solana uses the payment-channels program. The client escrows the ceiling amount in an onchain channel (open), and the server settles the actual amount with a signed voucher (settle_and_seal + distribute). The facilitator sponsors transaction fees and channel rent as a zero-share channel payee, and can always close abandoned channels to recover rent. Every channel commits to a receiverAuthorizer (authorized_signer) that signs settlement vouchers. Pick one:

Mode	Server config	When to use
Self-managed (recommended)	Pass `receiverAuthorizerSigner`	Any facilitator can relay your signed vouchers; channels survive facilitator changes
Facilitator-delegated	Omit `receiverAuthorizerSigner`	Simpler ops (no server hot key); requires a facilitator that advertises `receiverAuthorizer` and authenticates your settle requests out of band

Self-managed: pass a hot Ed25519 key that does not need SOL or tokens. Facilitator-delegated: the server picks up extra.receiverAuthorizer from the facilitator’s /supported response; the facilitator signs claim vouchers after correlating deposit and claim settles to the same authenticated caller. The server validates this at startup — if no local signer is configured and the facilitator does not advertise a valid receiverAuthorizer, initialize() fails before the first request. For custom facilitator implementations, use UptoSvmScheme from the facilitator package. The scheme’s rent cleanup manager asynchronously seals and reclaims rent from abandoned channels:

TypeScript
Go

import { toFacilitatorSvmSigner } from "@x402/svm";
import { UptoSvmScheme } from "@x402/svm/upto/facilitator";

// Pass the RPC URL to the signer, not to UptoSvmScheme
const svmSigner = toFacilitatorSvmSigner(
  keypair,
  process.env.SVM_RPC_URL ? { defaultRpcUrl: process.env.SVM_RPC_URL } : undefined,
);
const svmUptoScheme = new UptoSvmScheme(svmSigner, {
  maxChannelLifetimeSecs: 3600,
  // Optional: advertise receiverAuthorizer for delegated server mode.
  // Requires resolveCallerIdentity — construction throws without it.
  // authorizerSigner,
  // resolveCallerIdentity: ctx => authenticateSettleCaller(ctx),
  // Optional: tune channel re-read behavior after a confirmed open.
  // Re-reads use linear backoff: attempt N waits N * channelReadBackoffStepMs.
  // Defaults: 6 attempts, 200ms step (200/400/600/800/1000ms, totalling 3.0s).
  // Raise these on RPC providers with slower replica convergence.
  // channelReadMaxAttempts: 6,
  // channelReadBackoffStepMs: 200,
});

facilitator.register("solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", svmUptoScheme);

// Reclaim PDA rent from sealed/distributed channels
const rentCleanup = svmUptoScheme.createRentCleanupManager(
  "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
);
rentCleanup.start({ intervalSecs: 60, discoveryIntervalSecs: 86_400 });

import (
    uptosvm "github.com/x402-foundation/x402/go/v2/mechanisms/svm/upto/facilitator"
)

// Pass the RPC URL to the signer, not to uptosvm.Config
maxChannelLifetimeSecs := 3600
scheme := uptosvm.NewUptoSvmScheme(svmSigner, &uptosvm.Config{
    MaxChannelLifetimeSecs: &maxChannelLifetimeSecs,
    // Optional: advertise receiverAuthorizer for delegated server mode.
    // Requires ResolveCallerIdentity — construction panics without it.
    // AuthorizerSigner: authorizer,
    // ResolveCallerIdentity: func(ctx uptosvm.DelegatedSettleContext) (string, error) {
    //     return authenticateSettleCaller(ctx) // JWT / SIWX / mTLS subject
    // },
    // Optional: shared store for multi-replica facilitators. Default is in-memory.
    // DelegatedAuthStore: sharedRedisDelegatedAuthStore,
})
facilitator.Register([]x402.Network{network}, scheme)

// Reclaim PDA rent from abandoned, sealed, and distributed channels
cleanup := scheme.NewRentCleanupManager(string(network))
cleanup.Start(ctx, uptosvm.StartConfig{
    Interval:          5 * time.Minute,
    DiscoveryInterval: 24 * time.Hour,
})
defer cleanup.Stop()

Welcome

Getting Started

Core Concepts

Payment Schemes

Extensions

Advanced Concepts

Guides

Developer Tools

SDK Features

Server Setup

Client Setup

Settlement Override Formats

EVM Implementation

SVM Implementation

Examples

Specs

See Also

​Server Setup

​Client Setup

​Settlement Override Formats

​EVM Implementation

​SVM Implementation

​Examples

​Specs

​See Also

Server Setup

Client Setup

Settlement Override Formats

EVM Implementation

SVM Implementation

Examples

Specs

See Also