Skip to main content

Documentation Index

Fetch the complete documentation index at: https://luminouslabs-cc5545c6-bump-sdks.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

  1. 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.
  2. Your users use the same stablecoins, just stored more efficiently.
Creation CostSPLlight-token
Token Account~2,000,000 lamports~11,000 lamports

​
What you will implement

SPLLight
ReceivegetOrCreateAssociatedTokenAccount()createLoadAtaInstructions()
TransfercreateTransferInstruction()createTransferInterfaceInstructions()
Get BalancegetAccount()getAtaInterface()
Tx HistorygetSignaturesForAddress()rpc.getSignaturesForOwnerInterface()
Wrap from SPLN/AcreateWrapInstruction()
Unwrap to SPLN/AcreateUnwrapInstructions() / unwrap()
Find full runnable code examples here.
Use the payments-and-wallets agent skill to add light-token payment support to your project:
Add the marketplace and install:
/plugin marketplace add Lightprotocol/skills
/plugin install solana-rent-free-dev
For orchestration, install the general skill:
npx skills add https://zkcompression.com

​
Setup

npm install @lightprotocol/compressed-token@beta \
            @lightprotocol/stateless.js@beta
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);

​
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.
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.
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 {
  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.
import { Transaction, sendAndConfirmTransaction } from "@solana/web3.js";
import {
  createTransferInterfaceInstructions,
  getOrCreateAtaInterface,
  getAssociatedTokenAddressInterface,
} from "@lightprotocol/compressed-token/unified";

await getOrCreateAtaInterface(rpc, payer, mint, recipient);
const destination = getAssociatedTokenAddressInterface(mint, recipient);

const instructions = await createTransferInterfaceInstructions(
  rpc,
  payer.publicKey,
  mint,
  amount,
  owner.publicKey,
  destination
);

for (const ixs of instructions) {
  const tx = new Transaction().add(...ixs);
  await sendAndConfirmTransaction(rpc, tx, [payer, owner]);
}
Your app logic may require you to create a single sign request for your user. Here’s how to do this:
const transactions = instructions.map((ixs) => new Transaction().add(...ixs));

// One approval for all
const signed = await wallet.signAllTransactions(transactions);

for (const tx of signed) {
  // send...
  await sendAndConfirmTransaction(rpc, tx);
}
While almost always you will have only one transfer transaction, you can optimize sending in the rare cases where you have multiple transactions. parallelize the loads, confirm them, and then send the transfer instruction after.
import {
  createTransferInterfaceInstructions,
  getOrCreateAtaInterface,
  getAssociatedTokenAddressInterface,
  sliceLast,
} from "@lightprotocol/compressed-token/unified";

await getOrCreateAtaInterface(rpc, payer, mint, recipient);
const destination = getAssociatedTokenAddressInterface(mint, recipient);

const instructions = await createTransferInterfaceInstructions(
  rpc,
  payer.publicKey,
  mint,
  amount,
  owner.publicKey,
  destination
);
const { rest: loadInstructions, last: transferInstructions } = sliceLast(instructions);
// empty = nothing to load, will no-op.
await Promise.all(
  loadInstructions.map((ixs) => {
    const tx = new Transaction().add(...ixs);
    tx.sign(payer, owner);
    return sendAndConfirmTransaction(rpc, tx);
  })
);

const transferTx = new Transaction().add(...transferInstructions);
transferTx.sign(payer, owner);
await sendAndConfirmTransaction(rpc, transferTx);

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

​
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);

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.
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.
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
  )
);

​
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.
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]);
}

​
One-time: Create interface PDA to existing SPL Mint

For existing SPL mints (e.g. USDC), register the SPL interface once. This creates the omnibus PDA that holds SPL tokens when wrapped to light-token.
Find a full code example here.
Check if the interface already exists:
import { getSplInterfaceInfos } from "@lightprotocol/compressed-token";

try {
  const infos = await getSplInterfaceInfos(rpc, mint);
  const exists = infos.some((i) => i.isInitialized);
  console.log("Interface exists:", exists);
} catch {
  console.log("No interface registered for this mint.");
}
Register:
import { Transaction, sendAndConfirmTransaction } from "@solana/web3.js";
import { LightTokenProgram } from "@lightprotocol/compressed-token";
import { TOKEN_PROGRAM_ID } from "@solana/spl-token";

const ix = await LightTokenProgram.createSplInterface({
  feePayer: payer.publicKey,
  mint,
  tokenProgramId: TOKEN_PROGRAM_ID,
});

const tx = new Transaction().add(ix);
await sendAndConfirmTransaction(rpc, tx, [payer]);
Use createMintInterface with TOKEN_PROGRAM_ID to create a new SPL mint and register the interface in one transaction:
import { createMintInterface } from "@lightprotocol/compressed-token/unified";
import { TOKEN_PROGRAM_ID } from "@solana/spl-token";

const { mint } = await createMintInterface(
  rpc, payer, payer, null, 9, undefined, undefined, TOKEN_PROGRAM_ID
);

Sponsor rent top-ups for users

Abstract away SOL costs by sponsoring rent top-ups on behalf of your users.

​
Didn’t find what you were looking for?

Reach out! Telegram | email | Discord