Basic Payment

Send a single token transfer with Light Token APIs for stablecoin payments with comparison to SPL.

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.

	SPL	Light
Transfer	createTransferInstruction()	createTransferInterfaceInstructions()

Agent skill

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

Claude Code

Add the marketplace and install:

/plugin marketplace add Lightprotocol/skills
/plugin install solana-rent-free-dev

Cursor

1. Open Settings (Cmd+Shift+J / Ctrl+Shift+J)
2. Navigate to Rules & Commands → Project Rules → Add Rule → Remote Rule (GitHub)
3. Enter: https://github.com/Lightprotocol/skills.git

Any Agent

npx skills add Lightprotocol/skills

For orchestration, install the general skill:

npx skills add https://zkcompression.com

Guide

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 {
  createTransferInterfaceInstructions,
  transferInterface
} from "@lightprotocol/compressed-token/unified";

const rpc = createRpc(RPC_ENDPOINT);

Find full runnable code examples: instruction | action.

Send a payment

The SDK checks whether the sender’s account has a cold balance and adds load instructions if needed.

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.

Instruction

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

Your app logic may require you to create a single sign request for your user:

Sign all transactions together

const transactions = instructions.map((ixs) => new Transaction().add(...ixs));

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

for (const tx of signed) {
  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.

Optimize sending (parallel conditional loads, then transfer)

import {
  createTransferInterfaceInstructions,
  sliceLast,
} from "@lightprotocol/compressed-token/unified";

const instructions = await createTransferInterfaceInstructions(
  rpc,
  payer.publicKey,
  mint,
  amount,
  owner.publicKey,
  recipient
);
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);

Action

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

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

// Handles loading, creates recipient associated token account, transfers.
await transferInterface(rpc, payer, sourceAta, mint, recipient, 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);

AI Prompt

Integrate light-token APIs for stablecoin payments

CopiedCopy promptOpen in Cursor

---
description: Integrate light-token APIs for stablecoin payments
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, WebFetch, AskUserQuestion, Task, TaskCreate, TaskGet, TaskList, TaskUpdate, TaskOutput, mcp__deepwiki, mcp__zkcompression
---

## Integrate light-token APIs for stablecoin payments

Context:
- Guide: https://zkcompression.com/light-token/payments/integration-guide
- 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()    |
| Delegated Transfer | transfer() (delegate signs)  | transferDelegatedInterface()             |
| 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|Connection|Keypair|stablecoin|payment` across src/
- Glob `**/*.ts` and `**/*.tsx` for project structure
- Identify: RPC setup, existing token operations, payment flow, wallet 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 payment integration, migrate existing SPL payment flow, add 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
- 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

Related guides

Batch payments

Pack multiple transfers to multiple recipients into one transaction.

Gasless transactions

Abstract SOL fees from the user. Sponsor top-ups and transaction fees.

Receive payments

Unify token balances and share ATA address with the sender.

---

Didn’t find what you were looking for?

Reach out! Telegram | email | Discord