# SpotBlock

> Crypto scam and threat detection platform: track malicious Ethereum addresses and contracts, analyze transactions for harm, run vulnerability and AI deep scans on smart contracts, and monitor addresses in real time.

## Capabilities

- [Getting started](https://spotblock.org/docs/getting-started): platform overview and first steps.
- [Company quick start](https://spotblock.org/docs/company-quick-start): set SpotBlock up for a team or protocol.
- [AI reference](https://spotblock.org/docs/ai-reference): machine-readable reference for AI assistants.
- [Contributor manual](https://spotblock.org/docs/contributor-manual): how to contribute addresses and detections.
- [Detection & scoring system](https://spotblock.org/docs/detection-scoring-system): how threats are detected and scored.
- [Real-time monitoring](https://spotblock.org/docs/real-time-monitoring): wallet and contract watch system.
- [Rewards & claims](https://spotblock.org/docs/rewards-claims): contributor rewards program.
- [Integrations](https://spotblock.org/docs/integrations): REST, MCP, OpenAPI, and llms.txt surfaces for external agents.
- [Explorer](https://spotblock.org/explorer): browse the threat database in the browser.
- [Products](https://spotblock.org/products): SpotBlock product overview.

## Security API

Base URL: https://spotblock.org

| Method | Path | Purpose |
|---|---|---|
| GET | /api/threat-check?address=0x… | Check an address against the threat DB (also POST {"address"}) |
| GET | /api/security-check?selector=… | Umbrella check on an address, ENS name, or tx hash (all checks at once) |
| POST | /api/tx-harm {"txHash" or "rawTx"} | Determine whether a transaction involved known threats |
| GET | /api/rt-monitor/list | List active real-time watches |
| GET | /api/rt-monitor/status?address=0x… | Wallet monitoring status and alerts |
| POST | /api/rt-monitor/watch {"address"} | Register an address for real-time monitoring |
| POST | /api/rt-monitor/stop {"address"} | Stop monitoring an address |
| GET | /api/rt-contract-monitor/status?address=0x… | Contract monitoring status and alerts |
| GET | /api/rt-contract-monitor/state?address=0x… | Live on-chain contract state (owner, paused, proxy, roles) |
| GET | /api/vuln-scan/nonce | Nonce for a signature-gated vulnerability scan |
| POST | /api/vuln-scan/scan | Queue a vulnerability scan (signed request) |
| GET | /api/vuln-scan/status?id=… | Poll a vulnerability scan |
| GET | /api/super-analyst/nonce | Nonce for a signature-gated AI deep scan |
| POST | /api/super-analyst/scan | Queue an AI deep scan (signed request) |
| GET | /api/super-analyst/status?id=… | Poll an AI deep scan |
| POST | /api/wallet-info {"wallet"} | ETH balance and tx count for a wallet |
| POST | /api/ens-resolver {"input"} | Resolve .eth names to addresses and back |
| GET | /api/gastracker | Ethereum gas prices and ETH/USD |
| GET | /api/stats | Platform statistics |
| GET | /api/addresses | Query the threat-DB collection (filters, pagination, stats) |
| GET | /api/explorer/overview | Aggregated threat-DB overview |
| GET | /api/explorer/intelligence | Curated intelligence snapshot |
| GET | /api/contract-exists?address=0x… | Whether an address has deployed code |

Quick start:

```bash
# Threat check (GET)
curl "https://spotblock.org/api/threat-check?address=0x0000000000000000000000000000000000000000"

# Umbrella security check (address, ENS name, or tx hash)
curl "https://spotblock.org/api/security-check?selector=vitalik.eth"

# Transaction harm check (paste a tx, learn if it caused harm)
curl -X POST "https://spotblock.org/api/tx-harm" \
  -H "content-type: application/json" \
  -d '{"txHash":"0x0000000000000000000000000000000000000000000000000000000000000000"}'
```

## MCP Server

MCP (Model Context Protocol) server: `https://spotblock.org/api/mcp`

Tools:

- `spotblock_threat_check {address}` — threat-DB lookup.
- `spotblock_security_check {selector, network?}` — umbrella security check.
- `spotblock_tx_harm {txHash? | rawTx?, network?}` — transaction harm analysis.
- `spotblock_scan_status {id}` — poll a vulnerability or AI scan.
- `spotblock_monitor_list {}` — list active watches.
- `spotblock_monitor_status {address}` — wallet + contract monitor status.
- `spotblock_stats {}` — platform statistics.
- `spotblock_scan_instructions {}` — how to run the signature-gated deep scans.

Add as a custom connector in Claude (Settings > Connectors > Add custom connector > `https://spotblock.org/api/mcp`) or in ChatGPT (Connectors/Actions > add custom connector).

## OpenAPI

Machine-readable spec for GPT Actions / OpenAPI import: `https://spotblock.org/api/openapi.json`

Import it in ChatGPT (Create an action > Import from URL) or any OpenAPI client to call every endpoint above.

## Deep scans

Vulnerability scan and AI deep scan are signature-gated (they burn compute/AI budget), so they follow a wallet-signature flow:

1. `GET /api/vuln-scan/nonce` or `GET /api/super-analyst/nonce` → `{nonce, issuedAt}`.
2. Sign the exact request message your client builds from those fields with your wallet.
3. `POST /api/vuln-scan/scan` (body: wallet, address, chainId, nonce, issuedAt, signature) or `POST /api/super-analyst/scan` (adds depth: simple|advanced).
4. `GET /api/vuln-scan/status?id=…` or `GET /api/super-analyst/status?id=…` to poll.

Nonces expire after 10 minutes. Daily AI-scan caps: 3/day per wallet, 5/day per IP, 25/day global. MCP clients cannot sign wallet messages, so these actions are intentionally not exposed as MCP tools — use `spotblock_scan_instructions` and a wallet client instead.

## Rate limits

All per IP, sliding in-memory windows:

- `/api/security-check`: 20/min
- `/api/tx-harm`: 10/min
- `/api/mcp`: 60/min
- `/api/vuln-scan/nonce` and `/api/super-analyst/nonce`: 10/min
- `/api/contact`: 3/min
- `/api/platform-health`: 30/min