my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	{
#2	"skillId": "pump-claims-readonly",
#3	"name": "pump-claims-readonly",
#4	"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.",
#5	"category": "pump-protocol",
#6	"path": "pump-claims-readonly/SKILL.md",
#7	"url": "https://x402.wtf/api/skills/pump-claims-readonly",
#8	"tags": [
#9	"pump",
#10	"solana",
#11	"claims",
#12	"readonly"
#13	],
#14	"requiredEnv": [
#15	"SOLANA_RPC_URL"
#16	],
#17	"homepage": "https://github.com/nirholas/pump-fun-sdk",
#18	"attestation": {
#19	"status": "pending",
#20	"isFormallyVerified": false,
#21	"attestationPda": null,
#22	"verificationTimestamp": null
#23	},
#24	"markdown": "---\nname: pump-claims-readonly\ndescription: \"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.\"\nmetadata:\n openclaw:\n homepage: https://github.com/nirholas/pump-fun-sdk\n requires:\n env:\n - SOLANA_RPC_URL\n---\n\n# PumpFun Claims — Read-Only Queries\n\nQuery 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.\n\n## Overview\n\nThe Pump protocol has two claim domains:\n\n\| Domain \| What is claimed \| Who claims \|\n\|--------\|----------------\|------------\|\n\| Token Incentives \| PUMP governance tokens earned from trading volume \| Any trader \|\n\| Creator Fees \| SOL accumulated in creator vaults from coin creation fees \| Coin creators \|\n\nBoth domains span two on-chain programs — Pump (bonding curve) and PumpAMM (graduated pools). The `BothPrograms` variants aggregate across both.\n\n## Setup\n\n```typescript\nimport { Connection, PublicKey } from \"@solana/web3.js\";\nimport { OnlinePumpSdk } from \"@nirholas/pump-sdk\";\n\nconst connection = new Connection(process.env.SOLANA_RPC_URL!);\nconst sdk = new OnlinePumpSdk(connection);\nconst user = new PublicKey(\"...\");\n```\n\n## Token Incentive Queries\n\n### Unclaimed Token Rewards\n\nGet the total unclaimed PUMP tokens for a user. This includes all finalized day epochs but excludes the current day's rewards.\n\n```typescript\n// Single program (Pump bonding curve only)\nconst unclaimed: BN = await sdk.getTotalUnclaimedTokens(user);\n\n// Both programs (Pump + PumpAMM) — recommended\nconst unclaimedTotal: BN = await sdk.getTotalUnclaimedTokensBothPrograms(user);\n```\n\nHow it works: Fetches `GlobalVolumeAccumulator` and `UserVolumeAccumulator` accounts, then computes rewards using the pure function `totalUnclaimedTokens()` from `tokenIncentives.ts`.\n\n### Current Day Token Preview\n\nPreview how many PUMP tokens the user would earn from the current (in-progress) day. This is a projection — the day hasn't finalized yet.\n\n```typescript\n// Single program\nconst todayTokens: BN = await sdk.getCurrentDayTokens(user);\n\n// Both programs — recommended\nconst todayTokensTotal: BN = await sdk.getCurrentDayTokensBothPrograms(user);\n```\n\nImportant: Returns `BN(0)` if the user hasn't synced during the current day. Call `syncUserVolumeAccumulator` first for an accurate preview.\n\n### Volume Accumulator Stats\n\nFetch aggregate stats showing claimed, unclaimed, and current volume across both programs.\n\n```typescript\nconst stats: UserVolumeAccumulatorTotalStats =\n await sdk.fetchUserVolumeAccumulatorTotalStats(user);\n\n// stats.totalUnclaimedTokens — BN, finalized unclaimed PUMP tokens\n// stats.totalClaimedTokens — BN, lifetime claimed PUMP tokens\n// stats.currentSolVolume — BN, SOL volume in current epoch\n```\n\nReturn type:\n\n```typescript\ninterface UserVolumeAccumulatorTotalStats {\n totalUnclaimedTokens: BN;\n totalClaimedTokens: BN;\n currentSolVolume: BN;\n}\n```\n\n### Raw Volume Accumulators\n\nFor lower-level access, fetch the on-chain accounts directly:\n\n```typescript\n// Global config (start/end times, daily supply, daily volumes)\nconst global: GlobalVolumeAccumulator =\n await sdk.fetchGlobalVolumeAccumulator();\n\n// Per-user accumulator (returns null if account doesn't exist)\nconst userAcc: UserVolumeAccumulator \| null =\n await sdk.fetchUserVolumeAccumulator(user);\n```\n\nAccount structures:\n\n```typescript\ninterface GlobalVolumeAccumulator {\n startTime: BN;\n endTime: BN;\n secondsInADay: BN; // typically 86400\n mint: PublicKey; // PUMP token mint\n totalTokenSupply: BN[]; // tokens available per day\n solVolumes: BN[]; // total SOL volume per day\n}\n\ninterface UserVolumeAccumulator {\n user: PublicKey;\n needsClaim: boolean;\n totalUnclaimedTokens: BN;\n totalClaimedTokens: BN;\n currentSolVolume: BN;\n lastUpdateTimestamp: BN;\n}\n```\n\n### Pure Computation Functions\n\nIf you already hold the account data, compute rewards offline without RPC:\n\n```typescript\nimport { totalUnclaimedTokens, currentDayTokens } from \"@nirholas/pump-sdk\";\n\nconst unclaimed: BN = totalUnclaimedTokens(globalAcc, userAcc);\nconst today: BN = currentDayTokens(globalAcc, userAcc);\n\n// Optional: pass a custom timestamp for testing\nconst unclaimed2 = totalUnclaimedTokens(globalAcc, userAcc, 1700000000);\n```\n\n## Creator Fee Queries\n\n### Creator Vault Balance\n\nCheck how much SOL is sitting in a creator's fee vault, ready to be collected.\n\n```typescript\n// Single program (Pump bonding curve vault only)\nconst balance: BN = await sdk.getCreatorVaultBalance(creator);\n\n// Both programs (Pump + PumpAMM vaults) — recommended\nconst totalBalance: BN = await sdk.getCreatorVaultBalanceBothPrograms(creator);\n```\n\nNote: `getCreatorVaultBalance` subtracts the rent-exemption minimum — it returns only the withdrawable amount.\n\n### Minimum Distributable Fee\n\nCheck whether a token's fee-sharing configuration has enough accumulated fees to distribute, and the minimum threshold required.\n\n```typescript\nconst result: MinimumDistributableFeeResult =\n await sdk.getMinimumDistributableFee(mint);\n\n// result.minimumRequired — BN, minimum SOL needed to distribute\n// result.distributableFees — BN, current accumulated fees\n// result.canDistribute — boolean, true if fees >= minimum\n// result.isGraduated — boolean, true if token migrated to AMM\n```\n\nHow 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.\n\nReturn type:\n\n```typescript\ninterface MinimumDistributableFeeResult {\n minimumRequired: BN;\n distributableFees: BN;\n canDistribute: boolean;\n isGraduated: boolean;\n}\n```\n\n## PDA Addresses\n\nThe relevant PDAs for claim-related accounts:\n\n```typescript\nimport {\n userVolumeAccumulatorPda,\n creatorVaultPda,\n feeSharingConfigPda,\n GLOBAL_VOLUME_ACCUMULATOR_PDA,\n} from \"@nirholas/pump-sdk\";\n\nconst userVolumePda = userVolumeAccumulatorPda(user);\nconst vaultPda = creatorVaultPda(creator);\nconst sharingPda = feeSharingConfigPda(mint);\n```\n\n## Quick Reference\n\n\| Method \| Returns \| Programs \|\n\|--------\|---------\|----------\|\n\| `getTotalUnclaimedTokens(user)` \| `BN` \| Pump only \|\n\| `getTotalUnclaimedTokensBothPrograms(user)` \| `BN` \| Pump + AMM \|\n\| `getCurrentDayTokens(user)` \| `BN` \| Pump only \|\n\| `getCurrentDayTokensBothPrograms(user)` \| `BN` \| Pump + AMM \|\n\| `fetchUserVolumeAccumulatorTotalStats(user)` \| `UserVolumeAccumulatorTotalStats` \| Pump + AMM \|\n\| `fetchGlobalVolumeAccumulator()` \| `GlobalVolumeAccumulator` \| Pump \|\n\| `fetchUserVolumeAccumulator(user)` \| `UserVolumeAccumulator \\\| null` \| Pump \|\n\| `getCreatorVaultBalance(creator)` \| `BN` \| Pump only \|\n\| `getCreatorVaultBalanceBothPrograms(creator)` \| `BN` \| Pump + AMM \|\n\| `getMinimumDistributableFee(mint)` \| `MinimumDistributableFeeResult` \| Pump + AMM \|\n\n## Edge Cases\n\n\| Scenario \| Behavior \|\n\|----------\|----------\|\n\| User has no volume accumulator account \| `fetchUserVolumeAccumulator` returns `null`; unclaimed methods return `BN(0)` \|\n\| Creator vault doesn't exist \| `getCreatorVaultBalance` returns `BN(0)` \|\n\| Sharing config not found for mint \| `getMinimumDistributableFee` throws `Error` \|\n\| User hasn't synced current day \| `getCurrentDayTokens` returns `BN(0)` \|\n\| Global volume is zero for a day \| No tokens distributed (division-by-zero guarded) \|\n\| Token not yet graduated \| `isGraduated` is `false`; only bonding curve vault checked \|\n\n## Patterns to Follow\n\n- Always use `BothPrograms` variants unless you specifically need single-program data\n- All return values are `BN` (bn.js) — never convert to JavaScript `number` for financial math\n- `totalUnclaimedTokens` excludes current-day rewards — add `getCurrentDayTokens` for full picture\n- Call `syncUserVolumeAccumulator` before reading `getCurrentDayTokens` for accuracy\n- This skill covers read-only queries only — for claiming and collecting, see the `pump-token-incentives` and `pump-fee-sharing` skills\n\n"
#25	}
#26

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public