Debridge

Debridge USDC transfer quotes account for protocol fees and solver execution costs

Last updated:

Debridge quotes cross-chain USDC transfers with protocol fees and solver costs that affect the destination amount. Solvers supply destination liquidity through the Liquidity Network (DLN). Source-chain gas for creating the order remains a separate wallet expense. The quote's input and output fields describe different quantities, especially when the API adds operating expenses to the requested input. A cancelled order returns its source-chain order funds, which can differ from the original token after a pre-order swap.

USDC reserve inputs and routes that include a conversion

A reserve-asset USDC transfer avoids the source conversion that a quote for a non-reserve input may require. A quoted route may swap a non-reserve input into a reserve asset during order placement. A destination conversion can also appear when the requested output isn't a reserve asset. Those conversions introduce their own slippage costs, alongside the cross-chain settlement charges. When both chains offer USDC as a reserve asset, DLN prioritizes it for settlement.

The token address and chain identify the asset. Matching USDC tickers alone don't establish that the selected contracts represent the same supported token.

Read the destination amount before the settlement status

The dstChainTokenOut amount describes the requested destination tokens; a returned quote doesn't establish that those tokens have arrived. The response also identifies the token address, chain, and decimals. Its source fields distinguish the token amount used to create the order from any reserve asset produced by a pre-order swap, while the destination field identifies the token quantity that fulfillment must supply on the receiving chain. Prepended costs can make the source spend larger than the amount originally requested.

Visual outline: Read the destination amount before the settlement status (Debridge)

View image file

Created identifies a placed order awaiting fulfillment. For an ordinary transfer without a hook, Fulfilled identifies destination delivery to the specified recipient. SentUnlock and ClaimedUnlock describe the solver's later source-chain recovery. Neither state adds USDC to the recipient's amount, and a pending unlock shouldn't be mistaken for an unfinished destination transfer.

The fixed destination amount sets the fulfillment requirement. A solver still evaluates the order's economics, so even an accurately quoted market order can remain unfilled.

Which costs does a USDC quote include?

A cross-chain market quote incorporates protocol charges, the solver's margin, and operating expenses for fulfillment and source unlocking. The flat fee uses the source chain's native currency and compensates validators for the eventual unlock message. On EVM chains, its amount comes from the source contract's globalFixedNativeFee() setting. It sits alongside the source-token charge, so the complete cost cannot be expressed as a single USDC deduction without accounting for the native-currency payment.

Visual outline: Debridge USDC transfers: What the quote covers
Debridge USDC transfers

Debridge USDC transfers: What the quote covers

  • Which costs does a USDC quote include?
  • Prepended expenses change the required source amount
  • Quote options change both the cost and the fallback
  • Cancellation refunds order charges but needs a separate transaction

View image file

The documented DLN variable protocol fee is 4 basis points, or 0.04%, of the token amount supplied to the source order. The contract setting can change. The create-tx response supplies the variable-fee amount in protocolFee , and the published EVM DlnSource v1.4.0 implementation exposes globalTransferFeeBps() .

The fee schedule lists an approximate solver margin of 4 basis points of the input amount for market quotes. Operating expenses cover fulfillment, sending the unlock message, and claiming source funds. Network gas conditions affect those expenses. The margin sits within the spread. Operating expenses are either deducted from the spread or prepended to the input, which explains why the variable protocol fee alone doesn't describe the transfer's full economic cost.

Source-chain transaction gas and any ERC-20 approval gas remain separate wallet expenses. The solver pays destination fulfillment gas, and the quote incorporates that cost. Optional affiliate fees and hook rewards add integration-specific charges. These costs need their own token and currency units when comparing the requested input with the destination amount.

Prepended expenses change the required source amount

With prependOperatingExpenses=true , the API adds estimated solver operating expenses to the requested source-token input amount. srcChainTokenIn.amount can therefore exceed the request's srcChainTokenInAmount . For an ERC-20 input, the token allowance must cover the transaction's actual requirement. An allowance covering only the original request may be insufficient even when the wallet holds enough USDC. A quote on an Ethereum Virtual Machine (EVM) chain can also require a native-currency tx.value ; interpret that value in the source chain's native-currency units.

Each token amount follows the decimals supplied in its response field. Compare source and destination quantities in token units before interpreting their approximate USD values. The USD estimates describe valuation; they don't prove a received USDC balance.

Refresh an unsubmitted quote after about 30 seconds if signing has been delayed. Gas prices and route conditions can change during an approval, particularly when a refreshed estimate increases the operating-expense amount. A previously sufficient allowance can then require adjustment. The latest transaction payload and its associated estimate must remain consistent.

Quote options change both the cost and the fallback

The quote's configuration affects the amount committed to an order and the asset or destination available during recovery. Several options can apply to the same order, including an affiliate fee and a hook. A pending order with no enabled automatic cancellation needs its designated destination-chain authority and native currency before a manual cancellation can proceed. On EVM chains, hook settings also control whether fulfillment can survive a failed destination call.

Quote option Effect on amount Condition Refund or fallback
Reserve-asset USDC input Uses USDC directly for order placement The selected USDC is a reserve asset Cancellation returns the source order's USDC
Source input pre-swapped into USDC Conversion affects the locked source amount The route uses USDC as its reserve asset Refund uses USDC after the pre-order swap
Prepended operating expenses Adds the estimate to requested input prependOperatingExpenses=true Cancellation releases the order's source funds
Affiliate fee Allocates a share of input The request includes a referral code, fee percentage, and recipient Cancellation returns the affiliate fee
Atomic success-required EVM hook Applies destination action to order output Hook and fulfillment share a transaction Failed hook prevents fulfillment; order remains cancellable
Atomic optional-success EVM hook Applies destination action to order output A fallback address handles hook failure Failed hook sends output to fallback address
Non-atomic EVM hook Optional execution reward reduces output Hook execution may follow fulfillment Destination authority can cancel a pending hook

