> ## Documentation Index
> Fetch the complete documentation index at: https://coinstats.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Token Security

> Token security API for any token — honeypot, mint/blacklist, hidden-fee and upgradeable-proxy detection. Powered by Hexens. Risk score plus severity-ranked findings.

Anyone can deploy a token in minutes, and a large share of new tokens are built to take your users' money: contracts you can buy but never sell, hidden mint functions that dilute holders to zero, blacklists that freeze wallets, or "upgradeable" logic whose rules change after people ape in.

The CoinStats **token security** API (the Token Risks endpoint) screens a token's smart contract *before* a user buys or a bot routes into it. You get an overall risk score plus a severity-ranked list of findings, each with a plain-English explanation you can show directly in your UI.

<Note>**Endpoint:** `GET /token-risks` · **5000 credits** per request · `X-API-KEY` auth. See the [API reference](/openapi/token-risks) for the full schema.</Note>

## What "token risk" means

A token risk is a property of the contract that lets the deployer (or the code itself) harm holders — by seizing funds, blocking trades, silently changing balances, or changing the rules later. These are *logic-level* problems, not price or market problems: a token can have great volume and still be a honeypot.

## Risk categories

Every finding comes back with a `title`, a `severity`, a `value` (`"true"` = the risk is present), a plain-English `note`, and a technical `description`. The main categories:

<AccordionGroup>
  <Accordion title="Owner & centralization powers" icon="user-shield">
    The deployer keeps privileged control over the token or its funds.

    * **Centralized Mint** — *Dev can print new tokens anytime* (dilutes holders to zero).
    * **Centralized Burn** — *Dev can delete your tokens.*
    * **Balance Manipulation** — *Dev can secretly change your balance.*
    * **Unauthorized Token Approvals** — *Dev can spend your tokens without asking.*
    * **Asset Withdrawal** — *Dev can drain the contract's tokens.*
    * **ETH Balance Sweep** — *Dev can drain the contract's ETH.*
  </Accordion>

  <Accordion title="Trading restrictions" icon="ban">
    The contract can stop specific users (or everyone) from selling.

    * **Blacklist** — *Dev can block certain wallets from trading.*
    * **Whitelist** — *Only approved wallets can trade.*
    * **Blockable Transfer** — *Dev can stop you from sending tokens.*
    * **Pausable** — *Dev has a freeze button for all trades.*
    * **Cooldown checks** — *You need to wait before sending again.*
  </Accordion>

  <Accordion title="Fees & transfer integrity" icon="receipt">
    What you send isn't what arrives, or transfers aren't recorded faithfully.

    * **Hidden fees** — *Surprise taxes on every move.*
    * **Basic Transfer Fee** — *Hidden fee on each transfer.*
    * **Transfer event amount mismatch** — *What you see isn't what was sent.*
    * **No Transfer event emitted** — *Transfers happen without any record* (breaks explorers/indexers).
    * **Approval event not emitted** — *Approvals happen invisibly.*
  </Accordion>

  <Accordion title="Mutability & opacity" icon="code-branch">
    The contract can change after you buy, or is deliberately hard to verify.

    * **Proxy (Upgradeable)** / **Upgradeable** — *Rules can change after you buy / code can be swapped anytime.*
    * **Selfdestruct** — *Token can delete itself and your money.*
    * **External call in transfer** — *Hidden code executes during transfers.*
    * **Assembly usage in transfer** — *Code is complex and hard to verify.*
    * **Not fully ERC20 compliant** — *Token doesn't follow standard token rules.*
  </Accordion>
</AccordionGroup>

## How it works

Token Risks is powered by [Hexens](https://hexens.io) and its **Glider** engine. Instead of pattern-matching bytecode, Glider reasons over the contract's functions, execution paths, and dependencies to find logic-level threats. CoinStats then shapes the result into a stable response:

* **`score`** — overall risk, `0–100`. Higher means riskier.
* **`results[]`** — individual findings, each with `severity` (`critical` → `high` → `medium` → `low` → `minor`), a plain-English `note`, and a technical `description`.
* **`marketEndorsed`** — whether the token is endorsed by market consensus.
* **`ownershipRenounced`** — whether contract ownership has been renounced (no owner = many owner-powers can't be used).

Coverage spans EVM chains — Ethereum, BNB Chain, Polygon, Base, Arbitrum, Optimism, Avalanche, and more. Non-EVM tokens (e.g. Bitcoin) or contracts not yet indexed return an empty `results` list.

## Why it's better than the alternatives

Most token scanners are heuristic flag-lists: they miss logic-level scams or bury you in false positives. Per the [Glider benchmark](https://coinstats.app/blog/risks/), Glider caught **every critical threat with no false positives**, while competing tools missed **between 40% and 75%** of the same risks.

And because Token Risks runs on the same platform as prices, wallets, and portfolios, it's one API key and one integration — no separate security vendor to bolt on, and the same data that powers risk warnings for 1M+ CoinStats users.

## Using the API

Query by CoinStats `coinId` **or** a raw `contractAddress` + `chain` pair. Optional `sortBy=severity` orders findings critical → minor.

```bash theme={null}
# By CoinStats coin id
curl "https://api.coinstats.app/v1/token-risks?coinId=shiba-inu&sortBy=severity" \
  -H "X-API-KEY: YOUR_API_KEY"

# By contract address + chain
curl "https://api.coinstats.app/v1/token-risks?contractAddress=0xdac17f958d2ee523a2206206994597c13d831ec7&chain=ethereum" \
  -H "X-API-KEY: YOUR_API_KEY"
```

Example response (abridged):

```json theme={null}
{
  "score": 80,
  "marketEndorsed": true,
  "ownershipRenounced": false,
  "risksProviderUrl": "https://hexens.io/blog/glider-api-new-benchmark-in-smart-contract-security",
  "results": [
    {
      "key": "risk_blockable_transfer",
      "value": "true",
      "title": "Blockable Transfer",
      "subtitle": "Transfers can be blocked for specific senders using various checks",
      "note": "Dev can stop you from sending tokens",
      "description": "The token's transfer logic includes pausing / cooldown / large-amount checks that can freeze certain holders.",
      "severity": "medium"
    }
  ],
  "learnMoreUrl": "https://coinstats.app/blog/risks/"
}
```

<Warning>`value` uses the strings `"true"` / `"false"` (Hexens wire format). `"true"` means the risk **is present**. A `200` with an empty `results` array means no risk data is available for that token (non-EVM or not yet indexed) — not "safe".</Warning>

<CardGroup cols={2}>
  <Card title="Token Risks API Reference" icon="shield-halved" href="/openapi/token-risks">
    Full request/response schema, parameters, and try-it console.
  </Card>

  <Card title="How CoinStats scores token risk" icon="arrow-up-right-from-square" href="https://coinstats.app/blog/risks/">
    The Hexens Glider approach and the benchmark behind it.
  </Card>
</CardGroup>