Skip to main content

Prerequisites

Before you begin, ensure you have:
  • A crypto wallet with USDC (any EVM or SVM compatible wallet)
  • Node.js and npm, Go, or Python and pip
  • A service that requires payment via x402
Note
There are pre-configured examples available in the x402 repo, including examples for fetch, Axios, Go, and MCP.

1. Install Dependencies

Install the x402 client packages:

2. Create a Wallet Signer

Install the required package:
Then instantiate the wallet signer:

Solana (SVM)

Use SolanaKit to instantiate a signer:

Aptos

Use the Aptos TypeScript SDK to instantiate a signer:

Algorand (AVM)

Use the @x402/avm package to instantiate a signer:

Stellar

Use the Stellar SDK to instantiate a signer:

Keeta

Use the Keeta SDK to instantiate a signer:

Hedera

Use @x402/hedera to instantiate a signer:

Concordium

Use @x402/concordium with the Concordium web SDK to instantiate a signer:

TON (TVM)

Use @x402/tvm to instantiate a signer:

NEAR

Use @x402/near to instantiate a signer:

XRPL

Use @x402/xrpl to instantiate a signer:

3. Make Paid Requests Automatically

@x402/fetch extends the native fetch API to handle 402 responses and payment headers for you. Full example here

Multi-Network Client Setup

You can register multiple payment schemes to handle different networks:

Spend Controls

By default, the x402 client only pays recognized USD-pegged assets (e.g. USDC) and caps each payment at $1. You can adjust these limits when creating the client:
Spend controls run before any custom policies and before the payment payload is signed. For interactive approval flows (e.g. prompting the user), use onBeforePaymentCreation hooks instead.

Payment Schemes

The examples above use the simplest fixed-price scheme. If a resource advertises a different scheme in its 402 response, register that scheme for the same network namespace:
  • exact: fixed-price payments.
  • upto: usage-based payments where you authorize a maximum and the seller charges actual usage.
  • batch-settlement: high-volume payments where the client deposits into escrow, signs off-chain vouchers, and the seller claims value onchain in batches.

4. Discover Available Services (Optional)

Instead of hardcoding endpoints, you can use the x402 Bazaar to dynamically discover available services. This is especially powerful for building autonomous agents.
Learn more about service discovery in the Bazaar documentation.

5. Error Handling

Clients will throw errors if:
  • No scheme is registered for the required network
  • The request configuration is missing
  • A payment has already been attempted for the request
  • There is an error creating the payment header
Common error handling:

Summary

  • Install x402 client packages (@x402/fetch or @x402/axios) and mechanism packages (@x402/evm, @x402/svm, @x402/tvm, @x402/aptos, @x402/keeta, @x402/near, @x402/xrpl)
  • Create a wallet signer
  • Create an x402Client and register payment schemes (exact for fixed-price, upto for usage-based billing, batch-settlement for batched EVM micropayments when the server advertises it)
  • Use the provided wrapper/interceptor to make paid API requests
  • (Optional) Use the x402 Bazaar to discover services dynamically
  • Payment flows are handled automatically for you — including upto where you only pay the actual usage

Next Steps:
  • Explore Advanced Concepts like lifecycle hooks for custom logic before/after verification/settlement
  • Explore Extensions like Bazaar for service discovery
References: For questions or support, join our Slack.