# Transaction fee API

Source: https://docs.settlemint.com/docs/api-reference/token-features/transaction-fee
Update rates, change the fee recipient, freeze future rate changes, and read collection history for tokens with the transaction-fee feature attached.



The `transaction-fee` feature routes let you manage the full lifecycle of on-chain fee collection after a token is deployed. Use this reference when you need to adjust fee parameters, transfer the recipient wallet, permanently lock rates, or audit what the chain has collected to date.

For how fees are calculated and what invariants apply, see [Transaction Fee architecture](/docs/architects/components/token-features/transaction-fee). For operator steps in the Console, see [configure and operate transaction fee](/docs/operators/token-features/transaction-fee).

`transaction-fee` is mutually exclusive with [`transaction-fee-accounting`](/docs/api-reference/token-features/transaction-fee-accounting). Use `transaction-fee` when the asset deducts the fee on chain in its own units.

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

```json
{
  "transaction-fee": {
    "mintFeeBps": 100,
    "burnFeeBps": 100,
    "transferFeeBps": 50,
    "recipient": "0x..."
  }
}
```

| Parameter        | Type             | Required | Description                                                    |
| ---------------- | ---------------- | -------- | -------------------------------------------------------------- |
| `mintFeeBps`     | Integer          | Yes      | Mint fee in basis points. Zero suppresses mint-fee collection. |
| `burnFeeBps`     | Integer          | Yes      | Burn fee in basis points.                                      |
| `transferFeeBps` | Integer          | Yes      | Holder-initiated transfer fee in basis points.                 |
| `recipient`      | Ethereum address | Yes      | Wallet that receives collected fees in the asset's own units.  |

## Behaviour [#behaviour]

The platform deducts the fee from the operation amount before crediting the holder. A 100-unit mint with `mintFeeBps: 100` credits 99 units to the holder and 1 unit to `recipient`.

## Updating parameters [#updating-parameters]

All transaction-fee mutations execute through the transaction queue. You need the token permission for the operation, a verified wallet, and the `transaction-fee` feature attached to the target token.

### Set fee rates [#set-fee-rates]

Send all three rate fields together. Any field omitted from the body resets that rate to zero.

```http
PATCH /api/v2/tokens/{tokenAddress}/features/transaction-fee/rates
```

```json
{
  "mintFeeBps": 100,
  "burnFeeBps": 100,
  "transferFeeBps": 25
}
```

### Set fee recipient [#set-fee-recipient]

Update the wallet that receives collected fees. Supply the new address in `feeRecipient`.

```http
PATCH /api/v2/tokens/{tokenAddress}/features/transaction-fee/recipient
```

```json
{
  "feeRecipient": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
}
```

### Freeze fee rates [#freeze-fee-rates]

Permanently lock rate changes so no subsequent call can alter them.

```http
POST /api/v2/tokens/{tokenAddress}/features/transaction-fee/rate-freezes
```

This route has no fee-specific body fields beyond the address path parameter. User-authenticated requests still include the wallet verification body that all mutations require. Once the freeze succeeds, any later rate update fails with the token fee rates frozen error.

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

```http
GET /api/v2/tokens/{tokenAddress}/transaction-fee/collections
```

This endpoint returns paginated transaction-fee rows. Use it for dashboards, reconciliation jobs, and audit exports instead of scanning token events directly.

## Response model [#response-model]

Each write operation returns the standard queued blockchain response for the token. The body includes the status link for the queued transaction-fee operation.

## Related [#related]

* [Transaction Fee architecture](/docs/architects/components/token-features/transaction-fee): the calculation model and invariants.
* [Configure and operate transaction fee](/docs/operators/token-features/transaction-fee): Console operator steps.
* [transaction-fee-accounting](/docs/api-reference/token-features/transaction-fee-accounting): the mutually exclusive off-chain variant.
* [Feature constraints](/docs/architects/components/token-features/feature-constraints#mutually-exclusive-rules)