Every fee the platform charges, and where each one is set

"Why did the customer receive less than they asked for" is a weekly ticket, and the answer is never in one place. Fees on this platform are configured in six unrelated screens, stored in four different shapes, and compose in an order that is not obvious — and for the same nominal fee, a deposit and a withdrawal can behave in opposite directions.

This page is the map. Read the arithmetic section before you change any number, because "2.9% + 0.30" means something different on each of these screens.

The six places

There is a seventh input with no screen at all: the withdrawChainFee setting, which decides who bears the blockchain network fee on a spot withdrawal. It has its own section below.

The two shapes of "fee"

Every fee on this platform is one of two things, and the two behave differently:

• Added on top. The customer asks for 100 and 103.20 leaves their balance, or they are billed 103.20 at the checkout. They receive exactly what they asked for.
• Taken out. The customer asks for 100, 100 leaves their balance, and 96.80 arrives. They receive less than they asked for.

Which one applies is decided by the route, not by the setting. There is no switch.

The arithmetic, once

Every percentage-plus-fixed pair on this platform composes the same way:

fee = (gross × percentageFee) / 100 + fixedFee

Percentage on the gross first, then the fixed fee added. Not the other way round, and the percentage is never applied to the amount after the fixed fee.

Worked example, on a gateway at 2.9% + 0.30 with a 100 USD deposit:

The money tab on the gateway editor renders exactly this preview, per currency, against an amount you type. Use it — it is computed from the same expression the routes use.

1. Deposit gateways

Finance → Payment Systems → Payment Gateways, open a gateway, money tab. Editing needs edit.deposit.gateway.

Four fields — fixedFee, percentageFee, minAmount, maxAmount — and each is a JSON column that holds either a single number for every currency, or a map keyed by currency code:

"percentageFee": 2.9
"percentageFee": { "USD": 2.9, "EUR": 2.4, "GBP": 2.4 }

Both shapes are real and both are in the shipped seed data, which is why the editor makes you choose rather than inferring it. When the column holds a map, a currency missing from the map resolves to 0 — the accessor returns null for an absent or unparseable entry and the caller defaults to zero. Adding a currency to a gateway therefore silently gives it a free deposit until you add it to each fee map as well; the editor flags the missing keys.

Values are coerced with Number() on read, because a hand-edited row or a form post can store the entry as a string — and a string there would concatenate instead of adding.

alias is the join between the row and its payment handler, and it is deliberately not editable: renaming it saves cleanly and then 404s every payment through that gateway. See Connecting a fiat deposit gateway.

2 and 3. Deposit and withdrawal methods

Finance → Payment Systems → Payment Methods (create|edit|delete.deposit.method) and Finance → Withdrawal Management → Withdrawal Methods (create|edit|delete.withdraw.method).

Both carry the same four numeric columns as plain DOUBLEs — no per-currency map, no JSON:

A withdrawal method also has processingTime, which is display-only.

A fiat withdrawal debits the full requested amount and pays out amount − fee. The refusal messages name the method, so "Minimum withdrawal for Bank Transfer is 50 USD" points straight at the row to edit.

4. The three settings

System → Platform Settings → Wallet → Fees. All three are range controls clamped by the UI to 0–10%, and all three are stored as text.

Two of the three are Super Admin only to save: walletTransferFee and walletTransferSpread are on the protected-settings list, along with the legacy walletTransferFeePercentage name. spotWithdrawFee is not on that list — any admin holding the settings edit permission can change the spot withdrawal percentage, on a route that moves real money off the platform.

spotWithdrawFee is additive, and clamped

The spot withdrawal route computes:

combinedPercentageFee = exchangeCurrency.fee + spotWithdrawFee
percentageFeeAmount   = totalWithdrawAmount × combinedPercentageFee / 100

exchangeCurrency.fee is the currency's own percentage, imported from the exchange provider — you do not type it. So a 1% setting on a coin the provider already charges 0.5% for withdraws at 1.5%, not 1%.

The setting is read through CacheManager.toNumber with a 0–100 clamp, not parseFloat, so a hand-edited row cannot charge an absurd fee. If the combination still produces a non-finite result — a broken currency row, a broken precision — the route refuses the withdrawal with "Withdrawal fees are misconfigured for this currency" rather than processing it with the guards open.

walletTransferFee, and the key the UI never writes

The transfer engine reads walletTransferFee and falls back to walletTransferFeePercentage — a legacy key the settings screen has never written. The engine used to read only the legacy key, so the configured fee was silently never charged. If you find a walletTransferFeePercentage row in your settings table, it was set by hand or inherited from an old install; it still takes effect when the live key is absent.

The value is clamped to a maximum of 100, and anything non-finite or zero-or-below is treated as no fee.

