x402 is an open-source SDK for the x402 open payment standard — a protocol built on the HTTP 402 Payment Required status code. It enables web services to charge for APIs or content through a "pay-before-response" mechanism — without relying on traditional account systems or session management.
x402 currently supports the TRON and BSC networks, with plans to expand to a broader multi-chain ecosystem in the future.
Version 1.1.0. The SDK is a TypeScript-only pnpm/turbo monorepo published as granular @bankofai/x402-* packages (there is no umbrella package). core and the EVM mechanism are forks of the x402-foundation/x402 upstream; the TRON mechanism is in-house. Supported schemes: exact (ERC-3009 / Permit2), upto, batch-settlement, auth-capture (EVM), and exact_gasfree (TRON). See the v1.1.0 release notes for upgrade details.
The previous-generation Python + TypeScript SDK lives under
legacy/for reference and is slated for removal.
- Protocol Native: Restores the HTTP
402status code to its intended purpose. - AI Ready: First-class support for AI Agents via specialized x402 skills.
- Trust Minimized: Uses TIP-712/EIP-712 structured data signing. Facilitators cannot modify payment terms.
- Stateless & Accountless: No user accounts or session management required. Payments are verified per request.
- Framework Integrations (TypeScript): a wrapped-
fetchclient plus middleware for Express, Fastify, Hono, Next.js, Axios, and an MCP transport.
Install only the granular packages you need:
# client (wrapped fetch) + the chains you pay on
npm install @bankofai/x402-fetch @bankofai/x402-evm @bankofai/x402-tron
# resource server (Express shown; also fastify/hono/next/axios)
npm install @bankofai/x402-core @bankofai/x402-expressThe repo itself is a pnpm (>=11) workspace; from typescript/ run pnpm install && pnpm build. The examples/ workspace links these packages and builds from source.
A full loop has three roles: Client (payer), Resource Server (seller), Facilitator (verify + settle on-chain). Runnable trios for every scheme live under examples/typescript/ — start there.
The client wraps fetch so 402 challenges are paid automatically. Key custody is in @bankofai/agent-wallet; the signer factory adapts the wallet and builds the chain client internally from the CAIP-2 network.
TRON (Nile) example:
import { x402Client, wrapFetchWithPayment } from "@bankofai/x402-fetch";
import { createClientTronSigner } from "@bankofai/x402-tron";
import { ExactTronScheme } from "@bankofai/x402-tron/exact/client";
const wallet = /* resolve your @bankofai/agent-wallet */;
// The factory builds TronWeb from the network and auto-broadcasts the one-time
// Permit2 approve that USDT/USDD need. When TRON_GRID_API_KEY is unset, mainnet
// RPC falls back to a BankofAI-operated endpoint.
const signer = await createClientTronSigner(wallet, {
network: "tron:0xcd8690dc",
apiKey: process.env.TRON_GRID_API_KEY,
});
// The selector is the payment-selection policy: pick which advertised option to pay.
const client = new x402Client((_x402Version, accepts) => accepts[0]);
client.register("tron:*", new ExactTronScheme(signer));
const fetchWithPay = wrapFetchWithPayment(fetch, client);
const res = await fetchWithPay("http://localhost:4021/weather"); // 402 handled automatically
const data = await res.json();EVM (BSC) is symmetric — swap the imports and register under the exact chain id:
import { createClientEvmSigner } from "@bankofai/x402-evm/adapters/agent-wallet";
import { ExactEvmScheme } from "@bankofai/x402-evm/exact/client";
const signer = await createClientEvmSigner(wallet, {
network: "eip155:97",
// Permit2 tokens (e.g. USDC) read the chain; set a reliable RPC.
// ERC-3009 tokens (e.g. DHLU) sign offline and need none.
rpcUrl: "https://bsc-testnet-rpc.publicnode.com",
});
client.register("eip155:97", new ExactEvmScheme(signer));Build a resource server with createResourceServer (from @bankofai/x402-core), point it at a facilitator via HTTPFacilitatorClient (@bankofai/x402-core/server), and protect routes with the framework middleware — e.g. paymentMiddlewareFromHTTPServer from @bankofai/x402-express. The server is keyless (it only holds a payout address). Facilitator requests default to a 90-second timeout; set timeoutMs explicitly when your chain or deployment needs a different bound. See examples/typescript/servers/express for the full wiring.
The facilitator verifies signatures and settles on-chain. Construct new x402Facilitator() (from @bankofai/x402-core/facilitator) and register(network, scheme) per chain with a facilitator signer. Self-host it, or use the officially hosted Facilitator. See examples/typescript/facilitator/basic.
x402 is designed for the Agentic Web. AI agents can autonomously negotiate and pay for resources using the x402-payment skill, which lets agents detect 402 responses, sign TIP-712/EIP-712 authorizations, and manage the challenge-response loop.
Configuration: set up agent-wallet and let the signer factories resolve the active wallet. When TRON_GRID_API_KEY is unset, mainnet TRON RPC routes to a BankofAI-operated fallback (https://hptg.bankofai.io); set it for production.
export AGENT_WALLET_PRIVATE_KEY="your_private_key_here"
export TRON_GRID_API_KEY="your_trongrid_api_key_here" # recommended for productionThe x402 protocol involves three parties:
- Client: Entity wanting to pay for a resource
- Resource Server: HTTP server providing protected resources
- Facilitator: Server that verifies and settles payments on-chain
sequenceDiagram
participant Client
participant Server as Resource Server
participant Facilitator
participant Blockchain as Blockchain
Note over Facilitator: Facilitators are optional,<br/>all logical steps could be<br/>performed by the server<br/>when accepting stablecoins<br/>or crypto
Client->>Server: GET /api
Server->>Client: 402 PAYMENT-REQUIRED: {...}
Note over Client: Create payment<br/>payload
Client->>Server: GET /api<br/>PAYMENT-SIGNATURE: {...}
Server->>Facilitator: POST /verify<br/>PAYMENT-SIGNATURE<br/>PAYMENT-REQUIRED
Facilitator->>Server: 200 Verification: {...}
Note over Server: Do work
Server->>Facilitator: POST /settle<br/>PAYMENT-SIGNATURE<br/>PAYMENT-REQUIRED
Facilitator->>Blockchain: Submit tx
Blockchain->>Facilitator: tx confirmed
Facilitator->>Server: 200 Settled, tx_hash
Server->>Client: 200 Ok<br/>PAYMENT-RESPONSE<br/>Content
x402 currently supports TRC-20 tokens on the TRON network and BEP-20 tokens on the BSC network.
| Network | ID | Status | Recommended For |
|---|---|---|---|
| TRON Nile | tron:0xcd8690dc |
Testnet | Development & Testing |
| TRON Shasta | tron:0x94a9059e |
Testnet | Alternative Testing |
| TRON Mainnet | tron:0x2b6653dc |
Mainnet | Production |
| BSC Testnet | eip155:97 |
Testnet | Development & Testing |
| BSC Mainnet | eip155:56 |
Mainnet | Production |
Tokens seen in the examples: BSC testnet — DHLU (ERC-3009) and USDC (Permit2); TRON Nile — USDT and USDD (Permit2).
| Scheme | Chain | Description |
|---|---|---|
exact |
EVM, TRON | Fixed, pre-quoted single payment. Transfer method chosen via extra.assetTransferMethod: eip3009 (ERC-3009 TransferWithAuthorization, e.g. USDC/DHLU) or permit2 (Uniswap Permit2). |
upto |
EVM, TRON | Usage-based: the payer signs an up-to-max authorization; the server settles the actual amount used (≤ max). |
batch-settlement |
EVM, TRON | Payment channels: deposit once, pay many requests with off-chain vouchers, settle a batch (with refund of the remainder). |
auth-capture |
EVM | Refundable payments via Base's Commerce Payments escrow — authorize, then capture / void / refund. |
exact_gasfree |
TRON | Pay with USDT/USDD without holding TRX for gas; a relayer submits and pays energy via the official GasFree Proxy. |
- Node.js 22+
pnpm>= 11- A TRON wallet with TRX for gas/energy, and/or a BSC wallet with BNB for gas.
cd typescript
pnpm install
pnpm build # turbo run build (all packages → dist/, gitignored)
pnpm build:release # bypass build cache before packing/publishing
pnpm test # vitest unit tests (offline, no secrets)
pnpm test:integration # real-chain tests; self-skip without .env credsUse pnpm build:release before pnpm pack or pnpm publish. The forced build lets each package clean its output first, preventing stale hashed declaration files from entering release tarballs.
- Configure wallet access through
agent-wallet. TRON_GRID_API_KEY: recommended for production. When unset, mainnet TRON RPC uses a BankofAI fallback endpoint automatically.
Warning
Use at your own risk. Handling private keys involves significant risk of asset loss.
- Never commit secrets: Do not hardcode private keys or commit
.envfiles to version control. - Wallet Isolation: Use dedicated wallets for development with only necessary funds.
- Environment Variables: Always use environment variables or secure vaults to manage sensitive credentials.
- Protocol Status: x402 is in active development. Ensure you test thoroughly on Nile or Shasta testnets before any mainnet deployment.
We welcome contributions! Start normal work from develop and submit it back to develop.
Stable releases reach main through a release_* branch. See CONTRIBUTING.md
and BRANCHING.md for the complete workflow.
MIT License - see LICENSE for details.