Integrator Fees

How it works

Approved integrators can charge their own fee on top of Rialto’s on every swap they route. The fee is collected as part of the swap and paid to your wallet in the same onchain transaction. There is no separate claim step, no fee contract to deploy, and no settlement to run yourself.

You request a quote with a swap_fee_bps value, your fee in basis points.
Rialto adds your fee on top of its own and returns the full breakdown.
The same quote includes one executable transaction that, on execution, pays both Rialto’s treasury and your wallet atomically.
The taker signs or approves as needed, then submits the quote’s tx directly or signs Permit2 for gasless relay.

Your fee is additive. Rialto charges its standard fee, and your fee is taken on top. Rialto does not take any cut of your portion.

What is bound to your key

Bound to your key	Meaning
Payout wallet	The address your fees are sent to.
Maximum fee in bps	A per-key cap, the largest swap_fee_bps you may set.
Integrator id	An identifier used to attribute the swaps you route.

Because these are bound to the key and not the request, a leaked or tampered request can never redirect your fees or raise your fee above your cap.

Setting your fee

Add swap_fee_bps to the standard quote request. Your payout wallet and cap come from your key, so you do not pass them on the request.

Param	Description
swap_fee_bps	Your fee in basis points, applied on top of Rialto’s fee. 30 = 0.30%. swapFeeBps is also accepted.

INTEGRATOR_KEY='rialto_live_integrator.redacted_secret'

curl -sS 'https://rialto-trade-api.rialto.xyz/quote?sell_token=0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73&buy_token=0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168&sell_amount=0.01&taker=<taker_wallet_address>&slippage_bps=50&swap_fee_bps=30' \
  -H "Authorization: Bearer $INTEGRATOR_KEY"

Reading the fee in the response

A quote with an integrator fee gains two things: an integrator_fee block echoing your fee, payout wallet, and integrator id; and extra entries in platform_fee.fees, one line per recipient, each showing the token the fee is taken in and the exact amount. Rialto selects the most suitable fee token in the swap automatically, so you do not choose a fee token.

{
  "buy_amount": "19800022",
  "platform_fee": {
    "total_bps": 80,
    "fees": [
      {
        "side": "source",
        "token": "<sell_token_address>",
        "symbol": "WETH",
        "decimals": 18,
        "bps": "50",
        "amount": "50000000000000",
        "amount_decimal": "0.00005",
        "recipient": "<rialto_fee_recipient_address>"
      },
      {
        "side": "source",
        "token": "<sell_token_address>",
        "symbol": "WETH",
        "decimals": 18,
        "bps": "30",
        "amount": "30000000000000",
        "amount_decimal": "0.00003",
        "recipient": "<integrator_fee_recipient_address>"
      }
    ]
  },
  "integrator_fee": {
    "bps": 30,
    "recipient": "<integrator_fee_recipient_address>",
    "id": "your-integrator-id"
  }
}

In this example Rialto’s fee is 50 bps and your fee is 30 bps, for a combined total_bps of 80. The recipient on the second line is your payout wallet. The token and amount fields tell you exactly which token the fee is taken in and how much.

Python example

This example requests a quote with an integrator fee, handles any approval, signs and inserts a Permit2 signature when required, and submits the returned transaction.

python3 -m pip install requests web3 eth-account

export INTEGRATOR_API_KEY='rialto_live_integrator.redacted_secret'
export RPC_URL='<your-rh-rpc-url>'
export PRIVATE_KEY='0xREDACTED_PRIVATE_KEY'
python3 rialto_integrator_quote.py

import os
from urllib.parse import urlencode

import requests
from eth_account import Account
from eth_account.messages import encode_typed_data
from web3 import Web3

API_BASE = "https://rialto-trade-api.rialto.xyz"
CHAIN_ID = 4663
SELL_TOKEN = "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168"
BUY_TOKEN = "0xc93a8c440CEa26D7445dF01729f193b27965099f"
SELL_AMOUNT = "0.532262"
SLIPPAGE_BPS = 50
SWAP_FEE_BPS = 50

ERC20_ABI = [
    {
        "name": "approve",
        "type": "function",
        "stateMutability": "nonpayable",
        "inputs": [
            {"name": "spender", "type": "address"},
            {"name": "value", "type": "uint256"},
        ],
        "outputs": [{"name": "", "type": "bool"}],
    }
]


def require_env(name: str) -> str:
    value = os.getenv(name)
    if not value:
        raise RuntimeError(f"missing {name}")
    return value


def tx_fees(w3: Web3) -> dict:
    latest = w3.eth.get_block("latest")
    priority = w3.to_wei("0.01", "gwei")
    return {
        "maxPriorityFeePerGas": priority,
        "maxFeePerGas": int(latest["baseFeePerGas"]) * 2 + priority,
    }


