▣ FINANCE

WalletFinder - Historical On-Chain Trading Analytics

What it does

Wallet Finder helps you discover and inspect trading wallets, trades, and raw swap activity across Ethereum, Base, and Solana. Send a chain plus a timeframe, and get ranked wallet or trade results back with profit, win rate, risk, and other trading signals.

Use the Discover wallets endpoint to list wallets by metrics such as tokens, totalProfit, potentialATHprofit, speed, alphaPerc, gemPerc, winPerc, realAlphaPerc, riskPerc, suspiciousTokenPerc, or walletRiskStatus. You can filter results, choose ascending or descending sort order, and include or exclude scam and risky wallets. The response includes each wallet address plus the selected performance and risk fields, along with totalRecords for pagination.

Use the Discover trades endpoint when you want token-level activity instead of wallet summaries. It supports sorting by fields like tradeDate, block, investment, netProfit, netXs, ATHXs, and riskPerc, and can filter by tokenSymbol. Each result includes the trader wallet address, token address, token symbol, profit and investment values, risk status, alert counts, and the token image URL when available.

For deeper analysis, the Raw swap events endpoint returns low-level swap records sorted by block, timestamp, token, trader, or transaction hash. Each record includes swap side, amounts, price fields, pool and quote addresses, transaction hash, gas usage, and token metadata. Use Wallet overview or Wallet overview stats to fetch a single wallet’s metrics for a timeframe, including inv_prof_hist in the overview response and a compact stats payload in the stats endpoint.

▣ ENDPOINT 01 / 05

GET

Discover wallets

https://api.eu.apyhub.com/walletfinderai/historical-chain-trading-analytics/discoverWallets

QUICKSTART

GUIDE

Quickstart

Get a sorted list of wallets for a chosen chain and timeframe.

curl -X GET "https://api.eu.apyhub.com/walletfinderai/historical-chain-trading-analytics/discoverWallets?chain=ethereum&sortBy=totalProfit&sortOrder=desc&timeframe=day" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with a wallets array and a totalRecords integer. Each item in wallets is an object with wallet metrics such as walletAddress, tokens, totalProfit, walletRiskStatus, and related fields.

{
  "wallets": [
    {
      "walletAddress": "0xabc123...",
      "tokens": 12,
      "totalProfit": 2450.5,
      "walletRiskStatus": "NORMAL"
    }
  ],
  "totalRecords": 1
}

TRY ITLIVE · 10 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns a filtered and sorted list of discovered wallets. You control the chain, timeframe, sorting, and visibility of scam or risky wallets through query parameters.

Query Parameter(s)

Attribute	Type	Mandatory	Description
page	Integer	No	Page number to return. Default: `1`. Minimum: `1`.
chain	ENUM	Yes	Allowed values: `ethereum`, `base`, `solana`.
filter	String	No	Filter text. The schema also allows an array of strings, but the documented query type is a string.
sortBy	ENUM	Yes	Allowed values: `walletAddress`, `tokens`, `totalProfit`, `potentialATHprofit`, `speed`, `alphaPerc`, `diamondTokens`, `gemPerc`, `winPerc`, `realAlphaPerc`, `scamPerc`, `averageXs`, `averageATHXs`, `lastBuy`, `lastInvestment`, `averageHODL`, `riskPerc`, `suspiciousTokenPerc`, `walletRiskStatus`.
sortOrder	ENUM	Yes	Allowed values: `asc`, `desc`.
timeframe	ENUM	Yes	Allowed values: `hour`, `day`, `week`, `month`, `month3`, `year`.
showScamWallets	ENUM	No	Allowed values: `true`, `false`. Default: `false`.
showRiskyWallets	ENUM	No	Allowed values: `true`, `false`. Default: `false`.

Response

Returns a JSON object with a wallets array and a totalRecords integer. Each item in wallets is an object describing one wallet, and totalRecords is the total number of matching records.

