Every bid is a hold. The hammer is the payment.
Watch it | Try it, no login | Live app | Docs | API reference | Evidence | Limits
PayPal sandbox only: no real money moves.
GAVEL is a live auction where every bid is a PayPal authorization hold, and at the hammer only the winning price is captured. Bidders approve a ceiling up front, a deterministic engine checks every bid against it, the winner pays the hammer price, every other hold is voided, and a hash-chained ledger lets anyone verify the result. Bids can be spoken, and a spoken bid never counts until the bidder confirms it.
Built for the PayPal Hackathon 2026 by Harsh Bhanushali and Dhairya Patel.
The film, 2:56, captions on: one lot from hold to receipt on the PayPal sandbox. Watch on YouTube.
Online auctions usually make a bidder pay first or trust the bidder to pay later. GAVEL uses a third way: a PayPal authorization hold. The bidder approves a ceiling, PayPal holds that amount without charging it, and when the hammer falls GAVEL captures only the winning price and releases every other hold. Nobody is charged for a lot they lost, and nobody can bid more than they have put on hold.
| Feature | What it does |
|---|---|
| Hold, not charge | Every bid is backed by a PayPal authorization hold. Only the winner pays, and only the hammer price. |
| Crash-safe settlement | A real server process killed mid-capture: one capture, two losers voided, 0 differences between the journal and PayPal (evidence). |
| Verifiable result | A hash-chained ledger and a public export: anyone can re-hash the chain and spot an edited entry. |
| Voice bidding, with a confirm | Deepgram and Groq speech-to-text with failover; a spoken bid never counts until the bidder confirms it. 24 of 24 clips answered on the live socket; Deepgram parsed 11 of 11 scripted bids and Groq 9 of 11. |
| Fast landing page | PageSpeed Insights on /: 100 Performance, 100 Accessibility, 100 Best Practices, 100 SEO on mobile and desktop (Lighthouse 13.6.0, lab data, measured by hand on 10 Nov 2026; the landing page only, not the whole app). Details and screenshots. |
| Built in the open | 727 merged pull requests as of 11 Nov 2026, each through CI, in one MIT-licensed repository. More than 4,500 test cases run on every pull request. |
| Open and documented | A docs site with a guided tour, an OpenAPI spec, five open datasets on Hugging Face and an honest limits page. |
Watch it | Why GAVEL | Live links | Try it | What is proven | How it works | See it run | Tech stack and sponsors | Evidence and gates | Run it locally | Call the API | Limits | Security | Documentation | Team | License
| What | Where |
|---|---|
| Web app | gavel.dualmindlab.tech (also gavel-web.creharsh.workers.dev) |
| Judge panel | gavel.dualmindlab.tech/try: a live sandbox room, no operator key. It is not linked from the public landing page |
| Docs | docs.gavel.dualmindlab.tech, with a guided tour and a glossary |
| API | api.gavel.dualmindlab.tech on Render; API reference and the OpenAPI spec |
| Open data | Hugging Face collection: five datasets and an Evidence Explorer Space |
| Source | github.com/harshbhx/gavel-auction, MIT |
No login and no PayPal account needed. Do not use a personal PayPal account anywhere. The rooms below are sandbox rooms: the hold in a key-less demo room is a simulated demo hold, and real PayPal sandbox runs are listed under What is proven.
- Watch it (1 minute). Open the scripted demo at /demo/scripted. A recorded room plays in your browser, with no server and no PayPal calls.
- Run it (3 minutes), no login. Open gavel.dualmindlab.tech/try and press "Start a demo auction". The hub shows a room code and a QR code. Join as a bidder, press and hold to approve the hold, bid from two bidders, then hold the hammer button on the console. The big screen shows the sale and the receipt shows what was captured and released.
- Verify it. Open the audit trail of the room, or the ledger lab: every entry is hashed with the one before it, and an edited entry is marked as such.
- Call it (judge API path). The same flow runs over plain HTTP with the shared judge key from the Devpost testing instructions (optional; the rooms above need no key): see Call the API.
Sandbox buyer logins are in the Devpost testing instructions, not in this repository (testing instructions). The demo room uses demo holds unless you log in with a sandbox buyer. Whether a judge can start a key-less room depends on the host flag JUDGE_ROOMS (see docs/DEPLOY.md); docs/DEMO.md says what is verified. More paths, a rubric map and the evidence: For judges, Trust and FAQ and the judge walkthrough.
Numbers are as recorded in docs/GATES.md, as of 11 Nov 2026. Every run link below opens the Actions run, and redacted evidence is committed under docs/evidence. Each row says what kind of evidence it is: real sandbox (the real PayPal sandbox), simulated (the project's own fake PayPal or a fake clock) or speech clips (tested voice audio).
| Claim | Result | Evidence |
|---|---|---|
| Sandbox app, partial capture, wallet and guest card holds, real webhooks | Real sandbox. Gates G0, G1, G2, G3 and G4 PASS; six real webhooks verified | GATES.md, G0, G1, G2, G4 |
| A server killed mid-capture does not double-charge | Real sandbox, run on a CI runner. One kill after the capture request and before the response, restart on the same data folder: one capture of 12500 equal to the hammer price, two losers voided, journal equal to PayPal, ledger of 19 entries verifies | run 42558021614, evidence |
| Spoken bids never skip the confirm | Speech clips, fake PayPal in the server. Live /audio socket: both providers answered 24 of 24 clips, 0 spoken bids accepted without a confirm |
run 42575018866, evidence |
| The hosted judge flow works end to end | Simulated holds. Judge smoke on the live domains, 17 of 17 steps passed, from /try through join, bids, hammer and receipts |
run 42584326641 |
| The hosted API answers quickly | Hosted API. Webhook route p95 112.03 ms (n=50, runner network included); warmup after 16 minutes idle at most 0.66 s (n=2); security headers on the three custom domains | run 42558107791, hosted, headers |
| Settlement speed on the sandbox | Real sandbox. Hammer to SETTLED p95 6927.43 ms and hammer to CAPTURED p95 3766.67 ms (50 settlements of 6 holds, 49 completed, run INCOMPLETE: 1 timeout, 3 failed capture calls). An earlier n=20 run read 5591.30 ms and 3010.04 ms | run 42563147792, latency |
| Tested | More than 4,500 test cases run in CI; all eight P0 items of the security review PASS (as of 7 Nov 2026) | docs/SECURITY-REVIEW.md |
Gate G3 closed and the rest still open, stated as of 12 Nov 2026:
- G3, honor period and reauthorize: PASS. A real sandbox probe started on 7 Nov 2026 at 03:06 UTC and its final checkpoint ran on 12 Nov 2026 (run). The authorization stayed capturable at 3.5, 4 and 5 days (a partial capture of 1.00 was accepted each time, HTTP 201) and reauthorize was accepted at each checkpoint, while an immediate reauthorize was refused with
REAUTHORIZATION_TOO_SOON. Scope: sandbox, wallet buyer, partial capture of 1.00 only (not a card order, not a full-amount capture). Early readings on older authorizations at 3.24 and 3.5075 days (evidence) came first. The 30-day auction run is a simulation on a fake clock (SIM-MULTIDAY), not a sandbox result. - G5, voice accuracy: tested with voice clips, with a confirm step on every voice bid. The voice clips were generated speech. On two sets of 24 clips, Deepgram nova-3 and Groq whisper-large-v3-turbo score wrong accept 0.000 (tuned on those clips), and on a live run of 20 clips Deepgram parsed 11 of 11 scripted bids and Groq 9 of 11. A held-out noisy set of 120 clips, measured once, read wrong accept 0.058 for Groq and 0.092 for Deepgram (result). No live human test is claimed. A spoken bid never counts until the bidder confirms it.
- Scope: PayPal sandbox only. The server kill ran on a CI runner, not the deployed host. The live socket run used the fake PayPal, and the web console microphone has been tested with a fake microphone and socket. A
final_captureand a void on a guest-card authorization are not run, and the release of the remainder is inferred, not read from a buyer balance.
What is next, with owners and dates where known: Limits and next steps. What changed and when: changelog.
- Approve a ceiling. A bidder approves the most they may bid. PayPal places an authorization hold for that amount: held, not charged.
- Bid. A deterministic engine accepts or rejects each bid against the ceilings and writes every event to a hash-chained ledger.
- Hammer. The settlement saga captures the winning price with
final_capture, voids every other hold, and records each step in a journal so a crash cannot double-charge anyone. If PayPal's answer is unknown, settlement stops for review instead of guessing. - Receipt and verify. The outcome is a receipt, and anyone can replay the audit trail and check the hash chain from the public export.
sequenceDiagram
autonumber
actor B as Bidder
participant G as GAVEL server
participant P as PayPal sandbox
B->>G: Join and pick a ceiling of $500
G->>P: Create order, intent AUTHORIZE
B->>P: Approve
P-->>G: Authorization: $500 held, not charged
B->>G: Bid $350
G->>G: Engine decides, ledger appends a hash-chained event
Note over G: Hammer: the $350 bid wins
G->>P: Capture $350 with final_capture
G->>P: Void every other hold
P-->>G: Webhooks confirm each step
G->>G: Journal closes, audit trail is sealed
| Stage | Page |
|---|---|
| Hold | Registration and holds |
| Bid | Bid lifecycle |
| Hammer | Auction states |
| Settle | Settlement saga |
| Verify | Engine and ledger |
English ascending auction with ceilings and soft close. A deterministic core (decide, evolve, replay) with no Node built-ins, so the same events always give the same result.
|
Every event is linked to the one before it. A redacted public export and a verifier detect an edited chain; a cut tail shows as not closed and is proven only against a head hash published elsewhere. |
| Truth check at PayPal, capture of the winning price, bounded concurrent voids, a journal, and resume after a crash. | Holds on PayPal Orders v2 and Payments v2 with the JS SDK v6. Webhooks are signature-verified and de-duplicated. |
| Deepgram and Groq speech-to-text with failover, a rule parser, and a confirm prompt for every spoken bid. Typed and QR bids work without it. | A replay player for recorded auctions, a built-in fake PayPal for offline tests, and a scenario DSL with property tests that print replayable seeds. |
The Scoreboard interface, line by line
The web app (packages/web) uses the Scoreboard design: flat panels, hard shadows, big numerals (docs/DESIGN.md). Each line is covered by unit, component or browser tests that run in CI.
- Hold button. Press and hold for 3 seconds to approve a ceiling, or to hammer a lot on the console; release cancels. Keyboard users hold Space or Enter. Approving a ceiling also has a two-tap alternative; the console hammer does not.
- Price roll. Prices are integer cents in tabular numerals, and only the changed digits roll. Reduced motion swaps the value at once.
- Hold card. Hatched means held, solid means charged, hollow means released, always with a text status and a hide-amount toggle.
- Ceiling slider and join code input. Snapping ticks and full keyboard control; one slot per character with paste that drops a
GVL-prefix. - Alerts. Outbid, win and sold alerts on the bidder phone and a gavel sound on the projector, with a mute toggle.
- Hold explainer. A help button opens a sheet that explains the hold. Nothing opens over the page by itself.
- Fundraiser thermometer. The projector screen shows a goal bar when the auctioneer sets a goal. Only captured money counts as raised.
- Shareable receipt. A receipt can mint a link with a QR code and a copy button, and has a print layout.
- Judge rooms. With
JUDGE_ROOMS=true, "Start a demo auction" opens a key-less room on the PayPal sandbox (capped, rate limited, switchable off at runtime).
Still screenshots of the current app at gavel.dualmindlab.tech (cream and ink interface), taken from a sandbox demo room where the hold is a simulated demo hold, not a PayPal login. The app shows its own sandbox banner.
| Layer | What is used |
|---|---|
| Language | TypeScript (strict) in an npm-workspaces monorepo on Node 22; a Python reference implementation for differential tests |
| Web app | React and Vite, hosted on a Cloudflare Worker with static assets |
| API and realtime | One Node host with HTTP routes and a room WebSocket gateway, hosted on Render |
| Payments | PayPal Orders v2 and Payments v2, JS SDK v6, signature-verified webhooks; a built-in fake PayPal for offline tests |
| Auction core | Pure decide, evolve and replay functions and a hash-chained ledger |
| Voice | Deepgram and Groq speech-to-text with failover, a rule parser, and a confirm prompt for every spoken bid |
| Tables | AG Grid Community for the ledger, bids and holds |
| Docs | Fumadocs on a Next.js static export, hosted on Cloudflare, with a glossary and a guided tour |
| Checks | GitHub Actions: tests, type checks, lint, scenario and property tests, sandbox gates, docs build |
| Partner | How GAVEL uses it |
|---|---|
| PayPal | Orders v2 with intent AUTHORIZE, Payments v2 (authorize, capture, void, reauthorize), webhook signature verification and JS SDK v6, all on the sandbox. Gates G0, G1, G2, G3 and G4 PASS |
| Cloudflare | The web app runs as a Worker (gavel-web) and the docs site is deployed to Cloudflare; both serve the custom domains with security headers (checked on 9 Nov) |
| Render | One Node web service on the starter plan, always on, with a 1 GB persistent disk at /var/data for the ledger, room log, settlement journals and hold records; render.yaml is the blueprint (hosting write-up) |
| AG Grid | Community edition (MIT): the audit ledger, console bid history and the holds tables, with sorting, filters kept in the page link, CSV export of what you see, and a Verify chain button that re-hashes the sealed ledger in the browser (a check of the public export; audit-page rows are not sealed, so they have no chain status); lazy-loaded, so the landing and bidder pages do not carry it (docs/AG-GRID.md). Try it on the /ledger page |
| APIMatic | The OpenAPI 3.1 spec of the host API (openapi/gavel.yaml) is linted with Spectral in CI and checked against the server router; TypeScript, Python and C# SDKs (gavel-sdk 0.0.5, beta) generated from it are in sdks/ and published as the GitHub release sdk-v0.0.5 (docs/API.md) |
| Hugging Face | Five small datasets and a read-only Evidence Explorer Space, each labelled real sandbox, simulated or generated speech (collection) |
| Package | Purpose |
|---|---|
packages/shared |
Money in integer cents, ids, wire types, replay bundle format |
packages/engine |
Pure auction core and hash-chained ledger |
packages/payments |
Hold service, settlement saga, webhook verification, fake PayPal, gate scripts |
packages/voice |
Audio capture, speech-to-text clients, bid parser, decision step |
packages/server |
Single-process host: HTTP routes, room runtime, settlement scheduling, file stores |
packages/e2e |
Scenario DSL, runner and end-to-end specs |
packages/web |
Browser client (React and Vite) |
Other folders: docs/ (gates, judge paths, evidence, submission), docsite/ (the docs website), openapi/, hf/ and scripts/hf/ (Hugging Face Space and dataset builds), reference/python/, infra/ and render.yaml, etc/ (API reports). Diagram and details: docs/submission/ARCHITECTURE.md and the system architecture page.
A gate is a question answered by a recorded run. G0 to G4 ran against the real PayPal sandbox and G5 is measured on speech clips. Source of truth: docs/GATES.md, with redacted evidence in docs/evidence/. Behaviour no passed gate covers is exercised against the project's own fake PayPal.
| Gate | Question | Result | What it shows |
|---|---|---|---|
| G0 | Sandbox app and buyer accounts work | Token, scopes and an AUTHORIZE order; re-run on 9 Nov (G0) | |
| G1 | Partial capture and release of the remainder | Authorize 500.00, capture 350.00 with final_capture: the authorization reads CAPTURED for two PayPal-account buyers, and a later void answers 422 PREVIOUSLY_CAPTURED. The release of the remainder is inferred, not read from a balance |
|
| G2 | Card and guest AUTHORIZE | Wallet and guest card both authorized in PayPal JS SDK v6 | |
| G3 | Honor period, validity and reauthorize | A real probe from 7 Nov 03:06 UTC: capture of 1.00 and reauthorize accepted at 3.5, 4 and 5 days (wallet buyer, sandbox; run) | |
| G4 | Webhook signature verification on real events | 6 real deliveries verified by PayPal; rejection of a tampered event is covered against the fake PayPal | |
| G5 | Speech-to-text accuracy on noisy bids | Wrong accept 0.000 on 24 clips in each of two sets (tuned on them); 0.058 (Groq) and 0.092 (Deepgram) on a held-out noisy set of 120 clips. Every spoken bid goes through the confirm prompt |
Five small datasets and a read-only Evidence Explorer Space are on Hugging Face, each labelled for what it is. The speech, simulation and trace sets use generated audio, a fake clock and scripted auctions by design: GAVEL does not collect real people's data.
| Dataset | Label |
|---|---|
| gavel-gates | real sandbox, speech clips, G3 passed |
| gavel-latency | real sandbox, small n |
| gavel-sim-30d | simulated, fake clock |
| gavel-stt-bids | speech clips |
| gavel-audit-demo | simulated, fake PayPal |
Space: gavel-evidence-explorer. How they are built: docs/HF_COLLECTION.md.
Needs Node 22 and npm. No PayPal account is needed for the default run.
npm ci
PUBLIC_URL=http://localhost:8080 TOKEN_SECRET="$(openssl rand -hex 16)" ADMIN_KEY="$(openssl rand -hex 12)" \
PAYMENTS=fake PAYPAL_ENV=sandbox npm start -w @gavel/serverThe generated values are 32 and 24 hex characters, the minimum lengths the server accepts for TOKEN_SECRET and ADMIN_KEY (waived only when NODE_ENV=test). With PAYMENTS=fake the server uses the built-in fake PayPal and needs no network access; production mode refuses fake payments. All settings: packages/server/README.md.
To see the interface without a server, copy the web settings once and start the web dev server:
cp packages/web/.env.example packages/web/.env.local
npm run dev -w @gavel/webThen open /r/demo/screen?scripted=1. The flag plays a recorded scenario in the browser and makes no PayPal calls; /r/demo/bid?scripted=1&at=3000 and the console and receipt routes work the same way. Only development builds honour scripted=1; the hosted /demo/scripted page plays the recorded room in every build.
Use the real PayPal sandbox
Set PAYMENTS=sandbox and provide PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET and PAYPAL_WEBHOOK_ID. The names are in .env.example; keep the values in your local .env and never commit them. Nothing loads that file by itself: delete the lines you do not fill in (empty values count as unset), then run set -a; source .env; set +a before starting the server, or pass the variables inline. docs/RUNBOOK-GATES.md shows how each sandbox run is recorded.
Tests and quality checks
Every pull request runs tests, type checks, lint and the other quality checks in GitHub Actions (ci.yml). The same commands work locally:
| Command | What it runs |
|---|---|
npm test |
Unit tests for every package |
npm run test:property |
Property tests; each run prints its seed, GAVEL_PROPERTY_SEED=<n> replays it |
npm run typecheck |
Strict TypeScript across the workspace |
npm run lint |
ESLint with zero warnings allowed |
With a judge key (gvl_judge_<id>_<secret>) you can open a sandbox room, bid, hammer and read the ledger with plain HTTP. The key opens judge rooms only, never an operator route, and PayPal stays in the sandbox. Each key has its own room cap, hourly cap and expiry. A personal key stops on 30 November 2026 by default; the one shared judging key does not expire, can be revoked, and is the one judges receive in the Devpost testing instructions (added there by hand; it is never in this repository). You do not need a key to try GAVEL: a keyless judge room on /try works without one.
API=https://api.gavel.dualmindlab.tech
curl -s -X POST $API/api/judge/rooms -H "x-judge-key: $JUDGE_KEY" -H 'content-type: application/json' -d '{"title":"My lot"}'
curl -s -X POST $API/api/judge/rooms/$ID/bids -H "authorization: Bearer $SESSION" -H 'content-type: application/json' -d '{"amount":1500}'The whole path, with a "Try it" panel, is on the docs page Call the API as a judge. The operator makes keys with node scripts/make-judge-key.mjs. The spec is at openapi/gavel.yaml and rendered in the API reference.
- PayPal sandbox only: no live money and no live human test. The server kill ran on a CI runner, not the deployed host.
- G3 (honor period and reauthorize) passed for a wallet buyer and a 1.00 partial capture only; G5 voice accuracy is tested on voice clips only, which is why every spoken bid needs a confirm.
- Still open: the settlement latency decision, an independent security review of the judge-room items and a manual accessibility pass. Owners and dates are in docs/LIMITATIONS.md.
GAVEL talks to the PayPal sandbox only. No live PayPal call is made and no real money moves. Do not put real card numbers, real accounts or personal data into the demo. Secrets are never committed; report vulnerabilities as described in SECURITY.md. The open datasets contain no real people's data, and a privacy and secret scan runs on every dataset build (docs/PRIVACY.md).
| Read this | To learn |
|---|---|
| Docs site | Diagrams, proof pages and the judge paths |
| Guided tour | Ten steps from what GAVEL is to its limits |
| Judge walkthrough | A short path through the code and the evidence |
| Gate results | What each sandbox run proved |
| Limits and next steps | What is measured today and what comes next |
| Demo guide | What you can try today and what to expect |
| API reference | The OpenAPI spec, auth, errors, rate limits |
| Architecture | How the packages fit together |
| Design system, AG Grid tables | The Scoreboard interface and its grids |
| Decisions, plan | Why the design is the way it is |
| Deploy, gate runbook | Hosting the server, running a gate yourself |
| Changelog | What changed, day by day |
Package guides: server, voice, engine, web.
Read CONTRIBUTING.md and the code of conduct. Work goes through branches and pull requests, and the pull request template lists the checks.
Built by Harsh Bhanushali and Dhairya Patel for the PayPal Hackathon 2026. Product, engine, payments, voice, web app, docs and evidence are all in this repository.
Web app |
Docs |
Source |
Open data
PayPal sandbox only. Bids are held, not charged.





