Inspiration
Malagasy banks net their debts every day through BFM, the central bank. They do not move the full amount of every transfer. They move only the difference.
The traders in the market next door cannot do that. The rice seller gives credit to the restaurant. The restaurant owes the butcher. The butcher owes the vegetable seller. Each debt lives in a paper notebook and is settled in cash, one by one. Cash is scarce, so a single late payment blocks a whole chain of people who are, in total, almost even.
We asked a simple question: what if the market had its own clearing house?
What it does
Alamino is a clearing house for market traders.
- Add. A trader types a sentence ("I owe Hery 50 for rice") or takes a photo of a notebook page. The AI turns it into a draft debt.
- Confirm. The debtor and the creditor both approve. If their amounts differ, the AI proposes a fix. Both sides must still approve it.
- Clear. The engine cancels the debts that form circles. No money moves.
- Settle. Traders who still owe pay in with PayPal Checkout. When every pay-in is captured, PayPal Payouts pays the traders who are owed.
- Explain. Each trader gets a plain-language statement: what cancelled, what is left, and why.
In our demo market, five traders hold nine debts worth $990. Alamino settles all of them with $320 of real money:
| Amount | |
|---|---|
| Total debts | $990 |
| Cancelled by circles, no money moved | $570 |
| Absorbed by chains (traders in the middle pay nothing) | $100 |
| Paid through PayPal | $320 |
That is $1 - \frac{320}{990} \approx 67.7\%$ less cash for the same result.
How we built it
The netting engine is plain, tested TypeScript. It works in two stages.
Stage 1 cancels circles. For each circle $C$ of debts, it finds the smallest amount and removes it from every debt on the circle:
$$m = \min_{(i,j) \in C} d_{ij}, \qquad d_{ij} \leftarrow d_{ij} - m \quad \forall (i,j) \in C$$
Stage 2 computes the net position of each trader $i$ on what is left:
$$p_i = \sum_j d_{ji} - \sum_j d_{ij}, \qquad \sum_i p_i = 0$$
A negative position pays in. A positive position is paid out. Because the positions sum to zero, the clearing account always ends at zero.
PayPal does the real money movement in the sandbox:
- Orders v2 for each pay-in. The server reads the amount from the round, never from the browser, and checks the captured amount against the plan.
- Payouts for each pay-out, one batch per round. The batch id is the round id, so a retry cannot pay twice.
- No payout starts before every pay-in is captured.
- Amounts are integer cents in USD, because PayPal does not support the Malagasy ariary.
The AI reads messy input and writes explanations. It never computes or changes an amount. We call one vision language model through an OpenAI-compatible API, with a strict JSON schema on every call. It has three jobs:
- Read a typed sentence or a handwritten notebook photo (French, Malagasy, or both) and return draft debts.
- Suggest a fix when the two sides disagree on an amount.
- Write each trader's statement. The numbers come from the engine. The AI writes only the words.
The app is Next.js and TypeScript, with SQLite for the ledger, React Flow for the debt network, and AG Grid for the ledger and the finance dashboard. It is phone first, because traders use phones, not laptops.
The team is three people in Antananarivo. We built Alamino in about two days. AI coding agents wrote most of the code from one shared contract (types.ts plus an API table). The humans did what an agent cannot do: PayPal sandbox accounts, real notebook photos, phone tests, deploy, video.
Challenges we ran into
- Trust in money. A language model that reads "fifty" as "fifteen" is a disaster in a ledger. So the AI only proposes drafts, plain code builds every debt, and nothing is saved without a click from both sides.
- Who owes whom. "I owe Hery 50" depends on who is speaking. We made the person who captures always one side of the debt. The model returns only the other trader and the direction.
- Same name, two people. When a written name fits more than one trader, the app asks which one, with the answers as buttons.
- Handwritten notebooks. Real photos are tilted, dim and mix languages. We downscale phone photos and ask a question instead of guessing when the model is not sure.
- Money that must not move twice. Captures and payouts are idempotent, and the round follows a strict order: cleared, collecting, paying, done.
- No keys, still a demo. Without PayPal or AI keys, the app runs the full story in a simulated mode and a plain-code fallback. The UI labels both.
- Privacy. A trader sees only their own debts. Only the clearing house operator sees
Built With
- ag-charts
- ag-grid
- ag-studio
- better-sqlite3
- driver.js
- json-schema
- llm
- next.js
- node.js
- openai-api
- paypal
- paypal-checkout
- paypal-payouts
- paypal-sandbox
- playwright
- react
- react-flow
- sqlite
- tailwind-css
- typescript
