Integration Guide for Wallet Applications

The Light-token API matches the SPL-token API almost entirely, and extends their functionality to include the light token program in addition to the SPL-token and Token-2022 programs.
Your users hold and receive tokens of the same mints, just stored more efficiently.

Creation Cost	Light Token	SPL-Token
Token Account	0.000017 SOL	0.0029 SOL

What you will implement

	SPL	Light
Receive	getOrCreateAssociatedTokenAccount()	createLoadAtaInstructions() / loadAta()
Transfer	createTransferInstruction()	createTransferInterfaceInstructions() / transferInterface()
Get Balance	getAccount()	getAtaInterface()
Tx History	getSignaturesForAddress()	rpc.getSignaturesForOwnerInterface()
Wrap from SPL	N/A	wrap() / createWrapInstruction()
Unwrap to SPL	N/A	createUnwrapInstructions() / unwrap()

Find full runnable code examples here.

Agent skill

Use the payments agent skill to add light-token payment support to your project:

npx skills add Lightprotocol/skills

For orchestration, install the general skill:

npx skills add https://zkcompression.com

Guide
AI Prompt

Setup

compressed-token
SDK 2.0 (token-interface)

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

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

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";

import {
  createLoadAtaInstructions,
  loadAta,
  createTransferInterfaceInstructions,
  transferInterface,
  createUnwrapInstructions,
  unwrap,
  getAssociatedTokenAddressInterface,
  getAtaInterface,
  wrap,
} from "@lightprotocol/compressed-token/unified";

const rpc = createRpc(RPC_ENDPOINT);

About loading: Light Token accounts reduce account rent ~200x by auto-compressing inactive accounts. Before any action, the SDK detects cold balances and adds instructions to load them. This almost always fits in a single atomic transaction with your regular transfer. APIs return TransactionInstruction[][] so the same loop handles the rare multi-transaction case automatically.

SDK 2.0 (@lightprotocol/token-interface) is the latest JavaScript SDK. It has better API ergonomics, guarantees single-instruction loading, and is compatible with KIT (the new Solana SDKs).

Receive Payments

Find a full code example here.

Load creates the associated token account (ATA) if needed and loads any compressed state into it. Share the ATA address with the sender.

Instruction
SDK 2.0 (token-interface)
Action

import { Transaction, sendAndConfirmTransaction } from "@solana/web3.js";
import {
  createLoadAtaInstructions,
  getAssociatedTokenAddressInterface,
} from "@lightprotocol/compressed-token/unified";

const ata = getAssociatedTokenAddressInterface(mint, recipient);

// Returns TransactionInstruction[][].
// Each inner array is one transaction.
// Almost always returns just one.
const instructions = await createLoadAtaInstructions(
  rpc,
  ata,
  recipient,
  mint,
  payer.publicKey
);

for (const ixs of instructions) {
  const tx = new Transaction().add(...ixs);
  await sendAndConfirmTransaction(rpc, tx, [payer]);
}

import { Keypair, Transaction, sendAndConfirmTransaction } from "@solana/web3.js";
import { createRpc } from "@lightprotocol/stateless.js";
import { createLoadInstructions } from "@lightprotocol/token-interface";

const rpc = createRpc();
const payer = Keypair.fromSecretKey(/* ... */);

const mint = /* existing mint public key */;
const owner = payer.publicKey;

const instructions = await createLoadInstructions({
  rpc,
  payer: payer.publicKey,
  owner,
  mint,
  authority: owner,
});

if (instructions.length > 0) {
  const tx = new Transaction().add(...instructions);
  const signature = await sendAndConfirmTransaction(rpc, tx, [payer]);
  console.log("Tx:", signature);
}

import {
  loadAta,
  getAssociatedTokenAddressInterface,
} from "@lightprotocol/compressed-token/unified";

const ata = getAssociatedTokenAddressInterface(mint, recipient);

const sig = await loadAta(rpc, ata, recipient, mint, payer);
if (sig) console.log("Loaded:", sig);

Compare to SPL

import {
  createAssociatedTokenAccountInstruction,
  getAssociatedTokenAddressSync,
  getOrCreateAssociatedTokenAccount,
} from "@solana/spl-token";

const ata = getAssociatedTokenAddressSync(mint, recipient);

// Instruction:
const tx = new Transaction().add(
  createAssociatedTokenAccountInstruction(payer.publicKey, ata, recipient, mint)
);

