# Transaction Fee

Source: https://docs.settlemint.com/docs/architecture/components/token-features/transaction-fee
Per-transaction fee deducted from transfer amounts on every mint, burn, or transfer. Uses supportsRewriting to reduce the amount in-flight before compliance checks and recipient receipt.



Transaction Fee deducts a per-transaction fee from mint, burn, and transfer operations by rewriting the token amount in-flight. The recipient receives `amount - fee`; the configured fee recipient receives the fee in the same token. Redemption emits the same collection signal and uses the burn fee calculation, but the redemption payout asset is calculated by the redemption feature before the transaction-fee rewrite runs. The compliance rules that decide whether the operation may proceed belong to [asset policy](/docs/architecture/concepts/asset-policy).

***

## Interface (capabilities) [#interface-capabilities]

This feature exposes the following capabilities. It is a rewriting feature: it modifies the token amount in-flight for mint, burn, and transfer operations, so the recipient receives the post-fee amount.

| Capability              | Who can call      | Inputs                                                 | On-chain effect                          | Emits                     | Notes                      |
| ----------------------- | ----------------- | ------------------------------------------------------ | ---------------------------------------- | ------------------------- | -------------------------- |
| Deduct fee on operation | Automatic (hook)  | Triggered on mint, burn, transfer, redeem              | Rewrites amount; routes fee to recipient | `TransactionFeeCollected` | `supportsRewriting = true` |
| Set fee rates           | `GOVERNANCE_ROLE` | Rates per operation type (mint, burn, transfer in bps) | Updates fee rate configuration           | `FeeRatesUpdated`         | Blocked after freeze       |
| Set fee recipient       | `GOVERNANCE_ROLE` | Recipient address                                      | Redirects future fee collection          | `FeeRecipientUpdated`     | Effective immediately      |
| Freeze fee rates        | `GOVERNANCE_ROLE` | None                                                   | Permanently locks all rates              | `FeeRatesFrozen`          | Irreversible               |

***

## Business impact [#business-impact]

* **Holders:** Holders receive the post-fee token amount on mint, burn, and transfer operations. Senders initiate transfers for the gross amount; recipients receive the net amount.
* **Issuer / recipient:** Fees are collected in the token itself and routed to the configured `feeRecipient`.
* **Economics:** Fees are deducted on mint, burn, and transfer operations. Redemption uses the burn fee calculation for the in-token collection signal; it does not reduce the denomination-asset payout calculated by a redemption feature.

***

## Risks & abuse cases [#risks--abuse-cases]

* **Compliance module ordering risk:** Because `supportsRewriting = true`, the amount is rewritten before compliance modules run their checks. A compliance module checking minimum transfer amounts will see the post-fee (reduced) amount. Coordinate fee rates and compliance thresholds.
* **Rate freeze timing:** Leaving `freezeFeeRates()` uncalled allows GOVERNANCE\_ROLE to raise rates after deployment. Call at launch.
* **High-frequency fee accumulation:** Platforms with high transaction volume should monitor fee recipient balance; unexpected recipient addresses can drain value.

***

## Controls & guardrails [#controls--guardrails]

| Role              | Actions                                      | Recommended guardrail                |
| ----------------- | -------------------------------------------- | ------------------------------------ |
| `GOVERNANCE_ROLE` | `setFeeRates()`: set fee rates per operation | Call `freezeFeeRates()` after launch |
| `GOVERNANCE_ROLE` | `setFeeRecipient()`: set fee destination     | Multi-sig; audit all changes         |
| `GOVERNANCE_ROLE` | `freezeFeeRates()`: lock rates permanently   | **Call at launch**                   |

***

## Failure modes & edge cases [#failure-modes--edge-cases]

* **Zero-amount transfer after fee:** If fee equals the full transfer amount, the recipient receives zero tokens and the fee recipient receives the full amount. No revert: check minimum transfer amounts in compliance modules.
* **Fee on minting:** Minting to a holder results in holder receiving `amount - mint_fee`. If mint semantics require exact amounts, account for the fee in the mint call.

***

## Auditability and operational signals [#auditability-and-operational-signals]

* `TransactionFeeCollected(from, feeAmount, operationType)` is emitted per fee-bearing operation. Use it for reconciliation and monitoring.
* `FeeRatesUpdated(sender, mintRate, burnRate, transferRate)` is emitted on rate changes.
* `FeeRatesFrozen(sender)` is emitted once on freeze.

DALP also exposes indexed collection rows for the active transaction-fee feature at `GET /api/v2/tokens/{tokenAddress}/transaction-fee/collections`. The read returns a paginated `data`, `meta`, and `links` response with `counterpartyAddress`, `operationType`, `feeAmount`, `feeAmountExact`, `blockNumber`, `blockTimestamp`, `txHash`, and `logIndex` for each row.

Use this collection read when a dashboard or integration needs collection history without scanning token events itself. The endpoint returns an empty collection when the token has no attached transaction-fee feature.

***

## Dependencies [#dependencies]

* No external ERC-20 required: fee paid in the token itself.
* `supportsRewriting = true`: interacts with the amount-rewriting pipeline. Must run before analytics features.

***

## Compatibility & ordering notes [#compatibility--ordering-notes]

* **Must run before:** Historical Balances, Voting Power (analytics hooks must see post-fee amounts).
* **Compliance module interaction:** Compliance checks receive the post-rewrite amount. If any module enforces minimum amounts, ensure thresholds account for maximum fee rates.
* Compatible with AUM Fee (both collect in-token; order doesn't matter between them, but both before analytics).
* Compatible with External Transaction Fee (two separate fee mechanisms; External runs after).

***

## Change impact [#change-impact]

* **Enable after launch:** Only applies to transactions from activation point forward.
* **Disable:** No retroactive effect. In-flight transactions complete at old rate.
* **Rate change before freeze:** Effective immediately on next transaction.
* **Recipient change:** Effective immediately for all future collections.

***

## See also [#see-also]

* [Token Features Catalog](/docs/architecture/components/token-features): return to the full feature catalog
* [Transaction Fee Accounting](/docs/architecture/components/token-features/transaction-fee-accounting): off-chain tracking alternative
* [Compliance Modules](/docs/architecture/security/compliance): transfer-level enforcement layer