Documentation Index
Fetch the complete documentation index at: https://docs.wizpay.xyz/llms.txt
Use this file to discover all available pages before exploring further.
Introduction
WizPay is a programmable on-chain payment execution system. It accepts batches of payment instructions — payroll distributions, token swaps, cross-chain bridges, FX conversions — and executes them through a unified orchestration layer with deterministic state tracking.Technical Definition
WizPay is a task-based execution engine that:- Accepts structured payment payloads via HTTP
- Validates, batches, and queues them for asynchronous processing
- Routes each task to a domain-specific agent (payroll, swap, bridge, FX, liquidity)
- Settles on-chain through chain-specific adapters (Circle W3S, viem, Solana Web3.js)
- Tracks every state transition in an append-only audit log
Problem Statement
Executing on-chain payments individually introduces compounding costs:- Gas overhead — Each transaction pays a base gas cost. N separate transfers ≈ N× the cost of a batched approach.
- No atomicity — If transfer 47 of 100 fails, there is no built-in mechanism to identify which succeeded, which failed, and what to retry.
- Multi-chain fragmentation — Paying across EVM chains and Solana requires different signing flows, RPC endpoints, and token addresses. Managing this per-transaction is operationally fragile.
- No audit trail — Individual wallet-to-wallet transfers produce no structured record of intent, execution state, or outcome.
What WizPay Provides
| Capability | Mechanism |
|---|---|
| Batch execution | Multiple recipients grouped into TaskUnit records, processed within a single task lifecycle |
| State tracking | 8-state machine (created → assigned → in_progress → executed/partial/failed) with enforced transitions |
| Multi-chain abstraction | Adapters selected by execution router — agents never interact with chain libraries directly |
| Retry semantics | BullMQ exponential backoff (3 attempts), idempotent execution guards |
| Dual signing model | W3S (backend-signed via Circle) and Passkey (client-signed via AA wallet) |
System Boundary
| Layer | Technology | Responsibility |
|---|---|---|
| Frontend | Next.js | UI composition, task polling, wallet session |
| Backend | NestJS | Orchestration, state machine, queue, agent execution |
| Queue | BullMQ + Redis | Job scheduling, retry, concurrency |
| Database | PostgreSQL + Prisma | Task, unit, transaction, log persistence |
| On-chain | Circle W3S / viem / Solana Web3.js | Token transfers, bridge burns/mints, swaps |