Parameter	Type	Mandatory	Description
wallets	Object Array	No	Array of wallet objects. Each item may include these fields: `walletAddress`, `speed`, `tokens`, `gemPerc`, `lastBuy`, `winPerc`, `Category`, `riskPerc`, `alphaPerc`, `averageXs`, `averageHODL`, `totalProfit`, `averageATHXs`, `diamondTokens`, `realAlphaPerc`, `lastInvestment`, `walletRiskStatus`, `potentialATHprofit`, `suspiciousTokenPerc`.
totalRecords	Integer	No	Total number of matching records.

Notes

The wallets array items include a walletRiskStatus enum with values NORMAL, RISK, and SCAM. showScamWallets and showRiskyWallets default to false, so wallets in those categories are excluded unless you explicitly set the corresponding query parameter to true.

Query parameters

Name

Type

Description

pageOPTIONAL

integer

—

DEFAULT 1

chainREQUIRED

string

ethereum · base · solana

—

filterOPTIONAL

string

—

sortByREQUIRED

string

walletAddress · tokens · totalProfit · potentialATHprofit · speed · …

—

sortOrderREQUIRED

string

asc · desc

—

timeframeREQUIRED

string

hour · day · week · month · month3 · …

—

showScamWalletsOPTIONAL

string

true · false

—

DEFAULT false

showRiskyWalletsOPTIONAL

string

true · false

—

DEFAULT false

▣ ENDPOINT 02 / 05

GET

Discover trades

https://api.eu.apyhub.com/walletfinderai/historical-chain-trading-analytics/discoverTrades

QUICKSTART

GUIDE

Quickstart

Fetch the first page of Ethereum trades for the last day, sorted by trade date.

curl -X GET "https://api.eu.apyhub.com/walletfinderai/historical-chain-trading-analytics/discoverTrades?chain=ethereum&sortBy=tradeDate&sortOrder=desc&timeframe=day" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with a trades array and a totalRecords integer. Each item in trades is an object with trade details such as walletAddress, tokenAddress, tokenSymbol, tradeDate, and related metrics.

{
  "trades": [
    {
      "walletAddress": "0x1234...abcd",
      "tokenAddress": "0xabcd...1234",
      "tokenSymbol": "USDC",
      "tradeDate": "2026-09-03 09:30:00",
      "investment": 1000,
      "netProfit": 250
    }
  ],
  "totalRecords": 1
}

TRY ITLIVE · 10 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns a list of discovered trades filtered and sorted by the query parameters you provide, along with the total number of matching trades across all pages. The endpoint does not define a request body; all inputs are sent as query parameters.

Query Parameter(s)

Attribute	Type	Mandatory	Description
page	Integer	No	Page number. Default: `1`. Minimum: `1`.
chain	ENUM	Yes	Allowed values: `ethereum`, `base`, `solana`.
filter	String	No	String filter value. The schema also allows an array of strings, but this endpoint documents the parameter as a query string value.
sortBy	ENUM	Yes	Allowed values: `walletAddress`, `tokenAddress`, `tokenSymbol`, `tradeDate`, `block`, `firstBuy`, `maxATHProfit`, `ATHXs`, `investment`, `netProfit`, `netXs`, `riskPerc`.
sortOrder	ENUM	Yes	Allowed values: `asc`, `desc`.
timeframe	ENUM	Yes	Allowed values: `hour`, `day`, `week`, `month`, `month3`, `year`.
tokenSymbol	String	No	Token symbol to filter by.
showScamWallets	ENUM	No	Allowed values: `true`, `false`. Default: `false`.
showRiskyWallets	ENUM	No	Allowed values: `true`, `false`. Default: `false`.
showWrappedTokens	ENUM	No	Allowed values: `true`, `false`. Default: `false`.
excludeStableCoins	ENUM	No	Allowed values: `true`, `false`. Default: `true`.

Response

