@sperax/tool-four-meme

BSC meme token launchpad — create, trade, and track tokens on four.meme

Four.meme is an agent tool from SperaxOS, packaged headless so you can call it from any agent framework. It ships two things: the manifest — a JSON-Schema function definition a model can call — and the executor that runs the call against the real API.

There is no UI layer and no framework lock-in. It works anywhere TypeScript runs.

Install

npm install @sperax/tool-four-meme

Usage

Call it directly

import { fourMemeExecutor } from '@sperax/tool-four-meme';

const result = await fourMemeExecutor.invoke('getConfig', {}, {
  messageId: 'msg-1',
});

console.log(result.content); // prose summary written for the model to read
console.log(result.state);   // typed data payload for your own UI

Give it to a model

import Anthropic from '@anthropic-ai/sdk';
import { FourMemeManifest, fourMemeExecutor } from '@sperax/tool-four-meme';

const client = new Anthropic();

const response = await client.messages.create({
  model: 'claude-opus-4-8',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Ask something this tool can answer' }],
  tools: FourMemeManifest.api.map((api) => ({
    name: api.name,
    description: api.description,
    input_schema: api.parameters,
  })),
});

for (const block of response.content) {
  if (block.type !== 'tool_use') continue;
  const result = await fourMemeExecutor.invoke(block.name, block.input, { messageId: response.id });
  console.log(result.content);
}

FourMemeManifest.api is already in JSON-Schema form, so it maps onto any tool-calling API — Anthropic, OpenAI, the Vercel AI SDK, or an MCP server — without translation.

Every executor returns a BuiltinToolResult — { success, content, state }. content is prose written for the model to read; state is the typed data payload for your own code. Executors never throw: a failed call comes back as { success: false, content: '<reason>' }, so a network blip degrades the answer instead of crashing the agent loop.

Configuration

None. This tool calls a public API directly and needs no key or origin configuration.

Tool identifier

sperax-four-meme

API reference

getConfig

Get Four.meme public platform config — raisedToken address, TokenManager2 and Helper3 contract addresses. Read-only, no auth required.

Takes no parameters.

getTokenInfo

Look up a Four.meme token by BSC contract address. Returns on-chain version, tokenManager, current price, total supply, and remaining offers via Helper3.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | tokenAddress | string | yes | BSC token contract address (0x…). |

tokenList

Browse Four.meme tokens with filters (name, symbol, label, graduated) and pagination. Returns a paginated list of tokens.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | labels | string | no | Filter by label: Meme, AI, Defi, Games, Infra, De-Sci, Social, Depin, Charity, Others. | | listedPancake | boolean | no | Filter to tokens that graduated to PancakeSwap. | | orderBy | string | no | Sort: Hot (trending), Time (newest), ProgressDesc (bonding progress), TradingDesc (24h volume), Graduated. | | pageIndex | number | no | Page number (1-based, default 1). | | pageSize | number | no | Results per page (default 30, max 100). | | symbol | string | no | Filter by token symbol. | | tokenName | string | no | Filter by token name. |

tokenGet

Get full detail and trading info for a specific Four.meme token by address. Returns name, symbol, description, image, trading data via REST API.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | tokenAddress | string | yes | BSC token contract address (0x…). |

tokenRankings

Get Four.meme token rankings. Supports: Hot (trending), TradingDesc (24h volume), Time (newest), ProgressDesc (bonding progress), Graduated.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | barType | string | no | Time window for TradingDesc ranking: HOUR24 (default). Only used with TradingDesc orderBy. | | orderBy | string | yes | Ranking type: Hot | TradingDesc | Time | ProgressDesc | Graduated. |

quoteBuy

Get a buy price quote for a Four.meme token. Estimate only — no transaction is executed. Pass amountWei (token amount to buy) or fundsWei (BNB to spend).

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | amountWei | string | yes | Token amount to buy in wei (use "0" if buying by funds instead). | | fundsWei | string | no | BNB amount to spend in wei (use "0" or omit if buying by amount). | | tokenAddress | string | yes | BSC token contract address (0x…). |

quoteSell

Get a sell price quote for a Four.meme token. Estimate only — no transaction is executed.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | amountWei | string | yes | Token amount to sell in wei. | | tokenAddress | string | yes | BSC token contract address (0x…). |

getEvents

Fetch recent on-chain events from Four.meme TokenManager2: TokenCreate, TokenPurchase, TokenSale, LiquidityAdded. Specify a block range on BSC.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | fromBlock | number | yes | Start block number on BSC. | | toBlock | number | no | End block number (optional, defaults to latest block). |

getTaxInfo

Get tax/fee info for a Four.meme TaxToken — feeRate, burnRate, divideRate, liquidityRate, recipientRate, recipientAddress, minSharing.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | tokenAddress | string | yes | BSC token contract address (0x…). |

getCreatorTokens

Profile a token creator on Four.meme. Returns all tokens launched by the creator with risk flags: abandonment rate, graduation rate, average bonding progress, and creator age. Use to assess rug-pull risk before trading.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | creatorAddress | string | yes | Creator wallet address (BSC, 0x…). | | limit | number | no | Max tokens to return (default 20). |

getTopHolders

Analyze token holder concentration on BSC. Returns top holders with balances and percentages, plus a risk assessment (low/medium/high/critical) based on top-5 and top-10 concentration. Use to detect whale risk or rug-pull setups.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | limit | number | no | Max holders to return (default 10). | | tokenAddress | string | yes | BSC token contract address (0x…). |

Types

Shared types come from @sperax/agent-tools-core: BuiltinToolManifest, BuiltinToolResult, BuiltinToolContext, and the BaseExecutor class every tool executor extends.

Related

• @sperax/agent-tools-core — the tool contract
• All SperaxOS agent tools — tool-four-meme is one of many
• SperaxOS — the agent workspace these tools were built for

License

Apache-2.0