Transfer Fees

The Transfer Fee extension lets Token-2022 mints charge a fee on every transfer, withheld in token accounts until harvested to a fee collector. It enables on-chain revenue without custom transfer programs.

Recipe

spl-token create-token \
  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
  --decimals 6 \
  --transfer-fee-basis-points 100 \
  --transfer-fee-maximum-fee 1

--transfer-fee-maximum-fee is a UI amount, not raw base units - 1 caps the fee at one token, 1000000 would cap it at a million.

use anchor_spl::token_interface::{Mint, TokenAccount, TokenInterface};
// Use spl-token-2022 CPI helpers for harvest_withheld_tokens_to_mint.
// Transfers on a fee mint must use transfer_checked - Token-2022 rejects
// the unchecked Transfer instruction on mints carrying a transfer fee.

When to reach for this:

• Protocol revenue on secondary transfers
• Tokenized real-world assets with issuer fees
• Loyalty tokens with redistribution mechanics
• Replacing brittle off-chain fee tracking

Working Example

# Create mint with 1% fee (100 bps) and a 1-token fee cap.
# All spl-token amounts here are UI amounts, not raw base units.
MINT=$(spl-token create-token \
  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
  --decimals 6 \
  --transfer-fee-basis-points 100 \
  --transfer-fee-maximum-fee 1 | awk '/Creating token/{print $3}')
 
spl-token create-account "$MINT" --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
spl-token mint "$MINT" 10 --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
 
# Transfer 1 token (raw 1_000_000) - recipient receives less; fee withheld.
# The CLI issues TransferChecked, which is required on a fee mint.
spl-token transfer "$MINT" 1 <RECIPIENT> --fund-recipient \
  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
 
spl-token display <RECIPIENT_ATA> --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb

What this demonstrates:

• Fee computed in basis points (100 bps = 1%) capped by maximum_fee
• Withheld amount stays in recipient or sender account per config until harvest
• Wallets must show net amount, not gross transfer input

Deep Dive

How It Works

• Transfer fee config stored in mint extension (bps, max fee, transfer fee authority)
• On TransferChecked, the program moves the fee portion to a withheld bucket on the accounts. Token-2022 rejects the deprecated unchecked Transfer on a fee mint, because it cannot verify decimals for the fee math
• HarvestWithheldTokensToMint aggregates withheld fees to mint
• WithdrawWithheldTokensFromMint sends collected fees to collector ATA

Fee Math

TypeScript Notes

// When building transfers, fetch mint with extensions parsed
// Show: amount, estimated fee, net to recipient
// Include harvest instructions in treasury crank bots

Gotchas

• Users surprised by net receive - UX expects gross amount. Fix: display fee breakdown before sign.
• Withheld fees stuck in ATAs - no harvest crank. Fix: automate harvest_withheld in keeper bot.
• DEX incompatibility - routers may not pass extension accounts. Fix: verify Jupiter/Meteora Token-2022 support.
• Basis points overflow - max 10_000 bps (100%). Fix: validate at mint creation.
• Assuming the classic transfer instruction - spl_token::instruction::* builders call check_program_account and return IncorrectProgramId for the Token-2022 id, and Token-2022 rejects the unchecked Transfer on fee mints regardless. Fix: branch on mint owner, then use spl_token_2022::instruction::transfer_checked (or anchor_spl::token_interface, which dispatches over both programs).
• Treating CLI amounts as raw - --transfer-fee-maximum-fee and every mint/transfer amount are UI amounts. Fix: pass 1, not 1000000, for a one-token cap.

Alternatives

FAQs

Related

• Token-2022 Basics - program ID
• Transfer Hooks - custom transfer logic
• Token-2022 Best Practices - client checks

Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.