API Reference

Query enriched transaction events with filtering by protocol, action type, wallet, yield data, and more.

# Find high-yield Aave supply events
curl -H "X-API-Key: def_xxx" \
  "https://defeyes-api.vercel.app/api/events?protocol=Aave%20V3&action_type=SUPPLY&apy_min=5"

{
  "events": [
    {
      "id": 12345,
      "tx_hash": "0xabc...",
      "block_number": 417390882,
      "origin_user": "0x259B6b9C...",
      "protocol_name": "Aave V3 Pool",
      "action_type": "SUPPLY",
      "apy_percent": 5.23,
      "amount_usd": 1055.60,
      "token_symbol": "WETH",
      "timestamp": "2026-01-03T07:19:29Z"
    }
  ],
  "total": 1523,
  "limit": 100,
  "offset": 0
}

Export enriched events in CSV or JSON format for analysis. Includes yield data and protocol classifications.

# Export 100 enriched events as CSV
curl -H "X-API-Key: def_xxx" \
  "https://defeyes-api.vercel.app/api/events/export?format=csv&limit=100" \
  -o high_yield_events.csv

tx_hash,block_number,timestamp,origin_user,protocol_name,action_type,
method_name,amount_usd,token_symbol,apy_percent,yield_pool,...

Get aggregated statistics and activity profile for a specific wallet address.

# Get wallet profile
curl -H "X-API-Key: def_xxx" \
  "https://defeyes-api.vercel.app/api/wallets/0x4cdba844ceb949567e3dbf94c5b0f7b3c8e5d2a1"

{
  "address": "0x4cdba844ceb949567e3dbf94c5b0f7b3c8e5d2a1",
  "total_events": 156,
  "first_seen": "2025-11-15T10:23:45Z",
  "last_seen": "2026-01-05T08:12:33Z",
  "protocols_used": ["Aave V3", "CoW Protocol", "Uniswap"],
  "action_breakdown": {
    "SUPPLY": 45,
    "SWAP": 78,
    "BORROW": 23,
    "WITHDRAW": 10
  },
  "total_volume_usd": 125430.50
}

Returns real-time statistics about enriched events, unique wallets, classification coverage, and protocol breakdown.

{
  "enriched_events": 31239,
  "unique_wallets": 7895,
  "enrichment_progress": "99.7%",
  "protocol_breakdown": {
    "Aave V3 Pool": 17188,
    "Cow Protocol": 1305,
    "Uniswap": 856
  },
  "last_updated": "2026-01-05T08:00:00.000Z"
}

Simple health check endpoint to verify API is running.

{
  "status": "ok",
  "time": "2026-01-05T08:00:00.000Z"
}

Check Reactive Network RPC connectivity and chain status.

{
  "status": "ok",
  "chainId": 4078,
  "blockNumber": 12345678,
  "rpcUrl": "https://mainnet-rpc.rnk.dev"
}

Check database connectivity and event counts.

{
  "status": "ok",
  "database": "connected",
  "total_events": 31239,
  "last_event": "2026-01-05T08:00:00.000Z"
}

Creates a new customer in the system and Stripe, generates an API key.

{
  "customer": {
    "id": 1,
    "email": "user@example.com",
    "stripe_customer_id": "cus_xxx"
  },
  "apiKey": "def_xxxxxxxxxxxxxxxx",
  "message": "Customer created and API key generated"
}

Create a subscription for an existing customer.

Retrieve all subscriptions for a customer by email.

{
  "subscriptions": [
    {
      "id": 1,
      "plan_name": "Pro",
      "status": "active",
      "current_period_end": "2026-02-05T00:00:00Z"
    }
  ]
}

Get your current API usage and rate limit status.

curl -H "X-API-Key: def_xxx" \
  "https://defeyes-api.vercel.app/api/usage"

{
  "requests_today": 156,
  "requests_this_hour": 23,
  "rate_limit": 1000,
  "plan": "Pro",
  "reset_at": "2026-01-05T09:00:00Z"
}

Returns pricing information, supported networks, and the USDC payment wallet address.

{
  "currency": "USDC",
  "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f5bE91",
  "networks": [
    {
      "id": "base",
      "name": "Base",
      "chainId": 8453,
      "usdcContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    },
    {
      "id": "arbitrum",
      "name": "Arbitrum One",
      "chainId": 42161,
      "usdcContract": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
    }
  ],
  "pricing": {
    "/api/stats": 0.0005,
    "/api/events": 0.001,
    "/api/events/export": 0.01,
    "/api/analytics": 0.005
  }
}

Verify that a USDC payment transaction is valid before using it for API access.

Request Body

{
  "valid": true,
  "amount": 0.001,
  "from": "0xYourWalletAddress..."
}

Step 1: Make Request

Call any data endpoint without authentication:

curl https://defeyes-api.vercel.app/api/events

Step 2: Receive 402 Response

The API returns payment instructions:

{
  "error": "Payment Required",
  "x402": {
    "price": 0.001,
    "currency": "USDC",
    "wallet": "0x742d35Cc..."
  }
}

Step 3: Send USDC Payment

Send the required USDC amount to the payment wallet on Base or Arbitrum.

Step 4: Retry with Payment Proof

Include the transaction hash in your request:

curl https://defeyes-api.vercel.app/api/events \
  -H "X-Payment-Proof: 0xYourTxHash..." \
  -H "X-Payment-Network: base"

Python Example

import requests
from web3 import Web3

# 1. Make initial request
response = requests.get("https://defeyes-api.vercel.app/api/events")

if response.status_code == 402:
    payment_info = response.json()["x402"]
    
    # 2. Send USDC (using web3.py)
    w3 = Web3(Web3.HTTPProvider("https://mainnet.base.org"))
    usdc = w3.eth.contract(address=USDC_ADDRESS, abi=ERC20_ABI)
    
    tx = usdc.functions.transfer(
        payment_info["wallet"],
        int(payment_info["price"] * 1e6)  # USDC has 6 decimals
    ).transact()
    
    tx_hash = w3.eth.wait_for_transaction_receipt(tx).transactionHash.hex()
    
    # 3. Retry with payment proof
    response = requests.get(
        "https://defeyes-api.vercel.app/api/events",
        headers={
            "X-Payment-Proof": tx_hash,
            "X-Payment-Network": "base"
        }
    )
    
    data = response.json()

Returns method signatures that haven't been classified yet, ordered by frequency.

{
  "unknown_methods": [
    {
      "method_id": "0x1ad2cc3b",
      "count": 234,
      "sample_tx": "0xabc..."
    }
  ]
}

Add a new method classification to the enrichment registry.