WalletGuard API

v1.0

The WalletGuard API lets you integrate wallet risk scoring directly into your app, exchange, or dApp. One API call returns a full risk report — mixers, sanctions, wallet age, patterns, and a 0–100 risk score.

⚡

Fast

Median response under 200ms for cached addresses

🔒

Secure

All requests over HTTPS. API keys are hashed at rest.

🌐

Multi-chain

Ethereum now. Bitcoin, Solana, BNB Chain coming soon.

Authentication

Pass your API key in the Authorization header on every request.

            HTTP Header
          
            Authorization: Bearer wg_live_your_api_key_here

Get an API key at walletguard.io/pricing. Free tier includes 10 scans/day. Pro and Business tiers offer higher limits.

Base URL

https://api.walletguard.io/v1

Rate Limits

Plan	Requests / Day	Requests / Min	Batch size
Free	10	1	—
Pro	1,000	20	10
Business	100,000	200	100

Rate limit headers are returned on every response: X-RateLimit-Remaining and X-RateLimit-Reset.

POST /scan

Scan a single wallet address and receive a complete risk report.

Request Body

address required Ethereum address (0x…, 42 characters)

chain optional Blockchain. Default: "ethereum". Options: "ethereum"

include_txs optional Include raw transaction list in response. Default: false

JavaScript / Node.js

const response = await fetch('https://api.walletguard.io/v1/scan', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type':  'application/json',
  },
  body: JSON.stringify({
    address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
    chain:   'ethereum',
  }),
});

const report = await response.json();
console.log(report.risk_score); // 0–100

Python

import requests

response = requests.post(
    "https://api.walletguard.io/v1/scan",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "chain":   "ethereum",
    }
)
report = response.json()
print(report["risk_score"])  # 0–100

cURL

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

Response

JSON Response

{
  "address":      "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "chain":        "ethereum",
  "risk_score":   4,
  "risk_level":   "very_low",
  "verdict":      "Wallet appears safe to send to",
  "scanned_at":   "2025-05-06T10:22:31Z",

  "signals": {
    "sanctions":        false,
    "mixer_interaction": false,
    "wallet_age_days":   2982,
    "tx_count":          1247,
    "rapid_cycling":     false,
    "high_value_txs":    3,
    "failed_tx_ratio":   0.02,
    "unique_contracts":  89,
    "unique_tokens":     34
  },

  "risk_factors": [],
  "positive_signals": [
    { "id": "wallet_age", "title": "Active for 8 years" },
    { "id": "high_activity", "title": "1,247 transactions" }
  ],

  "label": {
    "name":  "Vitalik Buterin",
    "type":  "public_figure"
  },

  "balance_eth":  3.8821
}

POST /scan/batch Pro+

Scan up to 100 addresses in a single request. Results are returned in the same order.

JSON Body

{
  "addresses": [
    "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "0xd882cfc20f52f2599d84b8e8d58c7fb62cfe344b",
    "0x28c6c06298d514db089934071355e5743bf21d60"
  ],
  "chain": "ethereum"
}

GET /report/:address

Retrieve a cached report for an address. Returns a fresh scan if no cache exists.

Example Request

            GET /v1/report/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

GET /labels/:address

Return any known labels for an address (exchange, mixer, DeFi protocol, scammer, etc.) without running a full risk scan.

JSON Response

{
  "address": "0x28c6c06298d514db089934071355e5743bf21d60",
  "labels": [
    { "name": "Binance Hot Wallet", "type": "exchange", "confidence": 0.99 }
  ]
}

Risk Fields Reference

Field	Type	Description
risk_score	integer	0 (safe) to 100 (critical). Composite score across all signals.
risk_level	string	very_low · low · medium · high · critical
sanctions	boolean	Address appears on OFAC SDN or equivalent list.
mixer_interaction	boolean	Any transaction with a known coin mixer.
wallet_age_days	integer	Days since the first transaction.
rapid_cycling	boolean	Near-equal inflows and outflows — layering pattern.
failed_tx_ratio	float	Fraction of failed transactions (0.0–1.0).
label	object \| null	Known entity label if available.

Score Formula

The risk score is a weighted sum clamped to 0–100. Individual weights:

Signal	Points added
OFAC Sanctioned address	+60
Coin mixer interaction	+38
Wallet age < 7 days	+28
Wallet age 7–30 days	+12
Rapid cycling pattern	+15
High failed tx ratio (>30%)	+8
Fewer than 5 transactions	+8
No transaction history	+8
Verified known-safe label	caps at 12

Error Codes

HTTP	Code	Meaning
400	invalid_address	Address format is not valid
401	unauthorized	Missing or invalid API key
429	rate_limited	Too many requests — check your plan limits
500	upstream_error	Blockchain data provider error — retry with backoff

Official SDKs

JavaScript / TypeScript

npm install walletguard

import { WalletGuard } from 'walletguard';
const wg = new WalletGuard('wg_live_...');
const r = await wg.scan('0x...');

Python

pip install walletguard

from walletguard import WalletGuard
wg = WalletGuard("wg_live_...")
r  = wg.scan("0x...")

SDKs are open-source. Contributions welcome on GitHub.