Production Readiness

Non-exhaustive checklist for deploying Light Token payment flows to production, including RPC infrastructure, error handling, and security.

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

RPC infrastructure

Light Token requires a Photon-compatible RPC endpoint for cold account lookups and balance queries.

Provider	Photon support	Notes
Helius	Yes	Recommended. Maintains the Photon indexer.
Triton	Yes	Alternative provider.

Transaction landing

Light Token transactions follow standard Solana patterns for landing:

• Priority fees: Use ComputeBudgetProgram.setComputeUnitPrice() to increase transaction priority. See Solana priority fees.
• Compute units: Set appropriate compute unit limits with ComputeBudgetProgram.setComputeUnitLimit().
• Retry logic: Implement retries with fresh blockhashes for failed transactions.

Confirmation levels

Level	When to use
processed	Fastest. Use for UI updates. Not guaranteed to finalize.
confirmed	Recommended for most payment flows. Confirmed by supermajority of validators.
finalized	Highest certainty. Use for high-value transfers or irreversible actions.

Error handling

Handle both standard Solana errors and Light Token-specific scenarios:

• Cold account load failures: Retry the load if the indexer returns stale data.
• Associated token account creation: Idempotent — safe to retry.
• Rent top-up failures: Ensure the fee payer has sufficient SOL balance. See gasless transactions for cost breakdown.
• Transaction size limits: If TransactionInstruction[][] returns multiple batches, process them sequentially.

Fee sponsorship

Set your application as the fee payer so users never interact with SOL:

1. Rent top-ups and transaction fees: Set payer parameter on Light Token instructions. See gasless transactions.
2. Rent sponsor funding: Ensure the rent sponsor PDA is funded. See the cost breakdown for required amounts.

Pre-launch checklist

• Photon-compatible RPC endpoint configured and tested
• Fee payer wallet funded with sufficient SOL
• Error handling covers load failures, tx size limits, and retries
• Confirmation level appropriate for your use case
• Address verification implemented
• Wrap/unwrap flows tested for SPL / Token 2022 interoperability (if applicable)

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

---

Didn’t find what you were looking for?

Reach out! Telegram | email | Discord