API Reference

Base URL: https://ipfs.hoodpump.live

No API key required for anything below, it's all public.

POST /api/launch/prepare

Pins your logo + project metadata to IPFS and signs the Agent NFT voucher needed for HoodPumpFactory.deploy(). See How Launching Works for where this fits in the overall flow.

Request: multipart/form-data

Field	Required	Notes
logo	Yes	Image file. Accepted: PNG, JPEG, WebP, GIF, SVG. Max 10MB.
name	Yes	Token name.
symbol	Yes	Token symbol.
description	No
twitter	No
telegram	No
website	No

Response: 200 OK

{
  "logoCid": "bafybe...",
  "projectCid": "bafybe...",
  "agentCid": "bafybe...",
  "agentSignature": "0x..."
}

agentCid is always equal to projectCid, the Agent NFT reuses the project's own metadata, there's no separate metadata pool for it.

Errors: 400 with { "error": "..." } for a missing/invalid logo, missing name, or missing symbol.

WARNING

The returned agentSignature is only valid for this exact metadata. Call this endpoint again if any field changes, and deploy soon after. Don't cache and reuse a voucher across unrelated launches.

GET /api/holders/:tokenAddress

Top holders for a deployed token, sourced from an on-chain indexer with a 30-second cache.

Query params: limit (optional, default 20, max 50)

Response: 200 OK

{
  "holders": [
    { "wallet_address": "0x...", "amount": "12345000000000000000000", "usd_value": "482.10" }
  ]
}

GET /api/health

Liveness check. Returns 200 OK with no meaningful body. Use it to confirm the API is reachable.

Analytics endpoints

Mounted under /analytics on the same base URL.

Endpoint	Returns
GET /analytics/api/trending	Tokens ranked by recent swap activity
GET /analytics/api/top-mc	Tokens ranked by market cap
GET /analytics/api/top-volume	Tokens ranked by trading volume
GET /analytics/api/total-volume	Platform-wide cumulative volume
GET /analytics/api/global-mc	Platform-wide cumulative market cap

Each token entry in trending / top-mc / top-volume looks like:

{
  "token_address": "0x...",
  "name": "Baby Tendies",
  "symbol": "BabyTendies",
  "ipfs_hash": "bafkrei...",
  "last_mc": "3980.6862",
  "price_usd": "0.000003980686245003",
  "deployer_address": "0x...",
  "deployed_at_timestamp": "2026-07-17T21:07:19Z",
  "token_type": 1,
  "fee": 30000,
  "paired_token": "0x...",
  "pool_id": "0x...",
  "distributor": "0x...",
  "buy_count": 397,
  "sell_count": 341,
  "agent_token_id": "7",
  "trend_score": "30",
  "swap_count_24h": "21"
}

deployed_at_timestamp is always an explicit UTC ISO string (...Z suffix). Parse it as UTC directly, don't assume local time.

Working code

See the integration examples repo for runnable scripts that call every endpoint above, plus the on-chain deploy() call that follows it.