Returns a JSON object with a trades array field and a totalRecords integer field. Each item in trades is an object containing trade details such as wallet, token, profit, risk, and status fields.

Parameter	Type	Mandatory	Description
trades	Object Array	No	Array of trade objects. Each object may include: `ATHXs`, `block`, `netXs`, `Category`, `firstBuy`, `riskPerc`, `tokenUrl`, `netProfit`, `tradeDate`, `investment`, `tokenSymbol`, `maxATHProfit`, `tokenAddress`, `walletAddress`, `riskAlertCount`, `scamAlertCount`, `tradeRiskStatus`, `walletRiskStatus`.
totalRecords	Integer	No	Total number of matching trades across all pages.

Notes

The trades array items include several fields whose types are not fixed to a single JSON type in the schema: ATHXs and netXs may be either a number or a string, with the description indicating exponential-notation strings for very large magnitudes. The tradeRiskStatus and walletRiskStatus fields are enums with allowed values NORMAL, RISK, and SCAM.

Query parameters

Name

Type

Description

pageOPTIONAL

integer

—

DEFAULT 1

chainREQUIRED

string

ethereum · base · solana

—

filterOPTIONAL

string

—

sortByREQUIRED

string

walletAddress · tokenAddress · tokenSymbol · tradeDate · block · …

—

sortOrderREQUIRED

string

asc · desc

—

timeframeREQUIRED

string

hour · day · week · month · month3 · …

—

tokenSymbolOPTIONAL

string

—

showScamWalletsOPTIONAL

string

true · false

—

DEFAULT false

showRiskyWalletsOPTIONAL

string

true · false

—

DEFAULT false

showWrappedTokensOPTIONAL

string

true · false

—

DEFAULT false

excludeStableCoinsOPTIONAL

string

true · false

—

DEFAULT true

▣ ENDPOINT 03 / 05

GET

Raw swap events

https://api.eu.apyhub.com/walletfinderai/historical-chain-trading-analytics/swaps

QUICKSTART

GUIDE

Quickstart

Fetch the latest raw swap events for a chain, sorted by the field you choose.

curl -X GET "https://api.eu.apyhub.com/walletfinderai/historical-chain-trading-analytics/swaps?chain=ethereum&sortBy=timestamp&sortOrder=desc" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON array of event objects. Each object may include fields such as side, timestamp, token_name, amount_token, amount_quote, block_number, pool_address, token_address, trader_address, and transaction_hash.

[
  {
    "side": "buy",
    "timestamp": 1710000000,
    "token_name": "Example Token",
    "amount_token": 100.5,
    "amount_quote": 2500.75,
    "block_number": 12345678,
    "pool_address": "0xabc123...",
    "token_address": "0xdef456...",
    "trader_address": "0x789abc...",
    "transaction_hash": "0xdeadbeef..."
  }
]

TRY ITLIVE · 30 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns raw swap event records for the specified chain, sorted according to the requested field and order. The response is a JSON array of swap event objects.

Query Parameter(s)

Attribute	Type	Mandatory	Description
chain	ENUM	Yes	Allowed values: `ethereum`, `base`, `solana`.
filter	String	No	A string filter value; the schema also allows an array of strings.
sortBy	ENUM	Yes	Allowed values: `_price_native_usd`, `amount_native`, `amount_token`, `amount_quote`, `block_number`, `gas_price_native`, `gas_used`, `interacted_with_address`, `pool_address`, `price_token_usd_robust_tick_1`, `price_token_usd_tick_1`, `protocol_name`, `record_index`, `side`, `timestamp`, `quote_address`, `token_address`, `token_name`, `token_symbol`, `trader_address`, `transaction_fee_native`, `transaction_hash`.
sortOrder	ENUM	Yes	Allowed values: `asc`, `desc`.

Response

Returns a JSON array of swap event objects. Each object may include fields such as side (String), gas_used (Number), timestamp (Integer), token_url (String), and the other top-level properties declared in the output schema.

