Getting Started

The Eagle Virtual API provides programmatic access to our risk intelligence platform. Screen addresses for blacklist status, sanctions exposure, and proximity risk across EVM and TRON chains.

Base URL: https://eaglevirtual.com/v1

All endpoints require authentication via API key. Responses follow a consistent JSON envelope. The OpenAPI spec is available for code generation.

Authentication

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

Header

Authorization: Bearer YOUR_API_KEY

To create an API key, sign in to your account and navigate to Settings → API Keys. Keys can optionally be restricted to specific IP addresses.

Each request receives a unique X-Request-ID header (or you can send your own). Rate limit headers are included on every response — see Tiers & Rate Limits.

Response Format

All responses use a consistent envelope with status, data, and meta fields:

Success

{
  "status": "success",
  "data": {
    // Endpoint-specific data
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5f6g7h8",
    "timestamp": "2026-03-15T12:00:00Z"
  }
}

Error

{
  "status": "error",
  "error": {
    "code": "invalid_address",
    "message": "Invalid blockchain address format"
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5f6g7h8",
    "timestamp": "2026-03-15T12:00:00Z"
  }
}

Risk Measurement Snapshot

Every API response returns a structured risk measurement, not just a score:

risk_band — Critical, High, Moderate, Low, Minimal, Unsupported

confidence_band — Confirmed, Strong, Moderate, Weak, Insufficient

direct_status — OFAC, EU, issuer freeze/blacklist flags

risk_drivers — Top reasons for the risk band

coverage_state — Complete, partial, approximate, unsupported

evidence_bundle — Sources, paths, timestamps, methodology version

Check Address Risk

GET /v1/addresses/{address}/risk Free

Returns a multidimensional risk summary for a single blockchain address, including direct status, validated proximity, confidence, risk drivers, and sanctions / issuer-enforcement context.

Path Parameters

Parameter	Type	Description
addressrequired	string	Blockchain address (EVM `0x...` or TRON `T...`)

Example Request

cURL

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

Example Response

200 OK

{
  "status": "success",
  "data": {
    "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
    "risky": false,
    "risk_level": "clean",
    "depth": null,
    "display_depth": null,
    "validated_depth": null,
    "raw_depth": null,
    "blacklist_count": 0,
    "is_blacklisted": false,
    "is_sanctioned": false,
    "has_chronology_issues": false,
    "evidence_quality": "clean",
    "flagged_by": [],
    "report_url": "https://eaglevirtual.com/report/0xdac17f958d2ee523a2206206994597c13d831ec7"
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5f6g7h8",
    "timestamp": "2026-03-15T12:00:00Z"
  }
}

Response Fields

Field	Type	Description
risk_level	string	Machine-stable risk classification: clean, low, medium, high, critical, blacklisted
depth	int\|null	Raw graph depth (transfer hops from nearest flagged address, null = clean)
display_depth	int\|null	Confirmed screening depth from chronologically validated paths. Use this for compliance decisions.
validated_depth	int\|null	Depth based only on chronologically valid paths
raw_depth	int\|null	Pre-masking depth from the risk graph (before stop-node filtering)
has_chronology_issues	boolean	True if risk paths have chronological inconsistencies
evidence_quality	string	Evidence classification: clean, direct, confirmed, pending_validation, unreconstructed, invalid_chronology, indeterminate_chronology
flagged_by	string[]	Active flag sources (e.g., ["USDT", "OFAC"]). For depth=0: token issuers. For sanctioned: includes "OFAC".
report_url	string	URL to the full risk report for this address

Risk Levels

Level	Meaning
clean	No connection to blacklisted addresses
low	Distant proximity to blacklisted addresses
medium	Moderate proximity to blacklisted addresses
high	Close proximity to blacklisted addresses
critical	Direct connection to blacklisted addresses
blacklisted	Address is directly blacklisted by a token issuer

Evidence Quality

Value	Meaning
clean	No connection to any blacklisted address
direct	Address is itself blacklisted (depth 0)
confirmed	Chronologically valid path to a blacklisted address exists
pending_validation	Graph depth exists but chronology not yet verified
unreconstructed	Graph depth exists but no path has been reconstructed yet
invalid_chronology	Paths exist but all are chronologically invalid

