API Documentation

Overview

The ShieldScan API is a RESTful HTTP API that accepts JSON request bodies and returns JSON responses. All endpoints are served over HTTPS. The base URL for all endpoints is:

https://api.shieldscan.io/v1

All timestamps in responses are ISO 8601 strings in UTC. Monetary amounts are expressed as floating-point numbers in the native token unit (e.g., ETH, not Wei).

Authentication

All API requests must include a valid API key in the Authorization header using the Bearer scheme. You can obtain an API key from your dashboard after creating an account.

Request Header

Authorization: Bearer ss_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Example — cURL

curl -X POST https://api.shieldscan.io/v1/aml/scan \
  -H "Authorization: Bearer ss_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"}'

POST /api/aml/scan

Submit an Ethereum wallet address for AML risk analysis. Returns a risk score, entity labels, sanctions exposure, and indirect exposure up to the configured hop depth.

Request Body

Example Request

{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "depth": 3,
  "include_tokens": true
}

Example Response — 200 OK

{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "risk_score": 24,
  "risk_level": "LOW",
  "scanned_at": "2025-09-14T10:23:41Z",
  "sanctions": {
    "is_sanctioned": false,
    "lists_checked": ["OFAC", "UN", "EU", "HMT"]
  },
  "labels": ["Exchange", "High Volume"],
  "indirect_exposure": {
    "hops_analyzed": 3,
    "flagged_counterparties": 1,
    "max_indirect_risk": "MEDIUM"
  },
  "tokens": [
    { "symbol": "USDT", "name": "Tether USD", "balance": 12500.00, "contract": "0xdAC17F958D2ee523a2206206994597C13D831ec7" },
    { "symbol": "USDC", "name": "USD Coin", "balance": 3200.50, "contract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" }
  ],
  "transaction_count": 1847,
  "first_seen": "2022-03-10T08:15:22Z",
  "last_seen": "2025-09-13T23:59:01Z"
}

GET /api/wallet/{}address}

Retrieve wallet metadata for a given Ethereum address: ETH balance, ERC-20 holdings, transaction count, and account age. No AML risk analysis is performed by this endpoint.

Path Parameters

Example Request

GET /api/wallet/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

Example Response — 200 OK

{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "balance": 45231.75,
  "tokens": [
    { "symbol": "USDT", "name": "Tether USD", "balance": 12500.00, "contract": "0xdAC17F958D2ee523a2206206994597C13D831ec7" },
    { "symbol": "USDC", "name": "USD Coin", "balance": 3200.50, "contract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" }
  ],
  "transaction_count": 1847,
  "account_created": "2022-03-10T08:15:22Z"
}

Rate Limits

Rate limits are applied per API key on a rolling 60-second window. When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header indicating seconds until the next window.

Rate Limit Response Headers

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1726312800
Retry-After: 12

Error Codes

All error responses use standard HTTP status codes and include a JSON body with a machine-readable code and a human-readable message.

Error Response Shape

{
  "error": {
    "code": "INVALID_ADDRESS",
    "message": "The provided address is not a valid Ethereum hex address.",
    "status": 400
  }
}

Error Code Reference