← HostDeFi Home · Docs · Methodology · Precision report · Badges & embeds

HostDeFi Token Risk API

One call in, one verdict out. POST a token address and get back the same proprietary A+–F Safety Read that powers HostDeFi's token pages — a graded score with plain-English receipts of what was checked and, honestly, what could not be — plus the pre-graduation on-chain signals most risk APIs are blind to: bundled-launch detection, curve-aware holder concentration, and Token-2022 trap flags. Built for the people who scan tokens thousands of times a day: Solana trading bots, wallets, portfolio apps and DEX front-ends.

Base URL https://hostdefi.com/api — so the graded verdict lives at /api/v1/token-risk. (The legacy awake-integrity-production-faa0.up.railway.app host keeps working for existing integrations, but new code should use the hostdefi.com base — it is the one we guarantee.)

The verdict path never calls an LLM, so responses are fast and deterministic. All figures are computed from public on-chain and market data at request time and stamped with checkedAt.

Authentication & tiers

The free tier needs no key — just call the endpoint. It is rate-limited per IP, matching the "free, no signup" promise of the web scanner. For higher volume, batch access and the full pre-graduation signal set, buy an API key with SOL (see Getting a key) and send it as the x-api-key header.

Plan	Price	Requests	Batch
Free	—	100 / day per IP	—
Builder	0.15 SOL / week	10,000 / week	—
Pro	0.5 SOL / month	60,000 / month	✓
Scale	1.5 SOL / year	750,000 / year	✓
x402 (agents)	$0.01 / call in USDC	pay as you go — no key, no account	✓ ($0.08 flat, up to 10)

Prices are SOL-denominated and may be adjusted as the SOL price moves — check GET /v1/health for the current table.

Get a verdict

POST /v1/token-risk — body { "query": "<address or name/ticker>" }.
GET /v1/token-risk/:chain/:address — when you already know the chain (solana, ethereum, bsc, base, arbitrum, optimism, polygon, avalanche).

# Free tier — no key needed
curl -s https://hostdefi.com/api/v1/token-risk \
  -H 'Content-Type: application/json' \
  -d '{"query":"DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"}'

# Paid tier — send your key
curl -s https://hostdefi.com/api/v1/token-risk \
  -H 'Content-Type: application/json' -H 'x-api-key: vx_your_key' \
  -d '{"query":"WIF"}'

Response

{
  "ok": true,
  "token": { "chain": "solana", "address": "...", "name": "...", "symbol": "..." },
  "risk": {
    "graded": true,
    "score": 78, "grade": "B", "tier": "low",
    "verdict": "mint & freeze renounced · deep liquidity.",
    "knowns":   [ ["ok","Mint revoked"], ["ok","No freeze authority"], ["bad","Top-10 hold 41%"] ],
    "unknowns": [ "dev wallet", "launch bundling" ],
    "notGradedReason": null
  },
  "signals": {
    "authorities":        { "mintDisabled": true, "freezeDisabled": true },
    "token2022Extensions":{ "permanentDelegate": false, "transferHook": false, "pausable": false, "...": false },
    "holders":            { "top10Pct": 41.2, "curveExcluded": true },
    "launch":             { "bundled": false, "firstSlotTxs": 1, "preGraduation": false },
    "market":             { "liquidityUsd": 152000, "volume24h": 84000, "priceUsd": 0.0000123 }
  },
  "meta": { "checkedAt": "2026-08-08T...Z", "sources": ["dexscreener","verixia-onchain"],
            "partial": false, "plan": "free", "remaining": 97 }
}

On EVM chains the signals object carries evmSecurity instead (honeypot, buyTaxPct, sellTaxPct, mintable, pausable, blacklist, proxy, hiddenOwner, openSource), sourced from GoPlus.

The honesty contract

risk.graded can be false. A wrong grade is worse than no grade, so the engine refuses to grade a token that is too fresh or too under-described (e.g. authorities unknown). When that happens you still get every signal that is known — read notGradedReason.
unknowns is a real list. It names what could not be verified from public data (LP lock, deployer history, …) so you never mistake silence for a clean bill.
meta.partial: true means one enriching source was unreachable (e.g. the pre-graduation signal service); the verdict still stands on what was available.
The scoring is documented in the methodology, and its measured hit-rate is published in the self-grading precision report.

Why the pre-graduation signals matter

