Skip to main content

​
API & Integration Layer

All endpoints are served by the NestJS backend behind an Nginx reverse proxy (/api → backend).

​
Task Endpoints

​
POST /tasks

Create and enqueue a task for execution. 
{
  "type": "payroll" | "swap" | "bridge" | "liquidity" | "fx",
  "payload": { ... }
}
  • Validated via CreateTaskDto (class-validator, whitelist, forbidNonWhitelisted).
  • Calls OrchestratorService.handleTask().
  • Returns full TaskDetails with status and logs.

​
GET /tasks

List tasks with filters.
ParamTypeDefaultMax
typestring——
statusstring——
walletstring——
limitnumber50200
offsetnumber0—
The wallet filter searches across metadata.walletAddress, metadata.recipient, metadata.destinationAddress, metadata.sourceAddress, and their payload equivalents. Returns { data: { items: TaskDetails[], total: number } }.

​
GET /tasks/:id

Poll a single task. Returns TaskDetails including:
  • Status and metadata
  • All TaskLog entries (chronological)
  • All TaskUnit records with individual statuses
  • All TaskTransaction records with tx hashes and poll attempts

​
POST /tasks/payroll/init

Validate and batch a payroll run. Does not enqueue for execution. 
{
  "recipients": [
    { "address": "0x...", "amount": "100", "targetToken": "USDC" }
  ],
  "sourceToken": "USDC",
  "walletAddress": "0x...",
  "referenceId": "PAY-001"
}
Returns: 
{
  "taskId": "uuid",
  "approvalAmount": "5000",
  "referenceId": "PAY-001",
  "totalUnits": 2,
  "units": [{ "id": "uuid", "index": 0, "status": "PENDING", "payload": {} }]
}

​
POST /tasks/swap/init

Create a legacy on-chain swap task. Required fields: tokenIn, tokenOut, amountIn, recipient. Default/prod behavior: rejected unless WIZPAY_ENABLE_LEGACY_FX=true is set for isolated non-production testing. Official StableFX RFQ should use the FX quote/execute endpoints.

​
POST /tasks/liquidity/init

Create a legacy LP liquidity task. Required fields: operation (add | remove), token, amount. Default/prod behavior: rejected unless WIZPAY_ENABLE_LEGACY_LIQUIDITY=true is set for isolated non-production testing. The user-facing liquidity page is disabled during the official StableFX migration.

​
POST /tasks/:taskId/units/:unitId/report

Report the result of a single task unit. Used by the frontend after client-side execution (PASSKEY mode). 
{
  "status": "SUCCESS" | "FAILED",
  "txHash": "0x...",
  "error": "optional error message"
}
Atomically updates the unit, increments counters, recomputes task status, and returns the next pending unit (if any).

​
POST /tasks/fx/quote

Get an FX quote. Required: sourceCurrency, targetCurrency, sourceAmount.

​
POST /tasks/fx/execute

Execute an FX trade. Required: quoteId, signature, senderAddress.

​
Wallet Endpoints

EndpointMethodPurpose
/wallets/initializePOSTCreate wallet set + wallets via Circle W3S
/wallets/syncPOSTSync existing wallets from Circle
/wallets/ensurePOSTGet or create wallet for chain (EVM/SOLANA)
All require userToken in the request body.

​
Treasury Endpoints

EndpointMethodPurpose
/treasury/initPOSTInitialize app treasury wallet via Circle
/treasury/walletGETGet treasury wallet for a blockchain

​
External System Interfaces

The backend communicates with these external systems:
SystemAdapterProtocolOperations
Circle W3SCircleServiceRESTWallet provisioning, transfers, FX trades, tx status
Circle Bridge KitCircleBridgeServiceSDKCCTP burn+attest+mint
EVM RPCsBlockchainServiceJSON-RPC (viem)ERC-20 transfers, contract calls
Solana RPCSolanaServiceJSON-RPC (@solana/web3.js)SPL transfers, intent building
DEX protocolsDexServiceVariesSwap preparation
TelegramTelegramServiceRESTTask status notifications

​
Constraints

  • No direct frontend-to-chain calls in W3S mode. All on-chain operations route through the backend.
  • No concurrent task execution for the same wallet. BullMQ processes jobs sequentially per queue (except payroll at concurrency 5). No explicit wallet-level locking exists.
  • Circle rate limits apply. The backend does not implement its own rate limiting against Circle APIs. High-throughput payroll runs may encounter Circle-side throttling.
  • USDC-only for bridge. The CCTP bridge path only supports USDC. Non-USDC bridge requests are rejected at validation.
  • Passkey AA is EVM-only. Solana operations in PASSKEY mode return unsigned intents. The backend cannot sign Solana transactions for passkey wallets.
  • No webhook ingestion. Settlement confirmation relies on polling (tx_poll queue), not on-chain event subscriptions or Circle webhooks.