Approve → Propose → Check → Reserve → Sign → Receipt
How it works · Trust model · Status · Run it locally · Docs
Captured from a local build of the public rehearsal on 30 October 2026. No funds moved.
Allowance gives an AI agent a fixed, human-approved USDC budget for exact x402 payments on Solana. A person sets the budget, the per-request cap, the permitted tools or recipients, and the expiry. The agent only proposes: the server checks each request against that frozen policy, reserves the charge in a durable ledger, and only then lets a dedicated payer sign. Every decision, hold and settlement lands in a receipt.
Built by Matt (RVAClassic, Operator Uplift) for the Solana Foundation Agentic Payments sprint, September 2026.
| The limits live outside the model The model can only propose a purchase. Budget, per-call maximum, tools, recipient, network, mint and expiry form an immutable policy that application code enforces before anything is signed. |
Reserve, then sign A SQLite BEGIN IMMEDIATE transaction reserves the charge first. A unique purchase identity and a canonical request hash stop repeated signing, and a database failure denies new payments. |
Evidence, not claims A facilitator response, chain verification and a delivered result are recorded as separate evidence. A receipt only says SETTLED once the chain shows it. |
Two payment rails share one policy engine, one daily ceiling and one receipt format:
| Rail | What the agent can do | How it is gated |
|---|---|---|
| x402 tool purchases | Buy two first-party Solana data tools with exact x402 payments: wallet_snapshot for 0.010000 USDC and transaction_explain for 0.020000 USDC. |
The run's policy names the tools, the per-request cap and the budget. The guarded buyer checks the actual payment requirement before the payer signs. |
| Direct payments | Pay exact USDC to recipients the operator listed in advance, through the execute_guarded_payment MCP tool: one TransferChecked per request. |
A mandate fixes the per-request cap, ceiling, expiry and recipients. Blocked requests become durable BLOCKED receipts with nothing signed. See direct payments. |
React 19 · Vite 8 · Express 5 · TypeScript · SQLite (better-sqlite3) · @solana/kit 5 · x402 2.25 exact SVM · OpenAI Responses API · MCP stdio · Argon2id sessions · Vitest · Playwright · Docker
Allowance is a server-managed signer with application-enforced controls, and the scope is deliberate: controls live in application code, not in a custom onchain budget program, a smart wallet or a payment channel.
| Control | What it guarantees |
|---|---|
| Exact money | USDC is bounded integer micro-units inside, decimal strings at the API boundary. 0.04 is exactly 40000. |
| Frozen policy | Budget, per-call maximum, tools, destination, recipient, network and mint, expiry and call limit are bound at approval. A shared UTC daily ceiling applies across runs, and outstanding holds still count when the day changes. |
| Guarded signer | The signer checks the actual transaction and records a signing claim before it touches the key. An uncertain outcome stays held and freezes the payer instead of retrying. |
| Stop and expiry | Both block new signatures. Work already signed can still settle, and a restart restores receipts and reconciliation without restarting the old model authorization. |
What it does not claim: a compromised server could defeat application-level controls. That is why the signer stays backend-only and the documented setup uses a dedicated low-balance payer, and why both shipped merchants are labeled as first-party sample services rather than third-party adoption. The full analysis is in the threat model.
| The public rehearsal at allowanceonsolana.vercel.app: landing page, policy lab, narrated tour and walkthrough, developer guide, brand library and installable PWA. It runs no backend, signer, model or payment endpoint. | Vercel deployment | |
| Live x402 purchases and direct USDC payments on devnet or mainnet. Implemented and covered by controlled-adapter suites, closed until an operator supplies a persistent host, credentials and funded accounts. As of the 20 September 2026 inspection, no Allowance settlement had been observed on either network. | Integration status | |
| The Seeker Android shell and Solana dApp Store listing. The WebView shell builds; native exports and device behavior still need validation, and the listing waits for a live server. | Seeker and PWA | |
| Payment channels and remote MCP, kept as design notes. The local stdio MCP bridge is implemented and shares the same policy, ledger and receipts. | Payment channels |
| Prerequisites Node 22.19 or newer in the 22 or 24 line, npm and a writable local disk. Docker for the container check. |
Read first Live setup and the threat model, before any payment is switched on. |
What the checks prove The verification report says what each check covers and what none of them do. |
npm ci
npm run dev # http://127.0.0.1:4318, Express hosts Vite in one processFor a local production build, npm run build then npm start: Express serves dist/client and runs the bounded background worker.
2. Before a pull request, run what CI runs
npm run check # lint, types, unit and integration tests, production build
npx playwright install chromium
npm run test:browser
npm run build:rehearsal && npm run test:hostedTests use deterministic adapters and isolated SQLite databases. They never spend or call paid APIs.
cp .env.example .env
npm run setup:operator # Argon2id hash and session secret into .env, mode 0600
npm run build && npm run preflight # configuration and network checks, no signing, no model callsThere is no public registration. Every live API stays closed until the password hash and session secret are in place, so a deployment without operator credentials cannot spend.
| Setting | Effect |
|---|---|
LIVE_PAYMENTS_ENABLED=true |
Turns on real spending. Off by default. |
MAINNET_PAYMENTS_ACKNOWLEDGED=true |
Required as well for mainnet, the default network. |
PAYMENT_NETWORK=devnet |
Selects devnet for testing. Existing receipts keep their original network. |
DIRECT_PAYMENTS_ENABLED=true |
Opens the mandate rail for allowlisted recipients. |
MCP_ENABLED=true and MCP_GRANT_TOKEN |
Lets an authorized local agent use the stdio bridge (npm run mcp). |
OPENAI_API_KEY and OPENAI_MODEL |
Powers the built-in runner. The model ID is required and never guessed. |
# Only after configuring and explicitly authorizing a real-USDC spend:
npm run smoke:mainnet -- --confirm-mainnet-spend
# Testing alternatives, with PAYMENT_NETWORK=devnet:
npm run smoke:devnet -- --confirm-devnet-spend
npm run smoke:direct-devnet -- --confirm-devnet-spendThe scripted scenario spends at most 0.030000 USDC, and its separate 0.020000 probe must be denied before signing. Without the confirmation flag a smoke command exits before it creates a signer. Do not retry an uncertain payment under a new ID. Setup for payer and recipient accounts, the facilitator and the fee sponsor is in live setup; every variable is in the configuration reference.
Docker and persistent disk
Run exactly one application instance on one persistent volume, which holds SQLite, its WAL, sessions, purchase identities and the merchant response cache. Never put the live backend on an ephemeral serverless filesystem.
docker build -t allowance .
docker volume create allowance-data
docker run --name allowance --restart unless-stopped \
--env-file .env.docker \
-e APP_ORIGIN=https://allowance.example \
-e HOST=0.0.0.0 -e PROXY_HOPS=1 \
-e DATABASE_PATH=/data/allowance.sqlite \
-e PAYER_SECRET_FILE=/run/secrets/allowance-payer.json \
-p 127.0.0.1:4318:4318 \
--mount type=volume,src=allowance-data,dst=/data \
--mount type=bind,src=/absolute/path/to/allowance-payer.json,dst=/run/secrets/allowance-payer.json,readonly \
allowance- Put one HTTPS reverse proxy in front of the bound local port.
.env.dockeris ignored by git, and Docker env files take literal values, so drop the single quotes around the Argon2 hash when copying it from.env. - Never copy key files into the image. The image runs as the unprivileged
nodeuser, which must be able to read the mounted key. - For rehearsal-only hosting, omit the secret mount and keep
LIVE_PAYMENTS_ENABLED=false: the container then serves the full rehearsal with no signer present. - Back up and restore with the supported commands, never by copying an active SQLite file. A restored journal starts locked against new spending until an operator reviews it. Never run replicas or share one payer across journals.
Routes
| Route | Use |
|---|---|
/ |
Landing page and interactive receipt preview |
/demo |
Narrated product tour with captions and downloads, plus interactive outcome fixtures |
/lab |
Policy lab: set an allowance, a per-request cap and a daily limit, then save the plan |
/developers |
Tool descriptions and a server-side client example |
/brand |
Downloadable profiles, wallpapers, headers, social artwork and logos |
/login |
Single-operator password login |
/app |
Overview, Runs, Payments and Setup, with authenticated task and payment controls |
/runs/:id |
A private durable run: report, JSON export, print view and stop |
The workspace uses a desktop sidebar and phone navigation, with direct links such as /app?view=payments. The static deployment shows setup requirements; private activity and live controls need the persistent operator backend.
Repository layout
| Path | Contents |
|---|---|
src/ |
The React UI: landing page, policy lab, walkthrough, workspace, brand library |
shared/ |
Validated contracts, mandates and exact money handling shared by client and server |
server/ |
One Express service: auth, agent, policy, payments, direct, merchant, data, db and the MCP bridge |
examples/ |
paid-tool.ts: calling the guarded buyer outside the sample agent |
tests/ |
Vitest suites with controlled adapters, plus Playwright browser and hosted journeys |
android/ |
The Seeker WebView shell with native wallet-intent plumbing |
docs/ |
Architecture, setup, runbooks, threat model and dated release reports |
evidence/ |
Dated screenshots, deployment checks and read-only chain observations |
| Understand it Product description Architecture Threat model Receipt contract |
Operate it Live setup Configuration reference Runtime, backup and recovery Local MCP runbook |
Check it Verification report Integration evidence and gates Release report, 20 September 2026 Sources, SDK reuse and licenses |
| Show it Product tour and walkthrough guide Brand kit: 26 compositions, tokens and fonts |
Ship it Vercel rehearsal Seeker, Android and PWA dApp Store listing kit |
Submit it Sprint submission draft, written to be finalized with a funded run's receipts |
Original code and artwork are MIT licensed (see LICENSE); dependencies keep their own licenses. Allowance is a working product name: check trademark availability before any commercial use.
Built by Matt Sim, founder of Operator Uplift. More builds at github.com/operatoruplift. Want one built for your product? Book a 15-minute call.