Inspiration

AI agents are starting to buy things on their own: a hotel rate, a review summary, a walking time. Each of those is worth a few cents. Yet today an agent cannot pay a few cents per call. API subscriptions need a human to sign up with every provider in advance, checkouts need a human for every purchase, and a fixed fee per transaction is bigger than the call itself.

The x402 protocol brings back HTTP 402 Payment Required so a machine can pay per request, but it settles on a blockchain. Most operators and API sellers don't want to hold stablecoins. They already have PayPal.

We wanted electronic toll collection for APIs: link once, drive through, get billed once.

What it does

PayPer402 lets an AI agent pay for APIs one call at a time over x402, with the money settled through PayPal.

  1. Link once (human present). The operator links a PayPal account through the Vault v3 API and sets caps: per call, per day, total, and an unsettled cap.
  2. Pay per call (no human). A paid API answers 402 with a price. The agent signs a payment commitment with its Ed25519 key and retries. The facilitator checks the signature, the caps and replay protection, records the commitment, and the API serves the response.
  3. Settle in one charge (no human). Commitments are summed and charged to the saved PayPal account as one Orders v2 capture, when the unsettled cap is reached or once a day. A charge is never more than the sum of signed, unsettled commitments.
  4. Stop at any time. The payer clicks "Stop paying with PayPal" in their PayPal account, and the agent's next paid call is refused.

Why batch? A US PayPal checkout costs about 3.49% + $0.49. Charging a 2-cent call on its own:

$$0.49 + 0.0349 \times 0.02 \approx \$0.49 \approx 25\times \text{ the price of the call}$$

Batch 250 of those calls into one $5 charge and the fee drops to about a quarter of a cent per call.

In the demo, a Claude agent plans a trip to Kyoto on a $0.50 budget. It reads the 402 prices of five paid travel APIs (1 to 25 cents), decides which ones are worth buying, pays, answers, and ends with a plain-English spend report. Before each payment, Jev (TypeSafe) gives a calibrated second opinion: does this call serve the task, and is the result already in hand? Code makes the final decision with fixed thresholds.

The web app covers three people:

  • Operators: link PayPal, set caps, manage agents, watch a live run, and charge.
  • Sellers: revenue per endpoint and settlement status.
  • Developers: the payper402 npm command and an MCP server, so Claude Code or Claude Desktop can pay per call too.

The operator and seller dashboards are built with AG Studio, with a read-only Claude analyst inside.

How we built it

  • An x402 network binding for PayPal: network paypal:sandbox, asset USD, scheme batch-settlement. It is written as plug-ins for the official @x402/core SDK (client, resource server, facilitator). Sellers use the stock @x402/express middleware and agents use @x402/fetch; nothing is forked. The binding has its own spec, in the style of the x402 scheme specs.
  • A facilitator (Express, SQLite, zod): verifies commitments, keeps the ledger, enforces caps, runs the settlement job, and handles revocation.
  • PayPal (sandbox): OAuth; Vault v3 setup and payment tokens with usage_pattern: UNSCHEDULED_POSTPAID; Orders v2 create-and-capture with payment_source.paypal.vault_id and PayPal-Request-Id for idempotency; Payments v2 to read a capture back ("Verify with PayPal"); and Webhooks (VAULT.PAYMENT-TOKEN.DELETED) for instant revocation.
  • AI: a Claude agent with tool use and adaptive thinking (Anthropic SDK), Jev jev-1.14.0 as the decision layer, Claude behind a server route as the AG Studio analyst, and Claude powering one of the seller's paid APIs.
  • Web: Next.js, React, Tailwind CSS v4, and AG Studio 3.0.0 with a custom AgLlmAdapter, so the Anthropic key never reaches the browser.
  • TypeScript everywhere, in an npm workspaces monorepo, with more than 1,000 Vitest tests. Every PayPal, Anthropic and TypeSafe call is mocked in tests; the real sandbox is exercised by explicit end-to-end scripts.

We proved the riskiest assumptions first with small spikes: charging a saved PayPal wallet again and again with no payer present, plugging a fake network into the x402 SDK, Jev latency, and AG Studio in Next.js. Only then did we build.

Challenges we ran into

  • x402 assumes settle-per-call. On a blockchain, every payment settles on its own. With PayPal we had to split commitment from settlement: a call is served against a signed commitment, and money moves later in a batch. We had to do this inside the SDK's scheme interfaces without forking them.
  • Postpaid means credit risk. If a payer revokes before the next charge, unsettled usage is lost. We added an unsettled cap: when it is reached, the facilitator settles at once, and stops serving if that fails. The same threshold drives batching.
  • One agreement per payer and merchant. On sandbox, linking the same PayPal account to a second operator returned the same payment token. So a revocation must stop every operator that holds that token, and unlinking may delete the token only when nobody else uses it.
  • Noticing revocation fast. Webhooks need public HTTPS. So we combined three signals: the webhook, a wallet health check every 30 seconds, and PayPal's own errors on a charge (AGREEMENT_ALREADY_CANCELLED, TOKEN_NOT_FOUND).
  • Keeping the model away from the money. Payment tools accept only catalog ids, never free-form amounts, URLs or recipients. Every price is checked against the catalog, the per-call limit and the remaining budget before anything is signed. The numbers in the spend report come from the ledger, never from the model.
  • Calibrating Jev. Our first thresholds caught nothing on the newer Jev model. We built a labelled evaluation and took the thresholds from its results.

Accomplishments that we're proud of

  • The full flow works end to end on the real PayPal sandbox: link, pay per call, one batched charge, and revocation. For example, 8 paid calls became one $0.17 capture (4M443028VK142725B), checkable with "Verify with PayPal".
  • "Stop paying with PayPal" in the payer's account blocks the agent on its very next call.
  • An open x402 binding for the PayPal wallet, with no fork of the SDK and a written spec.
  • A complete product, not a script: onboarding, caps, live runs, operator and seller dashboards, empty and error states, an npm CLI, and an MCP server.
  • More than 1,000 tests.

What we learned

  • Fixed fees, not percentages, are what kill micropayments. Batching signed commitments, with credit bounded by a cap, is what makes cent-level pricing work on a card-style rail.
  • PayPal's Vault v3 with UNSCHEDULED_POSTPAID is a good fit for machine payments: the human approves once, and the payer keeps a clear way to stop it from their own PayPal account.
  • x402 is more open than it looks: a new network and scheme fit through its plug-in interfaces.
  • For decisions that move money, it works better to let a calibrated model give probabilities and let code decide than to let the LLM judge its own plan.

What's next for PayPer402

  • Go live: production PayPal credentials and merchant review.
  • Pay many sellers from one batch with PayPal Payouts.
  • Propose the paypal binding upstream to the x402 specs.
  • More seller tooling: drop-in middleware for other frameworks, and pricing per customer.
  • Optionally, a PYUSD settlement path next to the PayPal wallet.

Built With

Share this project:

Updates

Submission history