API Documentation

WalletIQ profiles EVM wallets by analyzing on-chain transaction history across 5 chains. One API call returns age, activity stats, risk scoring, behavioral labels, and wallet type classification.

Base URL (API key auth)

https://walletiq-zeta.vercel.app/api/v1

Base URL (x402 pay-per-call)

https://walletiq-zeta.vercel.app/api/v1/x402

Authentication

All API requests require a Bearer token. Get your API key from the dashboard.

Authorization: Bearer wiq_your_api_key_here

Keep your key secret. Never expose it in client-side code. Use environment variables and server-side requests.

x402 Pay-per-Call

No signup, no API key. Pay $0.005 USDC on Base per lookup using the x402 protocol.

GET /v1/x402/profile/:address

How it works

Request — Hit the endpoint without payment → get HTTP 402 with payment-required header

Parse — Decode the base64 payment-required header → get price, network, payTo address

Sign — Sign a USDC transfer on Base using your wallet (EIP-3009 transferWithAuthorization)

Pay — Replay the request with x-payment header → server verifies → serves profile → settles USDC

Payment Details

Price	$0.005 USDC per lookup
Network	Base mainnet (`eip155:8453`)
Token	USDC (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`)
Scheme	exact (x402 v2)
Payment header	`x-payment`

Quick test (get payment requirements)

curl -sD - https://walletiq-zeta.vercel.app/api/v1/x402/profile/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

Returns 402 with payment-required header (base64 JSON). Decode to see price and payTo.

Perfect for AI agents. x402 enables autonomous agents to pay for data without pre-configured API keys. See our TypeScript client demo for a complete working example.

Profile Endpoint

GET /v1/profile/:address

Parameters

Name	Type	Description
`address`	path	EVM address (0x + 40 hex chars)

Scans Ethereum, Avalanche, Arbitrum, Base, and Optimism.

Response Shape

{
  "address": "0x742d35cc6634c0532925a3b844bc9e7595f2bd18",
  "chains": [
    "ethereum",
    "arbitrum",
    "base"
  ],
  "firstSeen": "2018-06-15T10:30:00.000Z",
  "lastActive": "2025-05-10T14:22:00.000Z",
  "age": {
    "days": 2521,
    "label": "OG (2018)"
  },
  "stats": {
    "totalTransactions": 847,
    "uniqueContractsInteracted": 63,
    "totalValueWei": "158400000000000000000"
  },
  "risk": {
    "score": 18,
    "level": "low",
    "flags": []
  },
  "labels": [
    "power-user",
    "defi-user",
    "og"
  ],
  "walletType": "eoa",
  "scanDurationMs": 1243
}

Field Reference

address Lowercased EVM address

chains Chains where activity was found

firstSeen Timestamp of earliest transaction (ISO 8601)

lastActive Timestamp of most recent transaction

age.days Account age in days

age.label Human-readable: New, Recent, Active, Veteran, OG

stats.totalTransactions Total tx count across all chains

stats.uniqueContractsInteracted Unique contract addresses called

stats.totalValueWei Total value transferred in wei (string)

risk.score 0–100 risk score (lower is safer)

risk.level low / medium-low / medium / high / critical

risk.flags Array of risk indicators (e.g. "repetitive-pattern")

labels Behavioral tags: whale, power-user, defi-user, og, new-wallet, etc.

walletType eoa / contract / unknown

scanDurationMs Time taken to produce profile (milliseconds)

Rate Limits

Requests are rate-limited per API key using a sliding window. Every response includes rate limit headers.

Tier	Rate Limit	Price
Free	10 req/min	$0
Developer	60 req/min	$49/mo
Growth	300 req/min	$149/mo

Response Headers

X-RateLimit-Limit: 10       # Max requests per minute
X-RateLimit-Remaining: 7   # Remaining in current window
X-RateLimit-Reset: 1717000  # Unix timestamp when window resets

When rate-limited, the response includes a Retry-After header with seconds to wait.

Error Codes

Status	Meaning	Example
400	Bad Request	Invalid address format
401	Unauthorized	Missing or invalid API key
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Upstream provider failure

Error response format:

{
  "error": {
    "message": "Invalid Ethereum address. Expected format: 0x followed by 40 hex characters."
  }
}

Code Examples

curl -X GET \
  "https://walletiq.dev/api/v1/profile/0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18" \
  -H "Authorization: Bearer wiq_your_api_key_here"

Usage Endpoint

GET /v1/usage

Returns usage statistics for the authenticated API key.

{
  "tier": "free",
  "tierLabel": "Free",
  "rateLimit": 10,
  "totalRequests": 142,
  "requestsToday": 8,
  "lastUsedAt": "2025-05-10T14:22:00.000Z",
  "createdAt": "2025-04-01T09:00:00.000Z"
}