> For the complete documentation index, see [llms.txt](https://handsel.gitbook.io/handsel-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://handsel.gitbook.io/handsel-docs/agent-wallets-for-x402-bazaar.md).

# Agent wallets for x402 Bazaar

## Pay from the agent that makes the call

*Design proposal, checked against the Handsel repository and Coinbase x402 documentation on 2026-09-28. Per-agent Bazaar payments are not currently shipped.*

### Current state

Handsel can bind an agent to a paid HTTPS tool with a method, input key, per-call price ceiling (currently $1 maximum), and optional pinned recipient. It checks the agent's spend envelope, pins network and USDC, rejects over-cap or mismatched-recipient payment requirements, then records the selected spend. However, the signer is the deployment-wide `X402_BUYER_PRIVATE_KEY`. All agents share that EOA. The agent's `smartAccountAddress` is not the payer, and Handsel does not yet store a separate payer wallet per agent. See the [repository design note](https://github.com/Kairose-master/handsel/blob/main/docs/x402-agent-wallet-design.md).

### Recommended flow

1. **Search Bazaar.** Search by task intent, Base network, USDC and a maximum price. Coinbase's catalog is public; search and endpoint validation do not require a CDP API key.
2. **Review a candidate.** Treat every listing as untrusted input. Validate HTTPS, resource schema, network, asset, price and recipient; pin the endpoint and `payTo` before allowing repeated use.
3. **Apply agent policy.** Resolve the authenticated agent, verify its wallet, check a per-call cap and rolling daily limit, and require approval above the configured threshold. Reserve spend atomically before concurrent calls.
4. **Pay with that agent's signer.** Submit the x402 payment handshake from that agent's wallet only. Keep the signing operation server-side and reject any challenge that changes the approved network, USDC asset, recipient or amount.
5. **Verify and attribute.** Check settlement evidence, record payer, resource, recipient, amount and transaction/nonce against the agent, then return the resource result and cost to that agent's task.

Start with Bazaar discovery and call the selected HTTP endpoint through Handsel's guarded runtime. Coinbase's Bazaar MCP also offers `proxy_tool_call`; connecting its paid proxy directly would need to preserve Handsel's same agent-specific signing and spend controls.

### Choose a wallet path

**Preferred:** pay from the agent's existing smart account only after proving that the x402 client, exact payment scheme, USDC contract and CDP facilitator accept the account's contract-signature format. The current Kernel/ZeroDev account address does not itself provide a signer. ERC-3009's standard authorization flow is EOA-oriented and its specification excludes smart-contract accounts, so do not assume compatibility from the address alone.

**Fallback:** provision a dedicated x402 EOA sub-wallet for each agent, with its own address, balance and encrypted signer reference. Keep keys in an isolated KMS/HSM-backed signing service; allow signatures only after the Handsel policy check. This gives each agent a distinct payer identity but remains server-custodied and must be disclosed. Never reuse the deployment buyer key or expose secrets to the browser, prompts or logs.

If neither contract-signature support nor isolated per-agent sub-wallets are ready, keep paid Bazaar purchases disabled. Do not describe the current shared deployment signer as an agent personal wallet.

### Delivery steps

1. Store per-agent wallet type, payer address, chain and non-secret signer reference. Keep encrypted key material outside ordinary database rows; migrate off the shared buyer key without silent fallback.
2. Resolve a signer by authenticated agent ID; ensure the payment payer equals that agent's registered wallet.
3. Add per-agent daily caps, approval thresholds, atomic spend reservation and settlement reconciliation.
4. Add free Bazaar search/validation, then call reviewed HTTPS resources through Handsel's guarded payment client.
5. Test refusal cases and one low-value Base Sepolia payment for every wallet type. Verify payer, recipient and amount on-chain before any Base mainnet enablement.

**Target usage:** provision and fund an agent wallet, set its per-call and daily limits, search for a capability, review and pin a resource, then approve or allow the agent to call it. The call should show its payer and price, debit that agent's wallet, and return a spend record. These are design targets, not present functionality.

### Sources

* [Coinbase: Discover services (Bazaar)](https://docs.cdp.coinbase.com/x402/buyer/discover-services)
* [Coinbase: Discover and pay over MCP](https://docs.cdp.coinbase.com/x402/buyer/mcp-payments)
* [ERC-3009 specification](https://eips.ethereum.org/EIPS/eip-3009)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://handsel.gitbook.io/handsel-docs/agent-wallets-for-x402-bazaar.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.