Fee & Revenue Sharing

Copy page

The Trading API supports an on-chain, atomic custom-fee (also called Add Fee / referral fee / revenue share) feature: a configurable percentage of each swap is deducted on-chain and sent to a wallet address you designate, while the remainder follows the normal DEX route. This is useful for integrators who want to collect a platform fee or share revenue with affiliates.

All deductions happen atomically inside the swap transaction — the fee and the swap either succeed together or fail together. No off-chain settlement is required.

Supported Endpoints & Chains

The feature is available on every swap-building endpoint, across EVM chains and Solana:

Endpoint	Method	Fee parameters
/api/v1/dex/aggregator/quote	GET	feePercent + feeSource
/api/v1/dex/aggregator/swap	GET	feePercent + one referrer address
/api/v1/dex/aggregator/quote-and-swap	GET	feePercent + one referrer address
/api/v1/dex/aggregator/swap-instruction	GET	feePercent + one referrer address (Solana only)

Chain	feePercent range	Referrer address format
BNB Smart Chain, Ethereum, Arbitrum One, Base, Polygon, Optimism, Linea, Blast, Avalanche C-Chain, Scroll, Mode, Metis Andromeda, Sonic, Katana, Plasma, Monad, Robinhood	(0, 5] — greater than 0, up to 5% inclusive	0x + 40 hex chars
Tron	(0, 5] — greater than 0, up to 5% inclusive	Base58 (T + 33 chars)
Solana	(0, 10] — greater than 0, up to 10% inclusive	Base58 pubkey

feePercent is a decimal string with at most 2 decimal places (e.g. "1.5" = 1.5%). Values with more than 2 decimals are rejected with INVALID_FEE_PERCENT (40466).

Fee Directions

Two deduction directions are supported. On /quote the direction is chosen via feeSource; on the swap-building endpoints it is implied by which referrer address you pass.

Direction	/quote	Swap endpoints	Effect
FROM_TOKEN	feeSource=FROM_TOKEN	fromTokenReferrerWalletAddress	Fee is deducted from the sell token; the net amount is sent to the DEX. The user still receives the full DEX output.
TO_TOKEN	feeSource=TO_TOKEN	toTokenReferrerWalletAddress	The full input is swapped; the fee is deducted from the buy-token output. The user receives the DEX output minus the fee.

Fund flow

Code
FROM_TOKEN direction                    TO_TOKEN direction
─────────────────────                   ─────────────────────
sell token                              sell token
  │                                       │
  ├── feePercent ──► referrer             └── 100% ──► DEX ──► buy token
  │                                                ├── feePercent ──► referrer
  └── net amount ──► DEX ──► buy token              └── remainder ──► user
                       └──► user

Parameter Pairing

Each endpoint accepts a specific combination — parameters must be all present or all absent for a given fee direction:

Endpoint	Fee parameters	Rule
/quote	feePercent + feeSource	Both present or both absent.
/swap, /quote-and-swap, /swap-instruction	feePercent + exactly one of fromTokenReferrerWalletAddress / toTokenReferrerWalletAddress	The two referrer addresses are mutually exclusive — supplying both returns CONFLICT_REFERRER_PARAMS (40468).

If you omit all fee parameters, the swap executes as a regular fee-less swap.

Limits & Validation

Rule	Detail	Error on violation
feePercent range (EVM)	(0, 5] — > 0, ≤ 5, max 2 decimals	40466 INVALID_FEE_PERCENT
feePercent range (Solana)	(0, 10] — > 0, ≤ 10, max 2 decimals	40466 INVALID_FEE_PERCENT
Referrer address format	EVM: 0x + 40 hex chars; Solana: Base58 pubkey	40467 INVALID_REFERRER_ADDRESS
Both referrer addresses	Mutually exclusive — pick exactly one	40468 CONFLICT_REFERRER_PARAMS
Solana referrer not activated	Referrer wallet has no SOL balance (ATA cannot be created)	40469 REFERRER_NOT_ACTIVATED
Tax token on same side (Solana)	The token on the fee side is a tax token (buyTax > 0 or sellTax > 0)	40470 TAX_TOKEN_FEE_CONFLICT
four.meme tokens	Fee parameters are not supported when either side of the pair is a four.meme token	—
RFQ routes (equity / RWA tokens)	Fee parameters are ignored; the order executes as a standard fee-less RFQ order	—

Solana referrer activation: before using a referrer address on Solana, fund it with a small amount of SOL so the on-chain fee token account (ATA) can be created. An empty referrer wallet is rejected with 40469.

Quote ↔ Swap Consistency

When using the two-step flow (/quote → /swap), the fee direction (implied by which referrer address you pass to /swap) and the feePercent value must match the ones locked in the /quote cache for that quoteId. A mismatch returns SWAP_QUOTE_MISMATCH (40462).

The one-step /quote-and-swap Flash API has no prior quote, so the fee is fully determined by the single request — no consistency check applies.

Response Echo

