Whiteflow MCP Server

Whiteflow

A stablecoin payment gateway for merchants who sell internationally: payment links, payment pages, invoices, QR codes, discount vouchers, multi-currency prices, sales reports and instant settlement in USDT on Whitechain, with a one-line payment button and an SDK. Customers pay with zero gas. Plus Capital: get paid early from future sales. Testnet only (Whitechain Sepolia).

Status (Nov 7, submission): live on Whitechain testnet at whiteflow.org; every acceptance test below links its on-chain transaction. Requirements: docs/SRS.md. Design: ARCHITECTURE.md. How we built it: PIPELINE.md, AI_USAGE.md.

What makes it different

• Zero gas for the payer: the customer signs once; our relayer pays the gas.
• Instant settlement (T+0): money lands in the merchant's own wallet in the same transaction (included in about 1 s; Whitechain marks it finalized later); we never hold it.
• Exact amounts: the customer signs an authorization for an exact amount, so under- and overpayment (a common problem at crypto gateways) can't happen.
• Every receipt is an on-chain transaction anyone can check.
• Easiest to integrate: a one-line payment button or a small SDK, with signed webhooks.

Compared with existing gateways

We'd sit next to Whitepay, not replace it: Whitepay covers custodial, many-coin, fiat-settled processing; we're the non-custodial rail on Whitechain itself, with financing that only works when the payment is split on chain.

Why this needs on-chain stablecoin settlement

Repayment is enforced where the money arrives. One customer payment is split, in the same transaction, between the merchant, the investors who financed it and the gas fee, under rules neither the merchant nor we can change. A card rail or bank transfer can't route one payment to three parties by code, and an investor would have to trust the merchant to forward the money. With USDT on Whitechain, any verified investor can fund a café at 3 a.m. and gets repaid in one second.

Demo

• Live app: whiteflow.org (Whitechain testnet; test mode) · Demo shop: shop.whiteflow.org · Video (2:45): ⟨url⟩
• Walkthrough = acceptance tests AT-1 to AT-15 (docs/SRS.md §6)

Sponsor tracks

Whitechain (Operate · Scale · Tokenize; one prize)

Arkiv (Build on Arkiv)

Financing offers are read from Arkiv: the investor offer book queries mcplus.offer.v1 entities live (capital-arkiv.ts), and an offer drops out when its entity expires at the deadline. Discount codes are Arkiv entities (mcplus.voucher.v1) that expire with the code, and the checkout reads the live entity before applying a code: a missing or expired entity refuses the code, and if Arkiv can't be reached the code is refused while the sale can still be paid without it (applyVoucher, FR-ARK-7): code G4AT12 (10% off) is entity 0xf51f…482c, created in tx 0x3e21…1fa2 and expiring 7 Nov 06:30 UTC; the code is stored only as a keyed hash. A customer used it on a 6 + 5 USD page and paid 9.90 USDT on Whitechain AT-12. Financing offers are Arkiv entities (mcplus.offer.v1) that expire at the offer deadline; the investor offer book reads them (Capital tab). Writer address: 0xF216677A6c7635c34e7dD58927B98D141d538Cbe · Live proof (Phase 1 probe): create tx 0x2d651b87…771e (block 258050; create 3.2 s, ownedBy query 285 ms) · Runnable query: https://rabdi.explorer.arkiv.network/entity-explorer with arkiv.schema = str('mcplus.probe.v1'), or node --env-file=../../.env scripts/arkiv-probe.ts from apps/web (needs ARKIV_PRIVATE_KEY + ARKIV_ACCESS_KEY) · arkiv/schema.md, friction.md, reach.md, why-arkiv.md, how-you-use-arkiv.md.

Ethereum Foundation (Anon-RPC · CROPS)

Every chain read the app makes in the browser goes through Anon-RPC by default (Nym, Tor fallback), including Arkiv reads; a meter on the dashboard counts them (a production run showed Private reads 4 of 4, no CSP violations). The customer pay and checkout pages make no browser chain reads at all (the amount and merchant come from our server), so they can't leak the payer's IP. Exclusions (disclosed): relayer writes over HTTPS, the two mainnet bootstrap reads (eth_call to ethereum-rpc.publicnode.com), explorer history lookups, the server-side read behind the pay and checkout pages, the server's balance check behind "Pay with your wallet" (it answers only enough or not enough), the customer's own wallet's RPC traffic when they choose that option (their wallet, not ours), and, only if the customer presses "Use another wallet or email", Privy and the WalletConnect relay (see Privacy below), and the Nym worker's own plain traffic (directory lookups to validator.nymtech.net, one WSS to a Nym entry gateway, bundle fallbacks unpkg.com / raw.githubusercontent.com after jsDelivr). These carry no wallet data. The dashboard's Content-Security-Policy allows exactly these hosts on /merchant pages (not on /merchant/developers, which shows a new API secret); the customer pay, checkout, link and page routes allow no third-party hosts at all. Private-read proof (Phase 1): the app read Whitechain blocks through Nym (e.g. block 12,298,671) with 0 direct RPC requests in 12 browser test runs; a swapped worker bundle is refused (pinned hash). CROPS: C: payment functions are permissionless, so anyone can submit a signed authorization if our relayer is down · O: MIT (LICENSE) · P: private reads by default, no personal data on-chain or on Arkiv · S: non-custodial, keys stay on the user's device.

AI assistant (MCP)

packages/mcp is a local MCP server (stdio, also packaged as whiteflow.mcpb for Claude Desktop) that manages payment collection from an AI assistant. It has 14 tools: payment links, invoices, customers, list_payments, get_collection_summary and reminders. It can't move money.

• Sandbox (the default): a simulator on your computer, with no account and no network. Try it with no key.
• Testnet: the live gateway with your sk_test_ key. The key's merchant must belong to a Whiteflow workspace: sign in on whiteflow.org, then link the wallet in Settings.

cd packages/mcp && npm ci && npm run pack
claude mcp add whiteflow --env WHITEFLOW_MODE=testnet --env WHITEFLOW_API_KEY=sk_test_YOUR_KEY -- node "$PWD/dist/bundle/server/index.mjs"

Or connect any AI from one link, whiteflow.org/mcp: Add to Claude Desktop, Add to Cursor or Add to VS Code, or run npx -y whiteflow-mcp (npm) in any MCP client (Codex, Gemini CLI, Windsurf, Cline, Zed). Leave out both --env flags for sandbox mode. Details, the Claude Desktop install and the full tool list: packages/mcp/README.md. Parts of it are adapted from Pixa (MIT; licence in packages/mcp/THIRD_PARTY_LICENSES; ETHGlobal mentors confirmed this reuse is within Start Fresh).

Architecture

Full-stack: Next.js frontend, two TypeScript servers (relayer, web API incl. the gateway API: links, pages, vouchers, quotes, reports, settlements, keys, webhooks), a zero-dependency SDK + one-line pay button (packages/sdk), Postgres for sessions and rate limits only, and Solidity contracts on Whitechain that hold every money rule.

Shop server ──POST /api/v1/sessions──► Web API (apps/web) ──► checkout link
Customer /pay (no chain reads in the browser) ── signs a USDT authorization, no gas
        ▼
Relayer (apps/relayer): allowlist · payer has no code · signature, balance, window, replay
        · rate limits · daily gas budget · simulate first ── pays the WBT gas
        ▼
MerchantPay (one tx): pull USDT ─► 0.10 fee to relayer ─► advance holdback to investors ─► rest to merchant
        ▼
receipt → signed webhook to the shop
Dashboards read the chain privately via Anon-RPC (Nym), one Multicall per screen; offers live on Arkiv.

Contracts: contracts/ (Solidity 0.8.38, Foundry) · Relayer: apps/relayer/ (Node, viem) · Apps: apps/web/, apps/shop/ (Next.js 16) · Details: ARCHITECTURE.md

Setup

Requirements: Node 26, Foundry 1.8.6, git. Everything runs on Whitechain Sepolia (chain 1874); no mainnet funds are needed.

git clone --recursive https://github.com/Vishal4742/whiteflow && cd whiteflow
cp .env.example .env          # fill in the values; never commit .env

# Contracts (Foundry; fork tests run against Whitechain Sepolia with the real USDT)
cd contracts && forge build && forge test -vv && cd ..