Parameter	Type	Mandatory	Description
side	String	No	Swap side.
gas_used	Number	No	Gas used.
timestamp	Integer	No	Timestamp.
token_url	String	No	Token image/logo URL, unmodified. May be an empty string if unavailable.
token_name	String	No	Token name.
amount_quote	Number	No	Quote amount.
amount_token	Number	No	Token amount.
block_number	Integer	No	Block number.
pool_address	String	No	Pool address.
record_index	Integer	No	Record index.
token_symbol	String	No	Token symbol.
amount_native	Number	No	Native amount.
protocol_name	String	No	Protocol name.
quote_address	String	No	Quote address.
token_address	String	No	Token address.
trader_address	String	No	Trader's wallet address.
gas_price_native	Number	No	Native gas price.
transaction_hash	String	No	Transaction hash.
_price_native_usd	Number	No	Native price in USD.
price_token_usd_tick_1	Number	No	Token USD price using tick 1.
transaction_fee_native	Number	No	Native transaction fee.
interacted_with_address	String	No	Interacted-with address.
token_creation_timestamp	Integer	No	Token creation timestamp.
price_token_usd_robust_tick_1	Number	No	Token USD price using robust tick 1.

Query parameters

Name

Type

Description

chainREQUIRED

string

ethereum · base · solana

—

filterOPTIONAL

string

—

sortByREQUIRED

string

_price_native_usd · amount_native · amount_token · amount_quote · block_number · …

—

sortOrderREQUIRED

string

asc · desc

—

▣ ENDPOINT 04 / 05

GET

Wallet overview

https://api.eu.apyhub.com/walletfinderai/historical-chain-trading-analytics/walletOverview

QUICKSTART

GUIDE

Quickstart

Fetch a wallet overview for a specific wallet address and timeframe.

curl -X GET "https://api.eu.apyhub.com/walletfinderai/historical-chain-trading-analytics/walletOverview?walletAddress=0x8ba1f109551bD432803012645Ac136ddd64DBA72&timeframe=day" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with a data object and a chains array. The data object includes wallet overview metrics such as chain, speed, tokens, gemPerc, lastBuy, winPerc, riskPerc, alphaPerc, averageXs, averageHODL, totalProfit, averageATHXs, diamondTokens, inv_prof_hist, realAlphaPerc, walletAddress, lastInvestment, walletRiskStatus, and potentialATHprofit.

{
  "data": {
    "chain": "ethereum",
    "speed": "fast",
    "tokens": 12,
    "walletAddress": "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
  },
  "chains": ["ethereum", "base", "solana"]
}

TRY ITLIVE · 8 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns wallet overview data for the requested wallet address and timeframe, with an optional chain filter. The response includes a data object with wallet metrics and a top-level chains array listing supported chains.

Query Parameter(s)

Attribute	Type	Mandatory	Description
chain	String	No	Allowed values: `ethereum`, `base`, `solana`.
timeframe	String	Yes	Allowed values: `hour`, `day`, `week`, `month`, `month3`, `year`.
walletAddress	String	Yes	Wallet address.

Response

Returns a JSON object with a data object field and a chains string array field. The data object contains wallet overview metrics, including the wallet chain, counts, percentages, profitability fields, an investment history array, and the wallet risk status.

