🔍 Forensic Agent

AI-powered on-chain intelligence for investigating Ethereum wallets, transactions, and smart contracts.

Overview

The Forensic Agent provides real-time blockchain analytics powered by Google BigQuery and Gemini AI. Query on-chain data using natural language or direct API calls.

Key Features

✅ Wallet Balance Checking — Query ETH + top ERC20 holdings for any address ✅ Transaction History — Track fund flows and wallet activity ✅ Token Holder Analysis — Identify whale concentration and distribution ✅ Smart Contract Verification — Check ERC flags + explorer verification status ✅ AI Chat Integration — Natural language queries in English and Ukrainian

How to Use

Via AI Chat (Recommended)

Ask questions in natural language:

English:

What is the balance of wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?
Show me the top holders of USDT
Is 0xdAC17F958D2ee523a2206206994597C13D831ec7 an ERC20 contract?

Ukrainian:

Перевір баланс гаманця 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
Покажи топ холдерів USDT
Чи є 0xdAC17F958D2ee523a2206206994597C13D831ec7 ERC20 контрактом?

Via API

1. Check Wallet Balance

curl -X POST https://api.vartovii.com/api/forensic/check_wallet \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"}'

Response:

{
  "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "eth_balance": 32.111223478,
  "usd_value": 94241.62,
  "eth_price": 2934.2,
  "token_balances": [
    {
      "contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6,
      "balance": 2500.0,
      "usd_value": 2500.0
    }
  ],
  "found": true,
  "chain": "ethereum"
}

2. Get Transaction History

curl -X POST https://api.vartovii.com/api/forensic/transaction_history \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "address": "0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe",
    "limit": 10,
    "days": 30
  }'

Response:

{
  "address": "0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe",
  "transactions": [
    {
      "tx_hash": "0x...",
      "from": "0x...",
      "to": "0x...",
      "eth_value": 10.5,
      "gas_price_gwei": 12.4,
      "status": "success",
      "timestamp": "2026-01-15T10:30:00Z"
    }
  ],
  "count": 10
}

3. Get Token Holders

curl -X POST https://api.vartovii.com/api/forensic/token_holders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "contract_address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
    "limit": 20
  }'

Response:

{
  "contract_address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
  "holders": [
    {
      "rank": 1,
      "address": "0xf977814e90da44bfa03b6295a0616a897441acec",
      "balance": 2.195e16
    }
  ],
  "count": 20
}

4. Get Contract Info

curl -X POST https://api.vartovii.com/api/forensic/contract_info \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"contract_address": "0xdAC17F958D2ee523a2206206994597C13D831ec7"}'

Response:

{
  "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
  "found": true,
  "is_erc20": true,
  "is_erc721": false,
  "deployed_at": "2017-11-28T00:41:21+00:00",
  "has_bytecode": true,
  "is_verified_source": true,
  "verification_source": "etherscan",
  "verification_url": "https://etherscan.io/address/0xdac17f958d2ee523a2206206994597c13d831ec7#code",
  "contract_name": "Tether USD"
}

Technical Details

Data Source

Provider: Google BigQuery Public Datasets
Dataset: bigquery-public-data.crypto_ethereum
Update Frequency: Near real-time (~5 minute delay)

Supported Chains

✅ Ethereum (Mainnet)
🔜 Arbitrum (Coming Q2 2026)
🔜 Solana (via Helius API)

Rate Limits

Free Tier: 10 requests/day (Public API)
Authenticated: Unlimited (requires API key)
AI Chat: Included in chat limits
CoinGecko pricing calls: throttled + retried (429/5xx) for more stable valuation fields in forensic responses

Address Validation Contract (Updated 2026-03-04)

For POST /api/forensic/check_wallet, request validation now enforces:

Address format: 0x + exactly 40 hex characters.
Mixed-case addresses: EIP-55 checksum validation (Keccak-256).
Invalid payloads are rejected with 422 before query execution.

AI Output Safety Contract (Updated 2026-03-03)

For AI-assisted forensic analysis (backend/ai/services/forensic_service.py), output is normalized before returning to clients:

