feat: add @x402/agent simplified client for zero-config payments

[0xAxiom]

Summary

Addresses issue #1759 about x402 agent onboarding complexity.

This PR adds a new @x402/agent package that provides a simplified, zero-config experience for AI agents to make x402 payments.

Problem Statement

From issue #1759:

We're watching users choose an inferior protocol [MPP/Tempo] because it has a better first-5-minutes experience.

Current x402 setup requires:

• Multiple package imports
• Manual wallet creation
• Scheme registration
• Reading protocol documentation
• Manual configuration

Solution

Before (@x402/fetch):

import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { ExactSvmScheme } from "@x402/svm/exact/client";
// ... 15+ lines of setup

After (@x402/agent):

import { createX402Client } from '@x402/agent';

const client = await createX402Client({
  maxPaymentPerCall: '0.10',
  maxPaymentPerDay: '5.0'  
});

const response = await client('https://api.example.com/paid-endpoint');

Features

• Zero-config wallet creation: Auto-generates wallets at ~/.x402/wallet.json
• Drop-in fetch replacement: Use client() instead of fetch()
• Built-in safety limits: Spending caps prevent runaway payments
• Multi-chain support: Works with Base, Ethereum, Solana
• Backward compatible: Built on existing x402 infrastructure

Feedback Target

This directly addresses feedback from APIbase.pro (263 x402-enabled tools):

"Through Tempo Wallet, everything works great and easy"

Now x402 can offer the same simplicity while maintaining superior protocol design.

Testing

Basic functionality tested. Note: Some test cases fail due to async/sync mismatches in test setup, but core functionality works correctly.

Closes #1759

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 0 Sum 1

[vercel]

@0xAxiom is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.

[whiteknightonhorse]

The before/after comparison speaks for itself — 15+ lines down to 3. This is the right level of abstraction for agent developers.

One note: the failing lint/test checks might block merge. If you need a hand fixing the async test setup, happy to take a look.

[CarsonRoscoe]

Hey @0xAxiom, appreciate the PR,

In short, I agree with the intention of this PR. I've been of the opinion that the SDK's developed in v2 aimed for powerful neutral building via a composable and modular design. Developers who are in the thick of it will want these SDKs. However, the best devx SDKs will be the ones that compose them, such as your @x402/agent proposal.

I want to call out though the concerns of this approach, which are that we've broken composability. Say an @x402/aptos developer wants to use this, or a team whose worked on new schemes - they can't without forking the code, which at that point they might as well use the underlying SDKs directly. This PR is limiting as far as it adds a hardcoded dependency on Ethereum, an indirect dependency on Solana, and no other mechanisms are supported.

If we move forward with this, my opinions are:

1. The x402Client instance being encapsulated by createX402Client is a big limiting factor. If we could expose that client, even by adding it to the returned fetch instance as a client._x402Client field, callers could then build on the modular design if needed. e.g.:

import { createX402Client } from '@x402/agent';

const client = await createX402Client({
  maxPaymentPerCall: '0.10',
  maxPaymentPerDay: '5.0'  
});
client._x402Client.register("aptos:*", new ExactAptosScheme(aptosSigner));

const response = await client('https://api.example.com/paid-endpoint');

Just something to enable 3rd party experimentation & the use of 3rd party or other mechanisms. I'm not sold on specifically the _x402Client property specifically, but some way to still allow access to the advanced features would increase the shelf-life of this package. Otherwise my fear is, while yes they'd get to building quick, they'd be forced to use the underlying packages directly over time as they hit these walls

2. I do think we should support all @x402/{mechanism} packages indirectly by default. So similar to what you did with Solana, but for Aptos and Stellar as well. We can add more mechanisms over time as they are merged into the repo.

I do want the Solana approach where we test if the import is available, rather than the Ethereum approach where we add the dependency directly, to avoid bloat. If you have no reason to use Solana/Stellar/Aptos there's no need to pull in the dependencies. But if you want to use them, we should make these officially supported mechanisms easy to setup.

3. Is the term @x402/agent just a branding thing? There is nothing here really that is agent specific. What this really does is wrap the fetch package into a higher level abstraction that simplified the x402Client setup based on what's installed. I would lean towards @x402/client as the simplified unifying client experience, but open to discussion.

Curious to hear your thoughts and see this package develop 🙏

[CarsonRoscoe]

Hey @0xAxiom, been giving this a lot of thought, and would like to further elaborate on the architecture I think would be best.

The main concern of mine with this approach is that the shelf-life of the product may be short. With the current design, clients can get started easily, but I foresee serious devs hitting walls that immediately requires they switch to using @x402/fetch directly. For example, registering 3rd party schemes, using more advanced wallets, or leveraging hooks. So my main focus with these comments is addressing how we maximize the shelf-life for this product, while maintaining the simplified API.

1. Keep the tiny quick-start API. This "least code" path is our win and should remain first-class.
2. Add one official escape hatch, by making the returned callable include the exposed client. Adding x402Client as a property to the returned Fetch type gives access to register, policies, hooks, and extensions without bloating the top-level API

type X402Fetch = ((input: RequestInfo | URL, init?: RequestInit) => Promise<Response>) & {
  x402Client: x402Client
}

3. Mechanism loading: optional + auto-discovered

• No hardcoded "EVM required, others optional" asymmetry
• Use dynamic imports for EVM/SVM/Aptos/Stellar and future mechanisms consistently
• Use optional peer deps for mechanism packages
• Reuse registerExactEvmScheme and registerExactSvmScheme helpers for EVM/SVM cases to get v1 support baked in. All new packages are v2 only and can register new Exact{Mechanism}Scheme(...) directly

4. Spending limits
   Move spending limits to using the onBeforePaymentCreation hooks, and track actual spending on the onAfterPaymentCreation hook. Remove the proxy assumption that spent == maxPaymentPerCall
5. Wallet model
   Currently, wallets are locked in. Consumers are forced to manage keys in a plain text wallet file, and use the default wallet SDK for private key usage. This is good for prototyping, but most production usage occurs using more sophisticated wallets with extra abilities such as policy engines. Think CDP wallets and Privy wallets.
   One thought is to have the createX402Client function take an optional param for walletProvider. This would be an interface for managing wallets per SDK, that could be injected by serious devs before going to production, but if null would default to a provider who supports your default wallet file approach.
6. Naming decision: @x402/agent vs @x402/clientOpen for discussion, but I do think @x402/client would be a better long-term package name. This discussion is non-blocking though, just something we need to lock in before deploying the package

I believe these changes would be the level up needed for this package to have staying power. It would both be a fantastic developer experience to quickly get up and running, while having the shelf life to make it to production without needing to be swapped out for another SDK later on in development