// Action:
const ata = await getOrCreateAssociatedTokenAccount(
  connection, payer, mint, recipient
);

Send Payments

Find a full code example: instruction | action.

Instruction
SDK 2.0 (token-interface)
Action

import { Transaction, sendAndConfirmTransaction } from "@solana/web3.js";
import { createTransferInterfaceInstructions } from "@lightprotocol/compressed-token/unified";

// Returns TransactionInstruction[][].
// Each inner array is one transaction.
// Almost always returns just one.
const instructions = await createTransferInterfaceInstructions(
  rpc,
  payer.publicKey,
  mint,
  amount,
  owner.publicKey,
  recipient
);

for (const ixs of instructions) {
  const tx = new Transaction().add(...ixs);
  await sendAndConfirmTransaction(rpc, tx, [payer, owner]);
}

Compare to SPL

import {
  getAssociatedTokenAddressSync,
  createAssociatedTokenAccountIdempotentInstruction,
  createTransferInstruction,
} from "@solana/spl-token";

const sourceAta = getAssociatedTokenAddressSync(mint, owner.publicKey);
const destinationAta = getAssociatedTokenAddressSync(mint, recipient);

const tx = new Transaction().add(
  createAssociatedTokenAccountIdempotentInstruction(
    payer.publicKey, destinationAta, recipient, mint
  ),
  createTransferInstruction(sourceAta, destinationAta, owner.publicKey, amount)
);

import { Keypair, Transaction, sendAndConfirmTransaction } from "@solana/web3.js";
import { createTransferInstructions } from "@lightprotocol/token-interface";
import { rpc, payer, setup } from "../setup.js";

(async function () {
  const { mint } = await setup();
  const recipient = Keypair.generate();

  const instructions = await createTransferInstructions({
    rpc,
    payer: payer.publicKey,
    mint,
    sourceOwner: payer.publicKey,
    authority: payer.publicKey,
    recipient: recipient.publicKey,
    amount: 100n,
  });

  const tx = new Transaction().add(...instructions);
  const sig = await sendAndConfirmTransaction(rpc, tx, [payer]);
  console.log("Tx:", sig);
})();

import {
  getAssociatedTokenAddressInterface,
  transferInterface,
} from "@lightprotocol/compressed-token/unified";

const sourceAta = getAssociatedTokenAddressInterface(mint, owner.publicKey);

// Handles loading, creates recipient ATA, transfers.
await transferInterface(
  rpc,
  payer,
  sourceAta,
  mint,
  recipient,
  owner.publicKey,
  owner,
  amount
);

Compare to SPL

import {
  getAssociatedTokenAddressSync,
  getOrCreateAssociatedTokenAccount,
  transfer,
} from "@solana/spl-token";

await getOrCreateAssociatedTokenAccount(connection, payer, mint, recipient);

const sourceAta = getAssociatedTokenAddressSync(mint, owner.publicKey);
const destinationAta = getAssociatedTokenAddressSync(mint, recipient);
await transfer(connection, payer, sourceAta, destinationAta, owner, amount);

Show Balance

Find a full code example here.

import {
  getAssociatedTokenAddressInterface,
  getAtaInterface,
} from "@lightprotocol/compressed-token/unified";

const ata = getAssociatedTokenAddressInterface(mint, owner);
const account = await getAtaInterface(rpc, ata, owner, mint);

console.log(account.parsed.amount);

Compare to SPL

import { getAccount } from "@solana/spl-token";

const account = await getAccount(connection, ata);

console.log(account.amount);

Transaction History

Find a full code example here.

const result = await rpc.getSignaturesForOwnerInterface(owner);

console.log(result.signatures); // Merged + deduplicated
console.log(result.solana); // On-chain txs only
console.log(result.compressed); // Compressed txs only

Use getSignaturesForAddressInterface(address) if you want address-specific rather than owner-wide history.

Compare to SPL

const signatures = await connection.getSignaturesForAddress(ata);

Wrap from SPL

Wrap tokens from SPL/Token-2022 accounts to light-token ATA.

Find a full code example here.

Instruction
SDK 2.0 (token-interface)
Action

import { Transaction } from "@solana/web3.js";
import { getAssociatedTokenAddressSync } from "@solana/spl-token";
import {
  createWrapInstruction,
  getAssociatedTokenAddressInterface,
} from "@lightprotocol/compressed-token/unified";
import { getSplInterfaceInfos } from "@lightprotocol/compressed-token";

