-
-
Honest transaction
-
Cheat transaction
Inspiration AI agents are starting to buy things from each other — data, API access, digital work — but the money layer was never built for them. If a buyer agent pays first, the seller can ship garbage. If the seller delivers first, the buyer can refuse to pay. Humans solve this with escrow and chargebacks; agents have neither trust nor recourse.
We wanted a neutral third party both sides' agents could trust by construction: one that holds the funds, checks the deliverable itself, and settles or refunds automatically — on payment rails they already use. PayPal's authorize/capture/void primitives map cleanly onto escrow, but PayPal doesn't verify digital deliverables. That gap is Trustee.
What it does AI agents can negotiate, agree on a deal, and then have nowhere safe to settle it. If the buyer pays first, the seller can underdeliver. If the seller delivers first, the buyer can refuse to pay. Existing agent protocols cover discovery, identity, mandates, and checkout, but not conditional settlement between two parties that are both software.
Trustee is the missing trust layer. A buyer agent and seller agent form a signed, machine-readable contract. Trustee checks that contract against both parties' signed mandates before PayPal is ever called. If the deal is allowed, Trustee opens a PayPal authorization so the funds are held, not moved. The seller then hands Trustee the deliverable and records a signed delivery. Trustee checks the delivered bytes itself against the contract: SHA-256 hash, schema, row rules, and optional market-price checks. If the checks pass, Trustee captures payment to the seller. If they fail, it voids the hold and returns the money to the buyer. A partly valid delivery can settle pro-rata for the valid share.
Every contract, mandate, delivery, ruling, receipt, and ledger entry is signed. The ledger is hash-chained, and dispute evidence packs can be verified offline. The LLM can negotiate and explain, but only deterministic policy code can move money.
How it works Buyer and seller agents discover each other, negotiate terms, and sign a contract. Trustee checks both parties' mandates: budget caps, counterparty allowlists, categories, expiry, and spend limits. If the deal is outside policy, it is rejected before PayPal is called. Trustee creates a PayPal Orders v2 authorization so the buyer's funds are held. The seller uploads the deliverable to Trustee and records a signed delivery with its SHA-256 hash. Trustee runs the contract's acceptance checks on those exact bytes. Trustee captures to the seller, voids back to the buyer, or settles the valid share of a partial delivery. A signed receipt and evidence pack record what happened and why. PayPal integration Trustee uses PayPal's server-side REST APIs rather than a checkout button:
OAuth client-credentials authentication. Orders v2 with intent=AUTHORIZE to create escrow. /v2/checkout/orders/{id}/authorize to hold funds. /v2/checkout/orders/{id}/capture to settle to the seller, including supported partial captures. /v2/checkout/orders/{id}/void to release funds back to the buyer. Vault v3 setup tokens and payment tokens for consented, human-not-present payments. Webhook signature verification for PayPal events. PayPal-Request-Id idempotency keys and deterministic retry handling so money operations are not duplicated. custom_id links each PayPal order back to the Trustee contract hash. The hosted demo uses the PayPal sandbox. A sandbox payer may need to approve the payment once unless the optional Vault flow is configured.
AI integration Trustee uses an OpenAI-compatible LLM endpoint, defaulting to NVIDIA NIM (nvidia/nemotron-3.5-lightning-30b-a3b) with a scripted fallback for reproducible demos.
The model helps agents negotiate offers and counters, draft checkable acceptance criteria from a buyer's request, and explain decisions. It does not decide whether money moves. Every payment action is gated by deterministic policy code: signed mandates, contract checks, delivery verification, and the deal state machine.
How I built it Trustee is a single Python service with a React frontend, deployed as one Docker container on Render.
The core is a deterministic deal state machine. Contracts, mandates, deliveries, attestations, and settlement receipts are all Ed25519-signed, and every state transition is checked against signed policy before PayPal is ever called. The PayPal adapter (src/trustee/paypal.py) is the only module that talks to PayPal: Orders v2 authorize holds funds, capture settles to the seller (including pro-rata partial captures), and void releases them back to the buyer. Every money POST carries a stable PayPal-Request-Id so retries and webhook replays can't move money twice.
Delivery verification is deliberately not LLM-based. The seller uploads the file bytes with a signed delivery record; Trustee hashes them (SHA-256), checks CSV schema and row-level rules, and can cross-check prices against Channel3 market data. Only after those checks does the state machine capture, void, or settle the valid share.
The LLM layer (src/trustee/llm.py) is an OpenAI-compatible client defaulting to NVIDIA NIM (Nemotron). It negotiates offers, drafts acceptance criteria, and explains rulings — with a scripted fallback so demos are reproducible. It has no path to the PayPal client.
Around the core: a hash-chained JSONL ledger, a SQLite store for durable deal recovery, a public /v1 REST API, an A2A JSON-RPC server with Agent Cards, an arena UI (React/TypeScript/Vite/AG Grid) that replays scenarios live, and optional integrations for Elastic analytics, Zapier alerts/back-office via MCP, and Playwright/CDP sandbox approval.
Testing was adversarial-first: tests/test_attacks.py runs 17 attack scenarios (forged signatures, mandate overreach, replayed approvals, buyer framing) in CI, plus mocked-HTTP PayPal tests and an optional real-sandbox Playwright e2e.
Technical implementation Python 3.12 backend with FastAPI and Pydantic. React + TypeScript + Vite arena UI with AG Grid for the live ledger. SQLite-backed platform store and durable deal recovery. Ed25519 signatures for contracts, mandates, deliveries, attestations, receipts, and evidence packs. Hash-chained JSONL ledger. Public signed REST API under /v1. Agent2Agent JSON-RPC support with Agent Cards and task handling. Optional integrations: Channel3 market checks, Elastic ledger analytics/reputation, Zapier alerts, Postman collection, and KERNEL/CDP sandbox approval. Dockerized deployment on Render. Demo The hosted arena is at https://trustee-arena.onrender.com. It is connected to the PayPal sandbox. The free Render instance can sleep, so the first request may take about a minute.
Suggested judge path:
Open the demo URL. Run the honest scenario: the agents negotiate, escrow opens, the file is verified, and the seller is paid. Run the cheat scenario: the seller ships an invalid file, Trustee's own checks fail, and the buyer keeps the money. Optionally run partial, overreach, forged, a2a, or the Channel3 price-feed scenarios. Inspect the ledger and evidence pack for the PayPal order ID, checks, decision, and settlement result. For a no-credentials path, the repository can run the same scenarios locally in dry-run mode:
uv sync --extra dev uv run pytest cd arena/ui && npm install && npm run build && cd ../.. uv run python -m uvicorn trustee.arena.api:app --port 8000 Challenges we ran into LLM nondeterminism: models can propose invalid or unsafe moves. Trustee constrains outputs and lets only policy code touch PayPal. PayPal authorization semantics: sandbox AUTHORIZE orders may require payer approval before funds can be held. Trustee supports both approval links and Vault-backed consented payments. Idempotency: payment retries, webhook redelivery, duplicate accepts, and process restarts must not capture or void twice. Trustee uses stable request IDs, signed state transitions, and durable deal recovery. Independent verification: a buyer's claim cannot be the only evidence. Trustee checks the exact delivered bytes itself and prevents a buyer from framing an honest seller with unrelated uploads. Partial delivery: a file can be partly valid. Trustee counts valid units itself and settles only the contractually valid share. Honest demo constraints: the hosted free tier has no persistent disk, so the demo uses in-memory state and can lose platform deals on restart. That limitation is documented rather than hidden. What we accomplished Built an end-to-end agent-to-agent escrow and arbitration system on PayPal. Implemented conditional settlement: authorize, verify, capture or void. Added signed mandates, contracts, deliveries, receipts, and dispute evidence. Added a hash-chained ledger and offline-verifiable receipts. Added a public REST API and A2A agent interface so external agents can use Trustee. Added pro-rata settlement, stale-price checks, forged-identity rejection, mandate overreach handling, and human step-up approvals. Added a hosted demo arena showing the conversation, verification checks, PayPal order state, decision, and ledger. Added an executable attack suite covering 17 adversarial cases. What we learned The important boundary is not "AI versus rules." It is which layer is allowed to make a consequential decision. LLMs are useful for negotiation and explanation, but money needs deterministic policy, verifiable evidence, and idempotent execution. PayPal's authorize/capture/void primitives map naturally to escrow, but the trust layer still has to decide when each transition is valid.
What's next Complete the remaining real PayPal sandbox end-to-end and webhook validation. Move the hosted demo to durable storage for production-like operation. Expand verifier types beyond CSV/schema/hash and Channel3 market checks. Add more agent frameworks and marketplace integrations. Publish the contract, attestation, receipt, and evidence formats as an open protocol extension. Explore PayPal Partner Referrals, merchant onboarding, platform fees, and dispute evidence workflows. Measure auto-resolution rate, false release/capture rate, settlement time, stranded holds, and cost per deal.