SpendBound

Guardrail and receipt layer for agentic vendor payments.

SpendBound lets small crypto teams auto-pay approved USDC vendor invoices on Base with an agent that only executes within treasury policy and proves every decision with a receipt.

An AI agent reads invoices and proposes payments. A deterministic policy engine decides whether each payment is allowed. Locus executes the approved ones on Base.

---

How it works

Invoice text
  → Agent parses (Locus wrapped OpenAI)
  → Agent checks vendor (Locus wrapped Exa)
  → Policy engine evaluates
       │
       ├── APPROVED → Agent auto-pays (Locus /api/pay/send)
       │                → Agent logs reasoning (Locus /api/feedback)
       │                → Execution receipt with proof fields
       │
       ├── APPROVAL_REQUIRED → Checkout for human approval (Locus SDK)
       │                         → Agent logs reasoning
       │
       └── BLOCKED → No execution. Violated rule shown.
                      → Agent logs reasoning

1. An invoice or payment description is pasted into the agent input.
2. The AI agent extracts structured payment fields using an LLM routed through the Locus pay-per-use AI marketplace (wrapped OpenAI API). Locus handles both the AI call and the billing — the agent pays for its own intelligence in USDC.
3. The extracted request populates the payment form for human verification.
4. The policy engine evaluates six rules deterministically and returns one of three outcomes:
   • APPROVED — all rules pass, amount is within the auto-pay cap. The agent submits payment to Locus automatically.
   • APPROVAL_REQUIRED — all hard rules pass, but the amount exceeds the auto-pay cap while staying within the approval limit. A Locus Checkout session is created for explicit human authorization.
   • BLOCKED — a hard rule fails or the amount exceeds the approval limit. No payment is submitted.
5. Every outcome produces a receipt: approved receipts include Locus execution proof fields; blocked receipts show the violated rule and decision log.

---

Locus integration

SpendBound chains seven Locus capabilities in a single agent flow:

Capability	Locus endpoint	Role in SpendBound
Wrapped OpenAI	/api/wrapped/openai/chat	Agent parses invoices via Locus AI marketplace — pays for LLM in USDC
Wrapped Exa	/api/wrapped/exa/search	Agent checks vendor web presence via semantic search
USDC Transfers	/api/pay/send	Auto-pay for approved payments within the cap
Email Escrow	/api/pay/send-email	Pay vendors via email — no wallet required on their end
Checkout SDK	@withlocus/checkout-react	Human-in-the-loop approval for larger payments
Transaction polling	/api/pay/transactions/:id	Receipt refreshes with real lifecycle state and tx_hash
Feedback	/api/feedback	Agent logs decision reasoning to Locus after every evaluation

One click triggers Parse → Verify → Evaluate → Execute — four pipeline stages, seven Locus APIs, all autonomous. If the invoice has no wallet address but has an email, the agent uses Locus email escrow — the vendor claims USDC to any wallet they choose. The vendor receipt page (/receipt/[id]) gives vendors a live view of their payment status and on-chain proof.

---

Architecture

SpendBound separates intelligence, policy, and execution:

• AI agent (via Locus) — reads unstructured invoices and extracts structured payment requests using the Locus pay-per-use AI marketplace. Checks vendor web presence via Locus wrapped Exa search.
• App-level policy engine — deterministic allow/block/approval logic, request normalization, decision logs, human-readable rule checklists.
• Locus payment rail — Base-native USDC payment submission via wallet transfer or email escrow, Checkout for human-in-the-loop approval, spend controls, payment lifecycle, and execution references.
• Auditability — every decision is logged to Locus via /api/feedback with full rule results and reasoning.

---

Stack

• Next.js 14 — TypeScript, App Router
• Tailwind + shadcn/ui — minimal, premium UI
• Locus — USDC payment execution on Base (beta API)
• Locus wrapped OpenAI — pay-per-use AI for invoice parsing
• Locus wrapped Exa — vendor web presence check via semantic search
• Locus Email Escrow — pay vendors via email, no wallet required
• Locus Feedback — agent decision reasoning logs
• @withlocus/checkout-react — embedded Checkout for human approval

No custom smart contracts. No auth. No wallet connect. No Supabase. No chat UI. No OCR.

---

Demo

Demo thresholds: 5 USDC auto-pay cap, 25 USDC approval limit. Demo amounts: 3 / 10 / 50 USDC. Amounts are chosen to be credible for the story while still reasonable for live on-chain demos — the policy engine is threshold-agnostic and the same logic applies at any scale.

1. Approved (auto-pay) — 3 USDC

1. Load the auto-pay sample invoice. Click Process with Agent — the pipeline stepper shows Parse → Verify → Evaluate → Execute in real time.
2. The agent parses the invoice (Locus OpenAI), checks the vendor's web presence (Locus Exa), evaluates against policy — all six rules pass → APPROVED — auto-submits the payment (Locus pay/send or pay/send-email) and logs the decision (Locus Feedback).
3. Execution receipt appears: transaction_id, queue_job_id, status, from_address, to_address, amount, token. Real USDC on Base.

