HORKOS

the trust board
the landing page
the money tracker page
oath page
the live feed
the audit trail
the seller page
how it works

Inspiration

AI agents can already shop, hire and pay for things on our behalf. What nobody has really solved is trusting them with the money. A spending cap can't tell whether a payment matches what you asked for, and approving every payment by hand defeats the point of having an agent at all.

When PayPal opened this hackathon around agentic commerce, that gap was the first thing we wanted to close. We named the project after Horkos, the spirit of oaths in Greek myth, who punished anyone who broke a promise. That's the whole idea: let an agent spend, but make it keep its word.

What it does

Horkos sits between an AI agent and the payment.

You write your rules once, in plain English. Something like: "Spend up to $50 per job and $100 per day. Only on coding work. Ask me before anything over $30, and always ask me about a seller I haven't used before." Horkos turns that into a policy, shows you what it understood, and enforces it on every payment.

The Guard: When you ask for a job, a Buyer Agent proposes a payment. Then the Guard checks it in a fixed order. Hard rules come first (changed recipient, over a cap, excluded category). Then anything high risk is blocked. Then anything uncertain comes to you. The AI can never override a hard rule, and any error or doubt ends in "ask", never "approve". Every verdict comes with a plain-English reason.
Proof before payment: The money is held until the work is proven. A seller, who has their own account, submits Python code, and it runs against the acceptance tests inside an isolated Docker container with no network access. If the tests pass, the seller is paid. If they fail, the buyer is refunded. Trust follows the result: clean deliveries raise a seller's trust score and spending limit, and a failure tightens them straight away.
Everything is visible: Every step shows up live in a Live Feed and is kept in an Audit Trail with the reason behind each decision. There's also a Red Team panel where you can play the bad agent (swap the recipient, go over the limit, send a pushy message) and watch the Guard respond.

How we built it

I built the frontend and the design: Next.js, React and TypeScript, with Tailwind CSS and Motion for the animation. There's a landing page where the logo draws itself, sign-up and login for buyers and sellers, and the app screens: Oath, Live Feed, Money Tracker, Trust Board, Audit Trail, a Seller page and Settings. My teammate Levis built the backend in Python with FastAPI, SQLAlchemy and SQLite, plus the PayPal integration and the AI.

For PayPal, funding is simulated by default so anyone can run the app without PayPal keys. Set PAYPAL_FUNDING=sandbox and the same flow runs for real on PayPal's sandbox: an Orders v2 order with intent AUTHORIZE that the buyer approves on PayPal, a capture when the tests pass followed by a seller payout through the Payouts API, and a void or a refund when they fail.

Gemini powers two roles. The Buyer Agent turns a request into a payment proposal, acceptance tests and a test file, returned as structured JSON that the backend validates. The Auditor checks whether the payment buys the kind of work you actually asked for. Price is never left to the AI, because fixed rules in the code judge that. We tested the full Gemini Flash models and they were too slow for a live demo, so we use a lite model at about 3 to 4 seconds per call.

We used the APIMatic Context Plugin for PayPal inside VS Code, with GitHub Copilot's agent mode, to build the PayPal integration. It gave the agent the real SDK names and request shapes for creating an AUTHORIZE order, and it corrected our first error-handling approach: the SDK raises exceptions on failed responses instead of returning a result you check. Everything is logged in docs/apimatic-log.md.

Challenges we ran into

Docker and hosting. Our biggest challenge was hosting the backend. The core feature of Horkos needs Docker to run a stranger's code safely. We wanted a fully hosted backend, but Render (where our credits were) can't run Docker from inside a service, and Docker-in-Docker would need privileged mode, which it doesn't allow. The free virtual machines that do have Docker needed a card we couldn't verify in time. Running the code without Docker wasn't an option: it would sit next to our PayPal sandbox secret and Gemini key, so anyone who signed up as a seller could try to read them. We chose security and a genuine end-to-end flow over an unsafe public link. So the full verification flow runs locally from the repository, and the frontend is deployed separately as a preview.
Getting the Guard's order right. We first had the "ask" rules run before the high-risk block, which meant a risky payment from a new seller would be asked about instead of blocked. We flipped the order so high risk blocks first.
PayPal's approval step. Our first sandbox run failed with ORDER_NOT_APPROVED, because a buyer has to approve the order on PayPal before it can be authorized. That's why the app has a Fund this payment button and a return page that confirms the funding.
Keeping two halves in sync. The frontend and backend agreed on an API contract and had to stay in step. A missing payment status, awaiting_user, would have broken the whole approve flow, so we caught and fixed it early.
Windows. One backend dependency doesn't install on Windows. I found out when I ran the backend on my own machine, and we fixed it with a platform condition in the requirements.

Accomplishments that we're proud of

The whole loop works from end to end: write an oath, ask for a job, get a Guard decision with a reason, hold the money, have a seller submit code, run it in a sandbox, then pay or refund and update the seller's trust. We're proud that the hard rules really can't be talked around, and that the project is honest about its limits (see the README: funding is simulated by default, and there's no AI Verifier because verification is automated tests only). We also cared about the design, and we wanted it to look like a finished product and not a prototype.

A payment blocked by a hard rule

Failed work and the buyer is refunded Failed work: the buyer is refunded

What we learned

Trust comes from the structure around the AI, not from the AI. The most useful decisions we made were the boring ones: hard rules before the model, "ask" on any doubt, and a reason stored for every verdict. We also learned how much a clear API contract saves two people building in parallel.

What's next for HORKOS

Verification for work beyond Python code, such as writing, data and design. Trust that follows a seller across different buyers. Seller-side agents that negotiate scope and price. Durable payout reconciliation, and a managed blocklist. A production review of the payment flow and the sandbox runner before it goes anywhere near real money.

How judges can try Horkos

We want to make this as easy as possible, so here are the options from least to most effort:

Watch the demo video. It shows the real PayPal sandbox flow (fund, hold, pass and payout, then a refund) running on the local Docker setup.
Click through the frontend preview: Frontend preview. It is deployed with sample data and no backend, so you can explore the screens, the Live Feed and the Trust Board. On the sign-in page, use the "Fill in the demo account" button. It is a preview of the design, not the live system.
Run it locally for the full experience. The README has a setup of about 10 minutes. You need Python 3.12, Node 20.9 or newer, Docker running, and a Gemini API key from Google AI Studio. No PayPal credentials are needed, because funding is simulated by default. Run docker pull python:3.12-slim once before the first submission so the tests start fast. The demo logins are in the README.
A live walkthrough. If you'd like one, message us through Devpost and we'll run the backend and show it to you.

The source is public under the MIT license: GitHub repository.

Tools and how we used them

Gemini API: the Buyer Agent and the Auditor.
PayPal sandbox: Orders v2 (AUTHORIZE), authorize, capture, void and refund through the PayPal Python Server SDK, plus the Payouts REST API for seller payouts.
APIMatic Context Plugin for PayPal: used in VS Code with GitHub Copilot to build the PayPal integration accurately.
Docker: runs each seller submission against its tests in an isolated container.
FastAPI, SQLAlchemy, Alembic, SQLite, pytest: the backend, with Server-Sent Events for the live feed.
Next.js, React, TypeScript, Tailwind CSS, Motion: the frontend, deployed on Vercel as a preview.
GitHub Copilot and Claude: AI coding assistants we used while building.