Integrate crypto address screening into your compliance workflow

Getting Started

The Eagle Virtual API provides programmatic access to source-backed address screening. Screen addresses against covered government sanctions sources, stablecoin blacklist, freeze, and control facts, whitelist status, historical status where supported, freshness metadata, and coverage state across certified networks.

Eagle Virtual is the address-screening and evidence layer. The API does not provide transaction tracing, multi-hop path analysis, clustering, entity graphs, KYC onboarding, or case management — those stay with your existing tools.

All endpoints except the spec itself require an API key. The machine-readable OpenAPI spec is available for code generation. CSV export is available from the screening page on paid plans.

Onboard in three steps

1. Sign in and pick a plan on pricing (self-serve checkout).
2. Create an API key on the page. The full key (ev_…) is shown once at creation — store it securely; only a hash is kept server-side.
3. Make your first request:

curl "https://eaglevirtual.com/v1/addresses/0xdAC17F958D2ee523a2206206994597C13D831ec7/risk" \
  -H "Authorization: Bearer YOUR_API_KEY"

Authentication

Include your API key in the Authorization header with every request:

Authorization: Bearer YOUR_API_KEY

Keys are created on the page by account admins. Keys start with ev_, are shown in full exactly once, and can be revoked at any time from the same page. The number of active keys per account depends on your plan (see Plans & Rate Limits).

Response Format

Responses are plain JSON objects — no envelope. Success responses return the endpoint's documented fields directly. Errors return an error code (machine-stable) and usually a human-readable message:

{
  "error": "invalid_address",
  "message": "Invalid address."
}

Every screening response includes a machine-stable status, the boolean evidence fields behind it, the flagging providers, and fresh_as_of metadata. Field names such as sanction_direct are part of the existing API contract; treat them as machine names, not outcome claims. Stale or incomplete coverage is reported as UNKNOWN_STALE / UNKNOWN_INCOMPLETE — never silently converted to NO_KNOWN_HIT. Address fields intended for users are returned in the detector's chain-canonical display form (EIP-55 for EVM); machine-normalized keys, when present, are explicitly named address_normalized.

Screen One Address

curl "https://eaglevirtual.com/v1/addresses/0xdAC17F958D2ee523a2206206994597C13D831ec7/risk" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

r = requests.get(
    "https://eaglevirtual.com/v1/addresses/0xdAC17F958D2ee523a2206206994597C13D831ec7/risk",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
r.raise_for_status()
result = r.json()
if result["status"] in ("SANCTION_DIRECT", "BLACKLIST_DIRECT"):
    print("escalate:", result["providers"])

const r = await fetch(
  "https://eaglevirtual.com/v1/addresses/0xdAC17F958D2ee523a2206206994597C13D831ec7/risk",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } },
);
const result = await r.json();
if (!r.ok) throw new Error(result.error);
console.log(result.status, result.providers);

{
  "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
  "display_address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
  "canonical_display": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
  "address_normalized": "0xdac17f958d2ee523a2206206994597c13d831ec7",
  "chain": "evm",
  "account_family": "evm",
  "status": "NO_KNOWN_HIT",
  "sanction_direct": false,
  "sanction_historical": false,
  "blacklist_direct": false,
  "blacklist_historical": false,
  "whitelist": false,
  "providers": [],
  "fresh_as_of": "2026-06-09T12:00:00Z",
  "completeness": "complete",
  "checked_chains": [],
  "report_url": "/report/0xdAC17F958D2ee523a2206206994597C13D831ec7"
}

Screen an Address Batch

curl -X POST "https://eaglevirtual.com/v1/addresses/risk/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
    ]
  }'

{
  "results": [
    {
      "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "display_address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "address_normalized": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "chain": "evm",
      "status": "NO_KNOWN_HIT",
      "sanction_direct": false,
      "blacklist_direct": false,
      "whitelist": false,
      "providers": [],
      "fresh_as_of": "2026-06-09T12:00:00Z",
      "report_url": "/report/0xdAC17F958D2ee523a2206206994597C13D831ec7"
    },
    {
      "address": "not-an-address",
      "chain": "",
      "status": "error",
      "error": "invalid_address",
      "message": "Invalid address."
    }
  ],
  "checked": 1,
  "failed": 1
}

