External transaction fee
How operators configure the external-transaction-fee token feature to charge fixed fees in a separate ERC-20 asset for mint, burn, and transfer operations.
The external-transaction-fee token feature charges a fixed fee in a separate ERC-20 token (the fee token) for each mint, burn, or transfer operation. Unlike transaction-fee, which deducts a percentage from the operation amount in the operated asset, external-transaction-fee transfers a fixed amount in a different asset altogether.
Use external-transaction-fee for securitised-pool fee accrual, fund-of-fund operating fees paid in a stable denomination, or any model where the fee should not reduce the operated asset's balance.
For the architecture reference, see External transaction fee.
When it attaches
The asset-backed-token template (system-asset-backed-token) attaches external-transaction-fee. Custom templates may also use it.
What you configure
In the Asset Designer details step, the wizard surfaces:
| Parameter | Description |
|---|---|
feeToken | ERC-20 asset the fee is paid in. Must exist in the tenant or be registered as an external token. |
mintFee | Fixed fee on mint operations, in the fee token's base units. |
burnFee | Fixed fee on burn operations. |
transferFee | Fixed fee on holder-initiated transfers. |
recipient | Wallet that receives the collected fee-token balance. If omitted during token creation, DALP uses the deployer. |
The fee-token prerequisite is checked during template selection: if no compatible ERC-20 exists in the tenant, the template card is disabled until the operator creates or registers one.
What you operate
After deployment:
- Operations require fee-token allowance from the holder to the external-transaction-fee feature contract. Holders must approve that fee-token spending before they can transact under this asset, similar to standard ERC-20 fee-payment flows.
- Fees collect automatically as operations happen. The recipient wallet accrues fee-token balance directly.
- Inspect collected fees on the asset detail workspace's external-transaction-fee tab, or through
GET /api/v2/tokens/{tokenAddress}/external-transaction-fee/collection-eventswhen you need the indexed collection history for reconciliation.
Operating considerations
- The fee is in a different asset. Operators monitor the recipient's fee-token balance separately from the asset's own balance views.
- Operations fail if the holder lacks sufficient fee-token balance or allowance. Communicate the fee-token requirement clearly during holder onboarding.
- Fee amounts, recipient, fee token, and freeze state are updated through governance-controlled feature routes:
PATCH /api/v2/tokens/{tokenAddress}/features/external-transaction-fee/amounts,PATCH /api/v2/tokens/{tokenAddress}/features/external-transaction-fee/recipient,PATCH /api/v2/tokens/{tokenAddress}/features/external-transaction-fee/token, andPOST /api/v2/tokens/{tokenAddress}/features/external-transaction-fee/rate-freezes. Updates apply forward. - Changing the fee token mid-life is rare and requires careful migration; restricted-mutable updates apply forward, but holders need to grant allowance in the new token before they can transact.
Troubleshooting
| What you see | What to check |
|---|---|
| Transfer fails with "insufficient fee-token allowance" | The holder must approve the external-transaction-fee feature contract to spend the fee token. Communicate this before transfer. |
| Holder has fee-token balance but transfer fails | Confirm the allowance amount covers the configured fee for the operation. Allowance can be insufficient even when balance is sufficient. |
| Need percentage-based fee in the same asset | Use transaction-fee instead. |
Read next
- External transaction fee architecture
- Transaction fee for percentage-based fees in the same asset.
- System templates catalog
Transaction fee accounting how-to
How operators configure the transaction-fee-accounting token feature for off-chain settlement of mint, burn, and transfer fees.
Conversion
How operators configure the conversion token feature for convertible instruments that exchange holdings into a target equity or settlement token.