# TokenVet — token due-diligence for agents

You are reading the machine-facing manual for TokenVet, a pay-per-call API that
answers one question: **is this token safe to buy?**

Base URL: this site's origin. All endpoints are `GET` with query parameters and
return JSON. Paid endpoints use the **x402 protocol** — USDC on Base mainnet
(`eip155:8453`). On a `402 Payment Required` response, read the base64
`payment-required` response header, settle with any x402 client
(x402-fetch, AgentCash, Coinbase AgentKit, etc.), and retry with the
`payment-signature` header. No accounts, no API keys.

## Endpoints

### `GET /api/vet` — $0.25 · full due-diligence report
`?token=0x<address>&chain=base|ethereum|bsc` (chain defaults to `base`)

Returns a scored report:

- `verdict` — `PASS` | `CAUTION` | `FAIL` | `UNKNOWN`. Treat `FAIL` as do-not-buy.
- `score` — 0–100 safety score.
- `flags[]` — typed findings `{severity, code, detail}`. Severities: `critical`,
  `high`, `medium`, `info`. Codes include `HONEYPOT`, `EXTREME_SELL_TAX`,
  `MINTABLE`, `BALANCE_EDIT`, `SELFDESTRUCT`, `HIDDEN_OWNER`, `PAUSABLE`,
  `CONCENTRATED`, `DUST_LIQUIDITY`, `LP_UNLOCKED`, `BRAND_NEW`, `NO_SELLS`,
  `DATA_GAP`.
- `security` — honeypot sell-simulation result, buy/sell tax %, open-source,
  proxy, mintable, pausable.
- `market` — USD price, liquidity, FDV, 24h volume, buy/sell counts, pair age,
  LP locked %.
- `holders` — holder count, top-10 concentration %, creator holdings %.
- `sources` — which of goplus / honeypot.is / dexscreener answered. Partial
  data is flagged `DATA_GAP` rather than failing.

### `GET /api/batch` — $1.00 · vet 2–6 tokens in one call
`?tokens=0xA,0xB,0xC&chain=base` → `{chain, count, reports[]}` with the same
report shape per token. Use for screening candidates before entry.

### `GET /api/snapshot` — $0.10 · market data only
`?token=0x<address>&chain=base` → price, liquidity, FDV, volume, buy/sell
counts, top pair. No security analysis.

## Free

- `GET /api` — catalog of everything with prices and schemas.
- `GET /api/demo` — a real, full report for a sample token, free, so you can
  validate parsing before paying.
- `GET /openapi.json` — OpenAPI 3.1 with `x-payment-info` per operation.
- `GET /.well-known/x402` — x402 discovery manifest.

## Recommended agent policy

1. Before any token purchase, call `/api/vet`.
2. Refuse to buy on `verdict=FAIL` or any `critical` flag.
3. On `CAUTION`, cap position size and require human/policy approval.
4. Log `score` and `flags` alongside the trade for post-trade review.