If an order remains Created, a manual cancellation must come from its dstChainOrderAuthorityAddress on the destination chain. The cancellation response identifies the allowed sender, chain, beneficiary, and required native-currency value. ClaimedOrderCancel confirms that the source beneficiary has claimed the returned order funds. Changing the input from reserve-asset USDC to a token pre-swapped into USDC changes whether that refund matches the original asset. Cancellation returns the USDC held for the order, without reversing the completed source conversion.

Cancellation refunds order charges but needs a separate transaction

Cancelling an unfilled cross-chain order releases source funds and order charges, while a manual request incurs separate native-currency costs. The refund calculation follows the source order's asset and refundable charges. Transaction gas already spent on the network remains a separate cost. The mandatory flat and variable order-creation fees are refundable when a DLN order is cancelled. The cancellation flow also returns any affiliate fee associated with that order.

The manual cancellation payload includes a positive value in the destination chain's native currency that pays for the cancellation message and prepays source-chain gas for the keeper's claim, while the initiating wallet also pays destination transaction gas. The wallet must hold enough destination-chain native currency for these payments. Enabled automatic cancellation can subsidize the cancellation costs, with eligibility and authority settings that differ from a manual request.

An already fulfilled order can still have a pending non-atomic hook. Its cancellation path releases destination output; the cross-chain trade remains settled.

Hook rewards change the amount available to a destination action

A hook can direct purchased USDC into a destination application, and its execution settings determine how much remains available. For a transfer with a hook, the order's tokens can reach the hook adapter instead of a wallet. A destination deposit then has its own execution outcome. An optional execution reward in an EVM HookDataV1 envelope comes out of the order's destination output. The nominal output amount and the amount available to the target application can therefore differ.

Diagram: Hook rewards change the amount available to a destination action (Debridge)

View image file

The target contract receives a call through DLN's execution machinery. A beneficiary parameter such as onBehalfOf can identify the account receiving the application benefit. Hooks don't authenticate the original sender by default. A target that requires sender authentication needs a verified signature, or authenticated messaging for a contract sender. EVM supports atomic and non-atomic hook configurations, while Solana only supports non-atomic success-required hooks. Before choosing a wallet transfer or an application action, distinguish the quoted output from executor rewards and the destination that will actually receive the remaining USDC.

Debridge - common questions

Which amount does the API recommend for a USDC market order?

The recommendedAmount field accounts for fees and taker margin when suggesting the destination token amount. maxTheoreticalAmount describes a theoretical maximum, which doesn't establish that a solver will accept the trade. Raising the requested output can reduce the margin that pays the liquidity provider.

How do affiliate fees settle after a USDC transfer?

A cross-chain affiliate fee becomes available when the order reaches ClaimedUnlock. On EVM chains, it normally transfers in the solver's unlock transaction; failed transfers can leave fees pending a manual claim. On Solana, the beneficiary must withdraw the fee manually. The integration includes a referral code in the request and sets affiliateFeePercent and affiliateFeeRecipient to allocate a share of the input token. Destination fulfillment can precede that source-chain payout, so a received USDC transfer doesn't by itself establish that the affiliate has been paid. Cancellation returns the affiliate fee with the source order funds.

Why can usdPriceImpact be negative in a USDC quote?

usdPriceImpact can be negative because it represents the direction of estimated USD price movement caused by the trade. The field expresses that impact as a percentage of the input amount's estimated USD value. It isn't a negative protocol fee or a promise of extra USDC. The quote's token amounts and itemized costs describe different quantities from that valuation estimate.

Is a referral code enough to enable subsidized cancellation?

A referral code alone doesn't enable subsidized automatic cancellation. Debridge must approve and activate the feature for the integration, with the required cancellation parameters configured correctly. The documented service applies to market orders and excludes limit orders.

Where does an automatically cancelled USDC order return its funds?

The srcAllowedCancelBeneficiary setting identifies the source-chain beneficiary for an automatic cancellation refund. An integration should explicitly set it to the intended user-controlled wallet. If that setting is omitted, a supplied srcChainOrderAuthorityAddress provides the fallback. Automatic cancellation also changes the destination cancellation authority to a Debridge-controlled address. An incorrect beneficiary can leave the user unable to recover the refund.

Are same-chain USDC swaps charged through the cross-chain order model?

Same-chain USDC swaps use a different execution path and don't create an on-chain DLN order entity. Their quote exposes protocolFee, costsDetails, and estimatedTransactionFee for that swap. The Stats API can represent the transaction as an order-like record for consistent histories. That representation doesn't make cross-chain order-creation fees or destination-chain cancellation procedures apply to a same-chain swap. Compare its own cost breakdown and transaction outcome.

Which quote entries identify solver expenses separately from protocol fees?

The costsDetails breakdown distinguishes DlnProtocolFee, EstimatedOperatingExpenses, and TakerMargin entries. When prependOperatingExpenses=true, the API exposes the solver operating-expense estimate that it adds to the requested input. These fields identify different cost components, so the protocol fee alone doesn't represent the solver's total costs. Keep each feeAmount in its associated token units when comparing it with USDC input or output quantities.

How does a Universal Hook handle USDC that the destination contract leaves unused?

A Universal Hook sends unused ERC-20 output, including USDC, to the configured fallback address after the destination call. It gives the target contract a temporary allowance and expects that contract to pull the tokens it needs. The hook then resets the allowance to zero. A function that expects tokens to arrive through an immediate transfer uses a different funding pattern from this allowance-based call.