# WalletLens API

WalletLens is a paid API for EVM wallet intelligence: normalized portfolio snapshots, bundled wallet reports, and enriched transaction history. It is intended for AI agents, portfolio workflows, wallet monitoring tools, Base wallet lookup, USDC transfer analysis, and automation systems that need a clean response shape without maintaining their own multi-chain indexing pipeline.

Base URL:

```text
https://walletlens.wallyweb.com
```

## Discovery

Use these public, unpaid resources:

```text
GET /
GET /health
GET /status
GET /preview
GET /pricing
GET /examples
GET /examples?format=json
GET /examples/portfolio
GET /examples/tx-history
GET /examples/wallet-report
GET /discover
GET /wallets-to-try
GET /wallets-to-try?format=json
GET /ask?q=analyze wallet 0x... on base
GET /analyze?address=0x...&chains=base
GET /.well-known/x402
GET /.well-known/x402.json
GET /openapi.json
GET /llms.txt
GET /llms-full.txt
GET /docs/walletlens-agent-skill.md
GET /walletlens-agent-skill.md
```

Recommended evaluation flow:

1. Read `/discover` for capabilities, x402 payment details, and copy-paste examples.
2. Read `/wallets-to-try` for seeded wallet addresses with direct helper, quote, and paid URLs.
3. Call `/ask?q=analyze wallet 0x... on base` or `/analyze?address=0x...&chains=base` to convert intent into a valid paid URL.
4. Read `/examples/wallet-report`, `/examples/tx-history`, or `/examples/portfolio` to inspect the paid response shape without payment.
5. Read `/status` for resource, pricing, chain, and docs links.
6. Read `/.well-known/x402.json` or request `/portfolio`, `/tx-history`, or `/wallet-report` with a valid `address` to get the x402 payment requirement.
7. Pay only when live wallet data is needed.

## Payment

WalletLens uses x402. Paid endpoints return HTTP `402 Payment Required` when no valid x402 payment is supplied.

Payment details:

- Scheme: `exact`
- Network: `eip155:8453`
- Chain: Base mainnet
- Asset: USDC
- Price: `$0.02`
- Expected unpaid response: HTTP `402` with a `payment-required` header

Agent flow:

1. Convert user intent for free with `GET /ask?q=...` or `GET /analyze?address=...&chains=...`.
2. Validate the request for free with `GET /quote?address=...&chains=...`.
3. Request `GET /portfolio?address=...&chains=...`, `GET /tx-history?address=...&chains=...`, or `GET /wallet-report?address=...&chains=...`.
4. If HTTP `402`, parse the `payment-required` header.
5. Create and submit the x402 payment payload using an x402-compatible client.
6. Retry the exact same request with the payment header.
7. Parse the JSON response.

Missing or invalid `address` returns HTTP `400` before payment negotiation. A valid unpaid paid-endpoint request returns HTTP `402`.

## Endpoint: GET /portfolio

Returns a normalized EVM wallet portfolio snapshot.

Query parameters:

- `address`: required EVM address, formatted as `0x` plus 40 hex characters.
- `chains`: optional comma-separated chain list. Defaults to `base,ethereum`.

Supported chains:

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

Example:

```bash
curl -i "https://walletlens.wallyweb.com/portfolio?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&chains=base,ethereum"
```

## Endpoint: GET /tx-history

Returns TxLens enriched EVM transaction history.

Query parameters:

- `address`: required EVM address, formatted as `0x` plus 40 hex characters.
- `chains`: optional comma-separated chain list. Defaults to `base,ethereum`.
- `limit`: optional result cap from 1 to 100. Defaults to `50`.
- `days`: optional requested lookback intent from 1 to 365. Defaults to `30`.
- `category`: optional `all`, `external`, `internal`, `erc20`, `erc721`, or `erc1155`.

Example:

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

The paid response includes:

- `summary.transactionCount`
- per-chain transaction counts
- direction counts: `in`, `out`, `self`, `unknown`
- action counts, such as `token_transfer`, `native_transfer`, `nft_transfer`
- normalized transaction rows with `hash`, `timestamp`, `direction`, `counterparty`, `type`, `asset`, `value`, `decoded`, `labels`, and `riskFlags`

## Endpoint: GET /wallet-report

Returns a bundled wallet report for agents that need one paid call for portfolio plus transaction history.

Query parameters:

- `address`: required EVM address, formatted as `0x` plus 40 hex characters.
- `chains`: optional comma-separated chain list. Defaults to `base,ethereum`.
- `limit`: optional transaction result cap from 1 to 100. Defaults to `50`.
- `days`: optional requested transaction lookback intent from 1 to 365. Defaults to `30`.
- `category`: optional `all`, `external`, `internal`, `erc20`, `erc721`, or `erc1155`.

Example:

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

Use this endpoint for agent intents such as "analyze this wallet", "summarize this Base wallet", "get portfolio and transaction history", "find recent USDC transfers", "show top holdings and counterparties", or "explain EVM wallet activity".

Expected unpaid result:

```text
HTTP/2 402
payment-required: <base64 encoded x402 payment requirements>
```

Expected paid response shape:

```json
{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "timestamp": "2026-05-17T00:00:00.000Z",
  "chains": ["base", "ethereum"],
  "summary": {
    "totalValueUsd": "1234.56",
    "pricedTokenCount": 8,
    "unpricedTokenCount": 2,
    "tokenCount": 10,
    "stablecoinValueUsd": "125.50",
    "chains": [],
    "topHoldings": [],
    "warnings": ["2 tokens are missing USD prices"]
  },
  "tokens": [
    {
      "chain": "base",
      "chainId": "eip155:8453",
      "contract": "0x...",
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6,
      "logo": "https://...",
      "rawBalance": "1000000",
      "balance": "1",
      "priceUsd": "1.00",
      "valueUsd": "1"
    }
  ],
  "positions": [],
  "recentActivity": [],
  "provider": "alchemy"
}
```

## Error Behavior

- Missing or invalid `address`: HTTP `400`
- Unsupported `chains`: HTTP `400`
- Missing payment on `/portfolio` or `/tx-history`: HTTP `402`
- Provider or server failure: HTTP `500`

## Test Queries

Health:

```bash
curl https://walletlens.wallyweb.com/health
```

Status:

```bash
curl https://walletlens.wallyweb.com/status
```

Free cached live preview:

```bash
curl https://walletlens.wallyweb.com/preview
```

The preview is intentionally limited to the configured demo wallet and returns a compact token/activity list. Use paid `/portfolio` calls for arbitrary wallet addresses and full output.

x402 discovery:

```bash
curl https://walletlens.wallyweb.com/.well-known/x402.json
curl https://walletlens.wallyweb.com/.well-known/x402
```

Agent discovery:

```bash
curl https://walletlens.wallyweb.com/discover
curl "https://walletlens.wallyweb.com/wallets-to-try?format=json"
curl "https://walletlens.wallyweb.com/examples?format=json"
```

Intent helpers:

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

Free sample paid-response shapes:

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

Free quote:

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

Portfolio, unpaid 402:

```bash
curl -i "https://walletlens.wallyweb.com/portfolio?address=0x0000000000000000000000000000000000000000&chains=base"
```

Portfolio, multi-chain:

```bash
curl -i "https://walletlens.wallyweb.com/portfolio?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&chains=base,ethereum,arbitrum,optimism,polygon"
```

TxLens transaction history:

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

Bundled wallet report:

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

## OpenAPI

Fetch the OpenAPI schema at:

```text
https://walletlens.wallyweb.com/openapi.json
```

## Agent Skill

Fetch the shareable WalletLens agent skill at:

```text
https://walletlens.wallyweb.com/docs/walletlens-agent-skill.md
```