Parameter	Type	Mandatory	Description
data	Object	No	Wallet overview details.
data.chain	ENUM	No	Allowed values: `ethereum`, `base`, `solana`.
data.speed	String	No	Wallet speed.
data.tokens	Integer	No	Number of tokens.
data.gemPerc	Number	No	Gem percentage.
data.lastBuy	String	No	Last buy value.
data.winPerc	Number	No	Win percentage.
data.riskPerc	Number	No	Risk percentage.
data.alphaPerc	Number	No	Alpha percentage.
data.averageXs	Number	No	Average Xs value; can also be a string.
data.averageHODL	String	No	Average HODL value.
data.totalProfit	Number	No	Total profit.
data.averageATHXs	Number	No	Average ATH Xs value; can also be a string.
data.diamondTokens	Integer	No	Number of diamond tokens.
data.inv_prof_hist	Object Array	No	Investment profit history entries. Each item contains `profit`, `timestamp` (formatted in US Eastern Time), `investment`, and `tokenSymbol`.
data.inv_prof_hist[].profit	Number	No	Profit value.
data.inv_prof_hist[].timestamp	String	No	Formatted in US Eastern Time.
data.inv_prof_hist[].investment	Number	No	Investment value.
data.inv_prof_hist[].tokenSymbol	String	No	Token symbol.
data.realAlphaPerc	Number	No	Real alpha percentage.
data.walletAddress	String	No	Wallet address.
data.lastInvestment	Number	No	Last investment value.
data.walletRiskStatus	ENUM	No	Allowed values: `NORMAL`, `RISK`, `SCAM`.
data.potentialATHprofit	Number	No	Potential ATH profit.
chains	String Array	No	Supported chains. Allowed values: `ethereum`, `base`, `solana`.

Query parameters

Name

Type

Description

chainOPTIONAL

string

ethereum · base · solana

—

timeframeREQUIRED

string

hour · day · week · month · month3 · …

—

walletAddressREQUIRED

string

—

▣ ENDPOINT 05 / 05

GET

Wallet overview stats

https://api.eu.apyhub.com/walletfinderai/historical-chain-trading-analytics/walletOverviewStats

QUICKSTART

GUIDE

Quickstart

Fetch wallet overview stats for a wallet on the selected chain and timeframe.

curl -X GET "https://api.eu.apyhub.com/walletfinderai/historical-chain-trading-analytics/walletOverviewStats?walletAddress=0x742d35Cc6634C0532925a3b844Bc454e4438f44e&timeframe=month&chain=ethereum" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with a data object and a chains array. The data object includes wallet stats such as chain, speed, tokens, gemPerc, lastBuy, winPerc, riskPerc, alphaPerc, averageXs, averageHODL, totalProfit, averageATHXs, diamondTokens, realAlphaPerc, walletAddress, lastInvestment, walletRiskStatus, and potentialATHprofit; chains lists supported chain values.

{
  "data": {
    "chain": "ethereum",
    "speed": "fast",
    "tokens": 12,
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
  },
  "chains": ["ethereum", "base", "solana"]
}

TRY ITLIVE · 5 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Retrieves overview statistics for a wallet over a requested timeframe. The response returns a JSON object with a data object containing the wallet stats and a chains string array listing supported chains.

Query Parameter(s)

Attribute	Type	Mandatory	Description
chain	String	No	Allowed values: `ethereum`, `base`, `solana`.
timeframe	String	Yes	Allowed values: `hour`, `day`, `week`, `month`, `month3`, `year`.
walletAddress	String	Yes	Wallet address.

Response

Returns a JSON object with a data object and a chains string array. The data object contains wallet overview fields such as chain, performance metrics, counts, and risk status; chains lists the supported chain values.

Attribute	Type	Mandatory	Description
data	Object	No	Wallet overview stats object. Contains `chain`, `speed`, `tokens`, `gemPerc`, `lastBuy`, `winPerc`, `riskPerc`, `alphaPerc`, `averageXs`, `averageHODL`, `totalProfit`, `averageATHXs`, `diamondTokens`, `realAlphaPerc`, `walletAddress`, `lastInvestment`, `walletRiskStatus`, and `potentialATHprofit`.
chains	String Array	No	Supported chain values. Allowed values: `ethereum`, `base`, `solana`.

Query parameters

Name

Type

Description

chainOPTIONAL

string

ethereum · base · solana

—

timeframeREQUIRED

string

hour · day · week · month · month3 · …

—

walletAddressREQUIRED

string

—

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.