The problem

Making one x402 payment work is easy — the reference client does that. The hard part is trusting
the ten-thousandth, unattended. An agent is a loop with a private key: a per-request cap says
nothing about the total, and a budget check that runs after you've signed is a receipt, not a
control.

The protocol layer is settled — x402 v2 exists and works — and it deliberately leaves the buyer's
hard parts out of scope: budgets, route selection, balance checks, and error handling. The gap is
everything around the payment: spend governance first, then resilience, then knowing exactly what
happened.

Install

Chain support is optional in both languages, so the install command depends on which chain you
pay on. Importing tx402 itself loads no chain library in either language, and a subprocess test
asserts that so the property cannot rot.

# TypeScript / Node 20+ — pick the row you need
npm install tx402                                                   # core + CLI, no chain
npm install tx402 @x402/evm viem                                    # Base / EVM
npm install tx402 @solana-program/token @solana/kit @x402/svm viem  # Solana

# Python 3.10+ — the same split, spelled as extras
pip install tx402            # core, no chain
pip install "tx402[evm]"     # Base / EVM
pip install "tx402[svm]"     # Solana
pip install "tx402[all]"     # both

npm has no equivalent of Python's extras, so TypeScript names the chain packages directly. They are
optional peer dependencies: npm is deliberately told not to install them, which is what keeps a
core install free of two chain runtimes. tools/install-contract holds the commands above to the
package's own peerDependencies and smoke-installs every row from a clean directory, because a
README that is wrong about installation is worse than no README.

Sixty seconds

import { createTx402Client } from "tx402";

const tx402 = createTx402Client({
  signers: { evm, solana },
  policy: {
    maxPerRequest: "0.50 USDC",
    maxPerHour: "10.00 USDC",
    allowedNetworks: ["eip155:8453", "solana:mainnet"],
  },
});

const res = await tx402.fetch(url);

from tx402 import Policy, Tx402Client

with Tx402Client(
    evm_signer=evm,
    solana_signer=svm,
    policy=Policy(
        max_per_request="0.50 USDC",
        max_per_hour="10.00 USDC",
        allowed_networks=["eip155:8453", "solana:mainnet"],
    ),
) as tx402:
    res = tx402.get(url)

That is the whole integration. res is a normal response; if the resource cost money, it was paid
for. If it could not be paid for, you get a typed error that tells you which of seventeen things
went wrong — not a bare 402.

Or, without writing any code at all:

npx tx402 call <merchant-url> --max-spend "0.10 USDC" --dry-run   # never invokes a signer
npx tx402 call <merchant-url> --max-spend "0.10 USDC" --json

What happens on a 402

  request ──▶ 402 PAYMENT-REQUIRED
                │
                ├─ 1. decode strictly        base64 strict · ≤64 KiB · depth ≤16 · no duplicate keys
                ├─ 2. normalize + hash       resource origin checked against the URL you asked for
                ├─ 3. POLICY                 domain → network → scheme/asset → per-request → rolling hour
                ├─ 4. plan routes            every offered chain probed concurrently, then ranked
                ├─ 5. RESERVE                atomically, from your local ledger
                ├─ 6. sign                   ← the first time a key is touched
                ├─ 7. EXPOSE fence           durable, before the wire; the hold stops expiring
                ├─ 8. retry once             exactly one PAYMENT-SIGNATURE
                └─ 9. read PAYMENT-RESPONSE  → commit (settled) · release (declined) · stays exposed (ambiguous)

The EXPOSE fence (step 7) records the reservation durably before the signed request goes on the wire, so a
crash or ambiguous reply can't lose the payment. An exposed hold never expires on its own — it waits for an
operator to reconcile it, so an already-sent payment can never be silently retried.

Steps 3 and 5 happening before step 6 is the property the entire design is built around. A
budget check that runs after signing is not a budget check.

Route selection is a total ordering — viability, open circuit, your preference, buyer fee, health
score, observed latency, requirement index — so identical inputs and identical health state produce
an identical choice, every time. Not "whichever RPC answered first".

Design commitments

These are load-bearing, not aspirations. Each one is enforced by a test, a gate, or a type.

Networks

solana:mainnet and solana:devnet are accepted as aliases and normalised to the canonical
genesis-hash IDs. The network list and its RPC endpoints ship as an Ed25519-signed manifest
compiled into both packages; construction fails if the signature does not verify.

Documentation

Repository layout

packages/tx402/          npm "tx402"    — SDK + CLI (TypeScript, the reference implementation)
packages/tx402-python/   PyPI "tx402"   — SDK + CLI (Python, at behavioural parity)
core-spec/               language-neutral: JSON Schemas, 88 frozen conformance vectors,
                         and the signed release manifest. Neither SDK keeps a private copy.
docs/                    the documentation site (Astro Starlight)
examples/                runnable quickstart and dry-run, both languages
tools/                   size gate, manifest signer, conformance index, test merchant,
                         RPC stubs, fuzz + performance harnesses, supply-chain gates

The two SDKs are held together by files, not by intent. All 88 conformance vectors execute in
both languages against the same normalized output, route ordering, error codes and money rule. The
release manifest is signed by the Node tool and verified by the Python SDK, so the canonical-JSON
encoding and the Ed25519 envelope are proven identical by the signature itself.

Development

pnpm install                      # Node 22.12+ to develop; the published SDK supports Node 20.19+
pnpm check                        # every gate, in the order CI runs them

cd packages/tx402-python
uv sync --all-extras
uv run ruff check . && uv run ruff format --check . && uv run mypy && uv run pytest -q

pnpm check runs lint, format, types, the NUL-byte guard, the workflow linter, conformance index
integrity, the manifest signature, both test suites, the build, the size gate, and the docs site.
It starts with pnpm toolchain:check, because the docs site is an Astro build that needs Node
22.12+ while the package itself supports Node 20.19+ — two different numbers, both derived from
the manifests rather than restated here.
A gate is only evidence if it ran in the order and from the state CI uses — see
CONTRIBUTING.md for the traps that rule exists because of.

Live testnet suites are opt-in and skip silently without credentials, which looks exactly like
a green run. Source . tools/live-env.sh first; it prints which variables resolved.

Versioning and releases

Semantic versioning, with the 0.x caveat spelled out: see VERSIONING.md for
the compatibility contract, what counts as a break, and the release process. Changes are recorded
in CHANGELOG.md.

Security

Do not open a public issue for a vulnerability. Report it through
GitHub Private Vulnerability Reporting.
Scope, response times, and the guarantees a report can be filed against are in
SECURITY.md.

Contributing

CONTRIBUTING.md leads with the three rules that actually get a PR rejected:
the docs and the 88 frozen conformance vectors define behaviour, those vectors run identically in
both languages, and behavioural changes land in both languages together. Participation is governed by the
Contributor Covenant.

License

Apache-2.0.