API Reference

Programmatic access to the Web3defender scan engine - the same deterministic engine that powers the app. Read-only. No mutations, no wallet access.

Getting started

API access requires an active Business subscription.

Subscribe to Business at app.web3defender.tech/pricing.
Open Account in the app and go to API Keys.
Click Generate new key. Copy the key immediately - it is shown once.
Pass the key in every request as Authorization: Bearer <key>.

Key format: w3d_ followed by 64 hex characters (68 chars total). Store it like a password - never commit it to source control.

Authentication

Every request must include the Authorization header:

Authorization: Bearer w3d_a1b2c3d4...

Missing or invalid key returns 401. Expired subscription returns 403.

Endpoint

POST https://app.web3defender.tech/api/v1/scan

Request

Content-Type: application/json

Field	Type	Required	Description
`input`	string	Yes	Address or URL to scan. Max 600 chars.
`chain`	string	No	Chain hint for EVM addresses. Default: `ethereum`. Options: `ethereum`, `bsc`, `polygon`, `arbitrum`, `base`.

Supported input types

The engine auto-detects input type - no need to specify it:

EVM address - token or wallet on Ethereum, BSC, Polygon, Arbitrum, Base (0x...)
Solana address - token address on Solana (base58, 32-44 chars)
TON address - wallet on The Open Network (UQ... / EQ...)
URL - phishing / scam site check (https://...)

Example requests

EVM token

{ "input": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "chain": "ethereum" }

Solana token

{ "input": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" }

TON wallet

{ "input": "UQCmNobCMfMRZdOqm46LagP23yTMnPD8886dvjUtsz0c8HLS" }

URL

{ "input": "https://example.com" }

Response - 200 OK

Field	Type	Description
`version`	string	API response version. Currently `"1"`.
`status`	string	`SCORED` - full result available. `UNAVAILABLE` - upstream data source temporarily down, partial result. `NOT_FOUND` - address has no on-chain data.
`type`	string	Detected input type: `token`, `ton_wallet`, `url`.
`chain`	string	Chain that was scanned: `ethereum`, `bsc`, `polygon`, `arbitrum`, `base`, `solana`, `ton`, `web`.
`riskScore`	number \| null	0-100. Higher = more risk. `null` when status is not `SCORED`.
`riskLevel`	string \| null	`SAFE` (<30), `CAUTION` (30-59), `DANGER` (≥60). `null` when status is not `SCORED`.
`findings`	array	Risk signals found. May be empty. Each finding has `id`, `severity`, `text` fields.
`cached`	boolean	`true` if result was served from cache (up to 1 hour old). Still counts against your rate limit.

Example response

{
  "version": "1",
  "status": "SCORED",
  "type": "token",
  "chain": "ethereum",
  "riskScore": 12,
  "riskLevel": "SAFE",
  "findings": [
    {
      "id": "open_source",
      "severity": "info",
      "text": "Contract is open source"
    }
  ],
  "cached": false
}

Rate limits

Window	Limit
Per hour	300 requests
Per day	2 000 requests
Per 30 days	10 000 requests

Limits are per API key. Cached responses still count. Exceeding any limit returns 429.

Error codes

Status	Meaning
`400`	Bad request - invalid JSON, missing `input`, unrecognised input type, or unsupported chain.
`401`	Unauthorised - missing, malformed, or revoked API key.
`403`	Forbidden - active Business subscription required. Renew at app.web3defender.tech/pricing.
`413`	Request body too large (over 10 000 characters).
`429`	Rate limit exceeded. Check the hourly / daily / monthly caps above.
`500`	Scan failed - upstream error. Retry after a moment.
`503`	Could not verify subscription - temporary issue. Retry after a moment.

All errors return JSON: { "error": "..." }

Full example

curl

curl -X POST https://app.web3defender.tech/api/v1/scan \
  -H "Authorization: Bearer w3d_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"input":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48","chain":"ethereum"}'

Response

{
  "version": "1",
  "status": "SCORED",
  "type": "token",
  "chain": "ethereum",
  "riskScore": 12,
  "riskLevel": "SAFE",
  "findings": [],
  "cached": false
}

Notes

Deterministic engine. Verdicts are produced by GoPlus + on-chain data + local heuristics - the same engine the app uses. No LLM in the scan path. Same input = same output (until data sources update).
Read-only. The API only reads and scores. No write access, no mutations, no access to other users' data.
Per-key limits. Each API key has its own rate limit counter. You can create up to 5 keys per account.
Cache. Results are cached for up to 1 hour. Identical requests within that window return cached: true and still count against your rate limit.