Judging criteria at a glance

In short. Circlekeeper is for the organiser of a small savings circle. Each month every member pays the same share and one member takes the whole pot. Today the organiser tracks this in a notebook and a group chat. Circlekeeper bills each share as a PayPal invoice, lets a member split a share or swap a turn only with their own yes, and sends the pot by PayPal Payouts. An AI treasurer on Cloudflare Workers AI answers questions and proposes changes. People approve them.

Technological Implementation. PayPal Invoicing (one invoice per share, split into parts when a member asks), Orders (checkout and the test card), Payouts (the pot) and verified Webhooks. AI: Granite 4.0 H Micro on Cloudflare Workers AI, with read and propose tools. Code drops any sentence that claims an action no tool performed, and checks amounts, dates, people and payment status against tool results. "Try to break it" runs three checks, each with 0 PayPal writes. Check it: src/paypal/invoices.ts, src/paypal/payouts.ts, src/paypal/webhooks.ts, src/ai/drop.ts, docs/REVIEW-PACKAGE.md.

Design. The organiser's board always says what the round is waiting for, with that member's page one tap away. The schedule shows every member's turn at once. Each member gets a Bryntum Calendar with their own dates in their own language.

Potential Impact. For small savings circles that already have an organiser, who today tracks shares in a notebook and a group chat. In Africa south of the Sahara, 1 in 4 adults saved through a savings club or a person outside the family in 2021 (World Bank, Global Findex Database 2021).

Innovation/Idea. Group consent and PayPal money in one flow. A split needs the member's yes, a swap needs both members, a payout needs the two chosen confirmers, and the pot waits for the last part of every share. A notebook or a spreadsheet records who paid. It cannot hold the pot until every part of every share is in, or stop a turn from moving until both members agree. Check it: src/circle/split.ts, src/circle/swap.ts, src/circle/gate.ts.

Presentation. The video runs 2 minutes 48 seconds. Try it at https://circlekeeper.midknight-labs.workers.dev: split a share, agree a swap, pay out the pot and check the receipt. Video guide: 0:21 Start sends six PayPal invoices; 0:39 Marisol splits her share: 60 now, 40 later; 1:15 a turn swap waits for both members; 2:04 PayPal Payouts sends the $600 pot; 2:19 the receipt shows $600 in and $600 out.

Inspiration

Savings circles are common. In Africa south of the Sahara, 1 in 4 adults saved through a savings club or a person outside the family in 2021 (World Bank, Global Findex Database 2021, section 2.2, page 79). That number is context, not a claim about this app.

Circlekeeper is for a small group that already has an organiser. Members pay the same share each month, and each month one member receives the pot. The organiser tracks who paid, chases late shares and settles requests to change turns, usually in a notebook and a group chat. Circlekeeper keeps payment status and agreed changes in one place.

What it does

The organiser describes the circle in plain words. Code builds a rotation and shows any needs it could not meet before Start. The organiser reviews the rules, which sit right under the "Review the rules, then Start" line, and must accept leaving out any text the app could not use. The schedule shows every member's turn at once on a laptop screen.

The top of the organiser's board always says what the round is waiting for, for example "Waiting for Marisol's remaining $40.00" or "Waiting for Theo to confirm the pot", with a button to open that member's page. Activity, Changes and Try to break it stay one click away. Rare fallbacks such as "Record cash" are quiet links, so the next step stands out.

Each share becomes a PayPal invoice. Members pay through PayPal's sandbox page or the sandbox test card button. Verified PayPal webhooks update payment status on the board.

Marisol has $60 toward her $100 share. She asks for a split, and after her Yes her invoice is replaced by a $60 invoice and a $40 invoice. The pot waits until both parts are paid. With private amounts on, the group hears only that her share is in two parts.

Dana asks to move her turn to March. Every swap card shows the turns today and after the swap, the stated needs that still hold (for example "Keisha needs February 2027"), and who has said yes. These reasons come from the rotation code, not from the model. Turns move only after both members say yes. A swap that would break a need is refused and names that need.

A payout needs every member's full share, including any split balance. Code checks the invoices again with PayPal before sending, then the two members the circle chose confirm. The board shows the payout batch and its status.

After a pot is paid, its receipt shows money in, money out and the difference. A SHA 256 check in the browser rebuilds the hashes from the receipt data on the page. It checks that the data is consistent; it is not a bank statement.

The organiser can ask "What if Theo leaves in March?" and see a ghost schedule beside the real one. Nothing moves. Each member has a Bryntum Calendar with their own dates in their own language.

What this demo proves

  • A share can be split and paid in parts, and the pot waits for the last part.
  • Nothing moves until the members agree: a swap needs both members, a split needs the member, a payout needs the two chosen confirmers.
  • The pot is paid out in the PayPal sandbox, and the round's receipt adds up.

Running it with real money would need the group's own PayPal business account or a licensed partner. That is future work.

How we built it

A Cloudflare Worker serves the pages and API. Each circle has a Durable Object that runs its actions one at a time. The pages are HTML and JavaScript; the server is TypeScript.

PayPal Invoicing handles shares. PayPal Orders handles checkout and sandbox test card payments. PayPal Payouts sends pots. Verified webhooks bring payment events back.

The treasurer is a model on Cloudflare Workers AI with read and propose tools. With live answers on, it runs Granite 4.0 H Micro. The demo replays replies recorded earlier with Qwen3 30B A3B FP8 on Workers AI. In a live test on 7 Nov 2026, Granite often answered in words without calling a propose tool, so code now drops any sentence that claims an action ("I'll propose a swap") unless that tool succeeded in the same turn. Code also checks recognised claims about amounts, dates, people and payment status against tool results, in supported English, Spanish and French expressions, and drops unsupported ones.

The activity panel shows PayPal actions and errors with HTTP codes, plus completed model steps with neuron use.

Challenges we ran into

Payment recovery needs care when PayPal accepts a request but the response is lost. The app saves payout identifiers before sending, reuses them during recovery, and asks for a manual check when the result stays uncertain.

Split shares need careful state tracking. The app tracks each invoice part and blocks another payment while a captured payment is being recorded.

On 9 Nov 2026 the PayPal sandbox started returning our invoice tag (custom_id) on the capture instead of the purchase unit, and every card payment was held as uncertain. The app now accepts the tag in either place and still refuses a capture whose tag names another invoice. A test covers both.

Model replies need checks beyond fluent wording: a reply must not claim a payment, an amount or an action that did not happen.

Accomplishments that we're proud of

The payment flow and the decisions around it live together. Members pay, ask for a split and agree to a swap. The organiser sees what is waiting, previews changes and checks receipts.

"Try to break it" runs three checks on an isolated copy of the circle. It simulates some PayPal replies and blocks payment writes; each check shows 0 PayPal writes. It is not a full security audit.

docs/REVIEW-PACKAGE.md ties the published commit to the test results, one sandbox payout (item status SUCCESS) and the hosted demo's settings. A test fails if its settings stop matching the code.

What we learned

A shared money tool needs clear points of agreement, and a clear answer to "what are we waiting for?".

What's next

Run the user sessions in docs/USER-VALIDATION.md with real savings group members, then explore running through a group's own PayPal business account or a licensed partner, including the approvals payouts need.

Built With

  • bryntum-calendar
  • bryntum-scheduler-pro
  • cloudflare-workers
  • cloudflare-workers-ai
  • durable-objects
  • granite-4.0-h-micro
  • html
  • javascript
  • paypal
  • paypal-orders
  • paypal-payouts
  • paypal-webhooks
  • qwen3
  • typescript
Share this project:

Updates

Submission history