const splAta = getAssociatedTokenAddressSync(mint, owner.publicKey);
const tokenAta = getAssociatedTokenAddressInterface(mint, owner.publicKey);

const splInterfaceInfos = await getSplInterfaceInfos(rpc, mint);
const splInterfaceInfo = splInterfaceInfos.find((i) => i.isInitialized);

const tx = new Transaction().add(
  createWrapInstruction(
    splAta,
    tokenAta,
    owner.publicKey,
    mint,
    amount,
    splInterfaceInfo,
    decimals,
    payer.publicKey
  )
);

import { ComputeBudgetProgram, Keypair, Transaction, sendAndConfirmTransaction } from "@solana/web3.js";
import { createRpc } from "@lightprotocol/stateless.js";
import {
  createAtaInstruction,
  createWrapInstruction,
  getAtaAddress,
  getSplInterfaces,
} from "@lightprotocol/token-interface";

const rpc = createRpc();
const payer = Keypair.fromSecretKey(/* ... */);

const mint = /* existing SPL/Token-2022 mint */;
const splAta = /* existing SPL ATA */;
const lightTokenAta = getAtaAddress({ mint, owner: payer.publicKey });

const createAtaIx = createAtaInstruction({
  payer: payer.publicKey,
  owner: payer.publicKey,
  mint,
});

const splInterfaces = await getSplInterfaces(rpc, mint);
const splInterface =
  splInterfaces.find((info) => info.isInitialized) ?? splInterfaces[0];
if (!splInterface) throw new Error("No SPL interface found");

const wrapIx = createWrapInstruction({
  source: splAta,
  destination: lightTokenAta,
  owner: payer.publicKey,
  mint,
  amount: 500n,
  splInterface,
  decimals: 9,
  payer: payer.publicKey,
});

const tx = new Transaction().add(
  ComputeBudgetProgram.setComputeUnitLimit({ units: 200_000 }),
  createAtaIx,
  wrapIx
);
const signature = await sendAndConfirmTransaction(rpc, tx, [payer]);
console.log("Tx:", signature);

import { getAssociatedTokenAddressSync } from "@solana/spl-token";
import {
  wrap,
  getAssociatedTokenAddressInterface,
} from "@lightprotocol/compressed-token/unified";

const splAta = getAssociatedTokenAddressSync(mint, owner.publicKey);
const tokenAta = getAssociatedTokenAddressInterface(mint, owner.publicKey);

await wrap(rpc, payer, splAta, tokenAta, owner, mint, amount);

Unwrap to SPL

Unwrap moves the token balance from a light-token account to a SPL-token account. Use this to compose with applications that do not yet support light-token.

Find a full code example here.

Instruction
SDK 2.0 (token-interface)
Action

import { Transaction } from "@solana/web3.js";
import { getAssociatedTokenAddressSync } from "@solana/spl-token";
import { createUnwrapInstructions } from "@lightprotocol/compressed-token/unified";

const splAta = getAssociatedTokenAddressSync(mint, owner.publicKey);

// Each inner array = one transaction. Handles loading + unwrapping together.
const instructions = await createUnwrapInstructions(
  rpc,
  splAta,
  owner.publicKey,
  mint,
  amount,
  payer.publicKey
);

for (const ixs of instructions) {
  const tx = new Transaction().add(...ixs);
  await sendAndConfirmTransaction(rpc, tx, [payer, owner]);
}

import { Keypair, Transaction, sendAndConfirmTransaction } from "@solana/web3.js";
import { createRpc } from "@lightprotocol/stateless.js";
import { createUnwrapInstruction, getSplInterfaces } from "@lightprotocol/token-interface";

const rpc = createRpc();
const payer = Keypair.fromSecretKey(/* ... */);

const mint = /* existing SPL/Token-2022 mint */;
const lightTokenAta = /* existing Light ATA */;
const splAta = /* destination SPL ATA */;

const splInterfaces = await getSplInterfaces(rpc, mint);
const splInterface =
  splInterfaces.find((info) => info.isInitialized) ?? splInterfaces[0];
if (!splInterface) throw new Error("No SPL interface found");

const unwrapIx = createUnwrapInstruction({
  source: lightTokenAta,
  destination: splAta,
  owner: payer.publicKey,
  mint,
  amount: 500n,
  splInterface,
  decimals: 9,
  payer: payer.publicKey,
});

