Integrator fees and attribution

This feature is in private alpha and the details are subject to change!

You can add your own fee to a trade. The fee is paid in the input token to a wallet you choose. Sunrise also marks your trades onchain with a memo, so they count as yours. Both work only on the rfq-fill route, for tokenized stocks against USDC on Solana. See RFQ orders for how that route works. This recipe builds on the swap recipe and the RFQ orders recipe. It uses the same headers, account, stock, and signing code.

How it works

Fee. Send integratorFeeBps and integratorFeeRecipientAddress with POST /v1/quotes. The quote comes back with the fee built into its transaction. When the order fills, the fee goes to the recipient wallet.
Memo. Sunrise sets a memo on your API key. Every rfq-fill transaction quoted with your key includes it as a Solana Memo instruction. You don’t send the memo yourself.

Step 1: Get your key set up for fees

Contact contact@sunrise.xyz to enable fees on your API key. For each wallet you want to receive fees, send:

The Solana wallet address.
The highest fee rate you want to charge to it, in basis points. 100 basis points is 1%.

Sunrise approves each wallet and its maximum rate on your key. Your key also needs access to the rfq-fill route. Changes to your key can take up to five minutes to apply. You don’t need any setup to trade without a fee.

Step 2: Get a quote with a fee

Add the two fee fields to the quote request from RFQ orders:

const FEE_WALLET = "<your-approved-fee-wallet>";

const quoteResponse = await fetch("https://api.sunrise.xyz/v1/quotes", {
  method: "POST",
  headers,
  body: JSON.stringify({
    fromToken: USDC_MINT,
    toToken: stock.address,
    fromAmount: "100000000", // 100 USDC
    fromAddress: account.address,
    toAddress: account.address,
    integratorFeeBps: 25, // 0.25%
    integratorFeeRecipientAddress: FEE_WALLET,
  }),
});

const quoteResult = await quoteResponse.json();

if (!quoteResponse.ok || !quoteResult.success) {
  throw new Error(quoteResult.error?.message ?? "Could not get a quote");
}

const quote = quoteResult.data.quotes.find((q) => q.routeName === "rfq-fill");

Field	What it holds
`integratorFeeBps`	The fee in basis points, an integer from 0 to 100. `25` means 0.25%. It must not be above the maximum approved for the recipient wallet.
`integratorFeeRecipientAddress`	The Solana wallet that receives the fee. It must be one of the wallets approved on your key.

Send both fields for a fee. To trade without a fee, leave both out or send integratorFeeBps: 0. A request with a fee above 0 gets quotes only from rfq-fill. Other routes can’t charge the fee, so they’re skipped and listed in unavailableRoutes with the code integrator_fee_not_supported. If rfq-fill gives no quote, unavailableRoutes says why. The fee wallet needs no setup. Its token accounts are created on its first trade with a fee, with a small one-time SOL rent cost to your user.

Step 3: Check the fee on the quote

Each quote with a fee includes integratorFee:

{
  "quoteId": "b3c0f8e2-5d1a-4c7e-9f6b-2a8d4e1c7f90",
  "routeName": "rfq-fill",
  "fromToken": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "toToken": "<stock-mint>",
  "fromAmount": "100000000",
  "toAmount": "412345678",
  "integratorFee": {
    "recipient": "<your-approved-fee-wallet>",
    "bps": 25
  },
  "providerRequestId": "…",
  "unsignedTransaction": "…"
}

The fee is charged in the input token: USDC on a buy, the stock token on a sell. It comes out of fromAmount, so toAmount is what your user gets after the fee. Show your user the fee before they sign. The fee applies only to the part of the order that fills. Anything refunded carries no fee.

Step 4: Sign and execute

Sign and execute the quote as in RFQ orders. Nothing changes for a quote with a fee. Sign the unsignedTransaction exactly as returned. It carries the fee and your memo. If the transaction is changed, for example to remove or edit the memo, execute refuses it.

Attribution with a memo

Your memo is a short code, for example sun-Ab12, that Sunrise sets on your API key. It’s included in every rfq-fill transaction quoted with your key, whether or not you charge a fee. Anyone can read it onchain to see which trades came through you.

One memo per key. By default, every trade from your key carries the same memo.
One memo per wallet. Sunrise can also set a separate memo for each approved fee wallet. A quote that names that wallet in integratorFeeRecipientAddress uses its memo instead.
Attribution without a fee. To pick a wallet’s memo without charging a fee, send integratorFeeBps: 0 and that wallet in integratorFeeRecipientAddress. If the wallet has no memo of its own, the key’s memo is used.

Routes other than rfq-fill don’t include the memo. To get a memo set on your key, or one per wallet, contact contact@sunrise.xyz.

Fee errors

Code	Status	Why	What to do
`invalid_request`	400	`details.fields` names `integratorFeeBps` or `integratorFeeRecipientAddress`. One of the two is missing, the rate is above the wallet’s maximum, or the wallet isn’t approved on your key.	Fix the named field.
`integrator_fee_unavailable`	400	Fees aren’t enabled on your API key, or your key has no access to `rfq-fill`.	Contact Sunrise to enable fees, or send the quote without a fee.

See Errors for every other code.

Get started

Concepts

Guides

Recipes

API reference

Resources

Legal

Integrator fees and attribution

How it works

Step 1: Get your key set up for fees

Step 2: Get a quote with a fee

Step 3: Check the fee on the quote

Step 4: Sign and execute

Attribution with a memo

Fee errors

​How it works

​Step 1: Get your key set up for fees

​Step 2: Get a quote with a fee

​Step 3: Check the fee on the quote

​Step 4: Sign and execute

​Attribution with a memo

​Fee errors

How it works

Step 1: Get your key set up for fees

Step 2: Get a quote with a fee

Step 3: Check the fee on the quote

Step 4: Sign and execute

Attribution with a memo

Fee errors