Skip to main content
You set a fee on your key once, on top of every swap, and keep 60% of it (Pricing). It applies to every call that sends that key as x-api-key. A swap then pays you only when RAVN can prove it, and that takes two things from your code:
  1. Pay the fee an execution asks for, when it has one.
  2. Poll /status until the swap is final, reporting the fee’s transaction.
Skip either and the swap still fills for your user, but nothing is owed to you on it.
On JavaScript or TypeScript, executeAndTrack does both. The Quickstart script does both too.

1. Pay fee when the execution has one

Most routes take your fee inside the swap, so there’s nothing extra to pay. A few can’t, and then /execute adds a fee object. The ready-made payload already includes it: Rules that keep the fee provable:
  • Send the fee exactly as given, and only after the swap or deposit transaction has succeeded. Sending calls in order does that. A fee paid on a swap that reverts, or that the venue later refunds, stays with RAVN.
  • In a wallet batch (batch: true), put one fee-bearing swap per batch.
  • A native-coin fee (ETH, say) must be a plain transaction of its own unless batch is true. A contract wallet that can’t send a plain transaction (a Safe, an ERC-4337 account) can’t pay it.
  • Building a Bitcoin or Solana deposit yourself? The fee must go in the same transaction as the deposit, or RAVN can’t find it. A Bitcoin fee under 546 sats isn’t charged.

2. Report the swap to /status until it’s final

Poll /status with:
  • quoteToken: the one /execute returned.
  • ref: the statusRef (from /execute, or /submit-signature for SIGNATURE), else the swap’s transaction hash.
  • txHash: on an EVM chain, the hash of the last transaction you sent from calls. That’s the one carrying your fee (or the whole batch). Never a batch id or an ERC-4337 userOpHash. Not needed on Bitcoin or Solana: RAVN finds the fee inside the deposit.
Send txHash on every poll. Stop at success, refunded or failed. Keep polling through expired (a refund is on its way) and not_found (the venue hasn’t seen it yet).
RAVN stops waiting for a fee a day after /execute: a fee reported later earns nothing. A delivered swap can read processing for up to 15 minutes while RAVN confirms the fee transaction, so keep polling. Webhooks tell you a swap is final but don’t replace these polls.