Operators and solvers
Every swap on RecoilPay is filled by a solver: an independent operator who delivers your tokens on the destination chain from their own funds and is repaid from your escrowed input on the source chain. This page explains who they are, what is expected of them, and how to become one.
Operators can do more than fill swaps. From the same portal they can also pay out cash-outs and sell crypto for naira, and buy and sell gift cards. Each is optional and set up separately.
If you only want to swap, you don't need any of this. You never deal with a solver directly. RecoilPay picks one for you.
Who solvers are
A solver (or operator; the two words mean the same thing here) is anyone who:
- holds tokens on the chains RecoilPay supports,
- publishes standing offers, called quotes, for the routes they're willing to fill, and
- has their quotes settled on-chain when one of them wins an order.
Solvers compete on price. When you ask for a swap, RecoilPay collects every quote that fits your request, scores them, and shows you the best one. The solver earns the small spread between what you put in and what you receive.
Operators don't run any servers. Quotes are published from the solver portal, and RecoilPay's hosted worker carries out the on-chain settlement for them.
How a fill works
One swap is three on-chain transactions across two chains. All of them are signed by the operator's fill-wallet:
| Step | Chain | What happens |
|---|---|---|
| 1. Escrow | Source | The user's input is pulled into the escrow contract, using the signature the user gave when they confirmed. The funds are locked. Neither the solver nor RecoilPay can take them. |
| 2. Deliver | Destination | The fill-wallet sends the agreed output to the user. This spends the solver's own inventory. |
| 3. Claim | Source | Once delivery is proven, the escrowed input is released to the solver's fill-wallet. This is how the solver is paid. |
If step 2 never happens, the solver can't claim, and the user takes their input back from escrow once the order expires. A failing solver costs the user time, never money.
What is expected of an operator
Keep the fill-wallet funded
The fill-wallet needs two different things:
| What | Which chains | Why |
|---|---|---|
| Native gas | Every chain you quote, both source and destination | Escrow and claim run on the source chain; delivery runs on the destination. All three cost gas. |
| Token inventory | Destination chains only | This is what you hand the user. You're repaid on the source chain moments later. |
For routes to Solana, the delivery side lives in a separate Solana fill-wallet. See Filling orders to Solana.
A route that mostly flows one way will drain inventory on one chain and pile it up on the other. Plan to rebalance.
Only quote what you can honour
A quote is a promise: "I will fill this route, at this price, for orders this big, until this time." If your quote wins and you can't deliver, usually because of missing gas or inventory, the fill fails and your reputation drops sharply (see below). A quote you don't publish costs you nothing. A quote you can't keep costs you a lot.
Price honestly
Each quote has two cost parts:
- Margin: a percentage of the order. A 0.15% margin means the user receives 99.85% of their input.
- Gas fee: a flat amount taken from every fill to cover your settlement gas. It's the same for a 1-token order as for a 10,000-token order, so it dominates on small orders. Keep it close to your real cost.
The portal shows what the user would actually receive at both ends of your order-size range, and warns you when that drops below 95% of the input.
RecoilPay's own fee does not come out of yours. On a swap it is an extra output in the order the user signs, so you deliver the same total you quoted and claim the same input — your margin is exactly what you set. The fee comes out of what reaches the user, shown to them on its own line before they sign, and it is zero on testnet.
What this changes for you in practice: an order may carry two outputs instead of one. Fill each of them, then claim once. If you run RecoilPay's fill-worker this is already handled; if you run your own, finalise needs one SolveParams per output, each carrying the timestamp of the block that output's own fill landed in. A short list reverts after you have already delivered, so make sure your worker is up to date before fees are switched on. Swaps to Solana carry one output and no fee.
Watch your expiry windows
Quotes stay live for anywhere from 15 minutes to 7 days. You're committed to that price for the whole window. Long windows are fine on stablecoin pairs. On pairs whose prices move, they carry real risk.
Treat the fill-wallet as a hot wallet
RecoilPay holds the fill-wallet's private key, encrypted, so that settlements can be signed while you're offline. Fund it with working capital, not your treasury.
Taking funds back out
Each balance in Fill-wallet has a Withdraw next to it. It pays the wallet you registered, and only that wallet — there is no address to type in. That is deliberate: RecoilPay holds this key, so a withdrawal that let you name a destination would let anyone who stole your API key name one too.
- Everything available is the usual choice. For a token that is the whole balance; for the native coin it is the balance less the fee the withdrawal itself costs, which is why the figure you get back is slightly under what you saw.
- Withdrawing leaves nothing behind for fills. Keep gas on every chain you still quote, or your next fill fails and your reputation takes the hit.
- On Solana the money goes to your Solana identity, not to an EVM address, and you need one registered before you can withdraw at all. If your identity has never held that token, the withdrawal opens a token account for it and your fill-wallet pays the rent, so keep a little SOL there.
Filling orders to and from Solana
You can quote USDC routes between Solana devnet and any EVM testnet, in either direction.
- To Solana: the user pays on the EVM chain as usual; you deliver USDC to their Solana wallet.
- From Solana: the user locks USDC in RecoilPay's escrow on Solana; you deliver on the EVM chain and are paid on Solana. See From Solana.
What's different
| EVM → EVM | EVM → Solana | |
|---|---|---|
| Escrow and claim | Your fill-wallet, on the source chain | The same: your EVM fill-wallet |
| Delivery | Your fill-wallet, on the destination chain | Your Solana fill-wallet, through RecoilPay's fill program |
| Proof of delivery | Read from the destination chain | The fill program sends it over Hyperlane; your Solana fill-wallet pays Hyperlane to carry it |
| Paid back | Seconds after delivery | Usually 2 to 20 minutes after delivery, once the proof arrives |
The fill program checks every delivery: the right token, the full amount, to the user's own token account, and only once per order. The escrow then releases only for a proof that matches the user's order, so you're paid exactly for what you delivered.
From Solana
| Step | Where | What happens |
|---|---|---|
| 1. Escrow | Solana | The user's Solana wallet locks their USDC in RecoilPay's escrow program, keyed to this one order. The aggregator checks it on-chain before your worker sees the order. |
| 2. Deliver | Destination (EVM) | Your EVM fill-wallet delivers through the OIF output settler, naming your Solana fill-wallet as the solver to pay. |
| 3. Prove | Destination (EVM) | Your EVM fill-wallet calls RecoilPay's proof sender there, paying Hyperlane's fee in that chain's gas token, to carry the proof to Solana. |
| 4. Claim | Solana | Once the proof arrives, usually within minutes, the escrow pays your Solana fill-wallet. |
You need EVM inventory on the destination chain, gas there for the delivery and the proof, and a funded Solana fill-wallet: it's where you're paid, and it pays the claim's small fee. The fill program isn't involved.
Your worker fills only orders with at least 20 minutes before they can be refunded: an order nobody proved by its expiry, 30 minutes after the quote, can be returned to the user, so a proof that arrives too late would leave you unpaid.
Set up your Solana fill-wallet
- In the portal, open Fill Wallet and click Generate my Solana fill-wallet. Like your EVM fill-wallet, RecoilPay generates it and holds its key encrypted. It signs only fills and Hyperlane fees, and for fiat on Solana the locks and releases it pays for, nothing else.
- Fund it on Solana devnet with:
- SOL: up to about 0.01 SOL per fill. Most of it is rent for the accounts a fill creates: the fill record, Hyperlane's copy of the proof and its gas receipt, and the user's USDC account if they don't have one yet (about 0.002 SOL). Hyperlane's fee itself is a fraction of a cent. Get SOL from faucet.solana.com.
- USDC, the inventory you deliver. Devnet USDC is Circle's, from faucet.circle.com (choose Solana Devnet).
- Keep gas on the source chain in your EVM fill-wallet as well: it still opens and claims the escrow.
- In Quotes, choose USDC on solana-devnet as what you deliver, or as the source you're paid in. The form tells you if a pair has no Solana route yet.
The panel shows your SOL and USDC balances and warns when SOL runs low. Replacing the Solana fill-wallet is permanent — RecoilPay stops signing for the old one — so withdraw whatever is left to your Solana identity before you replace it.
How quotes are chosen
When a user asks for a price, a quote is skipped unless all of these hold:
- The source chain, destination chain and both tokens match exactly.
- The order size is inside the quote's range.
- The quote hasn't expired and isn't paused.
- The operator isn't circuit-broken (temporarily blocked after repeated failures).
The quotes that remain are scored:
| Factor | Weight | Meaning |
|---|---|---|
| Output | 50% | How much the user receives. Price matters most. |
| Reputation | 25% | Track record, between 0 and 1. New operators start at 0.5. |
| Success rate | 15% | Fills completed ÷ fills attempted. |
| Speed | 10% | Average time to settle. |
Reputation goes up +0.02 for each successful fill and down −0.10 for each failure. It takes five successes to undo one failure, so reliability pays off over time.
How to onboard
Onboarding takes a few minutes and costs no gas until you fund the fill-wallet.
- Read the operator handbook. The handbook in the solver portal is public and goes into more detail than this page. It's worth reading before you fund anything.
- Connect your wallet at solver.recoilpay.com. Any EVM wallet works. This wallet is your identity: there's no email or password, and you're never asked for a private key.
- Pick a handle. It's only a display name and doesn't affect matching.
- Sign one message. This is a plain-text signature proving you control the wallet. It isn't a transaction: it costs no gas and gives no one permission to spend your funds.
- Save what registration gives you. Two things are created:
- an API key, stored in your browser, which is how the portal knows it's you, and
- a fill-wallet, a fresh address that will sign your settlements.
- Add a settlement contract for each chain you want to fill on, from Settings. Quick-add buttons fill in RecoilPay's deployed contracts.
- Fund the fill-wallet. Send gas to every chain you'll quote, and token inventory to every chain you'll deliver on. The Fill Wallet tab shows live balances for each chain.
- Publish your first quote from Quotes: choose the route, the order-size range, your margin and gas fee, and an expiry.
- Watch your orders in Orders. Each one moves through
created → pending → executing → executed → settling → finalized, with a transaction hash recorded at each stage.executedmeans the user has been paid.finalizedmeans you've claimed the escrow.
The API key lives in your browser's local storage, so clearing site data logs you out. Register again with the same wallet and you'll get back the same operator account, with your quotes and reputation intact.
Fiat offers
A fiat offer trades USDC for naira over Nigerian bank transfers, in one or both directions:
- Cash-outs: a user's USDC is locked in escrow, you pay them naira from your bank, and the escrow pays you once they confirm it arrived.
- Selling crypto (users buying): your USDC is locked from your fill-wallet for the user, they pay you naira, and the escrow releases the USDC to them once you confirm the payment.
Fiat runs on Base Sepolia, Polygon Amoy, BNB Chain Testnet and Solana devnet today. Set it up under Fiat offers in the portal, in this order. Solana needs a little more first: see Fiat on Solana.
1. Stake a bond
Because you pay first on a cash-out, you stake a bond in USDC on each chain you offer. No bond, no offers:
- A single trade can't be bigger than your free bond, and everything in flight at once is capped at five times it.
- If a user shows that a cash-out you marked as paid never arrived, an admin can slash your bond to pay them. That can happen up to 72 hours after the trade settled. A slash is proposed and held for 24 hours before it can be taken, so you always see it coming.
- Withdrawing your bond takes 3 days, and part of it stays held while a claim against you is open.
2. Publish offers
For each chain and direction, set your rate (naira per USDC), a fixed fee and a percentage fee, the minimum and maximum trade in naira, and how long the offer stays valid. Users see your offer ranked against other operators' by what they'd get, your track record and how quickly you've paid.
RecoilPay's own fee does not come out of yours. It is a separate line on the offer, charged on the crypto and not the naira, and it is taken from the escrow when a trade completes — never from your rate or your spread. On a cash-out it is cut from the lock before you convert, so the amount you price is the amount you actually receive; on a purchase it is cut from what reaches the buyer, not from what you locked. Your margin is whatever you set it to either way. It is zero on testnet.
The escrow is also what charges it, so there is nothing for you to collect or remit, and a trade that is refunded or returned is charged nothing at all.
3. Set up your payee key (cash-outs)
Users encrypt their bank details for you alone. Set up a payee key once from Fiat trades: your wallet signs a message, and the key is derived from that signature in your browser. It's never stored anywhere, so to see who to pay, you sign again with the same wallet. Use a wallet that signs deterministically, such as MetaMask, Ledger or Trezor.
4. Pay out cash-outs
Under Fiat trades → Cash-outs to pay, open a trade to see the bank account and the exact amount. Pay it from your bank, then click I've paid. You have 15 minutes from the moment the user's USDC is locked. The user confirms the money arrived, and the escrow releases to your fill-wallet.
If you don't pay in time, the trade is cancelled and the user gets their USDC back. Three of those within seven days stop all your fiat offers until an admin lifts the stop. Your swap quotes aren't affected.
5. Sell crypto to users (optional)
Two things are needed before your buy offers are shown:
- The account users pay: a bank account for incoming transfers. It's shown in full to buyers, so use a business account.
- USDC in your fill-wallet on that chain. The user's purchase is locked from it automatically, before they're shown where to pay.
Then confirm each payment under Fiat trades → Crypto sales to confirm. Each trade shows the buyer's verified name, which you can compare with the sender on your bank alert. A payment from a different name may be a stolen account. Confirm once the money is in, or dispute it if it never came. If you don't answer within 30 minutes of the buyer saying they've paid, the USDC goes to the buyer.
Rather not watch your bank? Add a Paystack test secret key (sk_test_…). Each purchase then gets its own temporary account for the exact amount, and RecoilPay checks with Paystack that the money arrived and that the sender's name matches the buyer's verified name. If both hold, the USDC is released without you. Payments under any other name still wait for you. Only test keys are accepted, because a live key could move money out of your Paystack account.
Fiat on Solana
On Solana devnet, two Solana wallets do different jobs:
| What it is | What it does in fiat | |
|---|---|---|
| Solana identity | A Solana wallet of your own, such as Phantom. RecoilPay never holds its key. | Holds your bond. Cash-outs are released to it. |
| Solana fill-wallet | The one RecoilPay generates and holds for you (set up here). | Pays the network fees for locks and releases, and holds the USDC you sell to buyers, which purchases lock from it. |
They must be different wallets: the portal refuses your fill-wallet as your identity, because a bond held by a key RecoilPay holds could be withdrawn by RecoilPay.
- Register your identity. Under Fiat offers → Solana, connect your Solana wallet (set to devnet) and sign one message to make it your Solana identity. Without one you can't offer cash-outs on Solana. You can replace it later; trades already open keep paying the old one.
- Stake your bond from it. Connect the identity wallet and deposit USDC into your bond. Deposits and withdrawals are transactions from that wallet, so it needs a little SOL. The same rules apply as on the other chains, including the 3-day withdrawal and the 24-hour slash delay.
- Fund your Solana fill-wallet with SOL: about 0.003 SOL per cash-out, most of it rent for the lock's record, which stays on-chain. To sell crypto to buyers, put USDC in it too.
- Publish offers on Solana devnet as on any chain, and pay out cash-outs the same way. The Fiat trades page shows which identity a Solana cash-out pays.
Users need no SOL: your fill-wallet pays every fee on their side.
Gift card offers
Gift card merchants buy cards from users for USDC, sell cards to them, or both. Set it up under Gift card offers:
- Pick a payout chain (Base Sepolia, OP Sepolia or BNB Chain Testnet) and stake USDC in the gift card bond on it. Your open trades are capped at five times your stake, so with no stake no trade can open. A dispute decided against you is paid out of it. The portal doesn't have a staking screen for gift cards yet; until it does, ask the team to help you stake.
- Publish a rate. Choose the brand, country and card type, whether you're buying cards (users sell to you) or selling them (users buy from you), the card sizes you'll handle, and your rate as a percentage of face value.
- Settle trades under Gift card trades. The page shows whose turn each trade is:
- You buy a card: fund the escrow, wait for the user's code, redeem it, then confirm it was good. You have 30 minutes to check it. If you say nothing, the escrow pays the user.
- You sell a card: the user funds the escrow, and you send the code within 60 minutes. If you don't, the user is refunded.
Codes are encrypted between your browser and the user's, so RecoilPay never sees them. If a card is bad, dispute the trade and an admin decides.
Where earnings go
Profit is the spread: you deliver slightly less than you claim from escrow, minus gas. Claimed funds land in your fill-wallet on the source chain, so a completed swap partly refills the inventory it used, just on the other chain.
Testnet only, for now
Like the rest of RecoilPay, solvers run on public testnets today. The tokens have no real value, so this is the right time to learn how pricing, inventory and reputation behave before mainnet. Some details will change before then.