@cowprotocol/sdk-order-book 0.6.6 → 1.1.0

package/README.md

@@ -121,6 +121,39 @@ const orderBookApi = new OrderBookApi({
 })
 ```
 
+### Partner API (Authenticated Access)
+
+Partners can use the Partner API for authenticated, rate-limited access with higher request quotas. Provide your API key and the SDK will automatically route requests through the partner gateway and attach the `X-API-Key` header.
+
+| Environment | Partner API Base URL |
+|-------------|---------------------|
+| Production  | `https://partners.cow.fi` |
+| Staging     | `https://partners.barn.cow.fi` |
+
+```typescript
+const orderBookApi = new OrderBookApi({
+  chainId: SupportedChainId.MAINNET,
+  apiKey: 'your-partner-api-key',
+})
+```
+
+To use the Partner API with the Trading SDK, pass a configured `OrderBookApi` instance:
+
+```typescript
+import { TradingSdk } from '@cowprotocol/sdk-trading'
+
+const orderBookApi = new OrderBookApi({
+  chainId: SupportedChainId.MAINNET,
+  apiKey: 'your-partner-api-key',
+})
+
+const sdk = new TradingSdk(
+  { chainId: SupportedChainId.MAINNET, appCode: 'YOUR_APP_CODE' },
+  { orderBookApi },
+  adapter,
+)
+```
+
 ### Rate Limiting Configuration
 
 ```typescript

package/dist/index.d.mts

@@ -1049,18 +1049,22 @@ interface Costs<T> {
 /**
  * Details about costs and amounts, costs and fees of a quote.
  *
- * CoW Protocol quote has amounts (sell/buy) and costs (network fee), there is also partner fees.
- * Besides that, CoW Protocol supports both sell and buy orders and the fees and costs are calculated differently.
+ * CoW Protocol quote has amounts (sell/buy), network fee, and protocol fee.
+ * On the client side (after /quote response) we add partner fee and slippage.
+ * CoW Protocol supports both sell and buy orders and the fees and costs are calculated differently.
  *
  * The order of adding fees and costs is as follows:
- * 1. Network fee is always added to the sell amount
- * 2. Partner fee is added to the surplus amount (sell amount for sell-orders, buy amount for buy-orders)
- * 3. Protocol fee is already baked into the quoted amounts:
+ * 1. Protocol fee is already baked into the quoted amounts:
  *    - for SELL orders it has been deducted from the buy amount
- *    - for BUY orders it has been added on top of the sell amount.
+ *    - for BUY orders it has been added on top of the sell amount
+ * 2. Network fee:
+ *    - for SELL orders it has been deducted from the sell amount
+ *    - for BUY orders it's not added to any amount, and provided separately as `feeAmount`
+ * 3. Partner fee is added to the surplus amount (sell amount for sell-orders, buy amount for buy-orders)
+ * 4. Slippage is added to the surplus amount (sell amount for sell-orders, buy amount for buy-orders)
  *
- * For sell-orders the partner fee is subtracted from the buy amount after network costs.
- * For buy-orders the partner fee is added on top of the sell amount after network costs.
+ * For sell-orders the partner fee and slippage are subtracted from the buy amount after network costs.
+ * For buy-orders the partner fee and slippage are added on top of the sell amount after network costs.
  */
 interface QuoteAmountsAndCosts<T = bigint> {
     /**
@@ -1077,6 +1081,9 @@ interface QuoteAmountsAndCosts<T = bigint> {
      * so UIs can decide how to show it to the user.
      */
     costs: Costs<T>;
+    /**
+     * Before all the fees and costs. Spot price amounts
+     */
     beforeAllFees: Amounts<T>;
     /**
      * Amounts before network costs. This amount could be shown to the user to reflect how much they are expected to get
@@ -1084,17 +1091,22 @@ interface QuoteAmountsAndCosts<T = bigint> {
      */
     beforeNetworkCosts: Amounts<T>;
     /**
-     * Amounts after including network costs.
+     * 1. Same with beforeNetworkCosts.
+     * `beforeNetworkCosts` was here even before protocol fee existed, and we keep it for backward compatibility
+     */
+    afterProtocolFees: Amounts<T>;
+    /**
+     * 2. Amounts after including network costs.
      */
     afterNetworkCosts: Amounts<T>;
     /**
-     * Amounts after including partner fees (if any).
+     * 3. Amounts after including partner fees (if any).
      *
      * This amount could be shown to the user, as the expected to receive amount already including any fees or costs.
      */
     afterPartnerFees: Amounts<T>;
     /**
-     * Amounts after including the slippage tolerance.
+     * 4. Amounts after including the slippage tolerance.
      *
      * This is the minimum that the user will receive and the amount they will sign.
      *
@@ -1102,6 +1114,10 @@ interface QuoteAmountsAndCosts<T = bigint> {
      * event of the buy token appreciating.
      */
     afterSlippage: Amounts<T>;
+    /**
+     * Amounts that supposed to be signed as part of order
+     */
+    amountsToSign: Amounts<T>;
 }
 
 /**
@@ -1113,6 +1129,18 @@ declare const ORDER_BOOK_PROD_CONFIG: ApiBaseUrls;
  * An object containing *staging* environment base URLs for each supported `chainId`.
  */
 declare const ORDER_BOOK_STAGING_CONFIG: ApiBaseUrls;
+/**
+ * An object containing *partner production* environment base URLs for each supported `chainId`.
+ * Used when apiKey is set; requests include X-API-Key header.
+ * @see {@link https://partners.cow.fi}
+ */
+declare const ORDER_BOOK_PARTNER_PROD_CONFIG: ApiBaseUrls;
+/**
+ * An object containing *partner staging* environment base URLs for each supported `chainId`.
+ * Used when apiKey is set and env is staging; requests include X-API-Key header.
+ * @see {@link https://partners.barn.cow.fi}
+ */
+declare const ORDER_BOOK_PARTNER_STAGING_CONFIG: ApiBaseUrls;
 /**
  * The parameters for the `getOrders` request.
  */
@@ -1328,8 +1356,9 @@ declare class OrderBookApi {
      */
     private getContextWithOverride;
     /**
-     * Get the base URLs for the API endpoints given the environment.
-     * @param env The environment to get the base URLs for.
+     * Get the base URLs for the API endpoints given the context.
+     * Uses partner URLs when apiKey is set (and no custom baseUrls override).
+     * @param context The merged API context for the request.
      * @returns The base URLs for the API endpoints.
      */
     private getApiBaseUrls;
@@ -1385,44 +1414,136 @@ interface FetchParams {
  * @param body The body of the request.
  * @param rateLimiter The rate limiter to use.
  * @param backoffOpts The backoff options to use.
+ * @param additionalHeaders Optional additional headers (e.g. X-API-Key for Partner API).
  * @returns The response of the request.
  * @throws If the API returns an error or if the request fails.
  */
-declare function request<T>(baseUrl: string, { path, query, method, body }: FetchParams, rateLimiter: RateLimiter, backoffOpts: BackoffOptions): Promise<T>;
+declare function request<T>(baseUrl: string, { path, query, method, body }: FetchParams, rateLimiter: RateLimiter, backoffOpts: BackoffOptions, additionalHeaders?: Record<string, string>): Promise<T>;
 
-interface QuoteAmountsAndCostsParams {
-    orderParams: OrderParameters;
+type OrderAmountsBig = {
+    sellAmount: bigint;
+    buyAmount: bigint;
+};
+interface QuoteParameters {
     sellDecimals: number;
     buyDecimals: number;
-    slippagePercentBps: number;
-    partnerFeeBps: number | undefined;
+    orderParams: OrderParameters;
     protocolFeeBps: number | undefined;
 }
-declare function getQuoteAmountsWithCosts(params: {
-    sellDecimals: number;
-    buyDecimals: number;
+interface QuoteAmountsAndCostsParams {
     orderParams: OrderParameters;
-    protocolFeeBps?: number;
-}): {
+    protocolFeeBps: number | undefined;
+    partnerFeeBps: number | undefined;
+    slippagePercentBps: number;
+}
+interface QuotePriceParams {
+    numerator: bigint;
+    denominator: bigint;
+}
+interface QuoteAmountsWithNetworkCosts {
     isSell: boolean;
-    quotePrice: number;
-    sellAmountAfterNetworkCosts: bigint;
-    buyAmountAfterNetworkCosts: bigint;
-    buyAmountBeforeNetworkCosts: bigint;
+    quotePriceParams: QuotePriceParams;
     networkCostAmount: bigint;
     sellAmountBeforeNetworkCosts: bigint;
-};
+    buyAmountAfterNetworkCosts: bigint;
+    sellAmountAfterNetworkCosts: bigint;
+    buyAmountBeforeNetworkCosts: bigint;
+}
+
+/**
+ * Calculates all quote amount stages and costs from a `/quote` API response.
+ *
+ * Takes the raw order parameters (where protocol fee and network costs are already baked in)
+ * and reconstructs every intermediate amount stage: before all fees, after protocol fees,
+ * after network costs, after partner fees, and after slippage.
+ *
+ * The returned {@link QuoteAmountsAndCosts} includes `amountsToSign` — the final sell/buy
+ * amounts that should be used when signing the order.
+ *
+ * @see {@link ./README.md} for a detailed explanation of the fee application order.
+ *
+ * @param params - Quote parameters including order params, fee BPS values, and slippage.
+ * @returns All amount stages, cost breakdowns, and the amounts to sign.
+ */
 declare function getQuoteAmountsAndCosts(params: QuoteAmountsAndCostsParams): QuoteAmountsAndCosts;
-type BigNumber = {
-    big: bigint;
-    num: number;
-};
+
+interface QuoteAmountsAfterPartnerFeeParams {
+    afterNetworkCosts: Amounts<bigint>;
+    beforeAllFees: Amounts<bigint>;
+    isSell: boolean;
+    partnerFeeBps: number;
+}
+interface QuoteAmountsAfterPartnerFee {
+    partnerFeeAmount: bigint;
+    afterPartnerFees: OrderAmountsBig;
+}
 /**
- * BigInt works well with subtraction and addition, but it's not very good with multiplication and division
- * To multiply/divide token amounts we have to convert them to numbers, but we have to be careful with precision
- * @param value
- * @param decimals
+ * Calculates the partner fee amount and adjusts quote amounts accordingly.
+ *
+ * The partner fee is computed relative to the spot price (`beforeAllFees`) to ensure
+ * it reflects the full trade volume, not the volume already reduced by protocol fee.
+ *
+ * - **SELL orders:** partner fee is subtracted from `buyAmount` (user receives less)
+ * - **BUY orders:** partner fee is added to `sellAmount` (user pays more)
+ *
+ * @param params.afterNetworkCosts - Amounts after network costs, used as the base for adjustment.
+ * @param params.beforeAllFees - Spot price amounts used to calculate the fee percentage.
+ * @param params.isSell - Whether this is a sell order.
+ * @param params.partnerFeeBps - Partner fee in basis points (0 = no partner fee).
+ * @returns The partner fee amount and the adjusted amounts after partner fees.
+ */
+declare function getQuoteAmountsAfterPartnerFee(params: QuoteAmountsAfterPartnerFeeParams): QuoteAmountsAfterPartnerFee;
+
+interface QuoteAmountsAfterSlippageParams {
+    afterPartnerFees: OrderAmountsBig;
+    isSell: boolean;
+    slippageBps: number;
+}
+interface QuoteAmountsAfterSlippage {
+    afterSlippage: OrderAmountsBig;
+}
+/**
+ * Applies slippage tolerance to the quote amounts after all fees have been applied.
+ *
+ * Slippage protects the user from price movements between quoting and execution.
+ * It is always applied to the non-fixed (surplus) side of the order:
+ *
+ * - **SELL orders:** slippage reduces `buyAmount` (user accepts receiving less)
+ * - **BUY orders:** slippage increases `sellAmount` (user accepts paying more)
+ *
+ * @param params.afterPartnerFees - Amounts after partner fees have been applied.
+ * @param params.isSell - Whether this is a sell order.
+ * @param params.slippageBps - Slippage tolerance in basis points.
+ * @returns The adjusted amounts after slippage tolerance.
+ */
+declare function getQuoteAmountsAfterSlippage(params: QuoteAmountsAfterSlippageParams): QuoteAmountsAfterSlippage;
+
+interface ProtocolFeeAmountParams {
+    orderParams: OrderParameters;
+    protocolFeeBps: number;
+}
+/**
+ * /quote API returns `OrderParameters` where protocol fee is already included in the amounts
+ * From the quote response we only know:
+ *  - protocol fee percent (in BPS)
+ *  - quote amount after protocol fee
+ *
+ * To get the protocol fee amount, we need to derive the quote amount BEFORE the protocol fee first
+ * On the API side `quoteAmountAfterProtocolFee` is calculated like that:
+ *
+ * protocolFeePercent = 0.02
+ * quoteAmountBeforeProtocolFee = 100_000
+ * protocolFeeAmount = 100_000 * 0.02 / 100 = 20
+ * quoteAmountAfterProtocolFee = 100_000 - 20 = 99_980
+ *
+ * On the client side, we don't know `quoteAmountBeforeProtocolFee`, so we have to reverse it from `quoteAmountAfterProtocolFee`
+ *
+ * quoteAmountBeforeProtocolFee = 99_980 / (1 - 0.02 / 100) = 100_000
+ *
+ * Note: the example above is for SELL orders, for BUY orders the protocol fee is added to sellAmount instead of substracting from buyAmount
+ *
+ * @param params
  */
-declare function getBigNumber(value: string | bigint | number, decimals: number): BigNumber;
+declare function getProtocolFeeAmount(params: ProtocolFeeAmountParams): bigint;
 
-export { type Address, type Amounts, type AppData, type AppDataHash, type AppDataObject, type Auction, type AuctionOrder, type AuctionPrices, type BigUint, BuyTokenDestination, type CallData, type CompetitionAuction, CompetitionOrderStatus, type Costs, DEFAULT_BACKOFF_OPTIONS, DEFAULT_LIMITER_OPTIONS, type EcdsaSignature, EcdsaSigningScheme, type EnrichedOrder, type EthflowData, type ExecutedAmounts, type ExecutedProtocolFee, type FeePolicy, type FetchParams, type GetOrdersRequest, type GetTradesRequest, type InteractionData, type NativePriceResponse, ORDER_BOOK_PROD_CONFIG, ORDER_BOOK_STAGING_CONFIG, OnchainOrderData, type Order, OrderBookApi, OrderBookApiError, type OrderCancellation, OrderCancellationError, type OrderCancellations, OrderClass, type OrderCreation, OrderKind, type OrderMetaData, type OrderParameters, OrderPostError, type OrderQuoteRequest, type OrderQuoteResponse, type OrderQuoteSide, OrderQuoteSideKindBuy, OrderQuoteSideKindSell, type OrderQuoteValidity, OrderStatus, type PreSignature, PriceEstimationError, type PriceImprovement, PriceQuality, type Quote, type QuoteAmountsAndCosts, type QuoteAmountsAndCostsParams, SellTokenSource, type Signature, SigningScheme, type SolverCompetitionResponse, type SolverSettlement, type Surplus, type TokenAmount, type TotalSurplus, type Trade, type TransactionHash, type UID, type Volume, getBigNumber, getQuoteAmountsAndCosts, getQuoteAmountsWithCosts, request };
+export { type Address, type Amounts, type AppData, type AppDataHash, type AppDataObject, type Auction, type AuctionOrder, type AuctionPrices, type BigUint, BuyTokenDestination, type CallData, type CompetitionAuction, CompetitionOrderStatus, type Costs, DEFAULT_BACKOFF_OPTIONS, DEFAULT_LIMITER_OPTIONS, type EcdsaSignature, EcdsaSigningScheme, type EnrichedOrder, type EthflowData, type ExecutedAmounts, type ExecutedProtocolFee, type FeePolicy, type FetchParams, type GetOrdersRequest, type GetTradesRequest, type InteractionData, type NativePriceResponse, ORDER_BOOK_PARTNER_PROD_CONFIG, ORDER_BOOK_PARTNER_STAGING_CONFIG, ORDER_BOOK_PROD_CONFIG, ORDER_BOOK_STAGING_CONFIG, OnchainOrderData, type Order, type OrderAmountsBig, OrderBookApi, OrderBookApiError, type OrderCancellation, OrderCancellationError, type OrderCancellations, OrderClass, type OrderCreation, OrderKind, type OrderMetaData, type OrderParameters, OrderPostError, type OrderQuoteRequest, type OrderQuoteResponse, type OrderQuoteSide, OrderQuoteSideKindBuy, OrderQuoteSideKindSell, type OrderQuoteValidity, OrderStatus, type PreSignature, PriceEstimationError, type PriceImprovement, PriceQuality, type ProtocolFeeAmountParams, type Quote, type QuoteAmountsAfterSlippage, type QuoteAmountsAfterSlippageParams, type QuoteAmountsAndCosts, type QuoteAmountsAndCostsParams, type QuoteAmountsWithNetworkCosts, type QuoteParameters, type QuotePriceParams, SellTokenSource, type Signature, SigningScheme, type SolverCompetitionResponse, type SolverSettlement, type Surplus, type TokenAmount, type TotalSurplus, type Trade, type TransactionHash, type UID, type Volume, getProtocolFeeAmount, getQuoteAmountsAfterPartnerFee, getQuoteAmountsAfterSlippage, getQuoteAmountsAndCosts, request };

package/dist/index.d.ts

@@ -1049,18 +1049,22 @@ interface Costs<T> {
 /**
  * Details about costs and amounts, costs and fees of a quote.
  *
- * CoW Protocol quote has amounts (sell/buy) and costs (network fee), there is also partner fees.
- * Besides that, CoW Protocol supports both sell and buy orders and the fees and costs are calculated differently.
+ * CoW Protocol quote has amounts (sell/buy), network fee, and protocol fee.
+ * On the client side (after /quote response) we add partner fee and slippage.
+ * CoW Protocol supports both sell and buy orders and the fees and costs are calculated differently.
  *
  * The order of adding fees and costs is as follows:
- * 1. Network fee is always added to the sell amount
- * 2. Partner fee is added to the surplus amount (sell amount for sell-orders, buy amount for buy-orders)
- * 3. Protocol fee is already baked into the quoted amounts:
+ * 1. Protocol fee is already baked into the quoted amounts:
  *    - for SELL orders it has been deducted from the buy amount
- *    - for BUY orders it has been added on top of the sell amount.
+ *    - for BUY orders it has been added on top of the sell amount
+ * 2. Network fee:
+ *    - for SELL orders it has been deducted from the sell amount
+ *    - for BUY orders it's not added to any amount, and provided separately as `feeAmount`
+ * 3. Partner fee is added to the surplus amount (sell amount for sell-orders, buy amount for buy-orders)
+ * 4. Slippage is added to the surplus amount (sell amount for sell-orders, buy amount for buy-orders)
  *
- * For sell-orders the partner fee is subtracted from the buy amount after network costs.
- * For buy-orders the partner fee is added on top of the sell amount after network costs.
+ * For sell-orders the partner fee and slippage are subtracted from the buy amount after network costs.
+ * For buy-orders the partner fee and slippage are added on top of the sell amount after network costs.
  */
 interface QuoteAmountsAndCosts<T = bigint> {
     /**
@@ -1077,6 +1081,9 @@ interface QuoteAmountsAndCosts<T = bigint> {
      * so UIs can decide how to show it to the user.
      */
     costs: Costs<T>;
+    /**
+     * Before all the fees and costs. Spot price amounts
+     */
     beforeAllFees: Amounts<T>;
     /**
      * Amounts before network costs. This amount could be shown to the user to reflect how much they are expected to get
@@ -1084,17 +1091,22 @@ interface QuoteAmountsAndCosts<T = bigint> {
      */
     beforeNetworkCosts: Amounts<T>;
     /**
-     * Amounts after including network costs.
+     * 1. Same with beforeNetworkCosts.
+     * `beforeNetworkCosts` was here even before protocol fee existed, and we keep it for backward compatibility
+     */
+    afterProtocolFees: Amounts<T>;
+    /**
+     * 2. Amounts after including network costs.
      */
     afterNetworkCosts: Amounts<T>;
     /**
-     * Amounts after including partner fees (if any).
+     * 3. Amounts after including partner fees (if any).
      *
      * This amount could be shown to the user, as the expected to receive amount already including any fees or costs.
      */
     afterPartnerFees: Amounts<T>;
     /**
-     * Amounts after including the slippage tolerance.
+     * 4. Amounts after including the slippage tolerance.
      *
      * This is the minimum that the user will receive and the amount they will sign.
      *
@@ -1102,6 +1114,10 @@ interface QuoteAmountsAndCosts<T = bigint> {
      * event of the buy token appreciating.
      */
     afterSlippage: Amounts<T>;
+    /**
+     * Amounts that supposed to be signed as part of order
+     */
+    amountsToSign: Amounts<T>;
 }
 
 /**
@@ -1113,6 +1129,18 @@ declare const ORDER_BOOK_PROD_CONFIG: ApiBaseUrls;
  * An object containing *staging* environment base URLs for each supported `chainId`.
  */
 declare const ORDER_BOOK_STAGING_CONFIG: ApiBaseUrls;
+/**
+ * An object containing *partner production* environment base URLs for each supported `chainId`.
+ * Used when apiKey is set; requests include X-API-Key header.
+ * @see {@link https://partners.cow.fi}
+ */
+declare const ORDER_BOOK_PARTNER_PROD_CONFIG: ApiBaseUrls;
+/**
+ * An object containing *partner staging* environment base URLs for each supported `chainId`.
+ * Used when apiKey is set and env is staging; requests include X-API-Key header.
+ * @see {@link https://partners.barn.cow.fi}
+ */
+declare const ORDER_BOOK_PARTNER_STAGING_CONFIG: ApiBaseUrls;
 /**
  * The parameters for the `getOrders` request.
  */
@@ -1328,8 +1356,9 @@ declare class OrderBookApi {
      */
     private getContextWithOverride;
     /**
-     * Get the base URLs for the API endpoints given the environment.
-     * @param env The environment to get the base URLs for.
+     * Get the base URLs for the API endpoints given the context.
+     * Uses partner URLs when apiKey is set (and no custom baseUrls override).
+     * @param context The merged API context for the request.
      * @returns The base URLs for the API endpoints.
      */
     private getApiBaseUrls;
@@ -1385,44 +1414,136 @@ interface FetchParams {
  * @param body The body of the request.
  * @param rateLimiter The rate limiter to use.
  * @param backoffOpts The backoff options to use.
+ * @param additionalHeaders Optional additional headers (e.g. X-API-Key for Partner API).
  * @returns The response of the request.
  * @throws If the API returns an error or if the request fails.
  */
-declare function request<T>(baseUrl: string, { path, query, method, body }: FetchParams, rateLimiter: RateLimiter, backoffOpts: BackoffOptions): Promise<T>;
+declare function request<T>(baseUrl: string, { path, query, method, body }: FetchParams, rateLimiter: RateLimiter, backoffOpts: BackoffOptions, additionalHeaders?: Record<string, string>): Promise<T>;
 
-interface QuoteAmountsAndCostsParams {
-    orderParams: OrderParameters;
+type OrderAmountsBig = {
+    sellAmount: bigint;
+    buyAmount: bigint;
+};
+interface QuoteParameters {
     sellDecimals: number;
     buyDecimals: number;
-    slippagePercentBps: number;
-    partnerFeeBps: number | undefined;
+    orderParams: OrderParameters;
     protocolFeeBps: number | undefined;
 }
-declare function getQuoteAmountsWithCosts(params: {
-    sellDecimals: number;
-    buyDecimals: number;
+interface QuoteAmountsAndCostsParams {
     orderParams: OrderParameters;
-    protocolFeeBps?: number;
-}): {
+    protocolFeeBps: number | undefined;
+    partnerFeeBps: number | undefined;
+    slippagePercentBps: number;
+}
+interface QuotePriceParams {
+    numerator: bigint;
+    denominator: bigint;
+}
+interface QuoteAmountsWithNetworkCosts {
     isSell: boolean;
-    quotePrice: number;
-    sellAmountAfterNetworkCosts: bigint;
-    buyAmountAfterNetworkCosts: bigint;
-    buyAmountBeforeNetworkCosts: bigint;
+    quotePriceParams: QuotePriceParams;
     networkCostAmount: bigint;
     sellAmountBeforeNetworkCosts: bigint;
-};
+    buyAmountAfterNetworkCosts: bigint;
+    sellAmountAfterNetworkCosts: bigint;
+    buyAmountBeforeNetworkCosts: bigint;
+}
+
+/**
+ * Calculates all quote amount stages and costs from a `/quote` API response.
+ *
+ * Takes the raw order parameters (where protocol fee and network costs are already baked in)
+ * and reconstructs every intermediate amount stage: before all fees, after protocol fees,
+ * after network costs, after partner fees, and after slippage.
+ *
+ * The returned {@link QuoteAmountsAndCosts} includes `amountsToSign` — the final sell/buy
+ * amounts that should be used when signing the order.
+ *
+ * @see {@link ./README.md} for a detailed explanation of the fee application order.
+ *
+ * @param params - Quote parameters including order params, fee BPS values, and slippage.
+ * @returns All amount stages, cost breakdowns, and the amounts to sign.
+ */
 declare function getQuoteAmountsAndCosts(params: QuoteAmountsAndCostsParams): QuoteAmountsAndCosts;
-type BigNumber = {
-    big: bigint;
-    num: number;
-};
+
+interface QuoteAmountsAfterPartnerFeeParams {
+    afterNetworkCosts: Amounts<bigint>;
+    beforeAllFees: Amounts<bigint>;
+    isSell: boolean;
+    partnerFeeBps: number;
+}
+interface QuoteAmountsAfterPartnerFee {
+    partnerFeeAmount: bigint;
+    afterPartnerFees: OrderAmountsBig;
+}
 /**
- * BigInt works well with subtraction and addition, but it's not very good with multiplication and division
- * To multiply/divide token amounts we have to convert them to numbers, but we have to be careful with precision
- * @param value
- * @param decimals
+ * Calculates the partner fee amount and adjusts quote amounts accordingly.
+ *
+ * The partner fee is computed relative to the spot price (`beforeAllFees`) to ensure
+ * it reflects the full trade volume, not the volume already reduced by protocol fee.
+ *
+ * - **SELL orders:** partner fee is subtracted from `buyAmount` (user receives less)
+ * - **BUY orders:** partner fee is added to `sellAmount` (user pays more)
+ *
+ * @param params.afterNetworkCosts - Amounts after network costs, used as the base for adjustment.
+ * @param params.beforeAllFees - Spot price amounts used to calculate the fee percentage.
+ * @param params.isSell - Whether this is a sell order.
+ * @param params.partnerFeeBps - Partner fee in basis points (0 = no partner fee).
+ * @returns The partner fee amount and the adjusted amounts after partner fees.
+ */
+declare function getQuoteAmountsAfterPartnerFee(params: QuoteAmountsAfterPartnerFeeParams): QuoteAmountsAfterPartnerFee;
+
+interface QuoteAmountsAfterSlippageParams {
+    afterPartnerFees: OrderAmountsBig;
+    isSell: boolean;
+    slippageBps: number;
+}
+interface QuoteAmountsAfterSlippage {
+    afterSlippage: OrderAmountsBig;
+}
+/**
+ * Applies slippage tolerance to the quote amounts after all fees have been applied.
+ *
+ * Slippage protects the user from price movements between quoting and execution.
+ * It is always applied to the non-fixed (surplus) side of the order:
+ *
+ * - **SELL orders:** slippage reduces `buyAmount` (user accepts receiving less)
+ * - **BUY orders:** slippage increases `sellAmount` (user accepts paying more)
+ *
+ * @param params.afterPartnerFees - Amounts after partner fees have been applied.
+ * @param params.isSell - Whether this is a sell order.
+ * @param params.slippageBps - Slippage tolerance in basis points.
+ * @returns The adjusted amounts after slippage tolerance.
+ */
+declare function getQuoteAmountsAfterSlippage(params: QuoteAmountsAfterSlippageParams): QuoteAmountsAfterSlippage;
+
+interface ProtocolFeeAmountParams {
+    orderParams: OrderParameters;
+    protocolFeeBps: number;
+}
+/**
+ * /quote API returns `OrderParameters` where protocol fee is already included in the amounts
+ * From the quote response we only know:
+ *  - protocol fee percent (in BPS)
+ *  - quote amount after protocol fee
+ *
+ * To get the protocol fee amount, we need to derive the quote amount BEFORE the protocol fee first
+ * On the API side `quoteAmountAfterProtocolFee` is calculated like that:
+ *
+ * protocolFeePercent = 0.02
+ * quoteAmountBeforeProtocolFee = 100_000
+ * protocolFeeAmount = 100_000 * 0.02 / 100 = 20
+ * quoteAmountAfterProtocolFee = 100_000 - 20 = 99_980
+ *
+ * On the client side, we don't know `quoteAmountBeforeProtocolFee`, so we have to reverse it from `quoteAmountAfterProtocolFee`
+ *
+ * quoteAmountBeforeProtocolFee = 99_980 / (1 - 0.02 / 100) = 100_000
+ *
+ * Note: the example above is for SELL orders, for BUY orders the protocol fee is added to sellAmount instead of substracting from buyAmount
+ *
+ * @param params
  */
-declare function getBigNumber(value: string | bigint | number, decimals: number): BigNumber;
+declare function getProtocolFeeAmount(params: ProtocolFeeAmountParams): bigint;
 
-export { type Address, type Amounts, type AppData, type AppDataHash, type AppDataObject, type Auction, type AuctionOrder, type AuctionPrices, type BigUint, BuyTokenDestination, type CallData, type CompetitionAuction, CompetitionOrderStatus, type Costs, DEFAULT_BACKOFF_OPTIONS, DEFAULT_LIMITER_OPTIONS, type EcdsaSignature, EcdsaSigningScheme, type EnrichedOrder, type EthflowData, type ExecutedAmounts, type ExecutedProtocolFee, type FeePolicy, type FetchParams, type GetOrdersRequest, type GetTradesRequest, type InteractionData, type NativePriceResponse, ORDER_BOOK_PROD_CONFIG, ORDER_BOOK_STAGING_CONFIG, OnchainOrderData, type Order, OrderBookApi, OrderBookApiError, type OrderCancellation, OrderCancellationError, type OrderCancellations, OrderClass, type OrderCreation, OrderKind, type OrderMetaData, type OrderParameters, OrderPostError, type OrderQuoteRequest, type OrderQuoteResponse, type OrderQuoteSide, OrderQuoteSideKindBuy, OrderQuoteSideKindSell, type OrderQuoteValidity, OrderStatus, type PreSignature, PriceEstimationError, type PriceImprovement, PriceQuality, type Quote, type QuoteAmountsAndCosts, type QuoteAmountsAndCostsParams, SellTokenSource, type Signature, SigningScheme, type SolverCompetitionResponse, type SolverSettlement, type Surplus, type TokenAmount, type TotalSurplus, type Trade, type TransactionHash, type UID, type Volume, getBigNumber, getQuoteAmountsAndCosts, getQuoteAmountsWithCosts, request };
+export { type Address, type Amounts, type AppData, type AppDataHash, type AppDataObject, type Auction, type AuctionOrder, type AuctionPrices, type BigUint, BuyTokenDestination, type CallData, type CompetitionAuction, CompetitionOrderStatus, type Costs, DEFAULT_BACKOFF_OPTIONS, DEFAULT_LIMITER_OPTIONS, type EcdsaSignature, EcdsaSigningScheme, type EnrichedOrder, type EthflowData, type ExecutedAmounts, type ExecutedProtocolFee, type FeePolicy, type FetchParams, type GetOrdersRequest, type GetTradesRequest, type InteractionData, type NativePriceResponse, ORDER_BOOK_PARTNER_PROD_CONFIG, ORDER_BOOK_PARTNER_STAGING_CONFIG, ORDER_BOOK_PROD_CONFIG, ORDER_BOOK_STAGING_CONFIG, OnchainOrderData, type Order, type OrderAmountsBig, OrderBookApi, OrderBookApiError, type OrderCancellation, OrderCancellationError, type OrderCancellations, OrderClass, type OrderCreation, OrderKind, type OrderMetaData, type OrderParameters, OrderPostError, type OrderQuoteRequest, type OrderQuoteResponse, type OrderQuoteSide, OrderQuoteSideKindBuy, OrderQuoteSideKindSell, type OrderQuoteValidity, OrderStatus, type PreSignature, PriceEstimationError, type PriceImprovement, PriceQuality, type ProtocolFeeAmountParams, type Quote, type QuoteAmountsAfterSlippage, type QuoteAmountsAfterSlippageParams, type QuoteAmountsAndCosts, type QuoteAmountsAndCostsParams, type QuoteAmountsWithNetworkCosts, type QuoteParameters, type QuotePriceParams, SellTokenSource, type Signature, SigningScheme, type SolverCompetitionResponse, type SolverSettlement, type Surplus, type TokenAmount, type TotalSurplus, type Trade, type TransactionHash, type UID, type Volume, getProtocolFeeAmount, getQuoteAmountsAfterPartnerFee, getQuoteAmountsAfterSlippage, getQuoteAmountsAndCosts, request };