Batch Risk Check

POST /v1/addresses/risk/batch Starter+

Check risk for multiple addresses in a single request. Maximum 100 addresses per batch. Not available on the Free tier. Usage is charged per address, not per request.

Request Body

Field	Type	Description
addressesrequired	string[]	Array of blockchain addresses to check (max 100)

Example Request

cURL

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"
    ]
  }'

Example Response

200 OK

{
  "status": "success",
  "data": {
    "results": {
      "0xdac17f958d2ee523a2206206994597c13d831ec7": {
        "risky": false,
        "risk_level": "clean",
        "depth": null,
        "display_depth": null,
        "blacklist_count": 0,
        "is_blacklisted": false,
        "is_sanctioned": false,
        "evidence_quality": "clean",
        "flagged_by": []
      },
      "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": {
        "risky": true,
        "risk_level": "medium",
        "depth": 3,
        "display_depth": 3,
        "blacklist_count": 2,
        "is_blacklisted": false,
        "is_sanctioned": false,
        "evidence_quality": "confirmed",
        "flagged_by": []
      }
    },
    "count": 2,
    "query_time_ms": 45
  },
  "meta": { ... }
}

Risk Paths

GET /v1/addresses/{address}/paths Growth+

Returns detailed risk paths showing the chain of transfers connecting an address to blacklisted addresses. Each path includes edges with transaction details, timestamps, and values.

Path Parameters

Parameter	Type	Description
addressrequired	string	Blockchain address to trace risk paths for

Example Request

cURL

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

Example Response

200 OK

{
  "status": "success",
  "data": {
    "address": "0x1234...5678",
    "risky": true,
    "risk_level": "high",
    "depth": 2,
    "display_depth": 1,
    "is_blacklisted": false,
    "is_sanctioned": false,
    "blacklist_count": 1,
    "path_count": 1,
    "paths": [
      {
        "blacklist": {
          "address": "0xdead...beef",
          "name": "Tether Blacklisted",
          "reason": "blacklisted"
        },
        "edges": [
          {
            "from": "0x1234...5678",
            "to": "0xabcd...ef01",
            "chain": "ethereum",
            "tx_hash": "0xabc123...",
            "timestamp": "2025-08-15T10:30:00Z",
            "value": "5000.000000",
            "token": "0xdac17f...",
            "token_symbol": "USDT",
            "type": "transfer"
          }
        ],
        "chronological_validity": true
      }
    ],
    "evidence_quality": "strong",
    "query_time_ms": 120
  },
  "meta": { ... }
}

Address Events

GET /v1/addresses/{address}/events Free

Returns blacklist and freeze events associated with a specific address.

Parameters

Parameter	Type	In	Description
addressrequired	string	path	Blockchain address
limitoptional	integer	query	Number of results (default: 50, max: 100)

Example Response

200 OK

{
  "status": "success",
  "data": {
    "address": "0xdead...beef",
    "events": [
      {
        "id": "1-18500000-42",
        "chain_id": 1,
        "block_num": 18500000,
        "tx_hash": "0xabc123...",
        "issuer": "0xdac17f...",
        "issuer_name": "Tether",
        "issuer_symbol": "USDT",
        "target": "0xdead...beef",
        "category": "blacklist",
        "action": "addBlackList",
        "event_type": "AddedBlackList",
        "timestamp": "2025-11-10T15:42:00Z"
      }
    ],
    "count": 1,
    "limit": 50
  },
  "meta": { ... }
}

Address Timeline

GET /v1/addresses/{address}/timeline Free

Returns a chronological timeline of all blacklist and freeze events for an address. Similar to address events, but ordered by time for easy visualization.

Path Parameters

Parameter	Type	Description
addressrequired	string	Blockchain address

Example Response

200 OK

{
  "status": "success",
  "data": {
    "address": "0xdead...beef",
    "events": [ /* chronological event array */ ],
    "total": 3
  },
  "meta": { ... }
}

Recent Events

GET /v1/events Free

Returns the most recent blacklist and freeze events across all supported chains.

Query Parameters

Parameter	Type	Description
limitoptional	integer	Number of results (default: 50, max: 100)

