Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.1.0
info:
title: HostDeFi Token Risk API
version: 1.0.0
description: 'Public product surface of the scam-check-api service: the /v1 Token Risk API (same proprietary
A+–F Safety Read rendered on the HostDeFi token pages, plus pre-graduation on-chain signals for Solana),
key purchase/usage endpoints, and the free contract scanner at POST /analyze-token. Keyless callers
get a per-IP fair-use tier of 100 calls/day on the verdict endpoints; paid API keys (bought with SOL
via POST /v1/keys) raise the quota and unlock batch. Send an API key as the `x-api-key` header.'
contact:
url: https://hostdefi.com/docs/api/
email: trustdex.app@gmail.com
servers:
- url: https://hostdefi.com/api
description: 'Canonical branded base — /v1/* served via the hostdefi.com edge (use this in new integrations).
Note: /analyze-token is exposed here as POST /api/scan.'
- url: https://awake-integrity-production-faa0.up.railway.app
description: Origin host (Railway) — keeps working for existing integrations; all paths incl. /analyze-token.
security:
- {}
- ApiKeyHeader: []
paths:
/v1/token-risk/{chain}/{address}:
get:
summary: Token risk verdict by explicit chain + address
operationId: getTokenRisk
security:
- {}
- ApiKeyHeader: []
parameters:
- name: chain
in: path
required: true
schema:
type: string
description: Chain id, e.g. solana, ethereum, bsc, base, arbitrum, optimism, polygon, avalanche.
example: solana
- name: address
in: path
required: true
schema:
type: string
description: Token contract address (Solana mint or 0x EVM address).
example: DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
responses:
'200':
description: Verdict. Cacheable for 60s (`public` when keyless, `private` when keyed).
content:
application/json:
schema:
$ref: '#/components/schemas/Verdict'
'400':
$ref: '#/components/responses/V1Error'
'401':
$ref: '#/components/responses/V1Error'
'429':
$ref: '#/components/responses/V1RateLimited'
'500':
$ref: '#/components/responses/V1Error'
/v1/token-risk:
post:
summary: Token risk verdict by free-form query (address or name/ticker)
operationId: postTokenRisk
security:
- {}
- ApiKeyHeader: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
query:
type: string
description: A token contract address, or a name/ticker (resolved to the deepest-liquidity
match). `address` is accepted as an alias.
address:
type: string
description: Alias for `query`.
example:
query: BONK
responses:
'200':
description: Verdict. Cacheable for 60s (`public` when keyless, `private` when keyed).
content:
application/json:
schema:
$ref: '#/components/schemas/Verdict'
'400':
$ref: '#/components/responses/V1Error'
'401':
$ref: '#/components/responses/V1Error'
'404':
$ref: '#/components/responses/V1Error'
'429':
$ref: '#/components/responses/V1RateLimited'
'500':
$ref: '#/components/responses/V1Error'
/v1/token-risk/batch:
post:
summary: Batch token risk verdicts (Pro/Scale plans only)
description: 'Up to 10 items per call, keyed plans with batch access only (Pro and Scale — `batch:
true` in /v1/health''s plan table). Each attempted item counts against the key quota (an item
rejected up front for a missing address is not metered). Results preserve input order; a failing
item becomes a per-item error object instead of failing the whole batch. Keyless callers get 402;
keyed plans without batch get 403.'
operationId: postTokenRiskBatch
security:
- ApiKeyHeader: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
minItems: 1
maxItems: 10
items:
type: object
required:
- address
properties:
chain:
type:
- string
- 'null'
description: Optional chain id; inferred from the address/market data when omitted.
address:
type: string
description: Token contract address.
example:
items:
- chain: solana
address: DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
- chain: ethereum
address: '0x6982508145454Ce325dDbE47a25d4ec3d2311933'
responses:
'200':
description: 'Per-item results in input order. `Cache-Control: private, max-age=60`.'
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
const: true
plan:
type: string
description: Plan id of the calling key (month or year).
remaining:
type: integer
description: Calls remaining on the key's quota after this batch.
results:
type: array
description: One entry per input item, same order. Either a full verdict or a per-item
error object.
items:
oneOf:
- $ref: '#/components/schemas/Verdict'
- $ref: '#/components/schemas/BatchItemError'
'400':
$ref: '#/components/responses/V1Error'
'401':
$ref: '#/components/responses/V1Error'
'402':
description: No API key — batch is a paid feature (Pro/Scale). See https://hostdefi.com/docs/api/.
content:
application/json:
schema:
$ref: '#/components/schemas/V1ErrorBody'
'403':
description: Keyed plan without batch access (Builder). See https://hostdefi.com/docs/api/.
content:
application/json:
schema:
$ref: '#/components/schemas/V1ErrorBody'
'429':
$ref: '#/components/responses/V1RateLimited'
'500':
$ref: '#/components/responses/V1Error'
/v1/keys:
post:
summary: Buy an API key with a confirmed SOL payment
description: Verifies the payment signature on-chain (balance delta on the recipient wallet) and
mints an API key for the chosen plan. A signature can be redeemed exactly once, for either a web
pass or an API key.
operationId: postKeys
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- signature
- plan
properties:
signature:
type: string
description: Base58 Solana transaction signature of the payment (64–100 chars).
plan:
type: string
enum:
- week
- month
- year
description: week = Builder, month = Pro, year = Scale.
reference:
type:
- string
- 'null'
description: Optional base58 reference key that must appear on the transaction.
responses:
'200':
description: Key minted. The key is shown only once.
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
const: true
apiKey:
type: string
description: The new key (vx_ + 32 hex chars). Send it as the `x-api-key` header.
plan:
type: string
enum:
- week
- month
- year
planName:
type: string
enum:
- Builder
- Pro
- Scale
quota:
type: integer
description: Total calls included for the key's lifetime.
batch:
type: boolean
description: Whether the plan may call /v1/token-risk/batch.
expiresAt:
type: integer
description: Unix ms timestamp when the key expires.
note:
type: string
'202':
description: Payment not confirmed on-chain yet — retry shortly.
content:
application/json:
schema:
$ref: '#/components/schemas/V1ErrorBody'
'400':
$ref: '#/components/responses/V1Error'
'409':
description: This payment signature has already been redeemed.
content:
application/json:
schema:
$ref: '#/components/schemas/V1ErrorBody'
'500':
$ref: '#/components/responses/V1Error'
/v1/usage:
get:
summary: Usage and quota for an API key
operationId: getUsage
security:
- ApiKeyHeader: []
parameters:
- name: apiKey
in: query
required: false
schema:
type: string
description: Alternative to the `x-api-key` header.
responses:
'200':
description: Current usage for the key.
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
const: true
plan:
type: string
enum:
- week
- month
- year
planName:
type: string
enum:
- Builder
- Pro
- Scale
batch:
type: boolean
quota:
type: integer
used:
type: integer
remaining:
type: integer
expiresAt:
type: integer
description: Unix ms timestamp when the key expires.
'401':
$ref: '#/components/responses/V1Error'
/v1/health:
get:
summary: Liveness, plan table, and upstream configuration
operationId: getHealth
responses:
'200':
description: Service health and public configuration.
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
const: true
nexusConfigured:
type: boolean
description: Whether Solana pre-graduation on-chain signals are available.
goplusChains:
type: array
items:
type: string
description: EVM chains covered by security data.
plans:
type: object
description: Plan table keyed by plan id (week/month/year).
additionalProperties:
type: object
properties:
sol:
type: number
description: Price in SOL.
days:
type: integer
quota:
type: integer
batch:
type: boolean
label:
type: string
freeTier:
type: object
properties:
perIpPerDay:
type: integer
const: 100
/analyze-token:
servers:
- url: https://awake-integrity-production-faa0.up.railway.app
description: Railway origin only — this path is not proxied on the branded base. On hostdefi.com
the same handler is POST /api/scan (the /scan entry in this spec).
post:
summary: Free contract scanner (100/day/IP fair-use, no key required)
description: The free web scanner behind the HostDeFi token pages. No paywall — the per-IP fair-use
cap of 100 checks/day (honest 429) is the only limiter. Accepts a contract address, or an exact
token name/ticker (resolved to the top-liquidity match). Response combines an AI risk narrative
(with a deterministic data-driven fallback when the AI budget is exhausted) with DexScreener/CoinGecko
market metrics and on-chain contract permission reads.
operationId: postAnalyzeToken
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
text:
type: string
description: Token contract address, or an exact token name/ticker. `tokenAddress` is
accepted as an alias.
tokenAddress:
type: string
description: Alias for `text`.
example:
text: So11111111111111111111111111111111111111112
responses:
'200':
$ref: '#/components/responses/ScannerResult'
'400':
$ref: '#/components/responses/ScannerBadRequest'
'404':
$ref: '#/components/responses/ScannerNotFound'
'429':
$ref: '#/components/responses/ScannerRateLimited'
'500':
$ref: '#/components/responses/ScannerServerError'
'504':
$ref: '#/components/responses/ScannerTimeout'
/scan:
servers:
- url: https://hostdefi.com/api
description: Branded edge only — POST https://hostdefi.com/api/scan reaches the same handler as
POST /analyze-token on the Railway origin.
post:
summary: Free contract scanner — branded alias of POST /analyze-token
description: Identical handler to POST /analyze-token, exposed on the hostdefi.com edge as POST
/api/scan. Same request shape, responses, and 100/day/IP fair-use cap.
operationId: postScan
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
text:
type: string
description: Token contract address, or an exact token name/ticker. `tokenAddress` is
accepted as an alias.
tokenAddress:
type: string
description: Alias for `text`.
example:
text: So11111111111111111111111111111111111111112
responses:
'200':
$ref: '#/components/responses/ScannerResult'
'400':
$ref: '#/components/responses/ScannerBadRequest'
'404':
$ref: '#/components/responses/ScannerNotFound'
'429':
$ref: '#/components/responses/ScannerRateLimited'
'500':
$ref: '#/components/responses/ScannerServerError'
'504':
$ref: '#/components/responses/ScannerTimeout'
/v1/x402/token-risk/{chain}/{address}:
get:
summary: Token risk verdict, paid per call via x402
description: 'Machine-payable twin of the standard route for AI agents and bots: no key, no account,
no signup. First call returns HTTP 402 with payment options (x402 protocol v1, USDC on Solana
via an accountless facilitator); pay and retry with the X-PAYMENT header to receive the verdict.
You are charged only when a verdict is actually returned: server errors are never charged, and
a failed settlement withholds the response. Prices: see GET /v1/x402/pricing. The free tier (100/day/IP)
and API keys remain the better deal for humans and steady integrations.'
tags:
- x402 (machine-payable)
parameters:
- name: chain
in: path
required: true
schema:
type: string
description: Chain id, e.g. solana, ethereum, bsc, base, arbitrum, optimism, polygon, avalanche.
example: solana
- name: address
in: path
required: true
schema:
type: string
description: Token contract address (Solana mint or 0x EVM address).
example: DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
responses:
'200':
description: 'Verdict. Settled payment is confirmed by the X-PAYMENT-RESPONSE header (base64
JSON: payer, transaction signature, network) and meta.x402.'
headers:
X-PAYMENT-RESPONSE:
schema:
type: string
description: base64-encoded JSON settlement receipt.
content:
application/json:
schema:
$ref: '#/components/schemas/Verdict'
'402':
$ref: '#/components/responses/X402PaymentRequired'
'503':
description: x402 lane disabled or facilitator unreachable - the free tier and API keys are
unaffected.
x-payment-info:
price:
currency: USD
mode: fixed
amount: '0.01'
protocols:
- x402: {}
security: []
/v1/x402/token-risk/history/{chain}/{address}:
get:
summary: Token safety history (dated daily rows), paid per call via x402
description: 'Longitudinal safety series for one token: dated daily grade/score/liquidity/volume/price
rows, oldest first — how the risk picture changed, not just where it stands. Rows are recorded
whenever a verdict is computed anywhere on the API (recording began 2026-08-16), so any verdict
call on a token starts its series. Machine-payable: first call returns HTTP 402 with payment options;
pay and retry with the X-PAYMENT header. Charged only when a non-empty series is returned — a
token with no recorded history answers an uncharged 404, and server errors are never charged.'
tags:
- x402 (machine-payable)
parameters:
- name: chain
in: path
required: true
schema:
type: string
description: Chain id, e.g. solana, ethereum, base, arbitrum.
example: solana
- name: address
in: path
required: true
schema:
type: string
description: Token contract address (Solana mint or 0x EVM address; EVM matches case-insensitively).
example: DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 365
description: 'Daily rows returned: the most recent N days, oldest first (default 90).'
example: 90
responses:
'200':
description: The dated series. Settled payment is confirmed by the X-PAYMENT-RESPONSE header
and meta.x402. Each row carries the ts it was computed at.
headers:
X-PAYMENT-RESPONSE:
schema:
type: string
description: base64-encoded JSON settlement receipt.
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
chain:
type: string
address:
type: string
count:
type: integer
rows:
type: array
items:
type: object
properties:
ts:
type: string
grade:
type: string
nullable: true
score:
type: number
nullable: true
liquidityUsd:
type: number
nullable: true
volume24h:
type: number
nullable: true
priceUsd:
type: number
nullable: true
'402':
$ref: '#/components/responses/X402PaymentRequired'
'404':
description: No recorded history for this token yet - nothing was charged. Any verdict call
on it starts the series.
'503':
description: x402 lane disabled or facilitator unreachable - the free tier and API keys are
unaffected.
x-payment-info:
price:
currency: USD
mode: fixed
amount: '0.02'
protocols:
- x402: {}
security: []
/v1/x402/token-risk:
post:
summary: Token risk verdict by free-form query, paid per call via x402
description: 'Machine-payable twin of the standard route for AI agents and bots: no key, no account,
no signup. First call returns HTTP 402 with payment options (x402 protocol v1, USDC on Solana
via an accountless facilitator); pay and retry with the X-PAYMENT header to receive the verdict.
You are charged only when a verdict is actually returned: server errors are never charged, and
a failed settlement withholds the response. Prices: see GET /v1/x402/pricing. The free tier (100/day/IP)
and API keys remain the better deal for humans and steady integrations.'
tags:
- x402 (machine-payable)
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
query:
type: string
description: A token contract address, or a name/ticker (resolved to the deepest-liquidity
match). `address` is accepted as an alias.
address:
type: string
description: Alias for `query`.
example:
query: BONK
responses:
'200':
description: 'Verdict. Settled payment is confirmed by the X-PAYMENT-RESPONSE header (base64
JSON: payer, transaction signature, network) and meta.x402.'
headers:
X-PAYMENT-RESPONSE:
schema:
type: string
description: base64-encoded JSON settlement receipt.
content:
application/json:
schema:
$ref: '#/components/schemas/Verdict'
'402':
$ref: '#/components/responses/X402PaymentRequired'
'503':
description: x402 lane disabled or facilitator unreachable - the free tier and API keys are
unaffected.
x-payment-info:
price:
currency: USD
mode: fixed
amount: '0.01'
protocols:
- x402: {}
security: []
/v1/x402/token-risk/batch:
post:
summary: Batch token risk verdicts, paid per call via x402
description: 'Machine-payable twin of the standard route for AI agents and bots: no key, no account,
no signup. First call returns HTTP 402 with payment options (x402 protocol v1, USDC on Solana
via an accountless facilitator); pay and retry with the X-PAYMENT header to receive the verdict.
You are charged only when a verdict is actually returned: server errors are never charged, and
a failed settlement withholds the response. Prices: see GET /v1/x402/pricing. The free tier (100/day/IP)
and API keys remain the better deal for humans and steady integrations. Batch is a flat price
per call for up to 10 items - no Pro/Scale plan needed on this lane.'
tags:
- x402 (machine-payable)
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
minItems: 1
maxItems: 10
items:
type: object
required:
- address
properties:
chain:
type:
- string
- 'null'
description: Optional chain id; inferred from the address/market data when omitted.
address:
type: string
description: Token contract address.
example:
items:
- chain: solana
address: DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
- chain: ethereum
address: '0x6982508145454Ce325dDbE47a25d4ec3d2311933'
responses:
'200':
description: Batch results in input order; a bad item is a per-item error object. Settlement
receipt in X-PAYMENT-RESPONSE.
headers:
X-PAYMENT-RESPONSE:
schema:
type: string
description: base64-encoded JSON settlement receipt.
content:
application/json:
schema:
type: object
'402':
$ref: '#/components/responses/X402PaymentRequired'
'503':
description: x402 lane disabled or facilitator unreachable - the free tier and API keys are
unaffected.
x-payment-info:
price:
currency: USD
mode: fixed
amount: '0.08'
protocols:
- x402: {}
security: []
/v1/x402/pricing:
get:
summary: x402 price sheet and resource catalog
description: 'Machine-readable catalog of every x402-payable resource: price in USD, asset, scheme,
and resource URL. Also served as the discovery manifest at /.well-known/x402. No payment or auth
required.'
tags:
- x402 (machine-payable)
responses:
'200':
description: Catalog.
content:
application/json:
schema:
type: object
security: []
/v1/x402/signals/solana/{mint}:
get:
summary: Pre-graduation signals for a Solana mint, paid per call via x402
description: 'The standalone premium signal set most risk APIs are blind to: bundled-launch detection,
curve-aware top-holder concentration, dangerous Token-2022 extensions, and mint/freeze authority
state. You are charged only when data is actually returned - 4xx/5xx outcomes are never settled.
Pay-per-call via x402 (see the token-risk twin routes for the flow).'
tags:
- x402 (machine-payable)
parameters:
- name: mint
in: path
required: true
schema:
type: string
description: Solana mint address (base58).
responses:
'200':
description: Result. Settlement receipt in the X-PAYMENT-RESPONSE header.
content:
application/json:
schema:
type: object
'402':
$ref: '#/components/responses/X402PaymentRequired'
'404':
description: No data for that input - nothing was charged.
'503':
description: Backend not configured / temporarily unavailable - nothing was charged.
x-payment-info:
price:
currency: USD
mode: fixed
amount: '0.03'
protocols:
- x402: {}
security: []
/v1/x402/authority/solana/{mint}:
get:
summary: Authority quick-check for a Solana mint, paid per call via x402
description: 'Cheap subset: mint/freeze authority state, dangerous Token-2022 extensions, top-10
holder concentration. You are charged only when data is actually returned - 4xx/5xx outcomes are
never settled. Pay-per-call via x402 (see the token-risk twin routes for the flow).'
tags:
- x402 (machine-payable)
parameters:
- name: mint
in: path
required: true
schema:
type: string
description: Solana mint address (base58).
responses:
'200':
description: Result. Settlement receipt in the X-PAYMENT-RESPONSE header.
content:
application/json:
schema:
type: object
'402':
$ref: '#/components/responses/X402PaymentRequired'
'404':
description: No data for that input - nothing was charged.
'503':
description: Backend not configured / temporarily unavailable - nothing was charged.
x-payment-info:
price:
currency: USD
mode: fixed
amount: '0.005'
protocols:
- x402: {}
security: []
/v1/x402/portfolio:
post:
summary: Solana wallet portfolio audit, paid per call via x402
description: Pass { wallet } (a Solana address); the wallet's largest token holdings (up to 10,
by token balance) each get the full risk verdict. Flat price per audit. You are charged only when
data is actually returned - 4xx/5xx outcomes are never settled. Pay-per-call via x402 (see the
token-risk twin routes for the flow).
tags:
- x402 (machine-payable)
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- wallet
properties:
wallet:
type: string
description: Solana wallet address (base58).
responses:
'200':
description: Result. Settlement receipt in the X-PAYMENT-RESPONSE header.
content:
application/json:
schema:
type: object
'402':
$ref: '#/components/responses/X402PaymentRequired'
'404':
description: No data for that input - nothing was charged.
'503':
description: Backend not configured / temporarily unavailable - nothing was charged.
x-payment-info:
price:
currency: USD
mode: fixed
amount: '0.08'
protocols:
- x402: {}
security: []
/v1/x402/radar:
get:
summary: Recent trend-radar alerts, paid per call via x402
description: Structured JSON of the most recent HostDeFi trend-radar alerts (big dated movers with
real market cap - the same public alerts posted to the owned Telegram/Bluesky lanes). Query param
limit (1-100, default 50). You are charged only when data is actually returned - 4xx/5xx outcomes
are never settled. Pay-per-call via x402 (see the token-risk twin routes for the flow).
tags:
- x402 (machine-payable)
responses:
'200':
description: Result. Settlement receipt in the X-PAYMENT-RESPONSE header.
content:
application/json:
schema:
type: object
'402':
$ref: '#/components/responses/X4
# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hostdefi/refs/heads/main/openapi/hostdefi-token-risk-api-openapi.yml