Skip to main content

The Merchant Agent: automatic cash-out payouts

If you pay out cash-outs, the Merchant Agent can pay them for you. It's a small program you run on your own machine, next to your bank account, and it does what you'd do by hand for each cash-out:

  1. sees a cash-out waiting for you;
  2. checks on the blockchain, through your own node provider, that the user's USDC is locked in the escrow for you;
  3. opens the user's sealed bank details with your payee key;
  4. checks the amount, your limits and the account holder's name;
  5. pays from your bank account, through Paystack, your own payout API, or a person on your team;
  6. tells RecoilPay the transfer reference.

When anything looks wrong, it stops, holds the trade, and alerts you. A person decides.

What it never does​

  • It never sends bank details to RecoilPay. Users seal them to your payee key in their own browser. The agent opens them in memory to pay, and keeps only the last four digits.
  • It never pays without an on-chain lock. It reads the escrow lock itself, from your own RPC provider, rather than taking RecoilPay's word.
  • It never pays the same trade twice. Each payout has a fixed key, written down before your bank is called. After a crash or a timeout, it asks your bank about that key.
  • It never goes over your limits: per trade, per day, per customer account, how many an hour, and a minimum balance.
  • It never listens to the internet. It makes outbound calls only.

Verified sellers​

If you require verified sellers, or RecoilPay requires it for your account, run version 0.2.0 or later. On those trades RecoilPay sends the seller's verified legal name, and the agent checks that your bank's name for the account is that person:

  • the same name, in any word order: it carries on with its other checks;
  • another name, or a partial match (a missing middle name, initials): it holds the trade as verified name mismatch, for a person to check and approve or leave;
  • RecoilPay couldn't show the name: it holds the trade as verified name unavailable, which can't be approved. Contact RecoilPay.

Version 0.1.0 ignores the name, so it can't hold a payout to an account in someone else's name. The name is handled like the account holder's: never logged, alerted or stored.

Getting started​

The agent runs as one container (Docker Compose on a VM, or Kubernetes), and starts in sandbox mode: Base Sepolia testnet and a simulated bank, with no real money. From the solver portal you need your operator id and API key (from registering), and your payee key (from Fiat trades → Export payee key for the Merchant Agent).

The agent's code is public at github.com/recoil-labs/merchant-agent, so you and your security team can read and audit exactly what runs on your servers. It is source-available, not open source: you may run it for your own RecoilPay merchant account, but not modify, redistribute or use it elsewhere. The repository's licence has the terms. Its image is ghcr.io/recoil-labs/merchant-agent. Its guide:

Each release image is signed. The upgrading runbook shows how to check the signature before you run it.

Known limits​

Cash-outs only (no purchases), EVM chains only (no Solana), one instance at a time, and no webhooks: it checks RecoilPay and your bank on its own schedule.