Glossary

Every term this project uses. If a word appears elsewhere and is missing here, that is a bug in the glossary.

The protocol

x402 — an HTTP payment protocol. A server answers 402 Payment Required with machine-readable terms; the client

pays and retries. Revived by Coinbase in 2025 and now governed in the open. PayStage evaluates the terms *before* the

client pays.

x402Version — which revision of the protocol a 402 response speaks. Ours handles 2. A receipt from another

version is refused rather than interpreted hopefully.

PAYMENT-REQUIRED — the HTTP header a server sends with its 402. It carries a base64 JSON document: networks,

assets, amounts, payees, timeouts. decode_payment_required turns it into JSON.

PAYMENT-RESPONSE — the header a facilitator returns after a successful payment. It carries the settlement result:

success, transaction, network, payer. This is the only place the payer appears — not in the request.

facilitator — the service that verifies a payment and settles it on chain. Coinbase (CDP) and PayAI are

facilitators. A facilitator moves money; it does not judge whether you should. PayStage is not a facilitator.

settlement — the moment value actually moves on chain. Before it, a payment is a signed intention.

CAIP-2 — the naming scheme for a chain, e.g. eip155:8453. The number is the chain id, not a nickname.

eip155:8453 — Base mainnet. eip155:84532 is Base Sepolia, the test network.

EIP-3009 — a token standard allowing a transfer authorised by a signature rather than by the sender holding gas

(transferWithAuthorization). This is what makes gasless x402 payments possible, and why a payment can be signed and

settled by someone else.

Permit2 — a Uniswap contract that batches token approvals. Its authorisations are long-lived, which is why

evaluate_outstanding_auths exists: a signature you forgot about is still spendable.

ERC-20 allowance — the older approval mechanism. "Infinite approval" is an allowance of 2^256-1; it survives

almost any incident.

atomic units — how tokens are counted on chain. USDC has 6 decimals, so 12500000 is 12.5 USDC. Misreading the

decimals by 10^12 turns a 0.05 cap into a 40,000 USDC payment, which is why the policy schema refuses a mismatch.

payTo — the on-chain address that receives the payment, inside the 402 terms. Must be 40 hex characters; a

malformed one is refused because funds sent to it are unrecoverable.

USDC — the stablecoin x402 payments are denominated in. On Base, 0x8335…2913.

HIP-3 — Hyperliquid's framework for third-party perpetual markets, used by trade.xyz. evaluate_hip3_trade

judges an order against a local policy; it is not financial advice and cannot place an order.

The decision

policy — the JSON document stating what an agent may pay: a cap, allowed networks, assets and payees, a timeout,

optional velocity and time windows. You write it; we only enforce it.

allowlist — the set of payees a policy permits. Unknown payees are denied by default (unknown_payee: "deny"),

because an allowlist that defaults to permissive approves everything.

allowance / authorisation — a standing permission to spend someone's tokens. Different from a payment: it does not

need a signature each time, which is what makes a drain possible long after the incident.

velocity — spend rate over a rolling window. A per-payment cap does not stop twenty small payments; a velocity

check does.

time window — the hours (UTC) in which a policy permits payment. [22, 6] wraps midnight; the end hour is

exclusive.

drainer — an address or approval that takes funds without delivering. Our list is curated and every entry carries

a citation; it is deliberately precise rather than exhaustive.

sanctions / OFAC — the US Treasury's list of blocked persons, including crypto addresses. We screen the 123 EVM

addresses the Treasury publishes, regenerated from their own feed.

verdict — the answer: pay, review or do_not_pay for payments; allow, review, do_not_trade for trades.

review is an instruction to a human, not an error.

reason codes — the rule that fired, as a stable string, e.g. amount 1.00 USDC exceeds max_amount 0.05 USDC. This

is what makes a refusal arguable instead of mysterious.

The evidence

receipt — a signed statement of a decision: what was judged, what the verdict was, when, and by which key. Bound to

the payment terms and valid for five minutes.

verify / provenance — checking a receipt against our published key without trusting us. INVALID (altered),

EXPIRED (too old), payment-mismatch (about a different payment), UNVERIFIABLE (the key could not be fetched —

which is a refusal, not a pass). npm provenance is a separate, unrelated attestation about how a package was built.

The plumbing

MCP — Model Context Protocol, the interface agents use to call tools. api.paystage.xyz/mcp speaks Streamable

HTTP; the npm package speaks stdio.

Streamable HTTP — the transport where an MCP client POSTs JSON-RPC to one URL and may receive a stream in reply.

ERC-8021 / builder code — an attribution tag appended to calldata so a transaction can be credited to the tool that

produced it. Our builder code is bc_f7k4qn7g.

Bazaar — an index of paid x402 endpoints. Being listed there is discovery, not endorsement.

← back to PayStage · privacy