Transfer fees

Configure the TransferFeeConfig extension for automatic fee collection on every token transfer using Light Token.

Key Concepts

The TransferFeeExtension enables automatic fee collection on every token transfer. Fees accumulate in the recipient token accounts and can be withdrawn by the withdraw authority set on the mint account.

Transfer fees are configured with four parameters:

Parameter	Description
transferFeeBasisPoints	Fee percentage in basis points (100 = 1%). Must be zero for Light Token.
maximumFee	Upper limit on the fee charged per transfer, in token base units. Must be zero for Light Token.
transferFeeConfigAuthority	Authority that can modify fee settings.
withdrawWithheldAuthority	Authority that can collect accumulated fees from recipient accounts.

Use TransferFeeConfig With Light Token

Agent skill

Install the agent skill:

npx skills add https://zkcompression.com

See the AI tools guide for dedicated skills.

Guide

Setup

npm install @lightprotocol/compressed-token@beta \
            @lightprotocol/stateless.js@beta \
            @solana/spl-token

Snippets below assume rpc, payer, mint, owner, recipient, and amount are defined. See the full examples for runnable setup.

import { createRpc } from "@lightprotocol/stateless.js";

const rpc = createRpc(RPC_ENDPOINT);

Create a Token-2022 Mint With Transfer Fees

Instruction

import {
    Keypair,
    SystemProgram,
    Transaction,
    sendAndConfirmTransaction,
} from "@solana/web3.js";
import { createRpc } from "@lightprotocol/stateless.js";
import { LightTokenProgram } from "@lightprotocol/compressed-token";
import {
    TOKEN_2022_PROGRAM_ID,
    getMintLen,
    createInitializeMint2Instruction,
    ExtensionType,
    createInitializeTransferFeeConfigInstruction,
} from "@solana/spl-token";

const rpc = createRpc(RPC_ENDPOINT);

const mintKeypair = Keypair.generate();
const decimals = 9;

// Calculate space for mint + TransferFeeConfig extension
const mintLen = getMintLen([ExtensionType.TransferFeeConfig]);
const rentExemptBalance =
    await rpc.getMinimumBalanceForRentExemption(mintLen);

// Create account
const createAccountIx = SystemProgram.createAccount({
    fromPubkey: payer.publicKey,
    lamports: rentExemptBalance,
    newAccountPubkey: mintKeypair.publicKey,
    programId: TOKEN_2022_PROGRAM_ID,
    space: mintLen,
});

// Initialize TransferFeeConfig with zero fees
const initTransferFeeIx = createInitializeTransferFeeConfigInstruction(
    mintKeypair.publicKey,
    payer.publicKey, // transfer fee config authority
    payer.publicKey, // withdraw withheld authority
    0,               // fee basis points (must be zero)
    BigInt(0),       // maximum fee (must be zero)
    TOKEN_2022_PROGRAM_ID
);

// Initialize mint
const initMintIx = createInitializeMint2Instruction(
    mintKeypair.publicKey,
    decimals,
    payer.publicKey,
    null,
    TOKEN_2022_PROGRAM_ID
);

// Register interface PDA with Light Token
const createSplInterfaceIx = await LightTokenProgram.createSplInterface({
    feePayer: payer.publicKey,
    mint: mintKeypair.publicKey,
    tokenProgramId: TOKEN_2022_PROGRAM_ID,
});

const tx = new Transaction().add(
    createAccountIx,
    initTransferFeeIx,
    initMintIx,
    createSplInterfaceIx
);

const signature = await sendAndConfirmTransaction(rpc, tx, [
    payer,
    mintKeypair,
]);

Action

import "dotenv/config";
import {
    Keypair,
    SystemProgram,
    Transaction,
    sendAndConfirmTransaction,
} from "@solana/web3.js";
import { createRpc } from "@lightprotocol/stateless.js";
import { LightTokenProgram } from "@lightprotocol/compressed-token";
import {
    TOKEN_2022_PROGRAM_ID,
    getMintLen,
    createInitializeMint2Instruction,
    ExtensionType,
    createInitializeTransferFeeConfigInstruction,
} from "@solana/spl-token";
import { homedir } from "os";
import { readFileSync } from "fs";

// devnet:
// const RPC_URL = `https://devnet.helius-rpc.com?api-key=${process.env.API_KEY!}`;
// const rpc = createRpc(RPC_URL);
// localnet:
const rpc = createRpc();

const payer = Keypair.fromSecretKey(
    new Uint8Array(
        JSON.parse(readFileSync(`${homedir()}/.config/solana/id.json`, "utf8"))
    )
);

