> For the complete documentation index, see [llms.txt](https://docs.ston.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ston.fi/developer-section/omniston/referral-fees.md). # Integrator fees Configure current v1beta8 integrator addresses, pips, quote amounts, and settlement-specific payout paths. API v1beta8 calls application commissions **integrator fees**. Configure the fee when requesting a quote, then inspect the returned quote's fee amounts. Rate fields are not token-unit amounts. ## RFQ configuration | Protobuf JSON field | SDK property | Meaning | | -------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------- | | `integrator_address` | `integratorAddress` | `ChainAddress` receiving the fee on the destination blockchain | | `integrator_fee_pips` | `integratorFeePips` | Requested rate in pips: one pip = 0.0001% | | `settlement_params[].swap.flexible_integrator_fee` | swap branch `flexibleIntegratorFee` | Allow a lower effective fee where the swap route's fee constraints require it | One basis point is 100 pips: 0.1% = 1,000 pips; 0.3% = 3,000 pips; 1% = 10,000 pips. Do not carry a v1beta7 bps number unchanged into a v1beta8 pips field. The following JSON RFQ example requests a 0.3% fee with a TON destination. Set the integrator address to your fee-receiving address on the destination chain. ```json { "input_asset": {"ton":{"native":{}}}, "output_asset": {"ton":{"jetton":"EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs"}}, "input_units": "1000000000", "integrator_address": {"ton":""}, "integrator_fee_pips": 3000, "settlement_params": [{"swap":{"max_price_slippage_pips":10000,"flexible_integrator_fee":true}}] } ``` For a cross-chain output, use an integrator address on the output chain. Configure the same identities consistently throughout quote acceptance and settlement. Implementation examples are in [JS/TS](/developer-section/omniston/sdk/nodejs.md#quote-receiving-based-on-parameters), [React](/developer-section/omniston/sdk/react.md#quote-receiving-based-on-parameters), [WebSocket](/developer-section/omniston/swap/overview.md#request-quotes), and [gRPC](/developer-section/omniston/swap/grpc.md#first-quote-request). ## Effective amounts `output_units` is the trader's net output. `integrator_fee_units` and `protocol_fee_units` are fee amounts in the output asset's integer units. For order settlement, `resolver_sends_units` accounts for the resolver's output transfer including applicable fees; do not display it as the trader's net receive amount. Set `flexibleIntegratorFee` in the swap settlement parameters to allow the quote to use a lower fee when required by the route. Read the effective fee amounts from the returned quote. See [API amounts and fee fields](/developer-section/omniston/swap/v1beta8.md#amounts-and-fee-fields). ## Collection depends on the payout mechanism | Payout context | Detailed guide | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | STON.fi DEX v1 immediate payout | [DEX v1 direct payouts](/developer-section/dex/fees.md#dex-v1-direct-payouts) | | STON.fi DEX v2 fee Vault | [DEX v2 Vault payouts](/developer-section/dex/fees.md#dex-v2-vault-payouts) and [SDK withdrawal](/developer-section/dex/sdk/vault-operations.md) | | Existing TON external-protocol/minter or escrow Vault | [TON payout contract reference](/developer-section/omniston/migration/fee-payouts.md), using the deployed factory associated with the accrual | | Cross-chain orders | Fees are settled in the output asset on the destination chain | Use [DEX REST fee statistics](/developer-section/dex/api/reference.md#fee-statistics) for DEX Vault accruals and withdrawals, and [History](/developer-section/omniston/history.md) for finalized Omniston orders. ## Widget and direct DEX compatibility The Widget uses `referrerAddress` and `referrerFeeBps`. Direct DEX builders use referral parameters in basis points. See [Widget configuration](/developer-section/widget/widget.md#configuration-options) and the [DEX fee model](/developer-section/dex/fees.md#integrator-fees) for their parameter ranges. For old v1beta7 `referrer_address`/`referrer_fee_bps` requests, use the [API migration](/developer-section/omniston/migration/v1beta7-to-v1beta8-migration-guide.md). See [Versions and migrations](/developer-section/omniston/migration.md) for support status. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.ston.fi/developer-section/omniston/referral-fees.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.