Example Request

cURL

curl "https://eaglevirtual.com/v1/events?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK

{
  "status": "success",
  "data": {
    "events": [
      {
        "id": "1-21700000-7",
        "chain_id": 1,
        "block_num": 21700000,
        "tx_hash": "0xdef456...",
        "issuer": "0xa0b869...",
        "issuer_name": "Circle",
        "issuer_symbol": "USDC",
        "target": "0x9876...5432",
        "category": "blacklist",
        "action": "blacklist",
        "event_type": "Blacklisted",
        "timestamp": "2026-03-14T08:15:00Z"
      }
    ],
    "count": 10,
    "limit": 10
  },
  "meta": { ... }
}

Supported Chains

GET /v1/chains Free

Returns all blockchain networks currently supported by Eagle Virtual.

Example Request

cURL

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

Example Response

200 OK

{
  "status": "success",
  "data": {
    "chains": [
      {
        "chain_id": "1",
        "name": "Ethereum",
        "short_name": "ETH",
        "family": "evm",
        "native_symbol": "ETH",
        "status": "active",
        "enabled": true
      },
      // ... additional chains
    ]
  },
  "meta": { ... }
}

Currently supported networks include:

Chain	Family	Address Format
Ethereum	EVM	`0x...`
BNB Smart Chain	EVM	`0x...`
Polygon	EVM	`0x...`
Arbitrum	EVM	`0x...`
Optimism	EVM	`0x...`
Base	EVM	`0x...`
Avalanche	EVM	`0x...`
TRON	TRON	`T...` (Base58)

EVM addresses are shared across all EVM chains — a single risk check covers Ethereum, Polygon, Arbitrum, and all other EVM networks.

Address Profile

GET /v1/addresses/{address}/profile Growth+

Returns detailed address information including labels, entity classification, risk summary, and associated events.

Path Parameters

Parameter	Type	Description
addressrequired	string	Blockchain address

Example Response

200 OK

{
  "status": "success",
  "data": {
    "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
    "ens_names": [],
    "labels": ["stablecoin-issuer"],
    "entity_type": "token",
    "entity_name": "Tether USD",
    "risk": {
      "risky": false,
      "risk_level": "clean",
      "depth": null
    },
    "events": []
  },
  "meta": { ... }
}

Tiers & Rate Limits

API access and limits depend on your subscription tier. Rate limits are enforced per API key per minute. Daily quotas are enforced per account across all keys.

Free

Rate limit10/min

Lookups100 lifetime

Batch—

Profile / Paths—

API keys1

Starter

Rate limit10/min

Daily requests2,000

Batch100 addrs

Profile / Paths—

API keys3

Growth

Rate limit300/min

Daily requests25,000

Batch1,000 addrs

Profile / PathsYes

API keys10

Enterprise

Rate limit1,000/min

Daily requestsUnlimited

Batch1,000 addrs

Profile / PathsYes

API keysUnlimited

Rate Limit Headers

Every API response includes rate limit headers:

Response Headers

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

When rate limited, the response includes a Retry-After: 60 header indicating seconds to wait before retrying.

Endpoint Access by Tier

Endpoint	Free	Starter	Growth	Enterprise
`/addresses/{addr}/risk`	Yes	Yes	Yes	Yes
`/addresses/risk/batch`	—	Yes	Yes	Yes
`/addresses/{addr}/events`	Yes	Yes	Yes	Yes
`/addresses/{addr}/timeline`	Yes	Yes	Yes	Yes
`/events`	Yes	Yes	Yes	Yes
`/chains`	Yes	Yes	Yes	Yes
`/me/usage`	Yes	Yes	Yes	Yes
`/addresses/{addr}/profile`	—	—	Yes	Yes
`/addresses/{addr}/paths`	—	—	Yes	Yes

Google Sheets Integration

Compliance-grade address screening directly in Google Sheets. No setup required — uses your Google account automatically. Free tier includes 100 lifetime lookups.

Get the Template Learn More

Setup

Click "Get the Template" to copy the spreadsheet to your Google Drive
Enter addresses in column A on the Screen tab
EagleVirtual menu > Screen All (or click the Screen All button)
Results appear with color-coded risk levels, proximity, flag sources, and report links

