Skip to main content

🔍 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 holdings for any address
✅ Transaction History — Track fund flows and wallet activity
✅ Token Holder Analysis — Identify whale concentration and distribution
✅ Smart Contract Verification — Check contract types (ERC20, ERC721)
✅ AI Chat Integration — Natural language queries in English and Ukrainian

How to Use​

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,
  "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": [
    {
      "hash": "0x...",
      "from": "0x...",
      "to": "0x...",
      "value_eth": 10.5,
      "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.195e+16
    }
  ],
  "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
}

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

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​

  1. Sign up at vartovii.com
  2. Navigate to Settings → API Keys
  3. Generate a new key for Forensic Agent
  4. 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​

ErrorCauseSolution
Invalid address formatAddress doesn't start with 0xEnsure address has 0x prefix
BigQuery unavailableTemporary API issueRetry after 30 seconds
Wallet not foundAddress has no on-chain activityVerify address is correct
Rate limit exceededToo many requestsUpgrade to authenticated tier

Support​

Changelog​

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