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.

docs(sentiment): describe the pump.fun callout source behind the sentiment pulse, and retire its audit

nirholasc9ec72011d6f
diff --git a/docs/agent-abilities/ABILITIES.md b/docs/agent-abilities/ABILITIES.md
index 899f1114f..52f2741a7 100644
--- a/docs/agent-abilities/ABILITIES.md
+++ b/docs/agent-abilities/ABILITIES.md
@@ -2006,7 +2006,7 @@ Turn an agent into an on-chain business: its coin is its equity, its invoices ar
## Sentiment and narrative intel tools
-Token sentiment on demand: POST /api/sentiment scores any text (Positive/Negative/Neutral) with a deterministic lexicon scorer; /api/social/sentiment-pulse pulls the real comment thread for any Solana/pump.fun mint and returns an overall score with per-source breakdown and examples (also sold as the paid sentiment_pulse MCP tool); aixbt narrative intel and momentum-ranked project scans are exposed at api/aixbt/* and as aixbt_intel / aixbt_projects MCP tools. All packaged for developers as the @three-ws/intel npm module.
+Token sentiment on demand: POST /api/sentiment scores any text (Positive/Negative/Neutral) with a deterministic lexicon scorer; /api/social/sentiment-pulse pulls the real community commentary (pump.fun callouts) for any Solana/pump.fun mint and returns an overall score with per-source breakdown and examples (also sold as the paid sentiment_pulse MCP tool); aixbt narrative intel and momentum-ranked project scans are exposed at api/aixbt/* and as aixbt_intel / aixbt_projects MCP tools. All packaged for developers as the @three-ws/intel npm module.
Sentiment-pulse fetches recent commentary from pump.fun's frontend-api-v3 comments endpoint (the same source the pump.fun coin page renders) plus caller-supplied snippets, scored by the in-repo lexicon engine (src/social/sentiment.js); aixbt endpoints proxy the aixbt market-intelligence service.
diff --git a/docs/agent-abilities/FULL-ARTICLE.md b/docs/agent-abilities/FULL-ARTICLE.md
index 5241d5f6d..fbc49880e 100644
--- a/docs/agent-abilities/FULL-ARTICLE.md
+++ b/docs/agent-abilities/FULL-ARTICLE.md
@@ -2143,7 +2143,7 @@ Agents launched as pump.fun coins can charge for their services on-chain: build
## Sentiment and narrative intel tools
-Token sentiment on demand: POST /api/sentiment scores any text (Positive/Negative/Neutral) with a deterministic lexicon scorer; /api/social/sentiment-pulse pulls the real comment thread for any Solana/pump.fun mint and returns an overall score with per-source breakdown and examples (also sold as the paid sentiment_pulse MCP tool); aixbt narrative intel and momentum-ranked project scans are exposed at api/aixbt/* and as aixbt_intel / aixbt_projects MCP tools. All packaged for developers as the @three-ws/intel npm module.
+Token sentiment on demand: POST /api/sentiment scores any text (Positive/Negative/Neutral) with a deterministic lexicon scorer; /api/social/sentiment-pulse pulls the real community commentary (pump.fun callouts) for any Solana/pump.fun mint and returns an overall score with per-source breakdown and examples (also sold as the paid sentiment_pulse MCP tool); aixbt narrative intel and momentum-ranked project scans are exposed at api/aixbt/* and as aixbt_intel / aixbt_projects MCP tools. All packaged for developers as the @three-ws/intel npm module.
**How it works:** Sentiment-pulse fetches recent commentary from pump.fun's frontend-api-v3 comments endpoint (the same source the pump.fun coin page renders) plus caller-supplied snippets, scored by the in-repo lexicon engine (src/social/sentiment.js); aixbt endpoints proxy the aixbt market-intelligence service.
diff --git a/docs/tutorials/emotion-from-data.md b/docs/tutorials/emotion-from-data.md
index b28ab6dd4..d521d1caa 100644
--- a/docs/tutorials/emotion-from-data.md
+++ b/docs/tutorials/emotion-from-data.md
@@ -38,7 +38,7 @@ The pattern for "animation from data" is: **your data source picks a discrete ou
## Step 2: The free lane: sentiment → animation, no AI required
-The platform runs a public, unauthenticated sentiment scorer over live pump.fun token chat: [`POST /api/social/sentiment-pulse`](../../api/social/sentiment-pulse.js). It pulls recent comments for a token and scores them with an in-repo lexicon (no LLM call, no key), good enough to prove the wiring before you reach for a model.
+The platform runs a public, unauthenticated sentiment scorer over live pump.fun token commentary: [`POST /api/social/sentiment-pulse`](../../api/social/sentiment-pulse.js). It pulls a coin's recent pump.fun callouts (the commentary feed the coin page renders) and scores them with an in-repo lexicon (no LLM call, no key), good enough to prove the wiring before you reach for a model. If pump.fun is unreachable and you passed no `extraTexts` of your own, it answers `502 upstream_unavailable` rather than a neutral-looking score, so the `if (!res.ok) return null` guard below is what keeps a dead feed from animating your agent.
```html
<!DOCTYPE html>
diff --git a/mcp-server/README.md b/mcp-server/README.md
index ccd36112d..0e537063c 100644
--- a/mcp-server/README.md
+++ b/mcp-server/README.md
@@ -84,7 +84,7 @@ All 25 tools are listed below. Most quote a fixed USDC price and settle `exact`
| Tool | Price | What it returns |
| ----------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pump_snapshot` | $0.005 | Live token snapshot — USD price (Jupiter), 24h volume + pair (Dexscreener), mint metadata + image (pump.fun frontend-api-v3), and on-chain top-holder distribution (Solana RPC). Adds Helius DAS data when `HELIUS_API_KEY` is set. |
-| `sentiment_pulse` | $0.003 | Sentiment for a Solana token: scores recent pump.fun comments (plus optional caller-supplied snippets) with the three.ws deterministic lexicon. Returns overall + per-source breakdown with examples. Pairs with `pump_snapshot`. |
+| `sentiment_pulse` | $0.003 | Sentiment for a Solana token: scores the coin's recent pump.fun callouts (plus optional caller-supplied snippets) with the three.ws deterministic lexicon. Returns overall + per-source breakdown with examples. Pairs with `pump_snapshot`. |
| `vanity_grinder` | $0.05 | Solana keypair whose base58 address starts with `prefix` (and optionally ends with `suffix`). Returns the full base58 secret key — treat as a secret. Flat price (override with `MCP_VANITY_PRICE_USD`); a difficulty guard rejects prefixes too long to mine within the iteration cap. |
| `vanity_premium` | FREE | Browse the **premium** vanity inventory: long (4-5+ char) brandable Solana addresses ground ahead of time on batch CPU and sold from stock, which the live grinder cannot reach. Read-only and free: returns each address, its rarity tier, a difficulty-scaled price ($1-$50), and a ready-to-pay x402 `buyUrl`. Paying that URL (USDC on Base or Solana) reveals the private key exactly once; the ciphertext is destroyed on delivery. Filter by prefix or tier, sort by rarity/price/newest. Keys are platform-generated: use as a token mint or sweep to self-generated custody, not as a treasury. |
| `aixbt_intel` | $0.01 | aixbt narrative intelligence feed — recent intel items across crypto with category, description, observation count, official-source flag, and the project/ticker concerned. Optional category/chain filter. Live aixbt REST API. |
diff --git a/mcp-server/src/tools/sentiment-pulse.js b/mcp-server/src/tools/sentiment-pulse.js
index f8acdda98..3e40096f5 100644
--- a/mcp-server/src/tools/sentiment-pulse.js
+++ b/mcp-server/src/tools/sentiment-pulse.js
@@ -1,14 +1,16 @@
// `sentiment_pulse` — paid MCP tool that returns a real-time sentiment
-// pulse for a Solana token by pulling recent pump.fun comments and
-// scoring them with the three.ws lexicon scorer. Callers may attach
-// additional texts (e.g. X posts they have collected) to fold into the
-// overall score.
+// pulse for a Solana token by pulling the coin's recent pump.fun callouts
+// (the community commentary the coin page renders) and scoring them with
+// the three.ws lexicon scorer. Callers may attach additional texts (e.g. X
+// posts they have collected) to fold into the overall score.
//
// Pricing: $0.003 USDC, settled `exact` in USDC on Solana mainnet.
//
// Implementation: calls POST /api/social/sentiment-pulse on the three.ws
-// API surface. No keys are required — the endpoint relies on the public
-// pump.fun frontend-api-v3 replies route.
+// API surface. No keys are required: the endpoint reads the public
+// pump.fun frontend-api-v3 callout route. When that source is down and the
+// caller supplied no texts, the endpoint answers 502 and this tool reports
+// the outage instead of a fabricated neutral reading.
import { z } from 'zod';
@@ -18,7 +20,7 @@ import { resilientFetch } from '../lib/resilient-fetch.js';
const TOOL_NAME = 'sentiment_pulse';
const TOOL_DESCRIPTION =
- 'Sentiment pulse for a Solana token: fetches the most recent pump.fun comments via frontend-api-v3, optionally folds in caller-supplied snippets (e.g. recent X cashtag posts), and scores the combined stream with the three.ws deterministic lexicon. Returns overall + per-source breakdown with examples. Pairs naturally with pump_snapshot. Paid: $0.003 USDC.';
+ 'Sentiment pulse for a Solana token: fetches the coin\'s most recent pump.fun callouts (the community commentary the coin page renders) via frontend-api-v3, optionally folds in caller-supplied snippets (e.g. recent X cashtag posts), and scores the combined stream with the three.ws deterministic lexicon. Returns overall + per-source breakdown with examples. Pairs naturally with pump_snapshot. Paid: $0.003 USDC.';
function env(k, def) {
const v = process.env[k];
@@ -40,7 +42,7 @@ const inputZodShape = {
.max(44)
.refine((v) => SOLANA_MINT_RE.test(v), 'token must be a base58 Solana mint pubkey')
.describe('Solana SPL or pump.fun mint pubkey (base58).'),
- limit: z.number().int().min(1).max(200).describe('Max pump.fun comments to score.').optional(),
+ limit: z.number().int().min(1).max(200).describe('Max pump.fun callouts to score.').optional(),
extraTexts: z
.array(z.string().max(2000))
.max(200)
diff --git a/prompts/swarm-100/api-social-01.md b/prompts/swarm-100/api-social-01.md
deleted file mode 100644
index 3474cf9da..000000000
--- a/prompts/swarm-100/api-social-01.md
+++ /dev/null
@@ -1,102 +0,0 @@
-# API audit: api/social batch 01 (2 files)
-
-How to run: paste this file's repo path into a fresh Claude Code chat in this
-repository and say "run this work order". This file is fully self-contained:
-it depends on no other prompt file anywhere. If neighboring files in
-prompts/swarm-100/ are gone, that work is done; if present, ignore them.
-Every claim below rots; step 0 re-measures, and what you measure wins.
-
-## Operating clause (binding)
-
-- Read CLAUDE.md first. Its rules override everything, including this file.
-- Finish 100% in this session. Never end the turn with a question, an option
- list, or an unexecuted plan. A judgment call goes in one line of the final
- report; it never becomes a question that halts work.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real
- funds or any irreversible on-chain write, git push or a production deploy,
- committing content that references a crypto project other than $THREE, and
- destroying unrecoverable data.
-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no
- commented-out code. Real APIs and real integrations only.
-- The em-dash and en-dash characters are banned in everything you write.
-- Concurrent agents share this worktree: stage explicit paths only (never a
- bare add-everything), and commit finished work promptly.
-- Before committing, run: npm run check:rules -- --paths <files you touched>.
- It must exit 0.
-
-## Step 0: re-derive the current state
-
-1. Confirm each file below still exists; deleted ones are done, skip them.
-2. For each, decide routability: grep its path in vercel.json and read how
- server/index.mjs maps filesystem handlers. Routed files get an endpoint
- audit; internal modules get a code and test audit.
-3. Start a local server for endpoint checks: node server/index.mjs with .env
- loaded, on a free PORT if 3000 is busy.
-
-## Task: audit these api files, then fix everything found
-
-Files in this batch:
-
-- api/social/sentiment-pulse.js
-- api/social/sentiment.js
-
-For every routed handler:
-
-1. Exercise it with curl against the local server: the success path returns
- real data with the correct status; malformed input returns a 4xx JSON
- error, never a stack trace or an HTML error page; auth is enforced where
- the code intends it; CORS matches neighboring handlers.
-2. Hard-rule scan: no mock fallbacks, no fake-data arrays, no stubbed
- responses, no unfinished markers. Errors are handled at the boundary and
- internal code trusts itself.
-3. Do not spend funds or sign anything on-chain while probing. Payment and
- trading handlers get their validation and error paths exercised, never a
- live settlement.
-
-For every internal (non-routed) module:
-
-4. Something must import it; if nothing does, delete it as dead code (verify
- with a repo-wide grep first).
-5. Its main path and one failure path must be covered in tests/; add the
- missing test if not.
-
-## Definition of done
-
-- [ ] Every listed file has recorded evidence: a curl transcript for routed
- handlers, a passing test or a deletion for internal modules.
-- [ ] Zero hard-rule violations remain in these files.
-- [ ] vitest run passes; npm run check:rules -- --paths <touched files>
- exits 0.
-
-## Never blocked
-
-| Blocker | Resolution (act, do not ask) |
-|---|---|
-| Missing env var or credential | Check .env and .env.local, then the Cloud Run service env, then Secret Manager (the CLAUDE.md self-unblock playbook has the exact commands). If it truly exists nowhere, wire the code fully behind the env var, prove the wiring with a dry run, and name the single missing var in the report. |
-| gcloud not on PATH | Run: export PATH="$HOME/google-cloud-sdk/bin:$PATH" |
-| Dev server port 3000 busy | Another agent may be serving this repo; probe it and reuse if so. Otherwise start your own on a free port: npx vite --port 3101 |
-| Playwright browser missing | npx playwright install chromium |
-| A surface needs a signed-in user | Register a fresh account through the real /register flow against the real API and use it. Never mock the session. |
-| A defect sits in code you did not touch | Fix it if it blocks a Definition of done line (root cause it, never mask it). Otherwise note it in the report and continue. |
-| An unrelated test is red | Same rule. Never pipe npm test through tail; it masks exit codes. |
-
-## Close out (required)
-
-1. Verify every Definition of done line with the actual command output in
- front of you. Never claim a line you did not verify.
-2. Commit with explicit paths and a subject that describes the diff (house
- style: type(scope): what changed and why a reader cares).
-3. Delete this prompt file in that same commit:
-
- git rm prompts/swarm-100/api-social-01.md
-
- The shrinking directory is this campaign's only progress ledger; there is
- no progress log to update.
-4. Final report: what step 0 measured, what changed (file list), evidence per
- Definition of done line, and any one-line judgment calls. No trailing
- questions, no unexecuted plans.
-
-If a line genuinely cannot pass inside this session (an external party must
-respond, or an owner-gated action is the final step), finish everything else,
-leave this file in place, and state exactly which line remains and who owns
-it. Never delete this file on a partial.