# WalletLens API

> Paid x402 API for EVM wallet portfolio snapshots, wallet reports, and enriched transaction history.

WalletLens provides machine-readable wallet intelligence for agents and automation. It returns normalized token balances, native balances, USD prices where available, top holdings, stablecoin totals, Base wallet lookup data, USDC transfer history, decoded transfer rows, counterparties, and TxLens enriched transaction history across supported EVM chains. Paid endpoints use x402 over HTTP 402 Payment Required.

## Key URLs

- [Health](https://walletlens.wallyweb.com/health): Service health check.
- [Status](https://walletlens.wallyweb.com/status): Machine-readable status, resources, pricing, and docs links.
- [Discover](https://walletlens.wallyweb.com/discover): Machine-readable agent entrypoint with capabilities, paid resources, examples, and x402 flow.
- [Wallets to try](https://walletlens.wallyweb.com/wallets-to-try): Seed wallet addresses with free helper links and direct paid wallet-report URLs.
- [Ask](https://walletlens.wallyweb.com/ask?q=analyze%20wallet%200x52E29e0d2Aa49bfBfC548C0A9F2196F4aa51f3ea%20on%20base): Free intent helper that turns natural-language wallet requests into paid URLs.
- [Analyze](https://walletlens.wallyweb.com/analyze?address=0x52E29e0d2Aa49bfBfC548C0A9F2196F4aa51f3ea&chains=base): Free structured intent helper for agents that already have an address.
- [Preview](https://walletlens.wallyweb.com/preview): Free cached live demo wallet response and portfolio shape.
- [Examples](https://walletlens.wallyweb.com/examples?format=json): Copy-paste calls for agents.
- [Sample wallet report](https://walletlens.wallyweb.com/examples/wallet-report): Free static sample shaped like the paid `/wallet-report` response.
- [Sample transaction history](https://walletlens.wallyweb.com/examples/tx-history): Free static sample shaped like the paid `/tx-history` response.
- [Sample portfolio](https://walletlens.wallyweb.com/examples/portfolio): Free static sample shaped like the paid `/portfolio` response.
- [Pricing](https://walletlens.wallyweb.com/pricing): Price, network, and payment details.
- [x402 discovery](https://walletlens.wallyweb.com/.well-known/x402.json): Paid resource metadata.
- [x402 discovery alias](https://walletlens.wallyweb.com/.well-known/x402): Same metadata for clients that omit `.json`.
- [OpenAPI](https://walletlens.wallyweb.com/openapi.json): Machine-readable API schema.
- [Full LLM docs](https://walletlens.wallyweb.com/llms-full.txt): Complete agent usage guide.
- [WalletLens agent skill](https://walletlens.wallyweb.com/docs/walletlens-agent-skill.md): Shareable instructions for agent clients.
- [WalletLens agent skill alias](https://walletlens.wallyweb.com/walletlens-agent-skill.md): Root-level alias for crawlers.

## Paid Endpoints

- `GET /portfolio`
- `GET /tx-history`
- `GET /wallet-report`
- Price: `$0.02` USDC per request
- Payment network: Base mainnet, `eip155:8453`
- Payment protocol: x402
- Query params:
  - `address`: required EVM wallet address
  - `chains`: optional comma-separated chain list

## Supported Chains

- `base`
- `ethereum` or `eth`
- `optimism`
- `arbitrum`
- `polygon`

## Notes For Agents

Start with `/discover`, `/wallets-to-try`, `/ask`, `/analyze`, `/.well-known/x402.json`, and `/openapi.json`. For unpaid requests to `/portfolio`, `/tx-history`, or `/wallet-report` with a valid `address`, expect HTTP `402` with a `payment-required` response header. Use an x402-capable client to satisfy the payment requirement, then retry the same request with the payment header.

Use `/wallet-report` when the agent needs one answer for "analyze this wallet", "summarize this Base wallet", "get EVM wallet portfolio and transaction history", "find recent USDC transfers", or "explain this onchain wallet activity".

## How To Call

Free quote:

```bash
curl "https://walletlens.wallyweb.com/quote?address=0x52E29e0d2Aa49bfBfC548C0A9F2196F4aa51f3ea&chains=base"
```

Free intent helper:

```bash
curl "https://walletlens.wallyweb.com/wallets-to-try?format=json"
curl "https://walletlens.wallyweb.com/ask?q=analyze%20wallet%200x52E29e0d2Aa49bfBfC548C0A9F2196F4aa51f3ea%20on%20base"
curl "https://walletlens.wallyweb.com/analyze?address=0x52E29e0d2Aa49bfBfC548C0A9F2196F4aa51f3ea&chains=base"
```

Free sample response:

```bash
curl https://walletlens.wallyweb.com/examples/wallet-report
```

Paid wallet report negotiation:

```bash
curl -i "https://walletlens.wallyweb.com/wallet-report?address=0x52E29e0d2Aa49bfBfC548C0A9F2196F4aa51f3ea&chains=base&limit=20"
```

Paid TxLens transaction history negotiation:

```bash
curl -i "https://walletlens.wallyweb.com/tx-history?address=0x52E29e0d2Aa49bfBfC548C0A9F2196F4aa51f3ea&chains=base&limit=20"
```