Connect your agent: token-check API and MCP

What it is

The API reports the token page’s established contract verdict and the evidence and coverage behind it. Preflight adds a decision for a buy or sell request; it does not place a trade. Coverage varies by token, and a missing check is shown as missing.

The four decisions

Decision	Meaning	What an agent should do
allow	No blocking findings on the checks that ran.	Show the coverage and observation ages; make no broader assurance.
warn	Findings or missing, stale, or limited checks need review.	Relay the reasons and let the user review them. A blocked token on a sell returns warn with `exitOfBlocked: true`; selling remains an exit, though the contract may reject it.
block	The token page blocks a buy. The reasons name each blocking finding.	Do not offer a buy. Show the reasons and link to the token page.
unknown	A decision cannot be established yet.	Do not proceed as if it passed. Check `pending`, `errors`, and retry guidance.

Quick start

Replace the example token address, finding ID, and stock symbol with the one you want to check. sizeUsd is optional; chainId may be omitted, but if supplied it must be 4663.

curl -i 'https://hawkeyescan.xyz/api/v1/preflight?token=0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec&side=buy&sizeUsd=100&chainId=4663'
curl -i 'https://hawkeyescan.xyz/api/v1/token/0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec'
curl -i 'https://hawkeyescan.xyz/api/v1/finding/sim-transfer-reverts'
curl -i 'https://hawkeyescan.xyz/api/v1/stock/TSLA'
curl -i 'https://hawkeyescan.xyz/api/v1/openapi.json'

The token endpoint wraps buy and sell preflight responses in decisions. The preflight shape, shortened here, looks like this when every required check supports an allow decision:

{
  "decision": "allow",
  "headline": "No blocking findings on the checks that ran.",
  "reasons": [],
  "checks": {
    "verdict": { "status": "ran", "verdict": "OK", "ageSec": 45 }
  },
  "retryAfterSec": null
}

Each returned check object has ageSec; it is null when its observation time is unknown. The finding endpoint explains registered finding IDs. The stock endpoint reports an observed comparison, which can be unavailable or stale.

Status codes and retries

For preflight and token decisions, read the HTTP status as well as the JSON body:

Code	Meaning
200	Decided; a block can stay final while unrelated checks are pending.
202	Pending, with `Retry-After`; retry after that many seconds.
400	Bad input.
429	Rate limited, with `Retry-After`.
503	Our failure, with the unknown decision body; retry later.

No response is an empty 200. A 202 can still carry a partial decision; inspect pending and retryAfterSec. The finding and stock lookups can also return 404 for an unknown ID or symbol.

Limits

Up to 60 requests a minute per client. IPv6 clients count by /64. Uncached token loads are limited to 12 per 10 minutes per client and 60 per 10 minutes overall. Uncached loads wait their turn two at a time.

Remote MCP

Use https://hawkeyescan.xyz/mcp as a stateless, read-only Streamable HTTP endpoint. It returns JSON and supports protocol versions 2025-11-25, 2025-06-18, and 2025-03-26.

Tool	Inputs	Returns
`check_token`	`address`	Token checks and both buy and sell decisions.
`preflight_trade`	`address`, `side` (`buy` or `sell`), optional `size_usd`	The preflight decision.
`explain_finding`	`id`	A registered finding explanation.
`stock_fair_value`	`symbol`	The observed stock comparison and sweep age.

Claude Code

claude mcp add --transport http hawkeyescan https://hawkeyescan.xyz/mcp

Generic MCP configuration

{
  "mcpServers": {
    "hawkeyescan": {
      "type": "http",
      "url": "https://hawkeyescan.xyz/mcp"
    }
  }
}

In an AI app that accepts a remote MCP URL, add https://hawkeyescan.xyz/mcp as a custom connector.

Wording rules for agents

Never call a token safe. For allow, say exactly: “No blocking findings on the checks that ran.”
unknown is never a pass.
Identity findings, such as a name or ticker, only warn. Only behaviour findings can block: what the contract does, a proven liquidity pull, or a tokenised stock’s price gate.
Make no price predictions.
Do not describe a check as a trade. Hawkeyescan checks contract behaviour; it does not model a trade’s route or price impact.

Explore

Read the OpenAPI document, open an example token page, see the blocked tokens list, or learn how a verdict is made.