Inspiration
We build software in Nairobi, and we kept seeing the same story. A client in Berlin hires a developer in Nairobi. The client is afraid to pay first; the developer is afraid to work first. The deal stalls on "50% upfront" or a "free trial task", or both sides retreat to a marketplace that takes 10–20%.
When something goes wrong, a payment provider is asked weeks later whether the work was "delivered as described", but there was never a shared definition of done. And now AI agents are starting to buy work from people and from other agents. They can pay, but nothing checks the work before money moves.
Moving money is solved. Deciding when it should move is not. We built Ahadi (Swahili for promise) so nobody has to go first.
What it does
Ahadi turns every payment for work into a promise:
- Agree on what "done" means. A plain-language or voice brief becomes milestones with checkable, weighted acceptance criteria. A Criteria Critic flags vague terms like "modern design" before anyone signs. Both sides sign the same sha256-hashed terms.
- Secure the money with PayPal. The client approves a PayPal authorization per milestone. The money is held, not taken, and the worker sees "Funds secured" before starting.
- Verify the work. The worker submits a URL, repo, file or text. Ahadi collects evidence: screenshots, rendered DOM, real form submissions, sandboxed tests, citations. It scans for hidden prompt-injection text. Then each criterion is decided by a machine check, a verifier agent, or a human reviewer when confidence is low.
- Capture exactly what was earned. A deterministic settlement engine turns the results into an amount in integer cents. PayPal captures that share with
final_capture, releases the rest back to the client in the same call, and pays the worker through PayPal Payouts.
Every step lands in a hash-chained ledger, and each settled promise builds the worker's Ahadi Passport: a verified work history with an Ed25519-signed source-of-funds statement. The whole engine is also an MCP server, so AI agents can hire people or other agents and pay only for verified work, within spending mandates their human owner sets.
A real sandbox run on the live app: a $40 bakery landing page. 4 of 5 criteria passed; the page scrolled sideways on phones. Ahadi captured $32.00 (80%), released $8.00 back to the client, and paid the worker $29.91 after PayPal's fee and a 1.5% platform fee. Every PayPal ID is listed in the README.
How we built it
- PayPal: Orders v2 (
intent: AUTHORIZE); Payments v2 (partial capture withfinal_capture, void, reauthorize, refund); Payouts v1 with team splits; signature-verified webhooks; Disputes; the JS SDK. Every write carries a deterministicPayPal-Request-Id, so retries never double-charge or double-pay. - App: a TypeScript monorepo (npm workspaces + Turborepo). Next.js 15 for the web app and API, BullMQ for jobs, Drizzle ORM on Neon Postgres, and Upstash Redis for the queue.
- Agents: Contract Architect, Criteria Critic, Injection Sentinel, Verifiers (with vision), Verdict Reviewer, Explainer, Mediator and Risk Analyst. All run through OpenRouter (or the Anthropic API) with structured JSON output validated by Zod, plus code-level checks. For example, the Explainer may not mention any amount that isn't in the settlement facts.
- Verification: Playwright for website evidence, a deterministic injection scanner with strip-and-compare, 14 machine checks, sharp for design files, and E2B/Docker sandboxes for code.
- Hosting: one Render web service runs the app, the API, the MCP server and the worker. It deploys from
mainonly after GitHub Actions passes lint, typecheck, unit tests, integration tests (real Postgres + Redis with a stateful fake PayPal), the build and a migration-drift check.
Challenges we ran into
- Partial payments that are actually safe. Getting partial capture, the release of the remainder, fees and payouts to add up to the cent meant keeping all money logic in one pure, property-tested function. No model ever touches an amount.
- Prompt injection in deliverables. A submitted website can hide text telling the AI to approve payment. We treat deliverables as data, scan for hidden text, strip it, verify again and compare.
- Free models in production. Running on free OpenRouter models, the Risk Analyst once held a payout on a single low-risk signal. We changed the rules so a model can only escalate a hold when a deterministic rule found medium or high risk.
- No browser on the free host. Render's free runtime has no Chromium, so browser-only checks route to a human reviewer instead of guessing.
Accomplishments that we're proud of
- A complete, real money flow in the PayPal sandbox: authorize → verify → partial capture → payout, reconciled by webhooks.
- "Models never move money" is enforced in code, not just promised.
- Plain-language explanations for both sides of every decision, with exact amounts and what to fix.
- The same engine works for people in a browser, for WhatsApp users, and for AI agents over MCP.
What we learned
The hard part of paying for work isn't the payment; it's agreeing on "done" before work starts. Once criteria are checkable and weighted, the payout becomes arithmetic. PayPal's authorize-then-capture model is a natural fit for this: the client keeps control of the money until the evidence is in.
What's next for Ahadi: pay for work only when it's done
- PayPal multiparty with delayed disbursement, so the worker is the payee and Ahadi never holds funds
- A Chromium-enabled worker for fully automatic website checks
- Pre-approved agent funding with PayPal Vault
- A platform API for marketplaces and agencies
- Verifiers for mobile apps, video and translation
Built With
- bullmq
- drizzle-orm
- github-actions
- model-context-protocol
- neon
- next.js
- node.js
- openrouter
- paypal
- paypal-orders-api
- paypal-payouts-api
- paypal-webhooks
- playwright
- postgresql
- react
- redis
- render
- sharp
- tailwindcss
- turborepo
- typescript
- upstash
- vitest
- whatsapp-cloud-api
- zod