Getting Started

trends.fun tokens sit on Meteora bonding curves. When enough buy pressure fills the curve, the token “graduates” to a DEX pool and the price jumps. TrendSurfer predicts which tokens will graduate. Add this intelligence to any AI agent in 2 minutes.

$npm install trendsurfer-skill

Analyze any token in one call

agent.ts

import { TrendSurferSkill } from 'trendsurfer-skill'

const skill = new TrendSurferSkill({
  heliusApiKey: process.env.HELIUS_API_KEY,
})

// One-shot analysis — just pass a mint address
const { graduation, security, token } = await skill.analyzeByMint(
  'EK7NyRkRmstUZ49g9Z5a6Y3vFDywJu1cCph3SsRcvb8N'
)

console.log(token.name)              // → "CHILD HEALTH"
console.log(graduation.score)        // → 100 (0-100 scale)
console.log(graduation.curveProgress) // → 100.0 (% filled)
console.log(graduation.velocity)     // → "accelerating" | "steady" | "stagnant"
console.log(security.safe)           // → true (no honeypot/risks)
console.log(graduation.reasoning)    // → "Bonding curve is 100% filled..."

Or scan all launches and find the best ones

scanner.ts

// Scan for new launches, analyze each, find graduating tokens
const { launches } = await skill.scanLaunches()

for (const token of launches) {
  const analysis = await skill.analyzeGraduation(token)
  const security = await skill.checkSecurity(token.mint)

  if (analysis.score > 65 && security.safe) {
    console.log('🟢', token.symbol, 'score:', analysis.score)
    console.log('  ', analysis.reasoning)
  }
}

Installation

Install the SDK from npm and configure it with your Helius API key.

terminal

npm install trendsurfer-skill

Requirements

--Node.js 18 or later
--Helius API key (get one at helius.dev)
--Solana private key (only for trade execution)

Configuration

config.ts

import { TrendSurferSkill } from 'trendsurfer-skill'

const skill = new TrendSurferSkill({
  heliusApiKey: 'your-helius-api-key',
  poolConfigAddress: 'optional-trends-fun-config', // filter for trends.fun only
})

Parameters

heliusApiKeystring, required

Your Helius RPC API key for reading on-chain Meteora DBC state.

poolConfigAddressstring, optional

Filter launches to a specific pool config. Use the trends.fun config address to only track trends.fun tokens.

SDK Reference

All methods available on the TrendSurferSkill class, organized by category.

Scanning

scanLaunches(limit?: number)-> Promise<ScanResult>

Scan for new trends.fun token launches. Returns recently created tokens with bonding curve progress.

const { launches } = await skill.scanLaunches(10)

getLaunches()-> TokenLaunch[]

Get all cached/known launches from memory. No network call.

const launches = skill.getLaunches()

refreshLaunches()-> Promise<TokenLaunch[]>

Refresh bonding curve progress for all tracked launches from on-chain state.

const updated = await skill.refreshLaunches()

startPolling(callback: (launches: TokenLaunch[]) => void)-> void

Start continuous polling for new launches. Calls your callback whenever new tokens are detected.

skill.startPolling((launches) => {
  console.log('New launches:', launches.length)
})

stopPolling()-> void

Stop the continuous polling loop.

skill.stopPolling()

Analysis

analyzeByMint(mint: string)-> Promise<{ graduation, security, token }>

One-shot analysis from just a mint address. Finds the Meteora DBC pool, gets metadata, runs graduation + security analysis. The easiest way to analyze any token.

const { graduation, security, token } = await skill.analyzeByMint(mint)
// graduation.score → 87, security.safe → true

analyzeGraduation(launch: TokenLaunch)-> Promise<GraduationAnalysis>

Full graduation analysis for a token launch object. Use analyzeByMint() if you only have a mint address.

const analysis = await skill.analyzeGraduation(token)
// { score: 87, velocity: 'accelerating', reasoning: '...' }

recordSnapshot(mint: string, progress: number)-> void

Record a velocity snapshot for more accurate tracking over time.

skill.recordSnapshot(token.mint, 45.2)

getVelocity(mint: string)-> VelocityData

Get current bonding curve velocity data for a specific token.

const velocity = skill.getVelocity(mint)

getVelocityHistory(mint: string)-> VelocitySnapshot[]

Get the full velocity history for a token. Useful for charting curve progression.

const history = skill.getVelocityHistory(mint)

Security

checkSecurity(mint: string)-> Promise<SecurityCheck>

Check token safety on-chain. Detects honeypots, mint/freeze authority, and other warnings.

