# external-transaction-fee API

Source: https://docs.settlemint.com/docs/api-reference/token-features/external-transaction-fee
API reference for creating and updating the external-transaction-fee token feature, which charges fixed fees in a separate ERC-20 token for asset 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 on the asset. API integrations use the feature configuration during token creation, then use 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]

The update routes are governance mutations on the token feature:

| Action               | 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. Freezing the configuration permanently locks the fee token, recipient, and 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 with 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.