# Transaction fee API

Source: https://docs.settlemint.com/docs/api-reference/token-features/transaction-fee
API reference for configuring transaction-fee rates, recipient updates, rate freezes, and collection reads through DALP token-feature routes.



After a token has the `transaction-fee` feature attached, API callers can update rates, change the fee recipient, freeze future rate changes, and read collection history through token feature routes.

For the fee calculation model and feature invariants, 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 should deduct the fee on chain in the asset's 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. The caller needs the token permission for the action, wallet verification, and an attached `transaction-fee` feature on the target token.

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

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

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

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

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

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

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

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

The freeze route has no transaction-fee-specific body fields beyond the token address path parameter. User-authenticated requests still include the wallet verification body required by token mutations. After the freeze succeeds, later rate updates fail with the token fee rates frozen error.

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

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

The collection read 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 mutation returns the standard queued blockchain mutation response for the token. The response includes the queued transaction status link for the submitted transaction-fee operation.

## Related [#related]

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