Inspiration
Agents can already decide to buy things. What they can't do is hold a payment method without breaking something. Hand one a card and it can spend irreversibly. Charge a merchant before the work lands and the buyer eats the loss. The primitive to fix this exists inside PayPal: an authorization holds money first, and it captures only on evidence. Nobody had wired it as infrastructure an agent could call. That gap was the project.
What it does
Settlr is an MCP server and a settlement rail for agent purchases. An agent asks for a hold; the buyer approves it in PayPal; the money is ring-fenced, never sent. The agent then submits delivery proof, and code decides: deterministic checks run first (status, body match, contract), a model adjudicates only what code cannot settle, and the outcome is capture, void, or a human review gate. Every state change lands in an append-only audit log with the PayPal reference. The agent never holds a credential that can move money.
How we built it
TypeScript end to end. Next.js 15 console with AG Grid; Fastify API; embedded PGlite for local dev and Postgres 16 in production; an MCP server over stdio with four tools (escrow_create, escrow_submit_proof, escrow_status, catalog_search); PayPal Orders v2 (AUTHORIZE into CAPTURE / VOID) with idempotency keys on every mutation; a deterministic-first verifier with model adjudication (Groq, OpenAI-compatible); Channel3 for catalog search and contract drafting; an OpenAPI 3.1 contract as the single source of truth; Docker Compose and a Render blueprint for self-hosting
Challenges we ran into
Authorization is not a capture:The hard part is reconciling a buyer who approved on PayPal's domain and may not fire our callback. /approve-callback is idempotent and re-runnable, and /v1/webhooks/paypal is a signature-verified second path to the same state.
Expiry is real money: Authorizations that expire unclaimed are silent failures. The sweeper voids stale holds and records the outcome instead of leaving a mystery on the books.
Keeping the model out of the money path: The model drafts contracts, adjudicates evidence, and explains decisions, but it can only void on a confident underdelivered, anything ambiguous stops at a human gate, and every function returns null when the provider is unavailable.
Accomplishments that we're proud of
Real sandbox money moved, live. Not mocks: captured $24 and $12.50 in testing, and a $1 hold was released at the human review gate with a written reason. The same flows run on the hosted instance.
Agents hold no money power: The agent key can ask, prove, and read status. It cannot approve, capture, or move funds. The buyer approves in PayPal, every time.
End to end verified. CI green on every push, 5/5 verifier tests, a smoke script that walks signup to deal to capture through the real API, and a live deployment wired to sandbox PayPal.
What we learned
Deterministic first, model second. An unaccountable "the AI said it's fine" is not evidence; code checks are, and the model supports them rather than replaces them. Idempotency is not a nicety in money software, it is the whole job. Every settlement path must be safe to retry. Deployment is the fastest debugging tool. The two production defects above were invisible on localhost. PayPal's sandbox is a better teacher than its docs. Callbacks fire late, approvals land asynchronously, and the authorization lifecycle punishes optimism.
What's next for Settlr
PYUSD settlement, multi-merchant splits, webhook-driven capture for asynchronous delivery, spend ceilings per agent key, and a public hosted instance for evaluation alongside the self-hosted compose route. The protocol stays the same: hold first, pay on proof.