Metadata-Version: 2.4
Name: x402-aa-wallet
Version: 0.2.1
Summary: Give an ERC-4337 / account-abstraction agent a dedicated, non-custodial EOA so it can pay x402 (HTTP 402) challenges against any x402 merchant — smart-wallet signatures don't yet settle on today's facilitators. Optional max_amount_usd spend cap.
Project-URL: Homepage, https://github.com/MeMikko/hoodgrow-x402-aa#readme
Project-URL: Documentation, https://github.com/MeMikko/hoodgrow-x402-aa#readme
Project-URL: Repository, https://github.com/MeMikko/hoodgrow-x402-aa
Project-URL: Issues, https://github.com/MeMikko/hoodgrow-x402-aa/issues
Project-URL: Funding, https://www.hoodgrow.com/api-access
Author: HoodGrow
Maintainer: HoodGrow
License: MIT
License-File: LICENSE
Keywords: account-abstraction,agent,ai-agent,base,eip-3009,erc-4337,smart-wallet,wallet,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: eth-account>=0.13.0
Requires-Dist: requests>=2.31.0
Requires-Dist: x402[evm,requests]>=2.17.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: responses>=0.25.0; extra == 'dev'
Description-Content-Type: text/markdown

# x402-aa-wallet

**The easiest way for an ERC-4337 / account-abstraction agent to pay x402
API calls — with a dedicated, non-custodial EOA, since its smart-wallet
signature doesn't work with x402 yet.**

