An agent that pays on its own, and can't overspend

How a payment works

1. 1

   The agent calls a paid API

   The API answers 402 Payment Required with a price, for example 0.01 test USDC, using the open x402 standard.

2. 2

   The wallet checks the rules

   Before signing, the agent asks its wallet contract to authorise the payment. The contract checks every limit on-chain, where the agent can't get around it, and the reputation of any service that isn't on its list.

3. 3

   Allowed: the payment settles

   The agent signs a standard x402 payment with the wallet as payer. The x402 facilitator settles it in test USDC and the API returns its data.

4. 4

   Paid: the service gets rated

   After a payment settles, the wallet rates the service on the public ERC-8004 reputation registry. It can only rate payments that really happened, so a service's reputation comes from real use.

5. 5

   Refused: nothing moves

   The contract records the refusal as a public event with its reason. No money moves and the API is never paid.

The rules each agent wallet enforces

The operator sets these. A change applies from the agent's very next payment.

• Per-payment cap

  No single payment may be larger than this.

  Demo: 1.00 USDC

• Daily budget

  Total spend per day (UTC) can't go over this.

  Demo: 1.00 USDC

• Task budget

  Each task the agent works on has its own budget.

  Demo: market-research, 10.00 USDC

• Allowed payees

  The agent can only pay addresses on its list.

  Demo: the demo API only

• Trusted payees

  A service that isn't on the list can still be paid if it has an ERC-8004 identity and enough good ratings from reviewers the operator trusts.

  Demo: average ≥ 70 from ≥ 3 trusted reviews

• Pause switch

  The operator can stop all payments at once.

  Demo: off

Why a payment can be refused

Every refusal carries exactly one of these reasons, checked in this order.

1. PAUSEDThe operator has paused this agent.
2. INVALID_AMOUNTThe amount is zero, or the payment has already expired.
3. PAYEE_NOT_ALLOWEDThe recipient isn't on the agent's allowed list.
4. PAYEE_IDENTITY_UNVERIFIEDNot on the allowed list, and the service claims no ERC-8004 identity (with the reputation rule on).
5. PAYEE_IDENTITY_MISMATCHThe service claims an identity that's registered to a different address. Checked even for allowed payees.
6. REPUTATION_UNAVAILABLEThe reputation registry couldn't be read, so it doesn't pay rather than guess.
7. NOT_ENOUGH_TRUSTED_REVIEWSToo few ratings from the reviewers the operator trusts.
8. PAYEE_REPUTATION_TOO_LOWThe trusted reviewers' average is below the minimum.
9. OVER_PER_PAYMENT_CAPThis single payment is above the per-payment cap.
10. OVER_TASK_BUDGETIt would push the task over its budget.
11. OVER_DAILY_BUDGETIt would push today's spending over the daily budget.
12. INSUFFICIENT_FUNDSThe wallet doesn't hold enough USDC.

Built with

• Solidity + Foundry
• OpenZeppelin
• x402
• USDC on Base Sepolia
• ERC-8004
• viem
• Cloudflare Workers
• Astro