x402agent/pump-claims-readonly

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:

import {
  userVolumeAccumulatorPda,
  creatorVaultPda,
  feeSharingConfigPda,
  GLOBAL_VOLUME_ACCUMULATOR_PDA,
} from "@nirholas/pump-sdk";

const userVolumePda = userVolumeAccumulatorPda(user);
const vaultPda = creatorVaultPda(creator);
const sharingPda = feeSharingConfigPda(mint);

Quick Reference

| Method | Returns | Programs | |--------|---------|----------| | getTotalUnclaimedTokens(user) | BN | Pump only | | getTotalUnclaimedTokensBothPrograms(user) | BN | Pump + AMM | | getCurrentDayTokens(user) | BN | Pump only | | getCurrentDayTokensBothPrograms(user) | BN | Pump + AMM | | fetchUserVolumeAccumulatorTotalStats(user) | UserVolumeAccumulatorTotalStats | Pump + AMM | | fetchGlobalVolumeAccumulator() | GlobalVolumeAccumulator | Pump | | fetchUserVolumeAccumulator(user) | UserVolumeAccumulator \| null | Pump | | getCreatorVaultBalance(creator) | BN | Pump only | | getCreatorVaultBalanceBothPrograms(creator) | BN | Pump + AMM | | getMinimumDistributableFee(mint) | MinimumDistributableFeeResult | Pump + AMM |

Edge Cases

| Scenario | Behavior | |----------|----------| | User has no volume accumulator account | fetchUserVolumeAccumulator returns null; unclaimed methods return BN(0) | | Creator vault doesn't exist | getCreatorVaultBalance returns BN(0) | | Sharing config not found for mint | getMinimumDistributableFee throws Error | | User hasn't synced current day | getCurrentDayTokens returns BN(0) | | Global volume is zero for a day | No tokens distributed (division-by-zero guarded) | | Token not yet graduated | isGraduated is false; only bonding curve vault checked |

Patterns to Follow

• Always use BothPrograms variants unless you specifically need single-program data
• All return values are BN (bn.js) — never convert to JavaScript number for financial math
• totalUnclaimedTokens excludes current-day rewards — add getCurrentDayTokens for full picture
• Call syncUserVolumeAccumulator before reading getCurrentDayTokens for accuracy
• This skill covers read-only queries only — for claiming and collecting, see the pump-token-incentives and pump-fee-sharing skills