# Relayer: http://127.0.0.1:8787 locally; production https://relayer.whiteflow.org/health
cd apps/relayer && npm ci && npm test && npm run dev        # GET /health, POST /relay

# Web app (merchant, investor, customer pages): http://localhost:3000
cd apps/web && npm ci && npm run typecheck && npm test && npm run dev

# SDK + pay button (zero dependencies)
cd packages/sdk && npm ci && npm test

# Demo shop on the SDK (20 integration lines)
cd apps/shop && npm ci && npm run dev

Test funds: claim WBT at faucet.testnet.whitechain.io, then swap some to the prize USDT (0xcedfb56113143d55b2358b8cfbb0deb5ad2f55a7) on testnet.yetitrade.fi. CI runs the same checks on every push (.github/workflows/ci.yml).

Contract tests: 155 Foundry tests (fork tests against Whitechain Sepolia with the real USDT). Coverage of the four deployed contracts (forge coverage --ir-minimum): lines 346/349 (99.1%), branches 92/92 (100%), functions 61/61 (100%). Per contract: CapitalMarket 100% lines, ClaimToken 99.1%, InvestorRegistry 100%, MerchantPay 97.8% (the two missed lines are _pause/_unpause, an IR line-map artifact; the pause test runs them).

Privacy of the payer options

The default checkout uses a guest key kept in the browser (no email recovery) and loads no third-party scripts. "Pay with your wallet" adds a browser-wallet button (no third party) and an opt-in Privy option (any phone wallet over WalletConnect, or email). Privy loads only when pressed, and the sheet says what it shares. Privy receives the IP address, user agent and a Privy analytics id (Privy 3.51 has no analytics switch); with email it also gets the email, the email wallet's address and the payment approval it signs. The WalletConnect relay sees the IP; its messages are end-to-end encrypted. We clear Privy's local session and analytics id after each checkout, so one browser's checkouts aren't linked.

Operations (testnet)

• Our demo wallets were funded once by a seed script from the team wallet (test USDT swapped from faucet WBT on YetiTrade); the app has no faucet button.
• Admin trust (testnet): one deployer key (0xb4E7…714D) is the compliance admin and the contract owner. It can force-transfer claims between eligible investors, freeze claim units and revoke investor eligibility (ERC-7943 rules, simulated KYC), and it can pause MerchantPay. Ownership uses Ownable2Step; production would put these roles behind a multisig.
• The relayer keeps its send lock, daily gas budget and per-payer limits in Postgres (a lease row with a fencing write, FR-REL-10), so they hold across server instances and redeploys. A mined revert bans that payer until the owner lifts it, and 3 reverts in an hour pause all relaying. Its WBT is refilled by hand (the automatic fee-to-WBT swap, FR-REL-8, wasn't built).

Limitations (honest)

• Testnet only (official USD₮ isn't on Whitechain mainnet yet). Maturity lock 60 s and grace 120 s on testnet so the demo can show them; 1 day / 7 days in production.
• KYC is simulated: our compliance key keeps an investor allowlist (standing in for WhiteBIT KYC). Cut for time: EAS attestations, debtor acknowledgement, pay-on-due-date, and default and recourse (a claim that is never repaid stays outstanding).
• A merchant could take sales outside our checkout; default rules, recourse and public sales stats would mitigate this, not prevent it.
• Investor caps (1 per advance, 2 per invoice) and the rule that an invoice buy leaves a fundable remainder are enforced by our server before relaying, not by the contract (which allows 8 holders), so two first fundings sent in the same few seconds can both pass. Each extra holder adds about 34k gas to a repayment, and the relayer refuses anything above its gas limit rather than pay for a failure.
• Invoice repayments are limited per payer (10 an hour), not per merchant: a merchant who also controls an invoice's investors could spend the relayer's 0.1 WBT daily gas budget in about 40 heavy repayments, paying about 4 USDT in fees. No funds are at risk; relaying pauses until the next day.

What's next (after Mumbai)

• Pay from another chain: one tested corridor (Ethereum Sepolia USDC into Whitechain USDT) with an exact destination amount and a refund path, before any "any chain" claim.
• Business accounts with roles, and settlement-address changes that need a second approval.

Team and AI usage

⟨team⟩ · AI usage per file and the full build trail: AI_USAGE.md, .batches/