Basic Payment

Send a single token transfer with Light Token APIs with comparison to SPL. If the recipient is receiving this token for the first time, their token account can be created as part of the same transaction.

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:

npx skills add Lightprotocol/skills

For orchestration, install the general skill:

npx skills add https://zkcompression.com

Guide

1. Setup

   Installation

   npm

   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
   

   yarn

   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
   

   pnpm

   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
   

   SDK 2.0 (token-interface)

   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

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

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

   Devnet

   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.

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

   Create a Token Helper for Setup

   setup.ts

   import "dotenv/config";
   import { Keypair } from "@solana/web3.js";
   import { createRpc } from "@lightprotocol/stateless.js";
   import {
       createMintInterface,
       createAtaInterface,
       getAssociatedTokenAddressInterface,
   } from "@lightprotocol/compressed-token";
   import { wrap } from "@lightprotocol/compressed-token/unified";
   import {
       TOKEN_PROGRAM_ID,
       createAssociatedTokenAccount,
       mintTo,
   } 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!}`;
   // export const rpc = createRpc(RPC_URL);
   // localnet:
   export const rpc = createRpc();
   
   export const payer = Keypair.fromSecretKey(
       new Uint8Array(
           JSON.parse(readFileSync(`${homedir()}/.config/solana/id.json`, "utf8"))
       )
   );
   
   /** Create SPL mint, fund payer, wrap into light-token ATA. */
   export async function setup(amount = 1_000_000_000) {
       const { mint } = await createMintInterface(
           rpc,
           payer,
           payer,
           null,
           9,
           undefined,
           undefined,
           TOKEN_PROGRAM_ID
       );
   
       const splAta = await createAssociatedTokenAccount(
           rpc,
           payer,
           mint,
           payer.publicKey,
           undefined,
           TOKEN_PROGRAM_ID
       );
       await mintTo(rpc, payer, mint, splAta, payer, amount);
   
       await createAtaInterface(rpc, payer, mint, payer.publicKey);
       const senderAta = getAssociatedTokenAddressInterface(mint, payer.publicKey);
       await wrap(rpc, payer, splAta, senderAta, payer, mint, BigInt(amount));
   
       return { mint, senderAta, splAta };
   }
   

   Find full runnable code examples: instruction | action.

2. Send a Payment

   Use createTransferInterfaceInstructions to transfer tokens between wallets. The method:

   • automatically derives Associated Token Accounts for the sender and recipient. If the recipient’s ATA doesn’t exist, the instruction to create the account is automatically added to the same transaction.
   • determines 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.

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

   Instruction

   import {
       Keypair,
       Transaction,
       sendAndConfirmTransaction,
   } from "@solana/web3.js";
   import { createTransferInterfaceInstructions } from "@lightprotocol/compressed-token/unified";
   import { rpc, payer, setup } from "../setup.js";
   
   (async function () {
       const { mint } = await setup();
       const recipient = Keypair.generate();
   
       // Returns TransactionInstruction[][]. Each inner array is one txn.
       const instructions = await createTransferInterfaceInstructions(
           rpc,
           payer.publicKey,
           mint,
           100,
           payer.publicKey,
           recipient.publicKey
       );
   
       for (const ixs of instructions) {
           const tx = new Transaction().add(...ixs);
           const sig = await sendAndConfirmTransaction(rpc, tx, [payer]);
           console.log("Tx:", sig);
       }
   })();
   

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

   SDK 2.0 (token-interface)

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

   Action

   import { Keypair } from "@solana/web3.js";
   import { transferInterface } from "@lightprotocol/compressed-token/unified";
   import { rpc, payer, setup } from "../setup.js";
   
   (async function () {
       const { mint, senderAta } = await setup();
       const recipient = Keypair.generate();
   
       const sig = await transferInterface(
           rpc,
           payer,
           senderAta,
           mint,
           recipient.publicKey,
           payer.publicKey,
           payer,
           100
       );
       console.log("Tx:", sig);
   })();
   

   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/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
- Import from @lightprotocol/compressed-token/unified for all interface APIs

SPL → Light Token API mapping:
| Operation    | SPL                               | Light Token                              |
| Receive      | getOrCreateAssociatedTokenAccount() | createLoadAtaInstructions() / loadAta()  |
| Transfer     | createTransferInstruction()        | createTransferInterfaceInstructions()    |
| Delegated Transfer | transfer() (delegate signs)  | transferInterface(..., ownerPubkey, delegateSigner, ...) |
| 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

### Resources

Guides:
- Basic payment: https://zkcompression.com/light-token/payments/basic-payment
- Batch payments: https://zkcompression.com/light-token/payments/batch-payments
- Payment with memo: https://zkcompression.com/light-token/payments/payment-with-memo
- Receive payments: https://zkcompression.com/light-token/payments/receive-payments
- Verify payments: https://zkcompression.com/light-token/payments/verify-payments
- Verify recipient address: https://zkcompression.com/light-token/payments/verify-recipient-address
- Spend permissions: https://zkcompression.com/light-token/payments/spend-permissions
- Wrap and unwrap: https://zkcompression.com/light-token/payments/wrap-unwrap
- Production readiness: https://zkcompression.com/light-token/payments/production-readiness
- FAQ: https://zkcompression.com/faq
- Sign with Privy: https://zkcompression.com/light-token/wallets/privy
- Sign with Wallet Adapter: https://zkcompression.com/light-token/wallets/wallet-adapter
- Gasless transactions: https://zkcompression.com/light-token/wallets/gasless-transactions

Examples:
- All payments: https://github.com/Lightprotocol/examples-light-token/tree/main/toolkits/payments
- Send (instruction): https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments/send/basic-send-instruction.ts
- Send (action): https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments/send/basic-send-action.ts
- Batch send: https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments/send/batch-send.ts
- Payment with memo: https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments/send/payment-with-memo.ts
- Receive: https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments/receive/receive.ts
- Get balance: https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments/verify/get-balance.ts
- Get history: https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments/verify/get-history.ts
- Verify address: https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments/verify/verify-address.ts
- Wrap: https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments/interop/wrap.ts
- Unwrap: https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments/interop/unwrap.ts
- Privy (Node.js): https://github.com/Lightprotocol/examples-light-token/tree/main/toolkits/sign-with-privy/nodejs
- Privy (React): https://github.com/Lightprotocol/examples-light-token/tree/main/toolkits/sign-with-privy/react
- Wallet Adapter (React): https://github.com/Lightprotocol/examples-light-token/tree/main/toolkits/sign-with-wallet-adapter/react
- Gasless transfer: https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/gasless-transactions/typescript/gasless-transfer.ts

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.

Verify payments

Query balances and transaction history.

---

Didn’t find what you were looking for?

Reach out! Telegram | email | Discord