const tx = new Transaction().add(unwrapIx);
const signature = await sendAndConfirmTransaction(rpc, tx, [payer]);
console.log("Tx:", signature);

import { getAssociatedTokenAddressSync } from "@solana/spl-token";
import { unwrap } from "@lightprotocol/compressed-token/unified";

const splAta = getAssociatedTokenAddressSync(mint, owner.publicKey);

await unwrap(rpc, payer, splAta, owner, mint, amount);

Add light-token support to a wallet application

Open in Cursor

---
description: Add light-token support to a wallet application
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, WebFetch, AskUserQuestion, Task, TaskCreate, TaskGet, TaskList, TaskUpdate, TaskOutput, mcp__deepwiki, mcp__zkcompression
---

## Add light-token support to a wallet application

Context:
- Guide: https://zkcompression.com/light-token/wallets/overview
- Skills and resources index: https://zkcompression.com/skill.md
- SPL to Light reference: https://zkcompression.com/api-reference/solana-to-light-comparison
- Dedicated skill: https://github.com/Lightprotocol/skills/tree/main/skills/payments
- Packages: @lightprotocol/compressed-token, @lightprotocol/stateless.js
- Full examples: https://github.com/Lightprotocol/examples-light-token/tree/main/toolkits/payments

SPL → Light Token API mapping:
| Operation    | SPL                               | Light Token                              |
| Receive      | getOrCreateAssociatedTokenAccount() | createLoadAtaInstructions() / loadAta()  |
| Transfer     | createTransferInstruction()        | createTransferInterfaceInstructions()    |
| Get Balance  | getAccount()                      | getAtaInterface()                        |
| Tx History   | getSignaturesForAddress()         | getSignaturesForOwnerInterface()         |
| Wrap SPL     | N/A                               | createWrapInstruction() / wrap()         |
| Unwrap       | N/A                               | createUnwrapInstructions() / unwrap()    |

### 1. Index project
- Grep `@solana/spl-token|@lightprotocol|createTransferInstruction|getAccount|wallet|signTransaction|signAllTransactions|Connection` across src/
- Glob `**/*.ts` and `**/*.tsx` for project structure
- Identify: RPC setup, existing token display/balance logic, wallet adapter, transaction signing pattern
- Check package.json for existing @lightprotocol/* or @solana/spl-token dependencies
- Task subagent (Grep/Read/WebFetch) if project has multiple packages to scan in parallel

### 2. Read references
- WebFetch the guide above — review Instruction and Action tabs for each operation
- 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 wallet integration, migrate existing SPL wallet to light-token, add light-token alongside existing SPL)
- AskUserQuestion: which operations? (receive, send, balance, history, wrap, unwrap — or all)
- AskUserQuestion: instruction-level API (build your own transactions) or action-level API (high-level, fewer lines)?
- 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 (createRpc with ZK Compression endpoint)
- Key pattern: import from `@lightprotocol/compressed-token/unified` for all interface APIs
- APIs return TransactionInstruction[][] — handle multi-tx case with signAllTransactions
- 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`
- Set up RPC: `createRpc(RPC_ENDPOINT)` with a ZK Compression endpoint (Helius, Triton)
- Import from `@lightprotocol/compressed-token/unified` for the interface APIs
- Follow the guide and the approved plan
- 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
- 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

Introduction

Light Token APIs

PDA Accounts

For Other Use Cases

Learn

Resources

Integration Guide for Wallet Applications

What you will implement

Setup

Receive Payments

Send Payments

Show Balance

Transaction History

Wrap from SPL

Unwrap to SPL

More wallet guides

Sign with Privy

Sign with Wallet Adapter

Gasless Transactions

Didn’t find what you were looking for?

Introduction

Light Token APIs

PDA Accounts

For Other Use Cases

Learn

Resources

Documentation Index

​What you will implement

​Setup

​Receive Payments

​Send Payments

​Show Balance

​Transaction History

​Wrap from SPL

​Unwrap to SPL

​More wallet guides

Sign with Privy

Sign with Wallet Adapter

Gasless Transactions

​Didn’t find what you were looking for?

What you will implement

Setup

Receive Payments

Send Payments

Show Balance

Transaction History

Wrap from SPL

Unwrap to SPL

More wallet guides

Didn’t find what you were looking for?