const security = await skill.checkSecurity(mint)
if (security.safe) { /* proceed */ }

Trading

getQuote(params: QuoteParams)-> Promise<SwapQuote>

Get a swap quote for buying or selling a token on Meteora DBC.

const quote = await skill.getQuote({
  tokenMint: mint,
  side: 'buy',
  amount: '0.1',
  walletAddress: myWallet,
})

executeTrade(params: TradeParams)-> Promise<TradeExecution>

Execute a trade on Meteora DBC. Handles quote, confirm, sign, and send.

const trade = await skill.executeTrade({
  tokenMint: mint,
  side: 'buy',
  amountSol: '0.1',
  walletAddress: myWallet,
  signTransaction: mySigner,
})

getTradeStatus(orderId: string)-> Promise<OrderStatus>

Check the execution status of a previously submitted trade.

const status = await skill.getTradeStatus(trade.orderId)

Utility

addPool(launch: TokenLaunch)-> void

Manually add a known pool to the tracking list.

skill.addPool({ mint: '...', pool: '...' })

clearCache()-> void

Clear all cached launch and velocity data.

skill.clearCache()

destroy()-> void

Destroy the skill instance. Stops polling and cleans up all resources.

skill.destroy()

MCP Server

Use TrendSurfer as a Model Context Protocol server. Works with Claude Desktop, GPT, or any MCP-compatible agent framework.

Run the server

$npx trendsurfer-mcp

Claude Desktop configuration

claude_desktop_config.json

{
  "mcpServers": {
    "trendsurfer": {
      "command": "npx",
      "args": ["trendsurfer-mcp"],
      "env": {
        "HELIUS_API_KEY": "your-key-here"
      }
    }
  }
}

Available tools

ToolDescriptionReturns

analyze_by_mint

Analyze any token by mint address. Finds pool, checks graduation + security. The main tool.

{ graduation, security, token }

scan_launches

Scan trends.fun for new token launches with bonding curve progress.

ScanResult

analyze_graduation

Full graduation analysis (requires poolAddress). Use analyze_by_mint if you only have a mint.

GraduationAnalysis

check_security

Check token security (honeypot, mint/freeze authority).

SecurityCheck

get_quote

Get a swap quote for a token on Meteora DBC.

SwapQuote

get_launches

Get all currently tracked and cached token launches with latest curve data.

TokenLaunch[]

refresh_launches

Refresh bonding curve progress for all tracked launches from on-chain state.

TokenLaunch[]

score_dev_wallet

Score a token creator's wallet risk using GoldRush (Covalent). Returns wallet age, portfolio, activity, and risk level.

CreatorProfile

x402 API

Pay-per-call AI analysis via the x402 protocol. No API keys, no accounts. Just HTTP and USDC.

Try it: Visit the endpoint in your browser — you'll get a 402 response with payment requirements. That's the x402 protocol in action. Agents parse this response, pay the USDC amount, and retry to get the data.

Endpoint

https://solana-trends-agent.vercel.app/api/intelligence

Price

$0.001 USDC per call

Network

Solana mainnet USDC

Query parameters

mintstring, required

The token mint address to analyze.

How it works

Send a request without payment headers

curl https://solana-trends-agent.vercel.app/api/intelligence?mint=YOUR_MINT

Receive 402 with payment requirements in response headers

402 Payment Required + X-Payment-Required header

Pay $0.001 USDC on Solana and retry with signed transaction

X-Payment: <signed-transaction>

Receive full AI graduation analysis

200 OK

Example

x402-flow.ts

HTTP 402

// 1. Request analysis (no payment header)
const res = await fetch('/api/intelligence?mint=So1...')
// -> 402 Payment Required + X-Payment-Required header

// 2. Pay $0.001 USDC on Solana and retry
const paid = await fetch('/api/intelligence?mint=So1...', {
  headers: { 'X-Payment': signedTx }
})
// -> 200 OK

// 3. Response
const data = await paid.json()
// {
//   score: 87,
//   velocity: 'accelerating',
//   reasoning: 'High curve velocity + viral tweet...',
//   prediction: 'likely_graduate'
// }

Architecture

TrendSurfer sits between your agent and the Solana blockchain, providing structured intelligence about trends.fun token launches. AI analysis powered by CommonStack. Creator wallet risk scoring by GoldRush.

Your Agent

Claude, GPT, any LLM

TrendSurfer

SDK or MCP Server

CommonStack AI

Graduation Scoring

Helius RPC

On-Chain Data

Solana

Meteora DBC