[Reference]

API Reference

A single endpoint runs a full scan: validation, market data, holder data, scoring, and the AI summary, returned as one JSON response.

[ Note ]

No authentication, API key, or rate limiting is enforced by Knovo itself. If you build a client that calls this endpoint programmatically at volume, add your own request throttling.

POST /api/analyze

/api/token/analyze is kept as an alias that re-exports the same handler for backward compatibility; both routes behave identically.

Request body

Field	Type	Required	Description
`address`	string	Yes	A token contract address. EVM: 0x followed by 40 hex characters. Solana: base58, 32-44 characters.

POST /api/analyze
Content-Type: application/json

{
  "address": "0x71C9c4b4Fa4A2b9e9f9c2e8B3A1D6C5F4E3D2A1B"
}

Success response: 200

Returns { data: TokenAnalysisResult }. Fields are grouped by section below; all money values are plain numbers in USD unless noted.

token

Field	Type	Description
address	string	The resolved base token address
symbol	string	Token symbol, or "Unknown" if unavailable
name	string	Token name, or "Unknown" if unavailable
chain	string	Dexscreener chain id, e.g. "ethereum", "solana", "base"

liquidityBreakdown

Field	Type	Description
dexName	string	Formatted DEX name for the primary pair
pairAddress	string	The primary trading pair's address
baseToken / quoteToken	string	Symbols of the primary pair
priceUsd	number \| null	Current token price in USD
marketCapUsd	number \| null	Market cap, falling back to FDV when market cap is unavailable
liquidityUsd	number	USD liquidity in the primary pool
liquidityBase / liquidityQuote	number	Pool-side liquidity in base/quote token units
chainLiquidityUsd	number	Combined liquidity across all pairs on the same chain
chainTopDexName / chainTopPairAddress	string	Deepest DEX/pair on that chain
volume24h, volumeM5, volumeH1, volumeH6	number	Trading volume over each window
priceChange24h, priceChangeM5, priceChangeH1, priceChangeH6	number	Percent price change over each window
poolAgeHours	number \| null	Hours since the pair was created

activityAnalysis

Field	Type	Description
buysM5 / sellsM5 / buysH1 / sellsH1 / buysH6 / sellsH6 / buys24h / sells24h	number \| null	Transaction counts per window
summary	string	One-line human summary of 24h buy/sell counts

holderDistribution

null when holder data isn't available (unsupported chain, missing MORALIS_API_KEY, or a failed lookup).

Field	Type	Description
holderCount	number	Total known holders
topHolderPercent	number	% of supply held by the single largest wallet
top10Percent	number	% of supply held by the top 10 wallets combined
supply	number \| null	Total supply, when resolvable

analystReport

Field	Type	Description
whatHappened	string	Factual recap of the market snapshot
whyItMatters	string	The AI-generated (or fallback) risk summary
whatToVerifyNext	string[]	Suggested follow-up checks, including active penalties if any
finalVerdict	string	Top risk reason plus a note on what the score reflects

Top-level fields

Field	Type	Description
riskScore	number	0-100 score; see Risk Score Methodology
riskVerdict	string	Reserved for a future short-label verdict. Currently always an empty string.
launchIntelligence	object \| null	Reserved for future launch-forensics data. Currently always null.
scoreBreakdown	object	Per-component points; see Risk Score Methodology
scorePenalties	string[]	Penalty labels that applied to this scan
summary	string	The same value as analystReport.whyItMatters
dataAvailability	string[]	Notes about data that couldn't be fetched, e.g. "On-chain holder data unavailable"

Example response

{
  "data": {
    "token": {
      "address": "0x71C9...4a2B",
      "symbol": "EXAMPLE",
      "name": "Example Token",
      "chain": "ethereum"
    },
    "launchIntelligence": null,
    "liquidityBreakdown": {
      "dexName": "Uniswap V3",
      "pairAddress": "0xabc...123",
      "baseToken": "EXAMPLE",
      "quoteToken": "WETH",
      "priceUsd": 0.00042,
      "marketCapUsd": 4200000,
      "liquidityUsd": 312000,
      "liquidityBase": 5000000,
      "liquidityQuote": 62,
      "chainLiquidityUsd": 312000,
      "chainTopDexName": "Uniswap V3",
      "chainTopPairAddress": "0xabc...123",
      "volume24h": 118500,
      "volumeM5": 620,
      "volumeH1": 8100,
      "volumeH6": 41000,
      "priceChange24h": -3.42,
      "priceChangeM5": 0.1,
      "priceChangeH1": -0.8,
      "priceChangeH6": -2.1,
      "poolAgeHours": 432.5
    },
    "activityAnalysis": {
      "buysM5": 3,
      "sellsM5": 1,
      "buysH1": 41,
      "sellsH1": 29,
      "buysH6": 210,
      "sellsH6": 188,
      "buys24h": 812,
      "sells24h": 749,
      "summary": "The pair recorded about 812 buys and 749 sells in the last 24 hours."
    },
    "holderDistribution": {
      "holderCount": 4981,
      "topHolderPercent": 3.2,
      "top10Percent": 24.6,
      "supply": 1000000000
    },
    "analystReport": {
      "whatHappened": "EXAMPLE is currently trading primarily on Uniswap V3 with about $312,000 of visible liquidity, 118,500 in 24h volume, and a -3.42% move over the last day. Estimated market cap sits near $4,200,000.",
      "whyItMatters": "Knovo Score is 82/100. Liquidity, maturity, and market structure all look comparatively strong.",
      "whatToVerifyNext": [
        "Track whether liquidity stays stable as volume rotates through the pool.",
        "Watch for abrupt price and activity shifts across the primary trading pair."
      ],
      "finalVerdict": "Liquidity, maturity, and market structure all look comparatively strong. Score reflects liquidity, holder concentration, activity, and market structure."
    },
    "riskScore": 82,
    "riskVerdict": "",
    "scoreBreakdown": {
      "liquidity": 16,
      "marketCap": 10,
      "holders": 18,
      "activity": 12,
      "pressure": 7,
      "volatility": 10,
      "pool": 5,
      "security": 10
    },
    "scorePenalties": [],
    "summary": "Knovo Score is 82/100. Liquidity, maturity, and market structure all look comparatively strong.",
    "dataAvailability": []
  }
}

Error responses

Status	Cause	Body
400	address missing from the request body	`{ "error": "Token contract address is required." }`
400	address doesn't match the EVM or Solana pattern	`{ "error": "Enter a valid token contract address (EVM 0x... or Solana base58)." }`
404	no Dexscreener pair found for the address	`{ "error": "No token data found for this contract address." }`
500	an unexpected error during processing	`{ "error": "<message or fallback text>" }`

Example request

curl -X POST https://www.knovo.xyz/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"address":"0x71C9c4b4Fa4A2b9e9f9c2e8B3A1D6C5F4E3D2A1B"}'

See Risk Score Methodology for how riskScore and scoreBreakdown are computed.
See Data Sources for what each upstream provider contributes and what happens when a key is missing.

← PreviousData Sources Next →FAQ