walletTransferSpread is not a fee

It is a margin against the mid-market rate, applied only on a cross-currency transfer:

rate = midRate × (100 − spread) / 100

midRate is fromPriceUSD / toPriceUSD. The spread is clamped to 0–100, so a misconfigured value can never zero out or invert the rate. It is applied by the same function that serves the quote the customer was shown, so the displayed rate and the settled rate cannot disagree.

The transfer fee is taken first, and the conversion runs on what is left:

credited = (amount − transferFee) × rate

Neither figure is a separately itemised charge to the customer; the spread shows up only as a slightly worse rate.

5. Who bears the network fee

The spot withdrawal route reads the network fee from the exchange's own per-chain metadata (networks[chain].fee, falling back to networks[chain].fees.withdraw) and then:

The Super Admin exemption below does not cover this. Network fees apply to everyone, including you.

6. Ecosystem token withdrawals

Ecosystem admin → Trading → Tokens (/admin/ecosystem/token), the token's fee object:

"fee": { "percentage": 0.5, "min": 0.001 }

The charge is a floor, not a sum:

withdrawalFee = max(amount × percentage / 100, min)

and the user is debited amount + withdrawalFee, on every chain. The address receives the full amount.

The gas cost of the on-chain send is paid by the platform's master or gas wallet and recovered through this token-denominated fee. Network gas is never added to a token debit — an earlier version added a TRX gas estimate to a USDT withdrawal, which is where the phantom "required = amount + 28" refusals came from. So if this fee is set to zero on a chain with real gas costs, every withdrawal on it runs at a loss to your master wallet.

Super Admin pays no platform fee

Every internal fee path checks isSuperAdmin(userId) and zeroes the platform's cut:

• fiat deposits credited through the shared processor,
• fiat withdrawals,
• the internal percentage on spot withdrawals,
• and collectPlatformFee itself, which skips outright when the acting user is the Super Admin, because charging and crediting the same wallet is a circular no-op that inflates the profit report.

Network fees still apply. On a spot withdrawal the external fee is computed before the exemption and is untouched by it.

The Super Admin is resolved as the oldest user holding the "Super Admin" role, cached for five minutes. If that role, or a user holding it, does not exist, every platform fee on the install is dropped on the floor — logged as [CRITICAL] Dropped platform fee — no Super Admin configured, with the amount, currency, type and reference so it can be reconciled later. Fee collection never throws and never rolls back the customer's operation.

Where a collected fee goes

Every fee the platform keeps is booked by one helper, collectPlatformFee, which writes two records:

adminProfit is what Finance → Revenue Analytics (/admin/finance/profit, access.admin.profit) reports. A fee that was never booked there is invisible to that screen even though the money moved.

Fees are booked when the money actually moves, not when it is requested

This is the rule that stops rejected payouts minting revenue:

collectWithdrawalFeeOnSettlement runs on every settlement door — the admin approve endpoint, the withdraw-log update, the TransFi webhook, and the spot route once the exchange accepts the payout. The idempotency key inside collectPlatformFee is derived from the transaction id, so a retry, or an admin completing a row twice, cannot double-collect.

The coercion trap: why these values are read defensively

combinedPercentageFee  -> NaN
percentageFeeAmount    -> NaN
totalDeductionAmount   -> NaN
availableBalance < NaN -> false    insufficient-funds guard skipped
newBalance < 0         -> false    negative-balance guard skipped

Three defences are now in place, and they are why the numbers above are read the way they are:

• CacheManager.toNumber uses Number(), not parseFloat — because parseFloat("12abc") is 12, which turns a typo into a plausible-looking fee. Anything not a finite number yields the caller's stated fallback, an empty string means unset rather than zero, and min/max clamp a hand-edited row to the range the UI would have enforced.
• The spot withdrawal route refuses outright when the computed fee is not finite.
• The deposit-gateway accessors coerce with Number() and resolve anything unparseable to null, so the caller applies its default rather than concatenating a string into an amount.

Fix the rows. pnpm --filter backend repair:settings reports which numeric settings hold booleans; --apply writes them back. It reads which keys are numbers from the settings screen definition, maps "true" to "1" and "false" to "0", leaves switch-typed keys alone, and writes through the cache manager so no restart is needed. See Repair, reconcile and diagnostic scripts.

A checklist before you change a fee

Related

• Connecting a fiat deposit gateway — the readiness console, credentials and the alias join.
• Withdrawal approval and two-factor policy — who decides a payout leaves, which is when its fee is booked.
• Settings reference — every switch on the settings screen.
• Repair, reconcile and diagnostic scripts — repair:settings.
• When money does not move — triage when a fee is not the problem.