# External transaction fee API

Source: https://docs.settlemint.com/docs/api-reference/token-features/external-transaction-fee
Endpoint reference for the external-transaction-fee feature, covering creation-time parameters and the mutation routes for updating fee amounts, recipient, fee token, and freeze state.



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 on the asset. When you create the token, supply the feature configuration; afterward, use the feature-specific mutation routes to update amounts, recipient, fee token, or the permanent freeze state.

For the operator how-to, see [External transaction fee how-to](/docs/operators/token-features/external-transaction-fee). For the architecture model, see [External transaction fee architecture](/docs/architects/components/token-features/external-transaction-fee).

## Configuration during token creation [#configuration-during-token-creation]

```json
{
  "external-transaction-fee": {
    "feeToken": "0x...",
    "mintFee": "1000000",
    "burnFee": "1000000",
    "transferFee": "500000",
    "recipient": "0x..."
  }
}
```

| Parameter     | Type                | Required | Description                                                                                                   |
| ------------- | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `feeToken`    | Ethereum address    | Yes      | ERC-20 token used for fee payment. Must exist or be registered as an external token.                          |
| `mintFee`     | Asset amount string | No       | Fixed mint fee in `feeToken` base units. Omit or set to zero when minting should not collect an external fee. |
| `burnFee`     | Asset amount string | No       | Fixed burn fee in `feeToken` base units.                                                                      |
| `transferFee` | Asset amount string | No       | Fixed holder-initiated transfer fee in `feeToken` base units.                                                 |
| `recipient`   | Ethereum address    | No       | Wallet that receives collected fees in `feeToken`. When omitted, DALP uses the deployer as the recipient.     |

The API accepts base-unit amounts for the configured fee token. If the fee token has six decimals, a value of `1000000` represents one whole fee-token unit.

## Allowance requirement [#allowance-requirement]

Holders must approve the external-transaction-fee feature contract to spend `feeToken` before they can transact under this asset. Operations fail with insufficient allowance when the holder has not granted that feature contract permission to spend the fee token. Document the allowance requirement clearly in your integration onboarding.

## Reading collected fees [#reading-collected-fees]

Read token details through the token API and inspect the feature entry for the configured fee token, per-operation amounts, recipient, freeze state, and aggregate collected `feeToken` balance.

## Updating parameters [#updating-parameters]

Each route below is a governance mutation on the token feature. Mutation responses follow the standard asynchronous blockchain mutation envelope.

| Operation            | Method and path                                                                     | Body fields                         |
| -------------------- | ----------------------------------------------------------------------------------- | ----------------------------------- |
| Update fee amounts   | `PATCH /api/v2/tokens/{tokenAddress}/features/external-transaction-fee/amounts`     | `mintFee`, `burnFee`, `transferFee` |
| Update recipient     | `PATCH /api/v2/tokens/{tokenAddress}/features/external-transaction-fee/recipient`   | `feeRecipient`                      |
| Update fee token     | `PATCH /api/v2/tokens/{tokenAddress}/features/external-transaction-fee/token`       | `feeToken`                          |
| Freeze configuration | `POST /api/v2/tokens/{tokenAddress}/features/external-transaction-fee/rate-freezes` | No feature-specific body fields     |

Changing `feeToken` mid-life requires fresh allowance grants from every holder. The new fee token contract has no prior approvals from existing holders. Freezing the configuration permanently locks the fee token address, the configured recipient, and all fee amounts.

## Collection events [#collection-events]

```http
GET /api/v2/tokens/{tokenAddress}/external-transaction-fee/collection-events
```

The collection-events route returns indexed external fee collections. Results support pagination, filtering, sorting, and facets. Each row includes the payer, fee token, fee amount, operation type, block metadata, transaction hash, and log index.

## Related [#related]

* [transaction-fee](/docs/api-reference/token-features/transaction-fee): percentage-based same-asset fee variant.
* [External tokens](/docs/api-reference/external-tokens/external-tokens) for registering fee tokens.