Skip to content
operatorupliftPublic

About

Give your agent a budget. Guarded exact x402 Solana devnet tools, durable receipts, and a public rehearsal.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

56 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Allowance. AI agents, x402, Solana. Give your agent a budget. Human-approved USDC spending for AI agents: the limits live outside the model, and every call leaves a receipt. Exact x402 payments, Solana USDC, local MCP bridge, durable receipts. allowanceonsolana.vercel.app



Open the policy lab   Watch the product tour   Read the developer guide



CI status Public rehearsal status Payments: x402 exact SVM Settles in Solana USDC Agents connect over local MCP stdio Node 22.19 or newer License: MIT

Let it buy the tools it needs. See where every cent went.

Approve  →  Propose  →  Check  →  Reserve  →  Sign  →  Receipt


How it works  ·  Trust model  ·  Status  ·  Run it locally  ·  Docs


Four screens of the public rehearsal. 01, plan the allowance: set a total, a per-request cap and a daily limit in the policy lab. 02, keep the budget in code: the agent proposes a tool and the server checks the policy and reserves the charge before the payer signs. 03, watch a run unfold in the narrated walkthrough, with no funds moved. 04, keep the receipt: settled, held and remaining amounts stay visible, and a blocked request never consumes the allowance.

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.


How it works

Agent, Allowance and Solana. The agent proposes: a bounded OpenAI Responses run or any MCP client over local stdio, with narrow tool schemas, and it never sees the payer key. Allowance decides: it checks each request against the operator's frozen policy, reserves in a SQLite ledger before signing, and holds one dedicated backend signer. Solana settles: exact x402 USDC payments through a facilitator, allowlisted direct transfers under a mandate, and settlement checked against chain evidence. Every decision becomes a durable receipt.
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


The trust model

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.


Status

Live 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
Gated 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
Validating 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
Planned 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

Run it locally

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.

1. Run the app

npm ci
npm run dev        # http://127.0.0.1:4318, Express hosts Vite in one process

For 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:hosted

Tests use deterministic adapters and isolated SQLite databases. They never spend or call paid APIs.

3. Open the operator workspace

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 calls

There 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.

4. Live payments, only on purpose

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-spend

The 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.docker is 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 node user, 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

Documentation

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.

About

Give your agent a budget. Guarded exact x402 Solana devnet tools, durable receipts, and a public rehearsal.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages