FlowWage

FlowWage is a KeeperHub-native automation workflow for users who earn in stablecoins and need that money to do real work immediately: comply, route, deploy yield, off-ramp to fiat, and send private receipts.
It converts a fragmented multi-app manual process into one execution graph with verifiable outputs.

stablecoin income is growing, but post-receipt operations are still mostly manual. Users receive USDC, then separately handle compliance checks, chain routing, conversion timing, yield deployment, and notifications.

FlowWage unifies those steps in one keeper workflow:

1.⁠ ⁠Detect income context (invoice/stream/balance). 2.⁠ ⁠Parse encrypted payment intent. 3.⁠ ⁠Allocate funds by policy (liquid/yield/convert). 4.⁠ ⁠Enforce KYC gate before off-ramp. 5.⁠ ⁠Route and execute cross-chain transfer. 6.⁠ ⁠Deploy yield position. 7.⁠ ⁠Trigger and track fiat conversion. 8.⁠ ⁠Send wallet-native encrypted receipts.

Why This Is Necessary

From the requirements narrative: a user paid in USDC often faces:

•⁠ ⁠idle funds earning nothing, •⁠ ⁠manual corridor selection for conversion, •⁠ ⁠failed off-ramp attempts due to compliance not being pre-validated, •⁠ ⁠and poor traceability for what happened after payment.

Real-world example: A freelancer in Lagos receives 800 USDC. They need NGN for expenses and want the rest earning yield. Without orchestration, this means manually checking KYC status, searching off-ramp rates, deciding chain movement, approving contracts, and documenting transaction proofs.
FlowWage does this as one execution with structured outcomes (⁠ depositTxnRef ⁠, ⁠ conversionReference ⁠, XMTP conversation/message proof).

FlowWage implements the requirements narrative as a concrete KeeperHub workflow: from income signal and encrypted intent through compliance, cross-chain execution, yield deployment, conversion, and encrypted receipts.
It is built with minimal, pattern-consistent KeeperHub plugin changes and produces verifiable execution artifacts suitable for technical demos and real integration testing.

Added Integrations and Why Each Was Required

1. XMTP (⁠ xmtp ⁠)

XMTP provides the encrypted wallet messaging rail that turns payment intent and receipts into private, verifiable messages tied to the org wallet. It lets FlowWage listen for inbound intents, validate them, and reply with cryptographic receipts after execution.

•⁠ ⁠⁠ xmtp/send-message ⁠: send private, wallet-native messages for prompts and notifications. •⁠ ⁠⁠ xmtp/subscribe-to-inbox ⁠: register the inbox listener that powers event-driven intent triggers. •⁠ ⁠⁠ xmtp/parse-payment-intent ⁠: validate and normalize structured intent payloads before execution. •⁠ ⁠⁠ xmtp/send-transaction-receipt ⁠: deliver receipts that bind on-chain execution to the intent thread.

1. Persona (⁠ persona ⁠)

Persona is the compliance gate that prevents off-ramp failures by pre-validating identity status, corridor eligibility, and transaction limits before conversion attempts.

•⁠ ⁠⁠ persona/check-verification-status ⁠: reads current KYC state and tier for a user. •⁠ ⁠⁠ persona/create-inquiry ⁠: generates the verification link when a user is not yet cleared. •⁠ ⁠⁠ persona/get-cleared-corridors ⁠: returns approved country and currency corridors. •⁠ ⁠⁠ persona/subscribe-verification-webhook ⁠: resumes deferred conversions when KYC completes. •⁠ ⁠⁠ persona/get-transaction-limits ⁠: enforces daily and monthly limits based on tier.

1. Offramp (⁠ offramp ⁠)

Offramp is the fiat conversion engine. It discovers corridors, compares provider quotes, times conversions against rate history, initiates the transfer, and tracks settlement.

•⁠ ⁠⁠ offramp/get-supported-corridors ⁠: lists available fiat corridors for the user and asset. •⁠ ⁠⁠ offramp/get-best-quote ⁠: ranks providers by estimated receive and fees. •⁠ ⁠⁠ offramp/get-rate-history ⁠: supplies short-term rate trends for timing logic. •⁠ ⁠⁠ offramp/trigger-conversion ⁠: executes the selected conversion with provider metadata. •⁠ ⁠⁠ offramp/get-conversion-status ⁠: monitors conversion progress through settlement.

1. Superchain (⁠ superchain ⁠)

Superchain provides cross-chain routing and execution so funds can move to the chain that has the best yield or the cheapest off-ramp corridor.

•⁠ ⁠⁠ superchain/get-supported-routes ⁠: enumerates route and token availability. •⁠ ⁠⁠ superchain/get-route-quote ⁠: estimates cost and time for a specific route. •⁠ ⁠⁠ superchain/initiate-transfer ⁠: performs the cross-chain transaction. •⁠ ⁠⁠ superchain/poll-transfer-status ⁠: confirms the destination fill and settlement.

1. Request Finance (⁠ request-finance ⁠)

Request Finance provides invoice-native payment context so income can be detected immediately and correlated to payers and schedules.

•⁠ ⁠⁠ request-finance/subscribe-invoice-events ⁠: registers webhook triggers for invoice lifecycle events. •⁠ ⁠⁠ request-finance/get-payment-history ⁠: backfills historical cadence and payer context.

1. Existing protocol and signal integrations

Sablier and Superfluid supply the streaming income layer so FlowWage can detect and act on real-time accrual, not just balance snapshots. The Web3 actions handle approvals and token movements, while ⁠ aave-v3/supply ⁠ deploys the yield allocation into a secure lending market.

Deep Implementation Walkthrough

This section describes the implementation patterns that make the workflow reliable, repeatable, and auditable.

XMTP inbox subscription context initialization

This step establishes a stable XMTP client bound to the organization wallet. It resolves the correct environment, loads or creates the local inbox database path, and captures the sender address that is used for all downstream intent parsing and receipts. The persistence ensures the same inbox identity across repeated runs, which prevents thread fragmentation and message duplication.

Persona verification snapshot resolution

This step converts the provider response into a normalized snapshot that downstream nodes can evaluate deterministically. Status, tier, corridor eligibility, and limits are extracted into typed fields used by conditions and split logic, while the raw payload is preserved for audits and troubleshooting without blocking execution.

Offramp quote ranking logic

This step ensures provider selection is deterministic by ranking all eligible quotes by net receive. The result includes a best quote plus the ranked list so the workflow can either auto-select or present alternatives. This avoids hard-coding a single vendor and keeps the conversion outcome transparent.

Superchain initiate execution with nonce-safe sequencing

This step sequences approvals and swaps with explicit nonces to avoid race conditions across repeated runs. By fetching a pending nonce and incrementing locally, the approval and transfer are guaranteed to execute in order without accidental nonce reuse.

Across route preflight

Route preflight validates token, chain, and route compatibility before any transfer is initiated. It prevents wasted transactions by catching unsupported or mismatched routes early, then surfaces a clear error to the workflow.

Aave V3 support updates for Base Sepolia

The Base Sepolia updates add the pool and data provider mappings plus the required ABIs so testnet supply calls succeed. This ensures the yield path can run end-to-end in demos without ABI mismatches or missing pool addresses.