Biii MCP Server

BIII

Spoken "B3". Written BIII — a B with three bars. The real-world USDC till on Base: an independent merchant accepts USDC in person with just a phone. Non-custodial (their own wallet), no terminal, no PSP, no KYB middleman.

B = Base · 3 = phase three of the trilogy, and Base's three pillars.

---

The gap (researched, not assumed — 2026-07-21)

Accepting USDC on Base is solved for the online enterprise and unsolved for the real-world independent:

Nobody serves the café, the market stall, the plumber, the freelancer who wants to take USDC on Base with just a phone, keep the funds in their own wallet, and hand over a real receipt — in two minutes, with no account to open.

(Landscape verified on the date above; re-check before any public claim. We build compatible with Base/Coinbase/Flexa/Lyzi and claim no partnership.)

The trilogy — phase 3: the agentic economy pays real-world humans

MainStreet   →  WHO is safe to pay            (the reputation oracle)
LAWBOR       →  agent ↔ agent, outcomes PROVEN paid in USDC on Base
BIII         →  agents & humans  →  REAL-WORLD merchants     ← this

BIII is the bridge between the on-chain agent economy and the shopkeeper on the corner. The same "safe to pay" and "proven paid by a real USDC transfer" discipline, pointed at a till.

How it works

1. Merchant types an amount. → a charge (data only; the merchant's own address).
2. BIII shows a universal QR — an EIP-681 payment URI that every major wallet scans (Base App, Coinbase Wallet, MetaMask, Rainbow…).
3. The customer (or an AI agent) pays USDC on Base from their own wallet.
4. BIII watches the chain and verifies the transfer field-for-field — wrong token / chain / recipient / underpaid / unconfirmed ⇒ not paid, ever. Overpay is a tip.
5. Both sides get a receipt anchored to the txHash (refutable by anyone on Basescan).

BIII holds no key and moves no funds. It mints intents and reads the chain; the customer's wallet signs, and the chain — not us — is the only thing allowed to say "paid".

Run it

npm test                               # 226 assertions across 35 files + a 17-case eval harness, all offline
BIII_MERCHANT=0x<your address> npm run serve   # the non-custodial HTTP surface, :4700

• lib/till.js — pure core: money math, charges, EIP-681 URIs, verification, receipts
• lib/chain.js — read-only Base watcher (finds the paying transfer; never invents)
• lib/server.js — thin HTTP: /charge, /status, /receipt, /trust (the LOCAL safe-to-pay verdict as ONE fetch() — known-bad screen + this node's trust-core classifier + floor provenance, fail-closed, CORS-open: any web app embeds a pre-payment check with no MCP; shares lib/vet.js with the MCP tool so the two surfaces cannot drift), /asset (tokenized-asset authenticity as one fetch — genuine/impersonation/unsafe/unknown, fail-closed: a non-registry token is never a false genuine; a pre-trade check any page embeds and re-verifies on-chain)
• lib/trust.js — the trust triangle: composes reputation (MainStreet) + standing (LAWBOR) + settlement (chain) into one fail-closed verdict (unsafe/unknown/trusted/settled)
• lib/invoice.js — the same registry for Web2-style invoices: number, line items (exact micro math), due date, bill-to — paid by the same EIP-681, verified by the same chain discipline, settled/overdue lifecycle, and its receipt lands in the SAME provable till roll as a café sale
• lib/asset.js — the same registry for TOKENIZED ASSETS (stocks / treasuries / RWA): is a token contract the genuine issuer's or an impersonator? genuine / impersonation / unsafe / unknown, fail-closed — catches the FBI-flagged lookalike-token fraud, and composes into the trust triangle (till_vet_asset).
• Issuer-verified registry (data/issuer-verified.json, committed, multi-chain) — the AUTHORITATIVE, no-key, commercial-safe layer that earns the strong green "issuer-verified" badge. 147 entries across 9 chains, all from ISSUER-DIRECT sources: Dinari dShares (40, Base — enumerated on-chain from the factory's DShareAdded event, each re-verified via symbol()/name(); scripts/biii-rwa-issuer-direct.js), Backed / xStocks (100, across Ethereum/Arbitrum/Optimism/BSC/Mantle/XLayer/Ink — Backed's own public API api.backed.fi, no key; scripts/biii-issuer-backed.js), and Ondo (7 OUSG/USDY/rUSDY — official docs, each on-chain-verified). lib/asset-registry merges this over the aggregator by address, so a verified address reads provenance: issuer-official (green) while everything else stays aggregator-teal.
• scripts/biii-rwa-registry.js — builds the AGGREGATOR fallback (the teal "listed" layer). Coingecko's free tier (no key) → data/rwa-registry.json, generatedFrom: "coingecko (free)". Coingecko is an AGGREGATOR, so a match here is provenance: aggregator (teal "listed"), never the issuer-verified green — and the cross-check (scripts/biii-issuer-registry.js) flags any symbol the aggregator lists at a different address than the issuer-official one (potential lookalike). Fail-safe: every entry must validate (0x-40hex · integer chainId · symbol) or it's dropped — a schema drift yields an EMPTY registry, never a wrong "genuine" address.
• lib/export.js — the accounting export finance teams need: till_export turns the same verified receipts into an accountant-ready CSV (QuickBooks / Xero / Excel import it) where every row carries its txHash + Basescan link — a pointer to the chain, not a book to trust. Non-custodial, re-verifiable.
• lib/meter.js — the usage→bill mechanic for a white-label pilot: till_meter turns a month's receipts into a bill against an injected plan, split by trust — settled receipts are ON-CHAIN (provable), the verdict count is SELF-REPORTED (advisory) and labeled as such. Pure, stateless, non-custodial.
• lib/erc8004.js — interop with the dominant agent-reputation standard (ERC-8004): turns a ReputationRegistry.getSummary result into a SEPARATE, advisory, re-verifiable lens on till_trust. Feedback is client-submitted (sybil-farmable), so it never enters the payable decision — it informs, keeps the sybil caveat unless filtered to trusted clients, and always points to re-verify getSummary on Base.
• Decentralization is checkable, not claimed — the known-bad floor carries a content fingerprint (floorFingerprint / till_floor): two nodes with the same fingerprint judge on the same objective floor, re-derivable from named public MIT lists, so convergence is on public data + a deterministic hash, never on a central operator. The classifier is replicated (pure trust-core), the floor converges on public data, and relative reputation stays deliberately local — divergence, where it exists, is always fail-closed (a node with less data is more cautious, never more permissive).
• lib/identity.js — the agent glue: npub AND/OR did:key ↔ Base, trustless. Resolves a buzz/Nostr identity (secp256k1 npub) or a gitlawb identity (Ed25519 did:key) — or both — to a payable, trust-assessable Base address via a bidirectional attestation (each identity key present signs, and the Base key signs, the same canonical message; anyone re-verifies). Fail-closed: unverified / an identity key missing its signature / no identity key / expired ⇒ a claim, not a binding. Resolving is not trusting — you still run the triangle on the address.
• lib/skyfire.js — interop with Skyfire (Experian's agent-identity layer): (1) a KYA JWT lens — who backs an agent (advisory, aud anti-replay, weak posture surfaced: a no-exp or non-audience-bound token is flagged, strict callers refuse with requireExpiry); (2) authorizeCharge — the Programmable Payment: a charge only becomes an executable EIP-681 intent if it's inside what the agent's OWNER signed off — token, recipient allow-list, per-charge max, AND the cumulative cap (drain-safe: ten small charges can't beat a low cap; a malformed or absent limit is REFUSED, never treated as "no limit"). Both fail-closed; BIII does not verify JWT signatures itself (delegated, no dep).
• bin/biii-mcp.js — the agentic bridge: an MCP any agent loads (15 tools: till_vet_merchant, till_create_charge, till_check_payment, till_trust, till_create_invoice, till_check_invoice, till_vet_asset, till_receipt, till_roll, till_export, till_meter, till_floor, till_resolve, till_kya, till_authorize) — an agent can vet a merchant or a tokenized asset, get the whole trust triangle in one call, issue or pay an invoice, keep a receipt, export the books, meter usage, prove its floor, resolve a buzz npub or a gitlawb did:key to a Base address, read a KYA identity, spend only within a signed authorization, and render provable books (till_roll)
• pitch/trust-triangle.html — the sellable white-label one-pager (self-contained, theme-aware)
• COMPETITION.md — the researched landscape (dated): ride the rails (x402/Stripe), interop with the standards (ERC-8004/Skyfire KYA), never custodial — the open layer is the non-custodial trust registry
• INTEGRATION-buzz.md / INTEGRATION-gitlawb.md — honest partnership briefs, each with a runnable offline proof (examples/buzz-agent-pays.js, examples/gitlawb-agent-pays.js — smoke-tested in CI so the demos can't rot): a keypair agent resolves→Base, a sanctioned counterparty is BLOCKED, a clean payment settles with a txHash-anchored receipt
• web/ — the merchant phone app (PWA): amount → QR → PAID ✓ → receipt

Business model — the trust+bridge layer partners resell

BIII is not (only) an app to grow one merchant at a time. It's a white-label trust + bridge layer that companies who already have the merchants plug in:

They bring the clientele. BIII brings the trusted USDC payment + the human/agent bridge + the provable receipts. Sold to PSPs, neobanks, merchant platforms, Base ecosystem apps.

The one-pager for that conversation — the trust triangle, the four verdict states, the white-label split, the receipt, and the honest landscape — is pitch/trust-triangle.html (self-contained, theme-aware, no external requests).

Lyzi is white-label for PSPs but terminal/enterprise and human-only. BIII is white-label too — and it's the one that also lets AI agents pay, ships un-fakeable consumer receipts, and runs non-custodially (the partner never touches the merchant's funds, so no money-transmitter custody to license). That combination is the wedge.

Stance: genuinely open to partners with distribution. We build compatible with Base/Coinbase/Flexa/Lyzi and claim no partnership until one is signed (anti-hype).

Trust roadmap — make BOTH sides safe

• Now: the payer is protected by field-for-field on-chain verification; the merchant can be vetted via MainStreet's "safe to pay" reputation (till_vet_merchant), advisory.
• Next (ZK): privacy-preserving attestations so each side proves what matters without doxxing — "this merchant is verified", "this payer is reputable / has funds" — as a zero-knowledge badge, not a data dump. The receipt already proves the payment; ZK proves the parties. (Design tracked; not built yet — no ZK claims until it ships.)

The receipt & the books (the human layer)

lib/ledger.js turns a payment into a paper-ticket a non-crypto human instantly reads (merchant, B3-####, item, amount, tip, ✓ PAID, a verify link) and a provable day roll for the merchant — every line re-checkable on-chain, one txHash counted once, books that can't be padded. Nobody offers this for in-person USDC today; it's the trust made legible.

Non-negotiables

Non-custodial by construction · descriptor-only (never signs, never custodies) · the chain is the only source of truth for "paid" · every receipt re-verifiable by anyone · real numbers only, no invented usage or partnerships.