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.dev/api/v1

Base URL (x402 pay-per-call)

https://walletiq.dev/api/v1/x402

Billing

100 included monthly credits, Stripe subscriptions + top-ups, and x402 / MPP for pay-per-call.

Authentication

API-key requests use your WalletIQ monthly allowance first, then any prepaid Stripe credits. Get your key from the dashboard or programmatically via POST /api/v1/register.

http

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.

SDKs

Official SDKs for JavaScript/TypeScript and Python. Zero-config, typed responses, built-in error handling.

JS JavaScript / TypeScript

npm install walletiq

import { WalletIQ } from "walletiq";

const wiq = new WalletIQ({ apiKey: "wiq_..." });
const profile = await wiq.getProfile("0xd8dA...");
console.log(profile.risk.level);

PY Python

pip install walletiq

from walletiq import WalletIQ

wiq = WalletIQ(api_key="wiq_...")
profile = wiq.get_profile("0xd8dA...")
print(profile.risk.level)

Both SDKs support API key auth, playground access, and x402 payments (JS only for v0.1). See full SDK docs.

x402 Pay-per-Call

No signup, no API key. Pay $0.005 USDC on Base or Avalanche per lookup using the x402 protocol. MPP-capable agent clients can use the same route.

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 or Avalanche 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
Networks	Base mainnet (`eip155:8453`) and Avalanche C-Chain (`eip155:43114`)
Tokens	USDC on Base and USDC on Avalanche
Scheme	exact (x402 v2)
Payment header	`x-payment`

Quick test (get payment requirements)

bash

curl -sD - https://walletiq.dev/api/v1/x402/profile/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

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

Perfect for AI agents. x402 / MPP flows let autonomous agents 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

json

{
  "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

http

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

json

Error response format:

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

Code Examples

bash

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.

json

{
  "tier": "free",
  "tierLabel": "Free",
  "rateLimit": 10,
  "includedCredits": 100,
  "includedCreditsUsed": 12,
  "includedCreditsRemaining": 88,
  "prepaidCredits": 5000,
  "totalCreditsAvailable": 5088,
  "subscriptionStatus": "inactive",
  "currentPeriodEndsAt": "2026-04-30T23:59:59.000Z",
  "totalRequests": 142,
  "requestsToday": 8,
  "lastUsedAt": "2025-05-10T14:22:00.000Z",
  "createdAt": "2025-04-01T09:00:00.000Z"
}