When a token launches on a bonding curve it has no DEX pool yet, so pool-based tools return nothing about it — exactly when a sniper most needs a read. HostDeFi reads the mint directly on-chain and returns, for brand-new tokens: bundled-launch detection (launch.bundled — supply split across wallets that all bought in the same block, which defeats naive concentration checks), curve-aware concentration (holders.top10Pct with the bonding-curve account excluded, so a healthy token doesn't read 99% held), and Token-2022 trap flags (token2022Extensions — permanent delegate, transfer hook, pausable and the rest). launch.preGraduation: true marks a token that is still on the curve.

Getting a key: pay with SOL

Send the plan amount in SOL to the HostDeFi wallet 47sLuYEAy1zVLvnXyVd4m2YxK2Vmffnzab3xX3j9wkc5 (0.15 / 0.5 / 1.5 SOL for Builder / Pro / Scale).
Once the transaction confirms, POST its signature to claim your key:

curl -s https://hostdefi.com/api/v1/keys \
  -H 'Content-Type: application/json' \
  -d '{"signature":"<your_tx_signature>","plan":"week"}'
# plan: "week" (Builder) | "month" (Pro) | "year" (Scale)
# -> { "ok": true, "apiKey": "vx_...", "plan": "week", "quota": 10000, "expiresAt": ... }

The payment is verified on-chain by balance delta and the signature is burned after one use. Store the key — it is shown only once. Check remaining quota any time:

curl -s https://hostdefi.com/api/v1/usage -H 'x-api-key: vx_your_key'
# -> { "ok": true, "plan": "week", "quota": 10000, "used": 132, "remaining": 9868, "expiresAt": ... }

AI agents: pay per call with x402

Agents and bots that can't do signups can pay per request instead — no key, no account. The API speaks the x402 protocol (v1): call a paid twin route under /v1/x402/, get HTTP 402 with payment options (USDC on Solana), pay, and retry with the X-PAYMENT header. Any standard x402 client does the whole loop automatically:

import { wrapFetchWithPayment } from "x402-fetch";   // the standard x402 client

const payingFetch = wrapFetchWithPayment(fetch, yourWalletSigner);
const res = await payingFetch(
  "https://hostdefi.com/api/v1/x402/token-risk/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263");
const verdict = await res.json();                     // same A+–F Safety Read as every other tier

Paid twins: GET /v1/x402/token-risk/:chain/:address · POST /v1/x402/token-risk (free-form query) · POST /v1/x402/token-risk/batch (flat price, up to 10 items — no plan needed on this lane). Agent-only extras: GET /v1/x402/signals/solana/:mint (the standalone pre-graduation signal set, $0.03) · GET /v1/x402/authority/solana/:mint (authority quick-check, $0.005) · POST /v1/x402/portfolio (wallet audit — largest holdings graded, $0.08) · GET /v1/x402/radar (recent trend-radar alerts as JSON, $0.01). Live price sheet: GET /v1/x402/pricing; discovery manifest at https://hostdefi.com/.well-known/x402.

Bulk data products (same pay-per-call lane, dated weekly-snapshot data): GET /v1/x402/obituaries (the rug/collapse gate-exit ledger, $0.02) · GET /v1/x402/listings/:chain (graded token listing — solana, ethereum, base or arbitrum, $0.05) · GET /v1/x402/datasets/safety-snapshot (the full weekly safety dataset in one call, $0.25) · GET /v1/x402/radar/history (full retained radar alert history, $0.03). And with one x402 payment, POST /v1/x402/keys ($5) mints a 30-day Agent-plan API key (5,000 calls, batch enabled) — the key arrives in the paid response; no account, no signup. Offers now include USDC on Base, Polygon, Arbitrum and Avalanche rails alongside Solana where available.

Agent frameworks that speak MCP can use the same tools natively: point any MCP client at the streamable-HTTP server https://hostdefi.com/api/v1/mcp — six tools (verdicts, pre-grad signals, radar, provider-risk, key purchase, free pricing), same x402 pay-per-call flow, same charge-on-success contract.

Paying other x402 sellers too? Vet them first: GET /v1/x402/provider-risk?resource={url} ($0.02) grades any crawled x402 seller A–F from observable signals (402-spec fidelity, price sanity, payTo presence, TLS, latency), and GET /v1/x402/provider-risk/all ($0.10) returns the full dated dataset.

Agents can also trade, not just read: GET /v1/x402/swap/evm/quote ($0.01) returns a firm KyberSwap-routed EVM swap quote plus a ready-to-sign transaction for your own wallet — pass chainId, sellToken and buyToken (native or a 0x… address), sellAmount in base units and taker (your address). Non-custodial: you sign and broadcast; we never hold funds. A 3% platform fee in the chain's native coin is priced into the returned transaction, on top of the swap. GET /v1/x402/swap/evm/price ($0.002) is the cheap preview (expected + minimum output) before committing. A pair with no route answers an uncharged 404, never a paid empty answer.

Fair-charging contract: you are charged only when a verdict is actually returned. Server errors are never charged, and if settlement fails the response is withheld. The settlement receipt (payer, transaction signature) comes back in the X-PAYMENT-RESPONSE header and meta.x402. Doing steady volume? An API key above is the cheaper per-call price — x402 is the zero-commitment lane.

Status codes

Code	Meaning
`200`	Verdict returned (may be `graded:false` or `partial:true` — read the body).
`202`	`/v1/keys`: the payment is not confirmed yet — retry shortly.
`400`	Missing/invalid input.
`401`	Invalid or expired API key.
`404`	Could not resolve that token.
`402`	`/v1/x402/*`: payment required (or the payment failed verification/settlement) — the body carries the x402 payment options; pay and retry with `X-PAYMENT`.
`409`	`/v1/keys`: that payment signature was already redeemed.
`429`	Free fair-use limit (100/day) or plan quota reached — the body says which, with a reset time, plus an `x402` block showing the pay-per-call way to continue immediately.

Notes & limits

The free web scanner at hostdefi.com/scan stays free and unlimited — the API is additive.
EVM security fields come from GoPlus and may be cached up to ~10 minutes.
This is on-chain risk data, not financial advice. A high grade is never a guarantee.
Questions or a higher tier: @hostdefiapps or Telegram.