2. Approval required (human-in-the-loop) — 10 USDC

1. Click New Request, load the approval sample. Click Process with Agent.
2. Five hard rules pass, auto-pay cap exceeded → APPROVAL_REQUIRED.
3. A Locus Checkout session is created. The human operator reviews and explicitly authorizes.
4. Fallback: if Checkout is unavailable, the payment can be submitted directly via Locus.

3. Blocked — 10 USDC

1. Load the over-limit sample. Click Process with Agent.
2. The amount rule fails → BLOCKED.
3. No payment is submitted. The violated rule and full decision log are shown.

Session history

After running all three flows, a session history panel appears at the bottom showing every decision: vendor, amount, outcome, timestamp, and transaction reference. This accumulates within the session without any database.

---

Setup

Prerequisites

• Node.js 18+
• A Locus beta API key (self-registration or dashboard)
• USDC on Base in the Locus smart wallet

Install and run

git clone <repo-url>
cd spendbound
npm install

Create .env.local:

LOCUS_API_KEY=claw_dev_your_key_here
LOCUS_API_BASE_URL=https://beta-api.paywithlocus.com/api

npm run dev

Open http://localhost:3000.

Locus smoke test (optional)

node scripts/locus/smoke.mjs

Runs agent self-registration, wallet deployment polling, balance check, and an optional tiny USDC send.

---

Track alignment

Locus partner track

SpendBound chains seven Locus capabilities in a single agent flow: wrapped OpenAI for invoice parsing, wrapped Exa for vendor web presence checks, wallet transfers and email escrow for payment execution, the Checkout SDK for human-in-the-loop approval, transaction polling for lifecycle visibility, and the Feedback API for decision auditability. One click triggers four pipeline stages across seven Locus endpoints. The vendor receipt page (/receipt/[id]) gives vendors a live view of their payment status. Spend controls, auditability, composability, email escrow, and payment lifecycle handling are all central to the product.

Agents that Pay

SpendBound is an agent that reads invoices, proposes payments, and executes them within policy. It directly addresses scoped spending permissions, deterministic policy enforcement, human-in-the-loop approval for larger payments, and cryptographic proof of what the agent did. The product is designed around the question: how do you make an agent safe enough to trust with money?

Open Track

SpendBound is a coherent, focused agentic payments product aligned with the core hackathon thesis around trustworthy agent execution.

---

Known limitations

• Single policy, single vendor — this is a focused MVP, not a multi-tenant platform.
• No persistence layer — session history is in-memory and resets on page refresh.
• QUEUED is the expected initial payment status — Locus processes transactions asynchronously. A tx_hash may appear on status refresh but is not required for the receipt to be valid.
• Checkout completion depends on the Locus beta Checkout environment. A direct Locus submission fallback is always available.
• If the live payment path is unstable during demo, a previously captured real Locus execution receipt is used as fallback. The policy evaluation always runs live.
• Demo amounts (3 / 10 / 50 USDC) match the policy thresholds for a clear three-path demo. The policy engine is threshold-agnostic — the same logic applies at any scale.

---

Project structure

src/
  app/
    page.tsx                       # single-page dashboard
    api/evaluate/route.ts          # normalize + policy evaluation
    api/pay/route.ts               # evaluate + Locus payment submission
    api/status/route.ts            # Locus transaction status polling
    api/checkout/create/route.ts   # Locus Checkout session creation
    api/parse-invoice/route.ts     # agent invoice parsing via Locus wrapped OpenAI
    api/verify-vendor/route.ts     # vendor verification via Locus wrapped Exa
    api/notify-vendor/route.ts     # vendor email notification (best-effort)
    api/feedback/route.ts          # decision reasoning log via Locus Feedback API
    receipt/[id]/page.tsx          # vendor-facing receipt page (server-rendered)
  lib/
    types.ts                       # shared TypeScript types
    constants.ts                   # Base, USDC, vendor-services, thresholds
    demo-data.ts                   # seeded policy + demo requests + fallback proof
    parser.ts                      # request normalization
    policy-engine.ts               # deterministic 6-rule evaluation
    decision-log.ts                # structured decision log builder
    receipts.ts                    # approved/approval-required/blocked receipt builders
    locus.ts                       # thin Locus API wrapper (pay/send + transactions)
  components/
    invoice-input.tsx              # one-click agent invoice processor
    policy-card.tsx                # treasury policy display
    payment-request-form.tsx       # structured form + manual presets + agent prefill
    decision-card.tsx              # decision outcome + rule checklist + log
    receipt-card.tsx               # execution receipt with status refresh
    history-panel.tsx              # in-session decision history
scripts/locus/
  smoke.mjs                        # Locus beta smoke test