Verify Payments

Query token balances and transaction history to verify incoming payments.

	SPL	Light
Get Balance	getAccount()	getAtaInterface()
Tx History	getSignaturesForAddress()	rpc.getSignaturesForOwnerInterface()

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

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.

import { createRpc } from "@lightprotocol/stateless.js";

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

Query balance

getAtaInterface returns a unified balance aggregating Light Token (hot + cold), SPL, and Token 2022 sources in parsed.amount.

Find a full code example here.

  import { PublicKey } from "@solana/web3.js";                                              
  import { createRpc } from "@lightprotocol/stateless.js";                                  
  import {                                                                                  
      getAssociatedTokenAddressInterface,                                                   
      getAtaInterface,                                                                      
  } from "@lightprotocol/compressed-token/unified";                                         
                                                                                            
  const rpc = createRpc();                                                                  
  const mint = new PublicKey("YOUR_MINT_ADDRESS");                                          
  const owner = new PublicKey("YOUR_OWNER_ADDRESS");                                        
                                                                                            
  const ata = getAssociatedTokenAddressInterface(mint, owner);                              
  const account = await getAtaInterface(rpc, ata, owner, mint);                             
  console.log("Balance:", account.parsed.amount.toString())

Compare to SPL

	SPL	Light
Connection	new Connection(endpoint)	createRpc()
Derive ATA	getAssociatedTokenAddress(mint, owner)	getAssociatedTokenAddressInterface(mint, owner)
Fetch account	getAccount(connection, ata)	getAtaInterface(rpc, ata, owner, mint)
Read balance	account.amount	account.parsed.amount

  import { Connection, PublicKey } from "@solana/web3.js";                                
  import { getAssociatedTokenAddress, getAccount } from "@solana/spl-token";                
                                                                            
  const connection = new Connection("https://api.mainnet-beta.solana.com");                 
  const mint = new PublicKey("YOUR_MINT_ADDRESS");                                        
  const owner = new PublicKey("YOUR_OWNER_ADDRESS");                                        
                                                                                            
  const ata = getAssociatedTokenAddress(mint, owner);
  const account = await getAccount(connection, ata);                                        
  console.log("Balance:", account.amount.toString());

Transaction history

Find a full code example here.

Query all transactions for an owner across both on-chain and compressed state:

import { PublicKey } from "@solana/web3.js";
import { createRpc } from "@lightprotocol/stateless.js";

const rpc = createRpc();
const owner = new PublicKey("YOUR_OWNER_ADDRESS");

const result = await rpc.getSignaturesForOwnerInterface(owner);
console.log("Signatures:", result.signatures.length);

Compare to SPL

const signatures = await connection.getSignaturesForAddress(ata);

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

Receive payments

Load cold accounts and prepare to receive.

Basic payment

Send a single token transfer.

Verify address

Validate recipient addresses before sending.

---

Didn’t find what you were looking for?

Reach out! Telegram | email | Discord