/pump-claims-readonly

name: pump-claims-readonly
description: "Read-only query methods for PumpFun claims — unclaimed token rewards, creator vault balances, volume accumulators, distributable fees, and current-day token previews across Pump and PumpAMM programs."
metadata:
  openclaw:
    homepage: https://github.com/nirholas/pump-fun-sdk
    requires:
      env:
        - SOLANA_RPC_URL

PumpFun Claims — Read-Only Queries

Query unclaimed rewards, creator vault balances, volume accumulators, and distributable fee status without submitting any transactions. All methods are read-only RPC calls on the `OnlinePumpSdk` class.

Overview

The Pump protocol has two claim domains:

| Domain | What is claimed | Who claims | |--------|----------------|------------| | **Token Incentives** | PUMP governance tokens earned from trading volume | Any trader | | **Creator Fees** | SOL accumulated in creator vaults from coin creation fees | Coin creators |

Both domains span **two on-chain programs** — Pump (bonding curve) and PumpAMM (graduated pools). The `BothPrograms` variants aggregate across both.

Setup

import { Connection, PublicKey } from "@solana/web3.js";
import { OnlinePumpSdk } from "@nirholas/pump-sdk";

const connection = new Connection(process.env.SOLANA_RPC_URL!);
const sdk = new OnlinePumpSdk(connection);
const user = new PublicKey("...");

Token Incentive Queries

Unclaimed Token Rewards

Get the total unclaimed PUMP tokens for a user. This includes all finalized day epochs but **excludes** the current day's rewards.

// Single program (Pump bonding curve only)
const unclaimed: BN = await sdk.getTotalUnclaimedTokens(user);

// Both programs (Pump + PumpAMM) — recommended
const unclaimedTotal: BN = await sdk.getTotalUnclaimedTokensBothPrograms(user);

**How it works:** Fetches `GlobalVolumeAccumulator` and `UserVolumeAccumulator` accounts, then computes rewards using the pure function `totalUnclaimedTokens()` from `tokenIncentives.ts`.

Current Day Token Preview

Preview how many PUMP tokens the user would earn from the current (in-progress) day. This is a projection — the day hasn't finalized yet.

// Single program
const todayTokens: BN = await sdk.getCurrentDayTokens(user);

// Both programs — recommended
const todayTokensTotal: BN = await sdk.getCurrentDayTokensBothPrograms(user);

**Important:** Returns `BN(0)` if the user hasn't synced during the current day. Call `syncUserVolumeAccumulator` first for an accurate preview.

Volume Accumulator Stats

Fetch aggregate stats showing claimed, unclaimed, and current volume across both programs.

const stats: UserVolumeAccumulatorTotalStats =
  await sdk.fetchUserVolumeAccumulatorTotalStats(user);

// stats.totalUnclaimedTokens — BN, finalized unclaimed PUMP tokens
// stats.totalClaimedTokens   — BN, lifetime claimed PUMP tokens
// stats.currentSolVolume     — BN, SOL volume in current epoch

**Return type:**

interface UserVolumeAccumulatorTotalStats {
  totalUnclaimedTokens: BN;
  totalClaimedTokens: BN;
  currentSolVolume: BN;
}

Raw Volume Accumulators

For lower-level access, fetch the on-chain accounts directly:

// Global config (start/end times, daily supply, daily volumes)
const global: GlobalVolumeAccumulator =
  await sdk.fetchGlobalVolumeAccumulator();

// Per-user accumulator (returns null if account doesn't exist)
const userAcc: UserVolumeAccumulator | null =
  await sdk.fetchUserVolumeAccumulator(user);

**Account structures:**

interface GlobalVolumeAccumulator {
  startTime: BN;
  endTime: BN;
  secondsInADay: BN;        // typically 86400
  mint: PublicKey;           // PUMP token mint
  totalTokenSupply: BN[];   // tokens available per day
  solVolumes: BN[];         // total SOL volume per day
}

interface UserVolumeAccumulator {
  user: PublicKey;
  needsClaim: boolean;
  totalUnclaimedTokens: BN;
  totalClaimedTokens: BN;
  currentSolVolume: BN;
  lastUpdateTimestamp: BN;
}

Pure Computation Functions

If you already hold the account data, compute rewards offline without RPC:

import { totalUnclaimedTokens, currentDayTokens } from "@nirholas/pump-sdk";

const unclaimed: BN = totalUnclaimedTokens(globalAcc, userAcc);
const today: BN = currentDayTokens(globalAcc, userAcc);

// Optional: pass a custom timestamp for testing
const unclaimed2 = totalUnclaimedTokens(globalAcc, userAcc, 1700000000);

Creator Fee Queries

Creator Vault Balance

Check how much SOL is sitting in a creator's fee vault, ready to be collected.

// Single program (Pump bonding curve vault only)
const balance: BN = await sdk.getCreatorVaultBalance(creator);

// Both programs (Pump + PumpAMM vaults) — recommended
const totalBalance: BN = await sdk.getCreatorVaultBalanceBothPrograms(creator);

**Note:** `getCreatorVaultBalance` subtracts the rent-exemption minimum — it returns only the withdrawable amount.

Minimum Distributable Fee

Check whether a token's fee-sharing configuration has enough accumulated fees to distribute, and the minimum threshold required.

const result: MinimumDistributableFeeResult =
  await sdk.getMinimumDistributableFee(mint);

// result.minimumRequired    — BN, minimum SOL needed to distribute
// result.distributableFees  — BN, current accumulated fees
// result.canDistribute      — boolean, true if fees >= minimum
// result.isGraduated        — boolean, true if token migrated to AMM

**How it works:** Simulates a transaction to read the return data from the on-chain program. For graduated tokens, it also simulates consolidating AMM vault fees before checking the threshold.

**Return type:**

interface MinimumDistributableFeeResult {
  minimumRequired: BN;
  distributableFees: BN;
  canDistribute: boolean;
  isGraduated: boolean;
}

PDA Addresses

The relevant PDAs for claim-related accounts: