Integrator fees

You can charge your users a fee on each trade, from 0.01% to 10% of its output. Add two fields to the quote request:

• integrator_fee_bps: the fee in basis points, from 1 (0.01%) to 1000 (10%).
• integrator_fee_recipient: the address that receives the fee, on the to asset's chain.

Set both or neither. A request with only one of them returns 400. With the rift helper from the quickstart:

const quote = await rift("/quote", {
  from: "base.usdc",
  to: "base.eth",
  amount_in: "100",
  integrator_fee_bps: 50,
  integrator_fee_recipient: "0xYourAddressOnBase",
});

Every order created from the quote pays the fee.

How the fee is calculated

The fee is paid in the to asset, out of what the route delivers. The last step of the quote's route, its delivery, shows the split:

{
  "type": "delivery",
  "amount_in": "0.044499372574349938",
  "execution_cost": "0.000003601912938013",
  "integrator_fee": "0.000222478853307059",
  "amount_out": "0.044273291808104866"
}

• amount_in is what the route delivers, and execution_cost is the network fees the router pays to execute the order.
• integrator_fee is integrator_fee_bps of amount_in minus execution_cost, rounded down to the asset's smallest unit. Here, 0.5% of 0.044495770661411925 ETH.
• amount_out is the user's share, the quote's estimated_amount_out: what remains after the fee.

Rift pays the fee in the same delivery as the user's output. Once the order is delivered, GET /order/{id} shows what you were paid in integrator_fee, and the transaction that paid it in integrator_fee_tx. On EVM chains and Bitcoin that's the same transaction as the user's payout_tx; on HyperCore it's a separate one. A refunded order pays no fee.

When the fee isn't paid

Some fees can't be received on their chain. Rift doesn't charge those, and the user keeps the whole output: the quote shows "integrator_fee": "0", and estimated_amount_out includes what the fee would have been.

HyperCore: the recipient needs an account

On HyperCore, the fee is paid only to an address that already has a HyperCore account. Rift checks when it quotes and again when the order delivers, and pays the fee only if the account exists at delivery.

An address gets its account the first time it's funded on HyperCore. Before you use one as your fee recipient, deposit into it on Hyperliquid, or make a small Rift order that delivers to it. To check an address:

curl -s https://api.hyperliquid.xyz/info \
  -H 'content-type: application/json' \
  -d '{"type":"userRole","user":"0xYourAddress"}'

{"role":"missing"} means the address has no account yet.

Bitcoin: the fee must clear the dust limit

Bitcoin nodes don't relay an output smaller than its dust limit, which depends on the address type. A fee below its recipient's limit isn't paid:

For example, a 1% fee to a native SegWit address is paid only on orders that deliver at least 29,400 sats (0.000294 BTC). Native SegWit has the lowest limit.

Choosing the recipient

• Use an address on the to chain. The fee is paid on the chain the order delivers to: an EVM address for EVM chains and HyperCore, a Bitcoin address for Bitcoin. The zero address is refused.
• Make sure it can receive the asset. On EVM chains, the fee and the user's output arrive in one transaction. If the transfer to your address fails, for example to a contract that rejects native ETH or an address the token has blocked, the user's delivery fails with it. Rift retries, then refunds the order.