> ## Documentation Index
> Fetch the complete documentation index at: https://www.zkcompression.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify Payments

> Query token balances and transaction history to verify incoming payments.

<table>
  <thead>
    <tr>
      <th style={{ width: "15%" }} />

      <th>SPL</th>
      <th>Light</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**Get Balance**</td>
      <td>getAccount()</td>
      <td>getAtaInterface()</td>
    </tr>

    <tr>
      <td>**Tx History**</td>
      <td>getSignaturesForAddress()</td>
      <td>rpc.getSignaturesForOwnerInterface()</td>
    </tr>
  </tbody>
</table>

<Accordion title="Agent skill">
  Use the [payments](https://github.com/Lightprotocol/skills/tree/main/skills/payments) agent skill to add light-token payment support to your project:

  ```
  npx skills add Lightprotocol/skills
  ```

  For orchestration, install the [general skill](https://zkcompression.com/skill.md):

  ```bash theme={null}
  npx skills add https://zkcompression.com
  ```
</Accordion>

<Tabs>
  <Tab title="Guide">
    ## Setup

    <Accordion title="Installation">
      <Tabs>
        <Tab title="npm">
          Install packages in your working directory:

          ```bash theme={null}
          npm install @lightprotocol/stateless.js@^0.23.0 \
                      @lightprotocol/compressed-token@^0.23.0
          ```

          Install the CLI globally:

          ```bash theme={null}
          npm install -g @lightprotocol/zk-compression-cli
          ```
        </Tab>

        <Tab title="yarn">
          Install packages in your working directory:

          ```bash theme={null}
          yarn add @lightprotocol/stateless.js@^0.23.0 \
                   @lightprotocol/compressed-token@^0.23.0
          ```

          Install the CLI globally:

          ```bash theme={null}
          yarn global add @lightprotocol/zk-compression-cli
          ```
        </Tab>

        <Tab title="pnpm">
          Install packages in your working directory:

          ```bash theme={null}
          pnpm add @lightprotocol/stateless.js@^0.23.0 \
                   @lightprotocol/compressed-token@^0.23.0
          ```

          Install the CLI globally:

          ```bash theme={null}
          pnpm add -g @lightprotocol/zk-compression-cli
          ```
        </Tab>

        <Tab title="SDK 2.0 (token-interface)">
          Install packages in your working directory:

          ```bash theme={null}
          # 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:

          ```bash theme={null}
          npm install -g @lightprotocol/zk-compression-cli
          ```
        </Tab>
      </Tabs>
    </Accordion>

    <Tabs>
      <Tab title="Localnet">
        ```bash theme={null}
        # start local test-validator in a separate terminal
        light test-validator
        ```

        <Note>
          In the code examples, use `createRpc()` without arguments for localnet.
        </Note>
      </Tab>

      <Tab title="Devnet">
        Get an API key from [Helius](https://helius.dev) and add to `.env`:

        ```bash title=".env" theme={null}
        API_KEY=<your-helius-api-key>
        ```

        <Note>
          In the code examples, use `createRpc(RPC_URL)` with the devnet URL.
        </Note>
      </Tab>
    </Tabs>

    ```typescript theme={null}
    import { createRpc } from "@lightprotocol/stateless.js";

    const rpc = createRpc(RPC_ENDPOINT);
    ```

    <Accordion title="Create a Token Helper for Setup">
      ```typescript title="setup.ts" theme={null}
      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 };
      }
      ```
    </Accordion>

    ## Query balance

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

    <Note>
      Find a full code example [here](https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments/verify/get-balance.ts).
    </Note>

    ```typescript theme={null}
      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())
    ```

    <Accordion title="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`                           |

      ```typescript theme={null}
        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());
      ```
    </Accordion>

    ## Transaction history

    <Note>
      Find a full code example [here](https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments/verify/get-history.ts).
    </Note>

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

    ```typescript theme={null}
    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);
    ```

    <Accordion title="Compare to SPL">
      ```typescript theme={null}
      const signatures = await connection.getSignaturesForAddress(ata);
      ```
    </Accordion>
  </Tab>

  <Tab title="AI Prompt">
    <Prompt description="Integrate light-token APIs for stablecoin payments" actions={["copy", "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`}
    </Prompt>

    ```text theme={null}
    ---
    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
    ```
  </Tab>
</Tabs>

## Related guides

<CardGroup cols={3}>
  <Card title="Receive payments" icon="arrow-down" href="/light-token/payments/receive-payments">
    Load cold accounts and prepare to receive.
  </Card>

  <Card title="Basic payment" icon="arrow-right" href="/light-token/payments/basic-payment">
    Send a single token transfer.
  </Card>

  <Card title="Verify address" icon="shield-check" href="/light-token/payments/verify-recipient-address">
    Validate recipient addresses before sending.
  </Card>
</CardGroup>

***

## Didn't find what you were looking for?

<Callout type="info">
  Reach out! [Telegram](https://t.me/swen_light) | [email](mailto:support@lightprotocol.com) | [Discord](https://discord.com/invite/7cJ8BhAXhu)
</Callout>