The mergeTokenAccounts() function consolidates multiple compressed accounts of the same mint into a single compressed account. The function

consumes multiple compressed token accounts (up to 8 accounts), and
creates a single output compressed token account with combined balance for the owner.

State trees where compressed account’s are stored, are append only. mergeTokenAccounts() reduces account fragmentation to simplify balance calculations from getCompressedTokenAccountsByOwner.

// Combines multiple compressed token accounts into single compressed account
const transactionSignature = await mergeTokenAccounts(
    rpc,
    payer,
    mint, // SPL mint with interface PDA for compression
    owner,
);

Get Started

Merge Compressed Accounts

Installation

npm
yarn
pnpm
SDK 2.0 (token-interface)

Install packages in your working directory:

npm install @lightprotocol/stateless.js@^0.23.0 \
            @lightprotocol/compressed-token@^0.23.0

Install the CLI globally:

npm install -g @lightprotocol/zk-compression-cli

Install packages in your working directory:

yarn add @lightprotocol/stateless.js@^0.23.0 \
         @lightprotocol/compressed-token@^0.23.0

Install the CLI globally:

yarn global add @lightprotocol/zk-compression-cli

Install packages in your working directory:

pnpm add @lightprotocol/stateless.js@^0.23.0 \
         @lightprotocol/compressed-token@^0.23.0

Install the CLI globally:

pnpm add -g @lightprotocol/zk-compression-cli

Install packages in your working directory:

# npm
npm install @lightprotocol/stateless.js@^0.23.0 \
            @lightprotocol/token-interface@^0.1.2

# yarn
yarn add @lightprotocol/stateless.js@^0.23.0 \
         @lightprotocol/token-interface@^0.1.2

# pnpm
pnpm add @lightprotocol/stateless.js@^0.23.0 \
         @lightprotocol/token-interface@^0.1.2

Install the CLI globally:

npm install -g @lightprotocol/zk-compression-cli

Localnet
Devnet

# start local test-validator in a separate terminal
light test-validator

In the code examples, use createRpc() without arguments for localnet.

Get an API key from Helius and add to .env:

.env

API_KEY=<your-helius-api-key>

In the code examples, use createRpc(RPC_URL) with the devnet URL.

import "dotenv/config";
import { Keypair } from "@solana/web3.js";
import { createRpc, bn } from "@lightprotocol/stateless.js";
import { createMint, mintTo, mergeTokenAccounts } from "@lightprotocol/compressed-token";
import { homedir } from "os";
import { readFileSync } from "fs";

// devnet:
const RPC_URL = `https://devnet.helius-rpc.com?api-key=${process.env.API_KEY!}`;
// localnet:
// const RPC_URL = undefined;
const payer = Keypair.fromSecretKey(
    new Uint8Array(
        JSON.parse(readFileSync(`${homedir()}/.config/solana/id.json`, "utf8"))
    )
);

(async function () {
    // devnet:
    const rpc = createRpc(RPC_URL);
    // localnet:
    // const rpc = createRpc();

    // Setup: Create mint and mint multiple times to create multiple accounts
    const { mint } = await createMint(rpc, payer, payer.publicKey, 9);
    const owner = Keypair.generate();
    await mintTo(rpc, payer, mint, owner.publicKey, payer, bn(100_000_000));
    await mintTo(rpc, payer, mint, owner.publicKey, payer, bn(200_000_000));
    await mintTo(rpc, payer, mint, owner.publicKey, payer, bn(300_000_000));

    // Merge all accounts for owner
    const tx = await mergeTokenAccounts(rpc, payer, mint, owner);

    console.log("Mint:", mint.toBase58());
    console.log("Tx:", tx);
})();

Before we merge compressed accounts, we need

Multiple compressed token accounts of the same mint owned by the same wallet, and
an SPL mint with a token pool for compression. This token pool can be created for new SPL mints via createMint() or added to existing SPL mints via createTokenPool().

Troubleshooting

No compressed token accounts found

The owner has no compressed token accounts for the specified mint:

// Check if accounts exist before merging
const accounts = await rpc.getCompressedTokenAccountsByOwner(
    owner.publicKey,
    { mint }
);

if (accounts.items.length === 0) {
    console.log("No compressed token accounts found for this mint");
    console.log("Mint address:", mint.toBase58());
    console.log("Owner address:", owner.publicKey.toBase58());
    return;
}

console.log(`Found ${accounts.items.length} accounts to merge`);

Advanced Configuration

Conditional Merging

// Get account count
const accounts = await rpc.getCompressedTokenAccountsByOwner(
    owner.publicKey,
    { mint }
);

// Only merge if more than 2 accounts
if (accounts.items.length > 2) {
    console.log(`Merging ${accounts.items.length} accounts...`);

    const mergeTx = await mergeTokenAccounts(
        rpc,
        payer,
        mint,
        tokenOwner,
    );

    console.log("Merge completed:", mergeTx);
} else {
    console.log("Merge not needed - optimal account structure");
}

Merge Multiple Mints

const mints = [
    new PublicKey("MINT_1_ADDRESS"),
    new PublicKey("MINT_2_ADDRESS"),
];

// Merge accounts for each mint
for (const mint of mints) {
    console.log(`Merging accounts for mint: ${mint.toBase58()}`);

    const mergeTx = await mergeTokenAccounts(
        rpc,
        payer,
        mint,
        tokenOwner,
    );

    console.log(`Merge completed: ${mergeTx}`);
}

Introduction

Compressed Tokens

Compressed PDA

Custom ZK Applications

Learn

Resources

Merge Compressed Token Accounts

Get Started

Merge Compressed Accounts

Troubleshooting

Advanced Configuration

Next Steps

How to Approve and Revoke Delegate Authority

​Get Started

​Merge Compressed Accounts

​Troubleshooting

​Advanced Configuration

​Next Steps

How to Approve and Revoke Delegate Authority

Get Started

Merge Compressed Accounts

Troubleshooting

Advanced Configuration

Next Steps