Documentation Index
Fetch the complete documentation index at: https://docs.x402.org/llms.txt
Use this file to discover all available pages before exploring further.
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.
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: "..." });
});
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": "..."})
})
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
Register UptoEvmScheme alongside ExactEvmScheme if your client may call both fixed-price and usage-based EVM resources.
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 (
x402 "github.com/x402-foundation/x402/go"
exactevm "github.com/x402-foundation/x402/go/mechanisms/evm/exact/client"
uptoevm "github.com/x402-foundation/x402/go/mechanisms/evm/upto/client"
evmsigners "github.com/x402-foundation/x402/go/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 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))
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 |
"0" means no charge for that request.
EVM Implementation
upto 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.
Examples
Specs
See Also