Schema-Backed JSON: The runtime now requests structured JSON from Gemini and validates the typed payload before applying score and risk normalization.
Deterministic Fallback: If the AI layer times out or returns invalid structured data, the service falls back to deterministic guardrails instead of exposing malformed AI output.
Trust Score Clamp: AI trust_score is forced to integer range 0..100.
Risk Level Normalization: AI risk_level is validated against LOW|MEDIUM|HIGH|CRITICAL|UNKNOWN.
Alias Mapping: Common aliases are normalized:
- MODERATE -> MEDIUM
- SEVERE -> HIGH
- EXTREME -> CRITICAL
- SAFE -> LOW
- NONE -> LOW
Fallback for Invalid Values: Unknown/invalid labels resolve to UNKNOWN.
Safe Error Summary: Unexpected internal exceptions return a generic user-facing summary (no internal stack details in summary).
Sanitized Error Field: Public fallback payload exposes a safe error code (analysis_failed) instead of raw exception text.

Use Cases

🕵️ Wallet Investigations

Query: "Check balance for 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" Use Case: Verify team wallet holdings, track whale movements

📊 Token Distribution Analysis

Query: "Show top 20 holders of USDT" Use Case: Assess tokenomics risk, identify concentration

🔐 Contract Verification

Query: "Is 0xdAC17F... an ERC20 contract?" Use Case: Verify token standards before integration

💸 Fund Flow Tracking

Query: "Transaction history for 0xde0B... in last 30 days" Use Case: Audit wallet activity, investigate suspicious transfers

Limitations

Known Limitations

Transaction History: May have gaps due to BigQuery public dataset sync delays
Data Scope: Public blockchain data only (no private transactions)
Historical Data: Limited to Ethereum's public dataset timeframe
Real-time Updates: ~5 minute delay from on-chain finality :::

API Authentication

Getting an API Key

Sign up at vartovii.com
Navigate to Settings → API Keys
Generate a new key for Forensic Agent
Add to requests: X-API-Key: YOUR_API_KEY

Public Access

Health check endpoint is public (no auth required):

curl https://api.vartovii.com/api/forensic/health

Error Handling

Common Errors

Error	Cause	Solution
`Invalid address format`	Missing `0x` prefix or invalid length/hex chars	Ensure address is `0x` + 40 hex chars
`Invalid EIP-55 checksum`	Mixed-case address checksum mismatch	Use a checksummed address from a trusted wallet/explorer
`BigQuery unavailable`	Temporary API issue	Retry after 30 seconds
`Wallet not found`	Address has no on-chain activity	Verify address is correct
`Rate limit exceeded`	Too many requests	Upgrade to authenticated tier

Support

Documentation: docs.vartovii.com
Discord: discord.gg/vartovii
Email: support@vartovii.com

Changelog

v1.1 — March 5, 2026

✅ Wallet endpoint now returns top ERC20 positions (token_balances)
✅ Contract info endpoint now returns source verification metadata
✅ CoinGecko-backed valuation path hardened for rate-limit retries

v1.0 — January 23, 2026

✅ Initial release with Ethereum support
✅ AI Chat integration (English + Ukrainian)
✅ 4 core endpoints: wallet, transactions, holders, contract info
✅ BigQuery public dataset integration

Overview​

Key Features​

How to Use​

Via AI Chat (Recommended)​

Via API​

1. Check Wallet Balance​

2. Get Transaction History​

3. Get Token Holders​

4. Get Contract Info​

Technical Details​

Data Source​

Supported Chains​

Rate Limits​

Address Validation Contract (Updated 2026-03-04)​

AI Output Safety Contract (Updated 2026-03-03)​

Use Cases​

🕵️ Wallet Investigations​

📊 Token Distribution Analysis​

🔐 Contract Verification​

💸 Fund Flow Tracking​

Limitations​

API Authentication​

Getting an API Key​

Public Access​

Error Handling​

Common Errors​

Support​

Changelog​

v1.1 — March 5, 2026​

v1.0 — January 23, 2026​

Overview

Key Features

How to Use

Via AI Chat (Recommended)

Via API

1. Check Wallet Balance

2. Get Transaction History

3. Get Token Holders

4. Get Contract Info

Technical Details

Data Source

Supported Chains

Rate Limits

Address Validation Contract (Updated 2026-03-04)

AI Output Safety Contract (Updated 2026-03-03)

Use Cases

🕵️ Wallet Investigations

📊 Token Distribution Analysis

🔐 Contract Verification

💸 Fund Flow Tracking

Limitations

API Authentication

Getting an API Key

Public Access

Error Handling

Common Errors

Support

Changelog

v1.1 — March 5, 2026

v1.0 — January 23, 2026