external-transaction-fee API

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. For the architecture model, see External transaction fee architecture.

Configuration during token creation

{
  "external-transaction-fee": {
    "feeToken": "0x...",
    "mintFee": "1000000",
    "burnFee": "1000000",
    "transferFee": "500000",
    "recipient": "0x..."
  }
}

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

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

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

The update routes are governance mutations on the token feature:

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

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

• transaction-fee — percentage-based same-asset fee variant.
• External tokens for registering fee tokens.