When the fee is enabled, the /quote, /swap, /quote-and-swap, and /swap-instruction responses include three fields under each route / routerResult. All three are null when the fee is not enabled.

Field	Type	Description
feeAmount	string (integer, smallest unit)	Fee deducted for this swap. FROM_TOKEN = originalFromCoinAmount × feePercent/100 (HALF_UP); TO_TOKEN = originalToCoinAmount × feePercent/100 (HALF_DOWN).
feeToken	string (contract address)	Token in which the fee is denominated. FROM_TOKEN = sell-token address; TO_TOKEN = buy-token address.
actualSwapAmount	string (integer, smallest unit)	Amount that actually participates in the DEX swap. FROM_TOKEN = fromTokenAmount − feeAmount (net); TO_TOKEN = original input amount (fee taken from the output side).

Error Codes

Code	Message	Affected endpoints
40462	SWAP_QUOTE_MISMATCH — fee direction / feePercent on /swap differs from the cached /quote	/swap
40466	Invalid feePercent. EVM chains allow (0, 5], Solana allows (0, 10]	/quote, /swap, /quote-and-swap, /swap-instruction
40467	Invalid referrer address — format does not match the selected chain	/swap, /quote-and-swap, /swap-instruction
40468	fromTokenReferrerWalletAddress and toTokenReferrerWalletAddress are mutually exclusive	/swap, /quote-and-swap, /swap-instruction
40469	Referrer wallet address is not activated on Solana — fund it with SOL first	/swap, /quote-and-swap, /swap-instruction (Solana only)
40470	Tax token cannot configure referral fee on the same side — use the opposite direction or remove the fee	/quote, /swap, /quote-and-swap, /swap-instruction (Solana only)

Sample Calls (Python)

Both examples use a 1.5% fee deducted from the sell token (FROM_TOKEN direction).

Two-step: /quote then /swap

Code
import hmac, hashlib, base64, urllib.request
from datetime import datetime, timezone

API_KEY = "your-api-key"
SECRET  = "your-secret-key"
BASE    = "https://web3.binance.com/build"
HEADERS = {}

def sign(method, path_with_query, body=""):
    now = datetime.now(timezone.utc)
    ts  = now.strftime("%Y-%m-%dT%H:%M:%S.") + f"{now.microsecond // 1000:03d}Z"
    # requestPath MUST include the /build prefix — it is part of the signed string.
    request_path = "/build" + path_with_query
    prehash = ts + method + request_path + body
    sig = base64.b64encode(hmac.new(SECRET.encode(), prehash.encode(), hashlib.sha256).digest()).decode()
    HEADERS["X-OC-APIKEY"] = API_KEY
    HEADERS["X-OC-TIMESTAMP"] = ts
    HEADERS["X-OC-SIGN"] = sig

def call(path_with_query):
    req = urllib.request.Request(BASE + path_with_query)
    for k, v in HEADERS.items():
        req.add_header(k, v)
    return urllib.request.urlopen(req).read().decode()

# Step 1 — quote with a 1.5% FROM_TOKEN fee
quote_qs = (
    "/api/v1/dex/aggregator/quote"
    "?binanceChainId=56"
    "&fromTokenAddress=0x55d398326f99059fF775485246999027B3197955"
    "&toTokenAddress=0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d"
    "&amount=1000000"
    "&feePercent=1.5"
    "&feeSource=FROM_TOKEN"
)
sign("GET", quote_qs)
quote = call(quote_qs)
print(quote)
# Save quoteId from the response, then pass it to /swap within 30s.

# Step 2 — swap with the same 1.5% fee, FROM_TOKEN direction
swap_qs = (
    "/api/v1/dex/aggregator/swap"
    "?binanceChainId=56"
    "&quoteId=<quoteId-from-step-1>"
    "&fromTokenAddress=0x55d398326f99059fF775485246999027B3197955"
    "&toTokenAddress=0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d"
    "&amount=1000000"
    "&userWalletAddress=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
    "&slippagePercent=0.5"
    "&feePercent=1.5"
    "&fromTokenReferrerWalletAddress=0xCbF2B6E6e3D7e9e4e4e4e4e4e4e4e4e4e4e4e4e4"
)
sign("GET", swap_qs)
print(call(swap_qs))

One-step: /quote-and-swap

Code
# Reuse the sign() and call() helpers from the snippet above.

qs = (
    "/api/v1/dex/aggregator/quote-and-swap"
    "?binanceChainId=56"
    "&fromTokenAddress=0x55d398326f99059fF775485246999027B3197955"
    "&toTokenAddress=0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d"
    "&amount=1000000"
    "&userWalletAddress=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
    "&vendor=LiquidMesh"
    "&slippagePercent=0.5"
    "&feePercent=1.5"
    "&fromTokenReferrerWalletAddress=0xCbF2B6E6e3D7e9e4e4e4e4e4e4e4e4e4e4e4e4e4"
)
sign("GET", qs)
print(call(qs))