Supported Chains

curl "https://eaglevirtual.com/v1/chains" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "schema_version": 1,
  "generated_at": "2026-06-06T11:54:08Z",
  "chains": [
    {
      "chain_id": "1",
      "slug": "ethereum",
      "display_name": "Ethereum",
      "short_name": "ETH",
      "family": "evm",
      "native_symbol": "ETH",
      "status": "running",
      "is_active": true,
      "native_formats": ["0x EVM account"]
    },
    // ... additional chains (each entry also carries coverage, format,
    // and market-cap context fields)
  ]
}

The live list is the source of truth — see the supported chains page for the current networks. Coverage spans EVM networks (Ethereum, BNB Smart Chain, Polygon, Arbitrum, Optimism, Base, Sonic, HyperEVM, Avalanche, Celo, Gnosis, Mantle, ADI Network, and Robinhood Chain), TRON, Solana, XRP, and address-record sanctions coverage for Bitcoin-family networks.

Usage

{
  "plan": "growth",
  "plan_label": "Growth",
  "usage_model": "monthly_unique_addresses",
  "billing_month": "2026-06",
  "monthly_unique_addresses_used": 585,
  "monthly_address_limit": 2000,
  "monthly_addresses_remaining": 1415,
  "service_continues_after_limit": true,
  "resets_at": "2026-07-01T00:00:00Z",
  "api_rate_per_min": 1500,
  "api_batch_max": 1000,
  "max_api_keys": 10
}

Plans & Rate Limits

API access and operational safeguards depend on your subscription plan. Rate limits are enforced per API key per minute. Pricing is based on monthly unique canonical addresses across the shared customer account. Screening checks remain subject to the displayed rate, batch, and plan safeguards. See pricing for current plans.

Rate Limit Headers

Every authenticated API response includes rate limit headers. Monthly unique-address reporting is separate from these operational rate limits and does not create an automatic cutoff in v1.

X-RateLimit-Limit: 1500      # Requests allowed per minute
X-RateLimit-Remaining: 1495  # Requests remaining in current window
X-RateLimit-Reset: 1742054460 # Unix timestamp when limit resets

When the per-minute limit is exceeded, the API returns 429 rate_limited with a Retry-After header indicating seconds to wait before retrying:

Retry-After: 21

{
  "error": "rate_limited",
  "message": "Per-minute rate limit exceeded. Retry after the window resets (see Retry-After).",
  "retry_after_seconds": 21
}

Endpoint Access by Plan

Usage Model

Billing is measured in monthly unique canonical addresses per customer account across the UTC billing month — an address counts once per month no matter how many times it is checked, from the API, web screening, reports, or PDF exports. The same EVM address checked on multiple EVM networks counts once. Every screening check remains subject to the per-minute rate, batch-size, and plan safeguards above.

• Only successful checks count. Invalid addresses, rejected batches, and backend errors never consume usage.
• Service continues normally if you exceed your plan amount. There is no automatic cutoff and no automatic overage charge — if an account is consistently over, our team reaches out about right-sizing the plan.
• Track consumption with GET /v1/usage or on the ; account admins see team-wide usage.

Error Handling

Errors return an error code (machine-stable) and usually a human-readable message:

{
  "error": "api_key_required",
  "message": "API key required. Send \"Authorization: Bearer <your API key>\"."
}

Error Codes

Troubleshooting

Support

Stuck, or need a higher limit, an enterprise batch size, or scheduled data feeds? Email support@eaglevirtual.com, use the contact form, or reach sales@eaglevirtual.com for plan questions. Security reports: see /security.

Compliance workflow context

The API supplies source-cited screening evidence. Legal obligations, regulatory reporting, market-abuse controls, customer due diligence, and disposition remain with the customer.

Native-address sanctions-only networks

Bitcoin, Bitcoin Cash, Litecoin, Dogecoin, Dash, Zcash transparent addresses, and TRON have address-record checks against covered government sanctions sources. A no-known-hit response for that scope is not connection, balance, transaction-monitoring, mixer, bridge, token-control, name, or pricing coverage. Stale or incomplete coverage remains fail closed.