Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

fix(pumpfun): gate claim trust on verified attribution (#214)

ni3a33570338d0eb
diff --git a/api/cron/[name].js b/api/cron/[name].js
index 9850bfff2..c5be586db 100644
--- a/api/cron/[name].js
+++ b/api/cron/[name].js
@@ -2360,9 +2360,18 @@ function pumpfunSignalsFromClaim(ev) {
const out = [];
// Bot claims carry tx_signature; the pf:claims Redis lane carries signature.
const base = { tx_signature: ev.tx_signature || ev.signature, payload: ev };
- if (ev.first_time_claim) out.push({ kind: 'first_claim', ...base });
+ const attribution = ev.attribution_status || ev.attribution;
+ const verifiedRelationship = attribution === 'verified_repository'
+ || attribution === 'verified_creator_wallet'
+ || (!attribution && (ev.verified === true || ev.signal_verified === true));
+ // A first withdrawal is positive reputation only when the coin relationship
+ // is verified. Raw, mismatched, or pooled claims remain visible as evidence
+ // but must not boost an agent/token trust score.
+ if (ev.first_time_claim && verifiedRelationship) out.push({ kind: 'first_claim', ...base });
if (ev.fake_claim) out.push({ kind: 'fake_claim', ...base });
- if (ev.tier === 'mega' || ev.tier === 'influencer') out.push({ kind: 'influencer', ...base });
+ if (verifiedRelationship && (ev.tier === 'mega' || ev.tier === 'influencer')) {
+ out.push({ kind: 'influencer', ...base });
+ }
if (ev.github_account_age_days != null && ev.github_account_age_days < 30) {
out.push({ kind: 'new_account', ...base });
}
diff --git a/docs/pump-claims-channel.md b/docs/pump-claims-channel.md
index 1c126a46c..1fcb6ef29 100644
--- a/docs/pump-claims-channel.md
+++ b/docs/pump-claims-channel.md
@@ -3,10 +3,16 @@
A live feed of **first-time pump.fun creator fee claims**, delivered to a
Telegram channel (`@pumpfunclaims`), one message per claim.
-A "first claim" is the first time a creator ever pulls their accrued
-creator/delegated rewards out of the fee vault. It is an on-chain, irreversible
-signal that the creator is live and engaged with their coin, which is why it
-gets its own channel rather than a line in the holder changelog.
+A claim is a real on-chain withdrawal. For GitHub social fees, it proves payment
+to a GitHub fee account—not automatically that the GitHub user created, owns, or
+endorses a particular coin. Token metadata can name lookalike accounts, and one
+fee account can pool rewards from several coins.
+
+Trader-facing cards use five evidence labels: **Verified GitHub Fee Claim**,
+**Creator-Wallet GitHub Fee Claim**, **Identity Mismatch**, **Unverified**, and
+**Unresolved Pooled**. A pooled event selects no primary CA or per-coin amount.
+“First-ever” refers to the shared fee account, and trade links appear only for
+verified relationships. The feed is a research lead, not an endorsement.
## How it works
diff --git a/docs/solana-pumpfun.md b/docs/solana-pumpfun.md
index 46999f9f9..27c6c160e 100644
--- a/docs/solana-pumpfun.md
+++ b/docs/solana-pumpfun.md
@@ -2,6 +2,12 @@
Pump.fun is a Solana token launchpad, and three.ws agents can watch it live: an agent avatar reacts (speaks, gestures, emotes) as claims and token graduations happen, and the same activity feeds each agent's trust score. If you just want to see it, add the `pumpfun-feed` widget to an agent in Studio; this page documents the plumbing behind it for developers.
+GitHub social-fee claims are classified by evidence. A real withdrawal alone
+does not prove that a GitHub user created or endorses the coin. Only verified
+repository-owner or creator-wallet relationships receive a positive
+`first_claim` reputation signal; mismatched, unverified and pooled events remain
+visible without increasing trust. Pooled withdrawals select no primary CA.
+
This integrates the upstream [`pumpfun-claims-bot`](https://github.com/nirholas/pumpfun-claims-bot) MCP server into the three.ws platform so a Solana agent can:
- Observe live pump.fun activity (GitHub social-fee claims, token graduations)
@@ -94,9 +100,9 @@ Reactions are computed by the shared dispatcher in [src/widgets/pumpfun-reaction
|---|---|---|---|---|
| `graduation_standard` | any graduation | `celebration` 0.9 (up to 1.0 for moonshots) | celebrate clip | +0.7 to +0.95 |
| `claim_first_verified` | first claim, verified GitHub | `celebration` 1.0 | `thriller` (6s) | +0.85 |
-| `claim_first_raw` | first claim, no GitHub link | `celebration` 0.85 | `celebrate` (4.5s) | +0.7 |
+| `claim_first_raw` | unverified first withdrawal | `curiosity` 0.65 | `look_around` (3s) | 0 |
| `claim_fake` | fake claim detected | `concern` 0.85 | `shake` (1.8s) | -0.6 |
-| `claim_tier_mega` / `_influencer` | repeat claim by tier | `celebration` 0.7 / `curiosity` 0.55 | short taunt/reaction | +0.5 / +0.3 |
+| `claim_tier_mega` / `_influencer` | verified repeat claim by tier | `celebration` 0.7 / `curiosity` 0.55 | short taunt/reaction | +0.5 / +0.3 |
These are continuous-blend stimuli, not discrete states — they decay according to the per-second rates in [agent-system.md](agent-system.md#5-the-avatar-emotion-system-empathy-layer).
@@ -128,7 +134,7 @@ Default weights:
| Kind | Weight | Lane |
|---|---|---|
| `graduation` | +0.3 | graduations |
-| `first_claim` | +0.2 | claims |
+| `first_claim` | +0.2 | verified repository/creator-wallet claims only |
| `influencer` | +0.2 | claims |
| `whale_buy` | +0.1 | whales |
| `launch` | +0.05 | mints |
diff --git a/src/widgets/pumpfun-feed.js b/src/widgets/pumpfun-feed.js
index 567cb3b4f..11b7830d4 100644
--- a/src/widgets/pumpfun-feed.js
+++ b/src/widgets/pumpfun-feed.js
@@ -257,11 +257,37 @@ function renderFirstGithubClaim(ev) {
const creatorTokens = Array.isArray(ev.creator_recent_tokens) ? ev.creator_recent_tokens : null;
const verified = ev.verified ?? ev.signal_verified;
+ const candidateCount = Array.isArray(ev.candidate_mints) ? ev.candidate_mints.length
+ : Array.isArray(ev.all_candidate_mints) ? ev.all_candidate_mints.length : 0;
+ const repoOwner = repoFull ? String(repoFull).split('/')[0].toLowerCase() : '';
+ const claimUser = ghUser ? String(ghUser).toLowerCase() : '';
+ let attribution = ev.attribution_status || ev.attribution;
+ if (!attribution) {
+ if (candidateCount > 1) attribution = 'unresolved_pooled';
+ else if (claimUser && repoOwner && claimUser !== repoOwner) attribution = 'identity_mismatch';
+ // A matching username is not verification: `repoFull` may itself be
+ // synthesized from `github_user`, making equality tautological. Only the
+ // upstream verifier's explicit boolean can preserve the legacy status.
+ else if (verified === true) attribution = 'verified_repository';
+ else if (claimer && creator && claimer === creator) attribution = 'verified_creator_wallet';
+ else attribution = 'unverified';
+ }
+ const attributionCopy = {
+ verified_repository: ['✅ VERIFIED GITHUB FEE CLAIM', 'Claiming GitHub identity matches the repository owner in token metadata.'],
+ verified_creator_wallet: ['✅ CREATOR-WALLET GITHUB FEE CLAIM', 'Receiving wallet also created the token; repository ownership was not established.'],
+ identity_mismatch: ['🚩 IDENTITY MISMATCH — GITHUB FEE WITHDRAWAL', 'Claiming GitHub identity differs from the repository owner in token metadata.'],
+ unresolved_pooled: ['⚠️ UNRESOLVED POOLED GITHUB FEE WITHDRAWAL', `This shared fee account maps to ${candidateCount || 'multiple'} coins, so no single CA is proven.`],
+ unverified: ['⚠️ UNVERIFIED GITHUB FEE WITHDRAWAL', 'The withdrawal is real, but it does not prove this GitHub user created or endorses the coin.'],
+ };
+ const [claimHeadline, claimExplanation] = attributionCopy[attribution] || attributionCopy.unverified;
+ const isVerifiedRelationship = attribution === 'verified_repository' || attribution === 'verified_creator_wallet';
const sections = [];
sections.push(`
- <div style="font-weight:700;color:#ff6e6e;letter-spacing:0.5px">🚨🚨🚨 FIRST CREATOR FEE CLAIM</div>
+ <div style="font-weight:700;color:${isVerifiedRelationship ? '#6ce0c8' : '#ff9a76'};letter-spacing:0.5px">${escapeHtml(claimHeadline)}</div>
+ <div style="opacity:0.85;margin-top:3px">${escapeHtml(claimExplanation)}</div>
+ ${ev.first_time_claim ? '<div style="opacity:0.85;margin-top:3px">🆕 First-ever withdrawal observed for this GitHub fee account.</div>' : ''}
${tier ? `<div style="opacity:0.85;margin-top:2px">${escapeHtml(tier)}</div>` : ''}
${mint ? `<div style="font-family:ui-monospace,monospace;font-size:11px;opacity:0.7;margin-top:6px;word-break:break-all">${escapeHtml(mint)}</div>` : ''}
`);
@@ -305,7 +331,7 @@ function renderFirstGithubClaim(ev) {
if (ghLoc) devLines.push(`📍 Location: ${escapeHtml(ghLoc)}`);
if (ghBio) devLines.push(`<span style="opacity:0.85;font-style:italic">${escapeHtml(ghBio)}</span>`);
if (ghTwitter) devLines.push(`𝕏 <a href="https://x.com/${encodeURIComponent(ghTwitter)}" target="_blank" rel="noopener" style="color:#6ce0c8">${escapeHtml(ghTwitter)}</a>`);
- sections.push(headedBlock('👨‍💻 Linked Dev', devLines));
+ sections.push(headedBlock('👨‍💻 Claiming GitHub Identity', devLines));
}
if (repoFull) {
@@ -317,7 +343,7 @@ function renderFirstGithubClaim(ev) {
if (repoLastPush) repoLines.push(`🕐 Last push: ${repoLastPush}`);
if (repoCreated) repoLines.push(`📅 Repo created: ${repoCreated}`);
if (repoTopics?.length) repoLines.push(`🏷 Topics: ${repoTopics.map(escapeHtml).join(', ')}`);
- sections.push(headedBlock('📂 Repo Claimed', repoLines));
+ sections.push(headedBlock('📂 Repository in Token Metadata', repoLines));
}
if (creator) {
@@ -334,9 +360,12 @@ function renderFirstGithubClaim(ev) {
sections.push(headedBlock('🧑‍💻 Token Creator', cLines));
}
- if (verified || ev.ai_take) {
+ if (attribution || ev.ai_take) {
const sigLines = [];
- if (verified) sigLines.push('✅ Verified — token GitHub matches claimer');
+ if (isVerifiedRelationship) sigLines.push('✅ Verified relationship');
+ if (attribution === 'identity_mismatch') sigLines.push('🚩 Username mismatch — do not treat as project verification');
+ if (attribution === 'unverified') sigLines.push('⚠️ GitHub-to-coin relationship not verified');
+ if (attribution === 'unresolved_pooled') sigLines.push('⚠️ Shared withdrawal cannot be assigned to one coin');
if (ev.ai_take) sigLines.push(`<span style="font-style:italic;opacity:0.85">${escapeHtml(ev.ai_take)}</span>`);
sections.push(headedBlock('⚡ Signals', sigLines));
}
@@ -348,7 +377,7 @@ function renderFirstGithubClaim(ev) {
if (repoFull) links.push(`<a href="https://github.com/${repoFull.split('/').map(encodeURIComponent).join('/')}" target="_blank" rel="noopener" style="color:#6ce0c8">🌐 github.com/${escapeHtml(repoFull)}</a>`);
if (links.length) sections.push(`<div style="margin-top:8px;display:flex;flex-direction:column;gap:2px">${links.join('')}</div>`);
- if (mint) {
+ if (mint && isVerifiedRelationship) {
const trade = terminalLinks(mint)
.map((t) => `<a href="${attrEsc(t.url)}" target="_blank" rel="noopener" style="color:#6ce0c8">${t.label}</a>`)
.join(' | ');
diff --git a/src/widgets/pumpfun-reactions.js b/src/widgets/pumpfun-reactions.js
index 112c66872..de7cd32be 100644
--- a/src/widgets/pumpfun-reactions.js
+++ b/src/widgets/pumpfun-reactions.js
@@ -95,7 +95,10 @@ export function extractSignals(ev) {
// GitHub / claim legitimacy
const ghUser = ev.github_user || null;
const ghLinked = !!(ghUser || ev.github_repo || ev.github_account_age_days != null);
- const ghVerified = !!(ev.verified ?? ev.signal_verified);
+ const attribution = ev.attribution_status || ev.attribution;
+ const ghVerified = attribution === 'verified_repository'
+ || attribution === 'verified_creator_wallet'
+ || (!attribution && (ev.verified === true || ev.signal_verified === true));
const ghFollowers = num(ev.github_followers);
const ghAccountAgeDays = num(ev.github_account_age_days);
const repoStars = num(ev.github_repo_stars ?? ev.repo_stars);
@@ -250,11 +253,11 @@ function claimReaction(s) {
}
return {
variant: 'claim_first_raw',
- icon: '🚨',
- emote: { trigger: 'celebration', weight: 0.85 },
- gesture: { name: 'celebrate', duration: 4500 },
- speak: { text: `First-time claim on $${s.symbol || 'a new token'}.${s.aiTake ? ' ' + s.aiTake : ''}`, sentiment: 0.7 },
- lookAt: 'camera',
+ icon: '❓',
+ emote: { trigger: 'curiosity', weight: 0.65 },
+ gesture: { name: 'look_around', duration: 3000 },
+ speak: { text: `Unverified first withdrawal observed on $${s.symbol || 'a token'}.${s.aiTake ? ' ' + s.aiTake : ''}`, sentiment: 0 },
+ lookAt: 'token',
priority: 78,
};
}
diff --git a/tests/pumpfun-signals.test.js b/tests/pumpfun-signals.test.js
index 39041a04b..26bd2dea5 100644
--- a/tests/pumpfun-signals.test.js
+++ b/tests/pumpfun-signals.test.js
@@ -123,6 +123,7 @@ describe('pumpfun-signals cron', () => {
{
tx_signature: 'sig1', signature: 'sig1', timestamp: 1000,
claimer: 'WALLET_A', first_time_claim: true, tier: 'influencer',
+ attribution_status: 'verified_repository',
github_account_age_days: 5,
},
{ tx_signature: 'sig2', signature: 'sig2', timestamp: 1001, claimer: 'WALLET_UNKNOWN', first_time_claim: true },
@@ -145,8 +146,8 @@ describe('pumpfun-signals cron', () => {
h.recentClaims.mockResolvedValue({
ok: true,
data: [
- { tx_signature: 'c1', signature: 'c1', timestamp: 100, claimer: 'W', first_time_claim: true },
- { tx_signature: 'c2', signature: 'c2', timestamp: 200, claimer: 'W', first_time_claim: true },
+ { tx_signature: 'c1', signature: 'c1', timestamp: 100, claimer: 'W', first_time_claim: true, attribution_status: 'verified_repository' },
+ { tx_signature: 'c2', signature: 'c2', timestamp: 200, claimer: 'W', first_time_claim: true, attribution_status: 'verified_repository' },
],
});
linkedRows = [{ address: 'W', agent_asset: 'A' }];
@@ -164,6 +165,21 @@ describe('pumpfun-signals cron', () => {
expect(second.body.skipped_by_cursor).toBeGreaterThanOrEqual(1);
});
+ it('does not turn an unverified first withdrawal into positive reputation', async () => {
+ h.recentClaims.mockResolvedValue({
+ ok: true,
+ data: [{
+ tx_signature: 'unverified1', timestamp: 300, claimer: 'W',
+ first_time_claim: true, tier: 'influencer', attribution_status: 'identity_mismatch',
+ }],
+ });
+ linkedRows = [{ address: 'W', agent_asset: 'A' }];
+
+ const { body } = await run();
+ expect(body.inserted).toBe(0);
+ expect(insertedRows).toEqual([]);
+ });
+
it('emits whale_buy and launch signals from the redis lanes', async () => {
h.getWhales.mockResolvedValue([
{ signature: 'w1', timestamp: 10, mint: 'M1', amount_sol: 12.5, buyer: 'WB' },
diff --git a/tests/src/pumpfun-reactions.test.js b/tests/src/pumpfun-reactions.test.js
index a18e1a56b..8e13c0af4 100644
--- a/tests/src/pumpfun-reactions.test.js
+++ b/tests/src/pumpfun-reactions.test.js
@@ -52,6 +52,18 @@ describe('reactionFor', () => {
expect(r.priority).toBe(85);
});
+ it('does not trust a legacy verified flag when attribution says mismatch', () => {
+ const r = reactionFor('claim', {
+ mint: 'M',
+ first_time_claim: true,
+ github_user: 'alice',
+ signal_verified: true,
+ attribution_status: 'identity_mismatch',
+ });
+ expect(r.variant).toBe('claim_first_unverified_gh');
+ expect(r.gesture.name).not.toBe('thriller');
+ });
+
it('first-time GitHub-linked unverified claim plays silly', () => {
const r = reactionFor('claim', {
mint: 'M',
@@ -61,13 +73,15 @@ describe('reactionFor', () => {
expect(r.gesture.name).toBe('silly');
});
- it('first-time non-GitHub claim plays the celebrate clip', () => {
+ it('first-time non-GitHub claim stays neutral and curious', () => {
const r = reactionFor('claim', {
mint: 'M',
first_time_claim: true,
claimer: 'wallet1',
});
- expect(r.gesture.name).toBe('celebrate');
+ expect(r.gesture.name).toBe('look_around');
+ expect(r.emote.trigger).toBe('curiosity');
+ expect(r.speak.sentiment).toBe(0);
});
it('fake claim plays a head-shake with concern', () => {