Inspiration

Agreements and payments live in different worlds. People negotiate in chat or email, agree on something vague, and then hope the money follows. Whether a human or an AI agent is doing the negotiating, nobody can easily prove afterwards what was agreed, or that the payment matches it. Deals closes that gap by tying the agreement and the payment together.

What it does

Deals lets two parties, or their AI agents, negotiate an agreement and back it with a PayPal payment.

  1. Negotiate. Each side exchanges structured, immutable, hash-linked messages (PROPOSE, COUNTER, ACCEPT, REJECT, WITHDRAW) covering the bundle, price, delivery days, payment terms and late fees. A provider's price floor stays private, and a buyer's budget is a hard limit.
  2. Seal. When both sides accept, the terms are sealed and fingerprinted with a canonical hash.
  3. Hold. That fingerprint travels with the PayPal payment itself in the hold's custom_id. A PayPal Order with intent AUTHORIZE holds the funds. This is a payment hold, not escrow. The buyer approves it on PayPal.
  4. Capture on delivery. Confirmed delivery captures the payment, and partial captures are supported. If terms change, the hold is voided, and refunds are supported.
  5. Pay sub-contractors. PayPal Payouts send each approved sub-contractor their share after capture.
  6. Verify. Every webhook PayPal sends is signature-verified before we store it, and each event is stored once, so the payment trail can't be forged or replayed.
  7. Prove it. Every step goes into an append-only, hash-chained ledger. A sealed receipt shows whether anything was tampered with.

The agreement and the money are tied together and independently checkable.

How we use PayPal

  • Orders API (AUTHORIZE), capture, void and refund
  • Payouts for sub-contractors
  • Invoicing for balances and reminders
  • Webhooks, verified through PayPal's signature-verification endpoint
  • Terms hash stored in the hold's custom_id
  • Sandbox only. No real money moves.

How we use AI

Each party can be represented by an AI agent (Claude, through the Anthropic API or Amazon Bedrock) that proposes counter-offers and writes the negotiation messages. The AI proposes, the rules decide. A deterministic rules engine validates every offer against the buyer's budget, the provider's private floor and the protocol rules, so a model can't overspend or undercut. Without a model key, the rules engine alone can run the negotiation. Agents register in a public directory with scoped, one-time bearer credentials, so outside agents can use the same API as the built-in ones.

How we built it

Python and Django on PostgreSQL, deployed on Render. The architecture is layered and enforced by tests: the domain, rules engine, agent contract and PayPal adapter can't import each other's internals. Money never uses floats. Every lifecycle (deal, negotiation, payouts, webhooks) is a state-machine table that the services, UI and agents all read. The suite has 383 tests.

Challenges

  • Making negotiation messages safe to retry: POSTs use idempotency keys, a stale head returns 409 STALE, and a mismatched hash returns 409 TERMS_MISMATCH.
  • Keeping the provider's floor private while still enforcing it.
  • PayPal holds last up to 29 days and aren't escrow, so the design treats them honestly as holds.
  • The FX rate-lock API isn't available to ordinary apps, so local-currency figures are labelled as estimates.

What we learned

A payment is more useful when it carries proof of what it was for. Putting the terms' fingerprint inside PayPal's own record means neither side has to take the other's word for what was agreed.

What's next

  • Milestone-based releases and dispute handling
  • More agent scopes for payments, keeping hold approval with a human
  • Live (non-sandbox) deployment after review

Try it

Open the demo, run a negotiation at /negotiate/, approve the hold as the sandbox buyer, and confirm delivery. Setup steps are in the README and DEPLOY.md.

Share this project:

Updates

Submission history