Allowance

AI agents earn their budget, and their freedom, with PayPal holding the money until the work is approved.

Comment

Inspiration

As a kid I didn't get freedom handed to me; I earned it, one finished chore at a time. AI agents today get either no money at all, so they stall at the first paid tool, or a raw card with no limits. I wanted the in-between: agents that earn spending power by doing work a person approves, spend it on tools they choose, and gain or lose freedom based on how well they do.

What it does

An owner posts a task with a reward. PayPal authorizes and holds the reward instead of charging it. A Claude-powered agent works the task: when it needs a paid data tool, the tool answers 402 Payment Required with a price, and the agent asks to buy it with a written justification. The tools return real data from Wikipedia, Wikidata and Hacker News, and one purchase unlocks a tool for the whole task, so the agent can compare several companies after paying once. An 8-check policy engine decides whether it's allowed, and the owner approves anything above the agent's trust level, right in a live feed of the agent's reasoning.

The agent submits a preview; the full report stays locked. Approve it and PayPal captures the reward, the agent is paid, and the report unlocks. Reject it and PayPal captures only the agent's tool costs and releases the rest. Good work moves an agent from new to proven to trusted, with bigger limits; one rejection drops it a level. Vendors whose tools agents bought are paid through PayPal Payouts.

Every credit moves through a double-entry ledger you can watch three ways: a live dashboard, a 3D model where coins fly along each transfer, and an AG Grid journal of every transfer whose books always sum to zero.

How I built it

  • Backend: Python, FastAPI, SQLAlchemy, Postgres. A double-entry ledger with row locks and idempotency keys on every transfer and every PayPal call.
  • PayPal: Orders v2 (AUTHORIZE and CAPTURE intents); Payments v2 capture, partial capture with final_capture, void and reauthorize; Vault v3 so the owner saves PayPal once and later rewards fund instantly; Payouts for vendors; webhooks for 17 event types, verified by RSA signature and deduplicated, with a reconciler that polls PayPal as a safety net.
  • AI: Claude Haiku 4.5 through the Anthropic Messages API with tool use. Each step it sees the task, its wallet, its trust limits and what it has bought, and either buys one tool (with reasoning and a justification for the owner) or finishes with a preview and a full report. The agent talks to the server over plain HTTP, the same API an outside agent would use. The tools it buys return live public data (Wikipedia, Wikidata, Hacker News) with source links it cites in its report.
  • Frontend: plain HTML and JavaScript with no build step, Three.js for the 3D view, AG Grid Community for the journal.
  • Deploy: Docker on Render, from a Blueprint in the repo.

AI tools used

  • Claude Haiku 4.5 (Anthropic API) is every agent's decision-maker: which paid tool to buy, why, and when to stop and write the report.
  • Claude Code was my pair programmer: design discussions, writing code and tests, and testing flows against the live PayPal sandbox.

Challenges I ran into

  • PayPal holds quietly expire. An authorization is guaranteed for only 3 days and dies at day 29. Allowance tracks both clocks, reauthorizes after the honor period, renews from saved PayPal before day 29, and marks a dead hold so the owner can re-fund it in one click.
  • Resending a payout batch isn't a rejection. Testing live, PayPal answered a retried batch with 400 USER_BUSINESS_ERROR. Treating that as a failure would have paid the vendor twice, so the client recovers the original batch from the error's link instead.
  • PayPal's webhook signing certificate is past its expiry date* but still served. A strict date check would have rejected every real webhook, so origin, subject and signature are always checked and dates are opt-in.
  • Agent-written text is untrusted. An agent could plant HTML in a purchase justification to fake an "Approve all" button. Everything an agent writes is escaped before the dashboard shows it.

Accomplishments that I'm proud of

  • The money can't leak: 118 tests, plus Postgres tests where 50 parallel purchases never overspend and the same webhook delivered 20 times at once funds exactly once.
  • "Replay from zero" in the 3D view rebuilds every balance from the transfer history alone and checks it against the database: the ledger proving itself on screen.
  • Watching Claude decline to buy a tool because it judged the price wasn't worth it.

What I learned

The AI should only ever ask; plain code and a person should decide. I also learned to test against the real sandbox, not just mocks: three of the bugs above only showed up there.

What's next

Paid data from commercial providers, push notifications when an agent is waiting on its owner, and agents that sell their own work to other agents.

Built With

Share this project:

Updates

Submission history