(async function () {
    const mintKeypair = Keypair.generate();
    const decimals = 9;

    // Calculate space for mint + TransferFeeConfig extension
    const mintLen = getMintLen([ExtensionType.TransferFeeConfig]);
    const rentExemptBalance =
        await rpc.getMinimumBalanceForRentExemption(mintLen);

    // Instruction 1: Create account
    const createAccountIx = SystemProgram.createAccount({
        fromPubkey: payer.publicKey,
        lamports: rentExemptBalance,
        newAccountPubkey: mintKeypair.publicKey,
        programId: TOKEN_2022_PROGRAM_ID,
        space: mintLen,
    });

    // Instruction 2: Initialize TransferFeeConfig with zero fees
    // Light Token requires fees to be zero
    const initTransferFeeIx = createInitializeTransferFeeConfigInstruction(
        mintKeypair.publicKey,
        payer.publicKey, // transfer fee config authority
        payer.publicKey, // withdraw withheld authority
        0,               // fee basis points (must be zero)
        BigInt(0),       // maximum fee (must be zero)
        TOKEN_2022_PROGRAM_ID
    );

    // Instruction 3: Initialize mint
    const initMintIx = createInitializeMint2Instruction(
        mintKeypair.publicKey,
        decimals,
        payer.publicKey, // mint authority
        null, // freeze authority
        TOKEN_2022_PROGRAM_ID
    );

    // Instruction 4: Create SPL interface PDA
    // Holds Token-2022 tokens when wrapped to light-token
    const createSplInterfaceIx = await LightTokenProgram.createSplInterface({
        feePayer: payer.publicKey,
        mint: mintKeypair.publicKey,
        tokenProgramId: TOKEN_2022_PROGRAM_ID,
    });

    const tx = new Transaction().add(
        createAccountIx,
        initTransferFeeIx,
        initMintIx,
        createSplInterfaceIx
    );

    const signature = await sendAndConfirmTransaction(rpc, tx, [
        payer,
        mintKeypair,
    ]);

    console.log("Mint:", mintKeypair.publicKey.toBase58());
    console.log("Tx:", signature);
})();

createMintInterface creates a basic Token 2022 mint with an interface PDA. To include the TransferFeeConfig extension, use the instruction approach shown in the other tab.

Create Interface PDA for Existing Mint

If you already have a Token-2022 mint with a zero-fee TransferFeeConfig, create an interface PDA with Light Token.

import { LightTokenProgram } from "@lightprotocol/compressed-token";
import { TOKEN_2022_PROGRAM_ID } from "@solana/spl-token";

const createSplInterfaceIx = await LightTokenProgram.createSplInterface({
    feePayer: payer.publicKey,
    mint: mintKeypair.publicKey,
    tokenProgramId: TOKEN_2022_PROGRAM_ID,
});

AI Prompt

Create a Token-2022 mint with TransferFeeConfig and register with Light Token

CopiedCopy promptOpen in Cursor

---
description: Create a Token-2022 mint with TransferFeeConfig and register with Light Token
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, WebFetch, AskUserQuestion, Task, TaskCreate, TaskGet, TaskList, TaskUpdate, TaskOutput, mcp__deepwiki, mcp__zkcompression
---

## Create a Token-2022 mint with TransferFeeConfig and register with Light Token

Context:
- Guide: https://zkcompression.com/light-token/extensions/transfer-fees
- Skills and resources index: https://zkcompression.com/skill.md
- SPL to Light reference: https://zkcompression.com/api-reference/solana-to-light-comparison
- Packages: @lightprotocol/compressed-token, @lightprotocol/stateless.js, @solana/spl-token
- Constraint: fees MUST be zero (0 basis points, 0 maximum fee)

SPL equivalent: createInitializeTransferFeeConfigInstruction() + createMint()
Light Token: createInitializeTransferFeeConfigInstruction() + LightTokenProgram.createSplInterface()

### 1. Index project
- Grep `@solana/spl-token|Connection|Keypair|TransferFee|TOKEN_2022` across src/
- Glob `**/*.ts` for project structure
- Identify: RPC setup, existing mint logic, entry point for T22 mint with transfer fee extension
- Task subagent (Grep/Read/WebFetch) if project has multiple packages to scan in parallel

### 2. Read references
- WebFetch the guide above — follow the Instruction tab for the full flow
- WebFetch skill.md — check for a dedicated skill and resources matching this task
- TaskCreate one todo per phase below to track progress

### 3. Clarify intention
- AskUserQuestion: what is the goal? (new T22 mint with transfer fees, register existing T22 mint, migrate existing SPL code)
- AskUserQuestion: does the project already use Token-2022?
- Summarize findings and wait for user confirmation before implementing

### 4. Create plan
- Based on steps 1–3, draft an implementation plan: which files to modify, what code to add, dependency changes
- Verify existing connection/signer setup is compatible with the cookbook prerequisites
- Ensure fees are zero (0 basis points, BigInt(0) max fee) — non-zero fees cause Light Token registration to fail
- If anything is unclear or ambiguous, loop back to step 3 (AskUserQuestion)
- Present the plan to the user for approval before proceeding

### 5. Implement
- Add deps if missing: Bash `npm install @lightprotocol/compressed-token @lightprotocol/stateless.js @solana/spl-token`
- Create T22 mint: getMintLen([ExtensionType.TransferFeeConfig]) → SystemProgram.createAccount → createInitializeTransferFeeConfigInstruction (zero fees) → createInitializeMint2Instruction
- Register with Light Token: LightTokenProgram.createSplInterface({ mint, tokenProgramId: TOKEN_2022_PROGRAM_ID })
- Transfer: createTransferInterfaceInstructions() from @lightprotocol/compressed-token/unified
- Write/Edit to create or modify files
- TaskUpdate to mark each step done

### 6. Verify
- Bash `tsc --noEmit`
- Bash run existing test suite if present
- Confirm fees are zero in initialization code
- TaskUpdate to mark complete

### Tools
- mcp__zkcompression__SearchLightProtocol("<query>") for API details
- mcp__deepwiki__ask_question("Lightprotocol/light-protocol", "<q>") for architecture
- Task subagent with Grep/Read/WebFetch for parallel lookups
- TaskList to check remaining work

Related Guides

Transfer interface

Wrap and unwrap

---

Didn’t find what you were looking for?

Reach out! Telegram | email | Discord