Screening Modes

Mode	Description
`Screen All`	Screen every row (uses cache for already-screened addresses)
`Screen New Rows`	Only screen rows without existing results
`Refresh Existing`	Re-screen rows that already have results (ignores cache)
`Clear Results`	Clear result columns, preserve addresses and notes
`=EV_RISK(A2)`	Custom formula for single-address screening

Result Columns

Column	Description
Risk Level	BLACKLISTED, SANCTIONED, HIGH, MEDIUM, LOW, MINIMAL, CLEAN, PENDING, REVIEW
Proximity	Confirmed transfer hops from flagged address (* = unvalidated)
Connections	Unique flagged addresses connected in the risk graph
Status	Evidence quality: Confirmed, Pending Validation, Invalid Chronology
Flag Source	Active flag sources: USDT, USDC, OFAC, etc.
Report	Link to full risk report on eaglevirtual.com
Notes	Free-form analyst notes (never cleared by screening)

Error Handling

Errors use the same envelope format with an error object instead of data:

Error Response

{
  "status": "error",
  "error": {
    "code": "unauthorized",
    "message": "API key required. Use Authorization: Bearer <your_api_key>"
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5f6g7h8",
    "timestamp": "2026-03-15T12:00:00Z"
  }
}

Error Codes

Status	Code	Description
400	invalid_address	Address format is not valid for any supported chain
400	missing_address	Address is required in the URL path
400	empty_addresses	Batch request requires at least one address
400	too_many_addresses	Batch request exceeds maximum address count
400	invalid_json	Request body is not valid JSON
401	unauthorized	No API key provided
401	invalid_key	API key not found or malformed
401	invalid_token	Bearer token is empty
401	key_revoked	API key has been revoked
403	tier_insufficient	Your tier does not have access to this endpoint
403	batch_not_available	Batch endpoint requires Starter tier or higher
403	quota_exceeded	Daily request quota has been reached
403	api_disabled	API access is not enabled for your tier
404	not_found	Endpoint does not exist
405	method_not_allowed	Wrong HTTP method for this endpoint
429	rate_limited	Per-minute rate limit exceeded
500	internal_error	Unexpected server error
502	gateway_error	Backend service temporarily unavailable
503	service_unavailable	Service not yet initialized

Compliance & Regulatory Support

Eagle Virtual's API supports compliance requirements across multiple regulatory frameworks.

MiCA (EU)

Articles 68 & 92 — transaction monitoring, EU sanctions screening, and suspicious activity detection. Use /v1/addresses/{address}/risk for real-time checks on EURC, EURe, agEUR, and other supported assets.

MiCA compliance guide →

BCB / COAF (Brazil)

Resolutions 519–521 — AML screening and stablecoin monitoring. Risk check responses include evidence suitable for COAF suspicious activity reporting on BRZ, and major stablecoin flows.

Brazil compliance guide →

US Sanctions / OFAC

SDN list screening with multidimensional risk assessment. Responses include government-sanctions match status, validated sanctions exposure depth, confidence, risk drivers, and evidence paths for SAR documentation alongside EU and issuer-enforcement workflows.

Sanctions monitoring →

All plans include all supported chains. See pricing →

API Documentation

Getting Started

Authentication

Response Format

Risk Measurement Snapshot

Check Address Risk

Path Parameters

Example Request

Example Response

Response Fields

Risk Levels

Evidence Quality

Batch Risk Check

Request Body

Example Request

Example Response

Risk Paths

Path Parameters

Example Request

Example Response

Address Events

Parameters

Example Response

Address Timeline

Path Parameters

Example Response

Recent Events

Query Parameters

Example Request

Example Response

Supported Chains

Example Request

Example Response

Address Profile

Path Parameters

Example Response

Tiers & Rate Limits

Free

Starter

Growth

Enterprise

Rate Limit Headers

Endpoint Access by Tier

Google Sheets Integration

Setup

Screening Modes

Result Columns

Error Handling

Error Codes

Compliance & Regulatory Support

MiCA (EU)

BCB / COAF (Brazil)

US Sanctions / OFAC