diff --git a/fern/docs.yml b/fern/docs.yml index 2cafb987..7f91f712 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -138,10 +138,10 @@ navigation: - section: Additional Topics slug: additional-topics contents: - - page: How to Set Token Allowances + - page: Set Token Allowances slug: how-to-set-your-token-allowances path: docs/pages/0x-swap-api/additional-topics/how-to-set-your-token-allowances.mdx - - page: Handling Native Tokens + - page: Handle Native Tokens slug: handling-native-tokens path: docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx - page: 0x Parser @@ -153,6 +153,9 @@ navigation: - page: Buy/Sell Tax Support slug: buy-sell-tax-support path: docs/pages/0x-swap-api/additional-topics/buy-sell-tax-support.mdx + - page: Multi-Fee Support + slug: multi-fee-support + path: docs/pages/0x-swap-api/additional-topics/multi-fee-support.mdx - page: Swap and Send slug: swap-and-send path: docs/pages/0x-swap-api/additional-topics/swap-and-send.mdx diff --git a/fern/docs/pages/0x-swap-api/additional-topics/multi-fee-support.mdx b/fern/docs/pages/0x-swap-api/additional-topics/multi-fee-support.mdx new file mode 100644 index 00000000..da4ad49e --- /dev/null +++ b/fern/docs/pages/0x-swap-api/additional-topics/multi-fee-support.mdx @@ -0,0 +1,181 @@ +--- +title: Multi-Fee Support +description: Collect fees for multiple recipients in a single swap using the Swap and Gasless APIs. +--- + +The Swap and Gasless APIs support collecting fees for **multiple recipients in a single transaction**. This is useful for use cases like revenue sharing between a protocol and a frontend, splitting fees between partners, or distributing fees across multiple treasury addresses — all without requiring multiple transactions or custom contracts. + +## Overview + +Both `swapFeeRecipient` and `swapFeeBps` accept **comma-separated lists**, allowing you to define multiple fee recipients, each with their own fee rate. + +Each fee is: + +- Collected in the `swapFeeToken` (the buy token by default) +- Delivered directly to the specified recipient address +- Reported individually in the response under `fees.integratorFees` + +## Parameters + + + The wallet address(es) to receive trading fees. Accepts a single address or multiple comma-separated addresses. + +**Example:** `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045,0xfb6916095ca1df60bb79ce92ce3ea74c37c5d359` + +When providing multiple values, the list must be the same length as `swapFeeBps`. You must also specify `swapFeeBps` to use this parameter. + + + + + The fee amount(s) in basis points (Bps) to charge per recipient. Accepts a single value or multiple comma-separated values. + +**Example:** `5,10` + +When providing multiple values, the list must be the same length as `swapFeeRecipient`. The default maximum is **1000 Bps** per recipient. [Contact us](mailto:support@0x.org) if your integration requires a higher limit. + + + + + `swapFeeRecipient` and `swapFeeBps` are co-dependent — you must specify both + together. When using multiple fees, both lists must be the same length and + positionally matched (index 0 of `swapFeeBps` applies to index 0 of + `swapFeeRecipient`, and so on). + + +## Example Request + +The following examples split fees between two recipient addresses — 5 Bps to `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045` and 10 Bps to `0xfb6916095ca1df60bb79ce92ce3ea74c37c5d359`. + + + +```bash cURL +curl "https://api.0x.org/swap/allowance-holder/price\ +?chainId=1\ +&buyToken=0xdac17f958d2ee523a2206206994597c13d831ec7\ +&sellToken=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\ +&sellAmount=100000000\ +&taker=0x70a9f34f9b34c64957b9c401a97bfed35b95049e\ +&swapFeeRecipient=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045,0xfb6916095ca1df60bb79ce92ce3ea74c37c5d359\ +&swapFeeBps=5,10" \ +-H "0x-api-key: " +``` + +```typescript TypeScript +const feeRecipients = [ + "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", + "0xfb6916095ca1df60bb79ce92ce3ea74c37c5d359", +]; +const feeBps = [5, 10]; + +const params = new URLSearchParams({ + chainId: "1", + buyToken: "0xdac17f958d2ee523a2206206994597c13d831ec7", + sellToken: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", + sellAmount: "100000000", + taker: "0x70a9f34f9b34c64957b9c401a97bfed35b95049e", + swapFeeRecipient: feeRecipients.join(","), + swapFeeBps: feeBps.join(","), +}); + +const response = await fetch( + `https://api.0x.org/swap/allowance-holder/price?${params}`, + { + headers: { + "0x-api-key": process.env.ZEROX_API_KEY!, + "0x-version": "v2", + }, + }, +); + +const data = await response.json(); + +// Access full fee breakdown +const fees = data.fees.integratorFees; +fees.forEach((fee, i) => { + console.log( + `Recipient ${feeRecipients[i]} receives ${fee.amount} of ${fee.token}`, + ); +}); +``` + +```python Python +import os +import requests + +fee_recipients = [ + "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", + "0xfb6916095ca1df60bb79ce92ce3ea74c37c5d359", +] +fee_bps = [5, 10] + +params = { + "chainId": "1", + "buyToken": "0xdac17f958d2ee523a2206206994597c13d831ec7", + "sellToken": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", + "sellAmount": "100000000", + "taker": "0x70a9f34f9b34c64957b9c401a97bfed35b95049e", + "swapFeeRecipient": ",".join(fee_recipients), + "swapFeeBps": ",".join(str(b) for b in fee_bps), +} + +response = requests.get( + "https://api.0x.org/swap/allowance-holder/price", + params=params, + headers={"0x-api-key": os.environ["ZEROX_API_KEY"]}, +) + +data = response.json() + +# Access full fee breakdown +for i, fee in enumerate(data["fees"]["integratorFees"]): + print(f"Recipient {fee_recipients[i]} receives {fee['amount']} of {fee['token']}") +``` + + + +## Example Response + +When multiple fees are configured, the response includes both the legacy `integratorFee` field (containing the first fee, for backwards compatibility) and the new `integratorFees` array (containing all fees): + +```json +{ + "fees": { + "integratorFee": { + "amount": "49989", + "token": "0xdac17f958d2ee523a2206206994597c13d831ec7", + "type": "volume" + }, + "integratorFees": [ + { + "amount": "49989", + "token": "0xdac17f958d2ee523a2206206994597c13d831ec7", + "type": "volume" + }, + { + "amount": "99978", + "token": "0xfb6916095ca1df60bb79ce92ce3ea74c37c5d359", + "type": "volume" + } + ], + "zeroExFee": { + "amount": "149968", + "token": "0xdac17f958d2ee523a2206206994597c13d831ec7", + "type": "volume" + }, + "gasFee": null + } +} +``` + + + `fees.integratorFee` is retained for backwards compatibility and always + reflects the **first** fee in the list. Use `fees.integratorFees` to access + the full breakdown of all fees. + + +Each entry in `integratorFees` corresponds positionally to the `swapFeeRecipient` and `swapFeeBps` values in your request: + +| Index | Recipient | Fee (Bps) | Amount (in buy token) | +| ----- | -------------------------------------------- | --------- | --------------------- | +| 0 | `0xdac17f958d2ee523a2206206994597c13d831ec7` | 5 | 49,989 | +| 1 | `0xfb6916095ca1df60bb79ce92ce3ea74c37c5d359` | 10 | 99,978 |