# WalletFinder — Historical On-Chain Trading Analytics
> Historical wallet, trade, and swap metrics for Ethereum, Base, and Solana. Filterable analytics — not investment advice.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/walletfinder/..."
```

## Pricing
- **Free** (Free) — 100 calls/Mo, 1 req/s
- **Starter** ($15/Mo) — 10,000 calls/Mo, 5 req/s
- **Pro** ($40/Mo) — 75,000 calls/Mo, 15 req/s
- **Ultra** ($120/Mo) — 400,000 calls/Mo, 20 req/s

## Endpoints

### Discovery

#### `GET /discoverTrades` — Discover trades

Returns a paginated, filterable list of individual token trades made by tracked wallets. Wallet addresses are always returned in plain form on this API tier.

**Parameters:**
- `sortBy` (query, required, string)
- `sortOrder` (query, required, string)
- `timeframe` (query, required, string)
- `chain` (query, required, string)
- `filter` (query, optional, string) — Column filter expression(s), format `columnName:operator:value`. Can be repeated for multiple filters.
- `page` (query, optional, integer) — Page number, min 1. 100 records per page.
- `excludeStableCoins` (query, optional, string) — Exclude stablecoin trades from results.
- `tokenSymbol` (query, optional, string) — Filter to trades of a specific token symbol.
- `showRiskyWallets` (query, optional, string)
- `showScamWallets` (query, optional, string)
- `showWrappedTokens` (query, optional, string) — Include wrapped-token trades (Ethereum only).

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/walletfinder/discoverTrades"
```

**Response:**
```json
{
    "trades": [
        {
            "ATHXs": 8377.67,
            "block": "978943",
            "netXs": 1.13,
            "Category": "whale",
            "firstBuy": 3121.01,
            "riskPerc": 58,
            "tokenUrl": "https://logo1.birdeye.so/resources/ether/0x812ba41e071c7b7fa4ebcfb62df5f45f6fa853ee.jpeg",
            "netProfit": 7059.36,
            "tradeDate": "09/08/2026 21:17",
            "investment": 53650.9,
            "tokenSymbol": "Neiro",
            "maxATHProfit": 449416075.5,
            "tokenAddress": "0x812ba41e071c7b7fa4ebcfb62df5f45f6fa853ee",
            "walletAddress": "0x5b43453fce04b92e190f391a83136bfbecedefd1",
            "riskAlertCount": 0,
            "scamAlertCount": 0,
            "tradeRiskStatus": "NORMAL",
            "walletRiskStatus": "NORMAL"
        },
        {
            "ATHXs": 69.81,
            "block": "36724",
            "netXs": 2.41,
            "Category": "shark",
            "firstBuy": 1245.61,
            "riskPerc": null,
            "tokenUrl": null,
            "netProfit": 6378.97,
            "tradeDate": "09/07/2026 22:30",
            "investment": 4521.69,
            "tokenSymbol": "Marvin",
            "maxATHProfit": 311130.61,
            "tokenAddress": "0x42778037d69350508cdd34d9fa17053970591101",
            "walletAddress": "0x746b0cfd83f452059d15f68f9cea3fbc6c660761",
            "riskAlertCount": null,
            "scamAlertCount": null,
            "tradeRiskStatus": "NORMAL",
  
…(truncated, see openapi.json for full schema)
```

#### `GET /discoverWallets` — Discover wallets

Returns a paginated, filterable list of tracked wallets with sortable historical trading metrics (PnL, win rate, etc.). Wallet addresses are always returned in plain form on this API tier.

**Parameters:**
- `sortBy` (query, required, string)
- `sortOrder` (query, required, string)
- `timeframe` (query, required, string)
- `chain` (query, required, string)
- `filter` (query, optional, string) — Column filter expression(s), format `columnName:operator:value`. Can be repeated for multiple filters.
- `page` (query, optional, integer) — Page number, min 1. 100 records per page.
- `showRiskyWallets` (query, optional, string)
- `showScamWallets` (query, optional, string)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/walletfinder/discoverWallets"
```

**Response:**
```json
{
    "wallets": [
        {
            "speed": "> 1 day",
            "tokens": 20,
            "gemPerc": 70,
            "lastBuy": "09/08/2026 13:01",
            "winPerc": 55,
            "Category": "shrimp",
            "riskPerc": 76.65,
            "alphaPerc": 55,
            "averageXs": 1.17,
            "averageHODL": "< 5 mins",
            "totalProfit": 423372.12,
            "averageATHXs": 1361.92,
            "diamondTokens": 9,
            "realAlphaPerc": 51.05,
            "walletAddress": "0xc54b77b28ee4d18cd3d93991f08b79bc85c71097",
            "lastInvestment": 665.03,
            "walletRiskStatus": "NORMAL",
            "potentialATHprofit": 6572889.37,
            "suspiciousTokenPerc": 0.28061224489795916
        },
        {
            "speed": "> 1 day",
            "tokens": 52,
            "gemPerc": 59.62,
            "lastBuy": "09/08/2026 21:17",
            "winPerc": 50,
            "Category": "whale",
            "riskPerc": 74.28,
            "alphaPerc": 55.77,
            "averageXs": 0.75,
            "averageHODL": "< 24 hours",
            "totalProfit": 167418.58,
            "averageATHXs": 1665.48,
            "diamondTokens": 21,
            "realAlphaPerc": 58.62,
            "walletAddress": "0x5b43453fce04b92e190f391a83136bfbecedefd1",
            "lastInvestment": 426633.6,
            "walletRiskStatus": "NORMAL",
            "potentialATHprofit": 39059236.54,
            "suspiciousTokenPerc": 0.13793103448275862
   
…(truncated, see openapi.json for full schema)
```

### Swaps

#### `GET /swaps` — Raw swap events

Returns the raw list of individual swap events (up to 10,000 matching records per request) from the DEX trade log.

**Parameters:**
- `sortBy` (query, required, string)
- `sortOrder` (query, required, string)
- `chain` (query, required, string)
- `filter` (query, optional, string) — Column filter expression(s), format `columnName:operator:value`. Can be repeated for multiple filters.

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/walletfinder/swaps"
```

### Wallet

#### `GET /walletOverview` — Wallet overview

Returns a single wallet's historical trading metrics plus its investment/profit history for the selected timeframe.

**Parameters:**
- `chain` (query, optional, string) — If omitted, the wallet is looked up across all chains and the first match's chain is used.
- `walletAddress` (query, required, string) — Plain wallet address to look up.
- `timeframe` (query, required, string)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/walletfinder/walletOverview"
```

#### `GET /walletOverviewStats` — Wallet overview stats

Returns the same historical trading metrics as `/walletOverview`, without the investment/profit history array.

**Parameters:**
- `chain` (query, optional, string)
- `walletAddress` (query, required, string) — Plain wallet address to look up.
- `timeframe` (query, required, string)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/walletfinder/walletOverviewStats"
```


---
Marketplace page: https://www.oanor.com/api/walletfinder
OpenAPI spec: https://www.oanor.com/api/walletfinder/openapi.json