# token-risk

> Machine-payable API returning deterministic structural risk reports for ERC-20 tokens on Base (chainId 8453), paid per request in USDC via the x402 protocol (v2). Keyless x402-native payment per request — no signup, no API key; pay with USDC via EIP-3009 authorization. Also offers wallet-address structural-safety reports on Base via POST /v1/wallet.

The engine reports STRUCTURAL risk, not reputation — centralized-control powers (mint/pause/blacklist) are flagged regardless of issuer; score is a structural-safety score 0-100 where higher means structurally safer.

Keyless x402-native payment per request — no signup, no API key; pay with USDC via EIP-3009 authorization.

Version: 0.1.0
Price per scan: $0.01 (USDC, x402 "exact" scheme, network eip155:8453, payTo 0x332DbF15a8Bcca8eEB4390b380202360F4f45401)
Price per wallet report: $0.01 (USDC, same scheme/network/payTo)
Payment protocol: x402 v2 — requirements are advertised in the base64-encoded PAYMENT-REQUIRED header of the 402 response and settled by a facilitator; this service never signs or broadcasts transactions.

## Wallet scope (today)

Measures structural/contract signals for an address today: contract detection, verification status, and proxy/owner/privileged-function analysis.
Behavioral signals (account age, activity history, funding provenance) are not yet included.

## Scan context

Widely-held assets can carry centralized-control powers by design; context.knownAsset flags tokens on our compiled list of well-known Base assets (context only — it does not change verdict or score).

## Free samples (evaluate before paying)

See a full real report before paying: GET /samples/index.json lists free committed samples (GET /samples/{name}.json).

## Endpoints

- POST /v1/scan — paid ($0.01 USDC). Body: {"chainId": 8453, "address": "0x..."}. Returns a RiskReport JSON document (schema in /openapi.json).
- POST /v1/wallet — paid ($0.01 USDC). Body: {"address": "0x..."}. Returns a WalletReport JSON document (schema in /openapi.json).
- GET /health — free liveness probe.
- GET /openapi.json — free OpenAPI 3.1 document generated from the wire schemas.
- GET /llms.txt — this document.
- GET /samples/index.json — free list of committed real sample reports.
- GET /samples/{name}.json — free full RiskReport or WalletReport JSON (see index).

## Example flow (POST /v1/scan)

1. POST /v1/scan with the JSON body and no payment -> HTTP 402 with a PAYMENT-REQUIRED header (base64 JSON: accepted scheme/network/amount/asset/payTo plus the bazaar discovery extension).
2. Decode the header, create a USDC payment authorization (EIP-3009) matching the advertised requirements, retry the same request with the X-PAYMENT header.
3. Receive HTTP 200 with the RiskReport JSON body. Identical inputs are deterministic within the cache window; the report's "cache" field carries hit/age metadata.

## Example flow (POST /v1/wallet)

1. POST /v1/wallet with the JSON body and no payment -> HTTP 402 with a PAYMENT-REQUIRED header (base64 JSON: accepted scheme/network/amount/asset/payTo plus the bazaar discovery extension).
2. Decode the header, create a USDC payment authorization (EIP-3009) matching the advertised requirements, retry the same request with the X-PAYMENT header.
3. Receive HTTP 200 with the WalletReport JSON body. Identical inputs are deterministic within the cache window; the report's "cache" field carries hit/age metadata.