# Transaction fee accounting API reference

Source: https://docs.settlemint.com/docs/api-reference/token-features/transaction-fee-accounting
Reference for the transaction-fee-accounting API routes that configure rates, recipients, reconciliation, exemptions, and accrual reads.



This reference lists the public API surfaces for the `transaction-fee-accounting` token feature. Use it when you need route paths, request configuration, and read-model endpoints.

For the product model, controls, and event semantics, read the [canonical architecture explanation](/docs/architects/components/token-features/transaction-fee-accounting). For operating steps, read the [operator how-to](/docs/operators/token-features/transaction-fee-accounting).

The feature is mutually exclusive with [`transaction-fee`](/docs/api-reference/token-features/transaction-fee). Choose `transaction-fee-accounting` when settlement happens off chain and DALP is the accrual evidence source.

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

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

| Parameter        | Type             | Required | Description                                                                       |
| ---------------- | ---------------- | -------- | --------------------------------------------------------------------------------- |
| `mintFeeBps`     | Integer          | Yes      | Recorded mint-fee accrual rate.                                                   |
| `burnFeeBps`     | Integer          | Yes      | Recorded burn-fee accrual rate.                                                   |
| `transferFeeBps` | Integer          | Yes      | Recorded transfer-fee accrual rate.                                               |
| `recipient`      | Ethereum address | Yes      | Recipient identity recorded on accrual entries. Not transferred to automatically. |

## Reading accrual and reconciliation state [#reading-accrual-and-reconciliation-state]

```text
GET /api/v2/tokens/{tokenAddress}/transaction-fee-accounting/accrual-events
GET /api/v2/tokens/{tokenAddress}/transaction-fee-accounting/payers/{payer}
GET /api/v2/tokens/{tokenAddress}/transaction-fee-accounting/reconciliations
GET /api/v2/tokens/{tokenAddress}/transaction-fee-accounting/exemptions
```

| Endpoint          | What it returns                                                                                                                                                                                                                                                    | Default order                       |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- |
| `accrual-events`  | `FeeAccrued` rows with payer, from address, to address, operation type, operation amount, fee bps, fee amount, block number, and accrual timestamp. The list supports JSON:API pagination, sorting, filtering, and operation-count facets.                         | Collection sort from the API query. |
| `payers/{payer}`  | Accrued-fee totals, a per-operation-type breakdown, and the most recent accrual events for one payer.                                                                                                                                                              | Most recent payer events first.     |
| `reconciliations` | `FeesReconciled` rows with period end, caller, recipient, reconciled amount, block number, block timestamp, transaction hash, and log index. The list supports JSON:API pagination, sorting, and filtering by period, caller, recipient, amount, and block number. | Newest period end first.            |
| `exemptions`      | Current exemption state for each account, including the account address, exemption flag, last updated time, and last updated block. The list supports JSON:API pagination, sorting, and filtering by account, exemption state, update time, and update block.      | Newest update first.                |

Use the accrual-event and payer endpoints to explain fees owed. Use reconciliation history to prove which periods have already been settled. Use the exemption list to show which accounts are excluded from fee accrual at the current indexed state.

## Updating feature settings [#updating-feature-settings]

```text
PATCH /api/v2/tokens/{tokenAddress}/features/transaction-fee-accounting/rates
PATCH /api/v2/tokens/{tokenAddress}/features/transaction-fee-accounting/recipient
POST /api/v2/tokens/{tokenAddress}/features/transaction-fee-accounting/rate-freezes
POST /api/v2/tokens/{tokenAddress}/features/transaction-fee-accounting/reconciliations
PUT /api/v2/tokens/{tokenAddress}/features/transaction-fee-accounting/exemptions
```

These mutation routes update rates, recipient settings, rate freezes, reconciliations, and account exemptions. They require a token with the `transaction-fee-accounting` feature attached.

## Related [#related]

* [Transaction fee accounting architecture](/docs/architects/components/token-features/transaction-fee-accounting): canonical product model, controls, risks, and events.
* [Transaction fee accounting operator how-to](/docs/operators/token-features/transaction-fee-accounting): operating guidance for configuring and reconciling accruals.
* [transaction-fee API reference](/docs/api-reference/token-features/transaction-fee): on-chain collection variant.
* [Feature constraints](/docs/architects/components/token-features/feature-constraints#mutually-exclusive-rules)