def patch_permit2_signature(tx_data: str, signature_offset: int, signature: bytes) -> str:
    data = bytearray(bytes.fromhex(tx_data.removeprefix("0x")))
    if len(signature) != 65:
        raise RuntimeError("Permit2 signature must be 65 bytes")
    data[signature_offset : signature_offset + 65] = signature
    return "0x" + data.hex()


api_key = require_env("INTEGRATOR_API_KEY")
private_key = require_env("PRIVATE_KEY")
w3 = Web3(Web3.HTTPProvider(require_env("RPC_URL")))
taker = Account.from_key(private_key).address

params = {
    "sell_token": SELL_TOKEN,
    "buy_token": BUY_TOKEN,
    "sell_amount": SELL_AMOUNT,
    "taker": taker,
    "slippage_bps": SLIPPAGE_BPS,
    "chain_id": CHAIN_ID,
    "swapFeeBps": SWAP_FEE_BPS,
}

response = requests.get(
    f"{API_BASE}/quote?{urlencode(params)}",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=30,
)
response.raise_for_status()
quote = response.json()

print("quote_id:", quote["quote_id"])
print("buy_amount:", quote["buy_amount"])
print("min_buy_amount:", quote["min_buy_amount"])
print("integrator_fee:", quote.get("integrator_fee"))

issues = quote.get("issues") or {}
if issues.get("balance"):
    raise RuntimeError(f"insufficient balance: {issues['balance']}")

if issues.get("allowance"):
    allowance = issues["allowance"]
    token = Web3.to_checksum_address(quote["sell_token"])
    spender = Web3.to_checksum_address(allowance["spender"])
    amount = int(quote["sell_amount"])
    approve_tx = w3.eth.contract(address=token, abi=ERC20_ABI).functions.approve(
        spender, amount
    ).build_transaction(
        {
            "from": taker,
            "chainId": CHAIN_ID,
            "nonce": w3.eth.get_transaction_count(taker),
            **tx_fees(w3),
        }
    )
    approve_tx["gas"] = int(w3.eth.estimate_gas(approve_tx) * 1.2)
    signed_approval = Account.sign_transaction(approve_tx, private_key)
    approval_hash = w3.eth.send_raw_transaction(signed_approval.raw_transaction)
    receipt = w3.eth.wait_for_transaction_receipt(approval_hash)
    if receipt.status != 1:
        raise RuntimeError(f"approval reverted: {approval_hash.hex()}")

tx = quote["tx"]
data = tx["data"]
if quote.get("permit2"):
    typed_data = {
        "domain": quote["permit2"]["domain"],
        "types": quote["permit2"]["types"],
        "primaryType": quote["permit2"]["primaryType"],
        "message": quote["permit2"]["message"],
    }
    signed_permit = Account.sign_message(
        encode_typed_data(full_message=typed_data),
        private_key,
    )
    data = patch_permit2_signature(
        tx["data"],
        int(tx["signature_offset"]),
        bytes(signed_permit.signature),
    )

swap_tx = {
    "from": taker,
    "to": Web3.to_checksum_address(tx["to"]),
    "data": data,
    "value": int(tx.get("value", "0")),
    "chainId": CHAIN_ID,
    "nonce": w3.eth.get_transaction_count(taker),
    **tx_fees(w3),
}
gas_estimate = w3.eth.estimate_gas(swap_tx)
swap_tx["gas"] = int(gas_estimate * 1.3)

signed_swap = Account.sign_transaction(swap_tx, private_key)
swap_hash = w3.eth.send_raw_transaction(signed_swap.raw_transaction)
print("swap_tx:", swap_hash.hex())

Caps and rules

Rule	Behavior
Fee above your key’s cap	swap_fee_bps greater than your configured maximum is rejected with 400.
Combined fee too high	Rialto’s fee plus your fee must not exceed the protocol maximum, currently 100 bps total. Over the limit is rejected with 400.
Non-integrator key	A key without integrator access that sends swap_fee_bps is rejected with 403.
No fee requested	Omit swap_fee_bps or send 0 for a standard swap with no integrator fee.

Execute an integrator-fee quote exactly like any other quote. The fee recipient and cap are key-bound server-side, and the fee split is encoded into the transaction Rialto returns.

Get started

Swap API

propAMM Integration

Integrator Fees

How it works

What is bound to your key

Setting your fee

Reading the fee in the response

Python example

Caps and rules

​How it works

​What is bound to your key

​Setting your fee

​Reading the fee in the response

​Python example

​Caps and rules

How it works

What is bound to your key

Setting your fee

Reading the fee in the response

Python example

Caps and rules