A lightweight, typed SDK: generate a spend wallet, fund it from your
agent's own smart wallet, and every request through it pays x402
(HTTP 402) challenges automatically — retried and returned, no manual
handling — against **any** x402 merchant. Originally built for
[HoodGrow](https://www.hoodgrow.com) (see "Sponsored by" below), and works
the same way against any other x402 API.

```mermaid
flowchart LR
    A[AI Agent] --> B[Request API]
    B --> C[402 Payment Required]
    C --> D[x402_session pays automatically]
    D --> E[Retry request]
    E --> F[Response]
```

## Features

- 🤖 Built for ERC-4337 / account-abstraction agents
- 💳 Automatic x402 payment handling — detect a 402, pay, retry, transparently
- 💰 Optional `max_amount_usd` spend cap — a real enforcement boundary, not just a docs warning
- 🔒 Non-custodial — the private key never leaves your process, and is excluded from `repr()` (safe to log the wallet by accident)
- ⚡ Minimal dependencies (`eth-account`, `requests`, `x402`)
- 🌐 Works against any x402-compatible API
- 📦 Fully typed
- 🟦 TypeScript implementation also available (see Related projects)

## Installation

```bash
pip install x402-aa-wallet
```

> Formerly published as `hoodgrow-x402-aa`, importable as
> `hoodgrow_x402_aa` — same code, same maintainers, new name to reflect
> that it's a general-purpose x402 utility, not a HoodGrow-specific
> client. See "Sponsored by" below.

## Quick start

```python
from x402_aa_wallet import create_spend_wallet, get_usdc_balance, x402_session

# 1. Generate a dedicated spend wallet — locally, once.
wallet = create_spend_wallet()
print("fund this address:", wallet.address)
# store wallet.private_key yourself (env var / secret manager) — this
# library never sees it again after this call returns.

# 2. Fund `wallet.address` with a little USDC on Base — from your agent's
#    own smart wallet, using its own transfer/send call (not this library).

# 3. Check the balance whenever you want to know if it needs topping up.
balance = get_usdc_balance(wallet.address)

# 4. Pay any x402 endpoint with it — payment happens automatically.
#    max_amount_usd is optional but strongly recommended for autonomous
#    use: it refuses to pay any single challenge above this amount
#    instead of trusting whatever the server's 402 response asks for.
session = x402_session(wallet, max_amount_usd=0.5)

# First call: HoodGrow's own hello-world endpoint — $0.001, no API key, a
# real 402 challenge and settlement so you can watch the whole flow work.
ping = session.get("https://www.hoodgrow.com/api/agent/ping")
print(ping.json())

# Then: real data, same wallet, same call shape.
resp = session.get("https://www.hoodgrow.com/api/agent/token/NVDA")
print(resp.json())
```

Restarting your agent? Rehydrate the same wallet from the key you stored:

```python
from x402_aa_wallet import spend_wallet_from_private_key

wallet = spend_wallet_from_private_key(YOUR_STORED_PRIVATE_KEY)
```

## Why this exists

x402's "exact" EVM scheme settles payment via an EIP-3009 ECDSA signature,
which an account-abstraction owner key (often a P256/WebAuthn passkey, or
even secp256k1 but the wrong address) usually can't produce — full
ERC-1271/ERC-6492 smart-wallet support is still an open, unshipped
facilitator feature (see
[coinbase/x402#639](https://github.com/coinbase/x402/issues/639)). The fix
is giving the agent a small, dedicated EOA it funds itself, purely for
x402 spending. Full writeup:
[hoodgrow.com/blog/x402-account-abstraction-eoa](https://www.hoodgrow.com/blog/x402-account-abstraction-eoa).

## Non-custodial — read this before using it

**We never see your private key. Nobody does but you.**

- `create_spend_wallet()` generates a fresh secp256k1 keypair *entirely
  inside your own process*, using `eth_account`. Nothing is transmitted,
  logged, or persisted by this library.
- The private key is returned to you once, in memory. Store it yourself
  (env var, secret manager) — this library keeps no copy after the call
  returns.
- `SpendWallet` excludes `private_key` from its `repr()` — direct
  attribute access (`wallet.private_key`) still works, but
  `print(wallet)`, an unhandled exception's traceback, or a logging call
  that stringifies the object won't show it.
- Funding the spend wallet is **your** agent's job, using **your** agent's
  own smart-wallet infrastructure. This library never moves funds itself —
  it only tells you the address to send to and (via `get_usdc_balance`)
  how much is there.
- The published package is open source. Don't trust this description —
  read `src/x402_aa_wallet/`, it's short.

## Spend cap

`x402_session` accepts `max_amount_usd`:

```python
session = x402_session(wallet, max_amount_usd=0.10)
```

Without it, `x402_session` pays whatever a 402 response asks for — a
misbehaving or compromised merchant returning a much larger amount than
expected gets paid in full, silently. With `max_amount_usd` set, a payment
requirement above the cap is filtered out before signing (via a real
`x402ClientSync` policy, not a client-side amount check bolted on after
the fact), and if that leaves nothing payable, the request raises instead
of proceeding.

The cap only evaluates a requirement whose asset is a known 6-decimal
Circle USDC deployment (Base mainnet or Base Sepolia) — anything else is
excluded rather than evaluated with a guessed decimal count, since
guessing wrong could make a genuinely large charge on a different-decimals
asset look small enough to slip through.

## API

| Function | Returns |
| --- | --- |
| `create_spend_wallet()` | A new `SpendWallet(address, private_key, account)` |
| `spend_wallet_from_private_key(key)` | Rehydrates a `SpendWallet` from a key you already have |
| `get_usdc_balance(address, rpc_url=DEFAULT_BASE_RPC_URL)` | USDC balance (float, human units) on Base |
| `x402_session(wallet, *, max_amount_usd=None, network=NETWORK)` | A `requests.Session` that auto-pays x402 challenges — `wallet` can be a `SpendWallet`, an `eth_account` `LocalAccount`, or a raw private key string. `max_amount_usd` — see "Spend cap" above; `network` overrides the default `eip155:8453` (Base mainnet) |

`get_usdc_balance` talks to Base over plain JSON-RPC (`eth_call`) — no
`web3.py` dependency, one read-only call. Override `rpc_url` if you run
your own node.

## Use cases

- AI assistants and copilots
- MCP servers
- Autonomous agents built on ERC-4337 smart wallets
- Multi-agent systems
- Research agents
- Trading bots
- Automation workflows

## Payment safety

Every payment `x402_session` makes is real USDC on Base mainnet — not
reversible. Only fund the spend wallet with what you're willing to spend,
and never reuse an EOA that also holds funds you care about for anything
else. Set `max_amount_usd` (see "Spend cap" above) for any autonomous/agent
use — don't rely on funding discipline alone as the only safety boundary.

## Sponsored by

Built and maintained by the team behind
[HoodGrow](https://www.hoodgrow.com) — stock token data for Robinhood
Chain — to pay their own [x402-protected API](https://www.hoodgrow.com/api-access).
Released as a standalone, general-purpose tool because the AA/x402 gap
this solves isn't specific to HoodGrow.

## Related projects

Once your agent has a wallet that pays for itself, the next step is an
agent that already knows what to call:

- [hoodgrow-mcp](https://www.npmjs.com/package/hoodgrow-mcp) — an MCP
  server for HoodGrow's stock-token API. Free tier, no signup required for
  a key.
- [x402-aa-wallet (TypeScript)](https://www.npmjs.com/package/x402-aa-wallet) —
  TypeScript implementation of this package
- [x402](https://www.x402.org) — the HTTP 402 payment protocol

## Development

```bash
pip install -e ".[dev]"
pytest
```

## License

MIT
