A powerful metrics-based project filtering and sorting tool that works with cryptocurrency assets
based on their metrics and allows for ordered, paginated results.
The tool allows for filtering assets by a metric and sorting them according to that same metric
in ascending or descending metric, or just to sort the assets by a metric without filtering.
This tool allows you to discover projects that meet specific criteria by analyzing their
metrics over time periods. You can filter projects by absolute values (greater_than/less_than thresholds)
or by percentage changes, or just sort projects by some metric.
## When to use vs other metric tools
This tool scans the whole asset universe and returns one aggregated value per
matching asset — use it for "which assets satisfy X" and "top N by X".
It never returns a timeseries: for the values of a metric over time for
already-known slugs use `fetch_metric_data_tool`. To check that a metric
exists (or fix a mistyped metric/slug) use `metrics_and_assets_discovery_tool`.
## Use Cases
- Get top 10 assets by marketcap, sorted in descending order
- Get top 50 assets with highest dev_activity_1d
- Find assets with price more than $10
- Discover tokens whose price increased by more than 50% in the last 30 days
- Screen for projects with market cap less than $100M
- Identify assets that have dev_activity_1d decline by more than 20% in the past month
## Examples
- Get projects that have a price_usd in the last 24 hours and it's greater_than $500. Get the first 20
ordered by price_usd in descending order
`{metric: "price_usd", operator: :greater_than, threshold: 500.0, from: "utc_now-24h", to: "utc_now", sort: "desc, page: 1, page_size: 20}`
- Find projects whose price_usd today is 25% higher than 7 days ago, sorted by the highest percent increase in descending order. Get the first 100.
`{metric: "price_usd", operator: :percent_up, threshold: 25.0, from: "utc_now-7d", to: "utc_now", sort: "desc", page: 1, page_size: 100}`
- Projects with current market cap less_than $50M. Get 100 such projects, ordered by marketcap in descending order.
`{metric: "marketcap_usd", operator: :less_than, threshold: 50000000.0, from: "utc_now-1d", to: "utc_now", sort: "desc", page: 1, page_size: 100}`
Here is how the filtering works:
- For absolute value operators - `greater_than` and `less_than` - fetch the `metric` for each asset in the interval
`from`-`to`, aggregting it using the specified `aggregation` method (defaulting to the metric's default).
- For percent change operators - `percent_up` and `percent_down` - fetch the `metric` for each asset
in the interval `from-`to`, as well as in the same length interval immediately before `from`.
The two resulting values are compared to calculate the percentage change.
Some metrics like price_usd and marketcap_usd are aggregated with `LAST` aggregation by default,
meaning that the last known value in the queried interval is used. For percent change, this means that
the tool compares the last known price immediately before `from` and the last known price before `to`.
Other metrics like transaction_volume_usd and social_volume_total (and most other volume metrics) are aggregated by
default with SUM aggregation, meaning that the total combined sum in the queried interval is used. For these
metrics length of the time window is vital. A common mistake is to try to check if the social_total_total for
the last 5 minutes is greater_than some threshold. Five minutes is not enough for social volume to accumulate enough.
In such scenarios use a longer time window like 1 day or more.
