MerchantPro is a high-performance B2B payment gateway and treasury engine tailored for modern enterprise operators. By composing modular account abstraction layers (ERC-4337) with next-generation stablecoin rails (Circle and Arc Network), MerchantPro unlocks frictionless business operations—including gasless payroll distributions, multi-chain invoice bridging, and autonomous AI-agent escrows—all authenticated via secure hardware biometrics (WebAuthn).
MerchantPro decouples complex multi-chain execution from corporate administration through a modular architecture.
graph LR
%% Client & Auth
Operator["SME Operator"] -.->|WebAuthn Passkey| Client["MerchantPro App (Next.js)"]
%% Session & Ledger Boundaries
subgraph TreasuryEngine ["Treasury Engine Boundary"]
Client -->|Secure Sync| SessionCookies[("Session Cookies (httpOnly)")]
Webhook["Circle Console Event"] -->|POST Callback| WebhookHandler["/api/webhook Handler"]
WebhookHandler -->|HMAC-SHA256 Auth| SQLiteDB[("SQLite/Postgres Ledger")]
end
%% Web3 Execution Pipelines
subgraph Web3Rails ["On-Chain Settlement Rails"]
Client -->|Gasless userOp| ModularCore["Circle Modular Wallets Core"]
ModularCore -->|Submit transaction| Bundler["ERC-4337 Bundler RPC"]
Paymaster["Circle Gas Station"] -->|Sponsor Gas| Bundler
Bundler -->|Execute Transfer| ArcChain["Arc Network Testnet"]
Client -->|Cross-Chain Bridge| CCTP["Circle App-Kit (CCTP)"]
CCTP -->|Burn Token| SourceChain["Solana / Base"]
SourceChain -->|Iris Attestation| MintTarget["Arc Mint Event"]
end
%% Style Tokens
style Operator fill:#10B981,stroke:#059669,stroke-width:2px,color:#fff
style Client fill:#3B82F6,stroke:#2563EB,stroke-width:2px,color:#fff
style TreasuryEngine fill:#1E293B,stroke:#475569,stroke-width:1px,color:#fff
style Web3Rails fill:#0F172A,stroke:#334155,stroke-width:1px,color:#fff
style SQLiteDB fill:#F59E0B,stroke:#D97706,stroke-width:1px,color:#fff
- Lazy Contract Deployment: To bypass unnecessary gas costs, smart accounts (MSCA) are derived deterministically using
CREATE2address calculations at signup. The actual contract deployment on-chain is deferred until the first outgoing B2B transaction is executed. - HTTP-Only Session Isolation: Rather than exposing wallet configurations or credentials to client-side
localStorage(susceptible to XSS attacks), all session state is synced using server-signed HTTP-only cookies withSecure,SameSite=Strict, andPath=/parameters. - Concurrent Execution via 2D Nonces: To prevent sequential transaction queue blockage (where a pending trade halts the entire merchant queue), the platform leverages 2D sequential nonce keys. This enables independent payroll batches, FX swaps, and customer invoices to process concurrently.
MerchantPro implements rigorous defensive security protocols across both backend APIs and smart contract integration endpoints:
- Cryptographic Event Reconciliation: The payment webhook endpoint
/api/webhookprevents reconciliation spoofing by validating inbound payload signatures via HMAC-SHA256. It processes the raw HTTP request body against the configuredCIRCLE_WEBHOOK_SECRETto prevent tampering. - Secure Ephemeral Key Derivation: Autonomous agent tools and settlement engines derive keys dynamically at runtime from environment variables. If no EVM credentials are configured, the runner securely generates an ephemeral, one-time execution key in memory, avoiding hardcoded default fallback vectors.
- Compliance Screening Rails: All outgoing transactions (transfers, bridge actions, swaps) are screened before execution against OFAC / Tornado Cash sanctions lists and heuristic check parameters, generating an immutable audit ledger inside the database.
- 1-Click Biometric Wallet: Register and log in instantly via device-native biometrics (TouchID/FaceID) to derive a secure ERC-4337 smart account without seed phrases or plugins.
- Gasless Payroll Batches: Upload standard CSV payroll databases to dispatch USDC to employees and vendors simultaneously in a single transaction sponsored by Circle's Gas Station.
- On-Chain Auto-FX Conversions: Issue multi-currency invoices (USDC/EURC) featuring automated slippage-protected swaps via Circle Swap-Kit pools.
- Cross-Chain Bridge Engine: Seamlessly accept stablecoin assets from external ecosystems (Solana, Base) and bridge them onto Arc Network via Circle CCTP.
- Sub-Cent API Gateway (HTTP 402): Restrict premium enterprise APIs behind micro-payment check challenges verified via off-chain EIP-712 signature handshakes.
The platform runs a unified relational persistence schema (PostgreSQL for cloud environments, SQLit3 for local development cache) to manage merchant metadata, invoice states, and audit records.
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ merchants │───────<│ invoices │ │ webhook_events │
├─────────────────┤ ├─────────────────┤ ├─────────────────┤
│ id (PK) │ │ id (PK) │ │ id (PK) │
│ credential_id │ │ merchant_id (FK)│ │ notification_id │
│ msca_address │ │ client_address │ │ event_type │
│ display_name │ │ amount │ │ payload (JSON) │
│ contact_email │ │ status │ │ parsed_amount │
│ fee_settings │ │ tx_hash │ │ processed_at │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
│ │
│ ┌─────────────────┐ │ ┌─────────────────┐
├─<│ payroll_batches │ └─<│ loyalty_tokens │
│ ├─────────────────┤ ├─────────────────┤
│ │ id (PK) │ │ id (PK) │
│ │ merchant_id (FK)│ │ owner_address │
│ │ recipients_json │ │ contract_address│
│ │ tx_hash │ │ status │
│ └─────────────────┘ └─────────────────┘
│
│ ┌────────────────────────┐
└─<│ bridge_transactions │
├────────────────────────┤
│ id (PK) │
│ source_chain │
│ burn_hash / mint_hash │
└────────────────────────┘
- Node.js:
v18.0.0or higher - Database: SQLite (default local cache) or Postgres
-
Clone the Repository:
git clone <repository_url> cd track-2-MerchantPro
-
Configure Environment Parameters: Copy the example file and populate it with your API keys:
cp .env.example .env.local
-
Install Core Dependencies:
npm install
-
Boot Up Development Server:
npm run dev
The platform will start immediately at
http://localhost:3000. -
Verify Production Bundle: Ensure compile integrity before deployment:
npm run build
merchantpro/
├── app/
│ ├── api/
│ │ ├── auth/passkey/ # WebAuthn session cookie handlers
│ │ ├── webhook/ # HMAC webhook verification endpoint
│ │ └── rpc/ # Arc Testnet Bundler API proxy
│ ├── components/ # UI components and global modal system
│ ├── globals.css # Custom design tokens & visual theme
│ ├── layout.tsx # Next.js global layout wrapper
│ └── page.tsx # SME Treasury & Invoice dashboard portal
├── contracts/
│ └── MerchantProEscrowV2.sol# Solidity escrow invoicing contract
├── lib/
│ ├── arc-config.ts # Arc Network chain specification
│ ├── contracts.ts # ABI definitions and token addresses
│ ├── db.ts # Database client and SQLite schemas
│ └── web3-provider.tsx # React Web3 Provider integration
├── scripts/
│ └── deploy-contracts.ts # Smart contract deployment pipeline
├── CONTRIBUTING.md # Guidelines for open-source contributions
├── LICENSE # MIT open-source license
└── SECURITY.md # Vulnerability disclosure policy