Skip to main content
A swap on Vulcx has up to three separate costs. They are reported as distinct fields, never rolled into one number.

​
1. Pool fees

Each liquidity pool charges its own fee per hop, set by the pool operator (Valiant, Fluxbeam) and deducted automatically as the swap executes.
  • feeBps on GET /api/v1/quote — the total pool fee across all hops, in basis points.
  • feeAmount on POST /api/v1/swap and POST /api/v1/instructions — the same fee as an amount, in the INPUT token’s smallest units, because pool fees are taken on the way in. It is not comparable to platformFeeAmount or integratorFeeAmount, which are output-denominated, and it must never be subtracted from amountOut.
This is the DEX’s fee, not Vulcx’s. Vulcx never sets or receives it.

​
2. Vulcx’s protocol fee

Vulcx takes platformFeeBps of the output amount, reported alongside it as platformFeeAmount in the output token’s smallest units. The rate comes from the protocol config on-chain and is the same for every caller. It is 0 when the protocol fee is disabled on-chain.

​
3. Your integrator fee

Set integratorFeeBps on the request to charge your own fee on top. You keep 100% of it.
It is paid on-chain, in the output token, to the referrer wallet in the same transaction as the swap — so there is nothing to invoice, reconcile or settle later. The response reports it back as integratorFeeBps and integratorFeeAmount.
integratorFeeBps requires a referrer wallet to pay it to. Sending a rate with no referrer returns HTTP 400 — the program refuses a fee with no destination, and the API rejects it one layer earlier so you get an error instead of a failed transaction.

​
Set it once on your API key

Instead of sending the fee on every request, set a default fee and fee wallet on the key at portal.vulcx.xyz. A /swap, /instructions or /cpi/route-accounts request that omits integratorFeeBps uses the key’s default; one that omits referrer pays the key’s fee wallet. Anything you send on the request still wins, and an explicit "integratorFeeBps": 0 turns the default off for that call. Requests without a key have no defaults. A key can also carry a ceiling: any request on that key asking for more returns 400 FEE_ABOVE_KEY_MAX. Use it when the key ships inside a client other people can modify. The portal’s Earnings page shows what your fee wallets were paid, read from settled transactions.

​
The two rates add — they are not a split

platformFeeBps and integratorFeeBps are independent. Yours is not a share of Vulcx’s, and neither rate moves the other. Your user pays the sum: Because your rate is yours alone, it comes straight off the request without authentication — it cannot be used to take anything from Vulcx’s side.
The sum is capped at 100 bps (1%). A request whose platformFeeBps + integratorFeeBps exceeds the cap returns HTTP 400. The cap is enforced on-chain too; the API checks it first so an over-cap request fails as a validation error rather than as a reverted transaction.Capping each rate separately would let a user be charged twice the ceiling, which is why the check is on the total.
Both rates stand down together when the protocol fee is disabled on-chain — the kill switch cannot leave one side charging.

​
What the numbers mean

amountIn and amountOut are the trade itself. Pool fees are already deducted from them, because the pools take those as the swap executes. Vulcx’s fee and yours are not included in amountOut. Both come off it on-chain, in the output token. What your user actually receives is:
All three are the same token in the same units, so that subtraction is exact. Do not subtract feeAmount — it is denominated in the input token, and on a 1 FOGO → USDC swap it is several hundred times larger than the entire output.
Last modified on September 14, 2026