Transaction fee accounting API reference
Configure rates, manage recipients, submit reconciliations, manage exemptions, and read accrual state for tokens with the transaction-fee-accounting feature.
These routes drive the off-chain settlement cycle for tokens with transaction-fee-accounting attached. Use them to adjust rates and recipients as fund terms change, submit periodic reconciliations to mark accrual periods closed, and query accrual entries or exemptions for reporting and audit evidence. For the product model and event semantics, see the architecture page. For operating steps, see the operator how-to.
transaction-fee-accounting is mutually exclusive with transaction-fee. Use transaction-fee-accounting when settlement happens off chain and DALP records the accrual data.
Configuration during token creation
{
"transaction-fee-accounting": {
"mintFeeBps": 50,
"burnFeeBps": 50,
"transferFeeBps": 25,
"recipient": "0x..."
}
}| Parameter | Type | Required | Description |
|---|---|---|---|
mintFeeBps | Integer | Yes | Mint-fee accrual rate, in basis points. |
burnFeeBps | Integer | Yes | Burn-fee accrual rate, in basis points. |
transferFeeBps | Integer | Yes | Transfer-fee accrual rate, in basis points. |
recipient | Ethereum address | Yes | Address stored on each accrual entry. The platform does not transfer automatically. |
Reading accrual and reconciliation state
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 with sorting and filtering, plus 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 with sorting; you can filter by period, caller, recipient, amount, or block. | 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 with sorting; you can filter by account, exemption state, update time, or update block. | Newest update first. |
Query the accrual-event and payer endpoints to explain fees owed. Check the reconciliation history to confirm which periods the platform has already settled. Review the exemption list to identify which accounts the platform excludes from fee accrual at the current indexed state.
Updating feature settings
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/exemptionsThese routes cover rate changes, fee-recipient updates, rate freezes, reconciliation submissions, and account exemptions. The target token must have transaction-fee-accounting attached.
Related
- Transaction fee accounting architecture: the product model, control points, and emitted events.
- Transaction fee accounting operator how-to: how to configure rates and reconcile accruals in the Console.
- transaction-fee: the on-chain collection variant.
- Feature constraints
Transaction fee API
Update rates, change the fee recipient, freeze future rate changes, and read collection history for tokens with the transaction-fee feature attached.
External transaction fee API
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.