Strategy Tools — fere_tools Reference

import fere_tools as F

# Discovery
F.catalog("wallet")
meta = F.describe("current_prices_tool")

# Invoke (unwrapped result)
prices = F.call("current_prices_tool", token_names=["ETH", "SOL"])

Available Cryptocurrency Categories And chains supported by coingecko. These categories are useful for fetching `search_coins_by_category` present in a category from coingecko (www.coingecko.com).

Returns:
  CategoryResponse: A list of categories (category id and category name) and a map of chains (chain name to its networkId) supported by coingecko.

CategoryResponse: A list of categories (category id and category name) and a map of chains (chain name to its networkId) supported by coingecko.

Fetch current USD price + market data for one or more tokens (CoinGecko).

Args:
  token_names: List of token symbols/names (e.g. ``["ETH", "SOL"]``).
  remove_optional: Drop the bulky ``tickers`` field (exchange-by-
    exchange data). Keep ``True`` unless you truly need per-exchange
    price data; if you must, limit token_names to ≤ 10 per call.

Returns (``CryptocurrencyList`` serialized as dict) — already unwrapped
when called via ``F.current_prices_tool(...)``. **Top-level key is
``currencies``, not ``cryptocurrencies``.** Field names match the
``Cryptocurrency`` pydantic model in
``friday/airflow/dags/friday/libs/tokens/schema.py`` — snake_case,
``current_price`` / ``market_cap`` / ``total_volume`` with **no
``_usd`` suffix** (values are in USD by default). Concrete shape::

    {
      "currencies": [
        {
          "id": "ethereum",
          "symbol": "eth",                   # lowercase; upper() to compare
          "name": "Ethereum",
          "market_cap_rank": 2,
          "current_price": 3456.78,          # USD
          "market_cap": 416_000_000_000,     # USD
          "total_volume": 15_000_000_000,    # USD, 24h
          "high_24h": 3478.55,
          "low_24h": 3390.22,
          "price_change_24h": -42.3,
          "price_change_percentage_24h": -1.23,
          "price_change_percentage_7d": 4.56,
          "price_change_percentage_1h": 0.12,
          "ath": 4878.26,                    # NOT ath_usd
          "atl": 0.4327,                     # NOT atl_usd
          "circulating_supply": 120_000_000.0,
          "total_supply": 120_000_000.0,
          "contract": "0x...",               # contract on motherchain
          "motherchain": 1,                  # numeric chain id
          "chains": {"ethereum": {"contract": "0x...", "decimals": 18}, ...},
          # Many optional fields (``links``, ``description``,
          # ``sparkline_in_7d``, social/interaction metrics, etc.)
          # may be present — check one row with list(c.keys()) if you
          # need a rarely-used field.
          # "tickers": [...]  only when remove_optional=False
        },
        ...
      ]
    }

Index by symbol::

    by_symbol = {c["symbol"].upper(): c for c in prices["currencies"]}
    eth_price = by_symbol["ETH"]["current_price"]

On upstream failure this returns a **plain string** error message
(no ``currencies`` key) — guard with ``isinstance(prices, dict) and
"currencies" in prices``.

Fetch trending coins/tokens sorted by trending score. Can be filtered by chain or return cross-chain results.

Data Provider: Codex (on-chain data aggregator)

Args:
    chain_name (str): Optional. The blockchain network name. If empty, returns trending coins across ALL chains. Supported chains: `abstract`, `abstract testnet`, `apechain`, `aptos`, `arbitrum`, `arbitrum nova`, `astar`, `aurora`, `avalanche`, `avalanche dfk`, `base`, `base sepolia`, `blast`, `blast sepolia`, `bnb chain`, `boba`, `callisto`, `canto`, `celo`, `cheesechain`, `chiliz`, `conflux`, `conwai`, `core`, `cronos`, `degen chain`, `dogechain`, `echelon`, `echos`, `elastos`, `energi`, `energy web`, `ethereum`, `ethereum sepolia`, `evmos`, `fantom`, `flow evm`, `flow evm testnet`, `fuse`, `goerli`, `gravity alpha`, `ham`, `harmony`, `heco`, `hoo smart chain`, `hyperevm`, `immutable`, `ink`, `iotex`, `kardiachain`, `klaytn`, `kucoin community chain`, `manta`, `mantle`, `meld`, `meter`, `metis`, `milkomeda`, `mode`, `moonbeam`, `moonriver`, `oasis emerald`, `odyssey chain`, `oec`, `opbnb`, `optimism`, `over protocol`, `plasma`, `plume`, `plume legacy`, `polis`, `polygon`, `polygon mumbai`, `polygon zkevm`, `pulsechain`, `re.al`, `ronin`, `saigon`, `sanko`, `sanko sepolia`, `scroll`, `sei`, `sei arctic`, `shibarium`, `shiden`, `smartbch`, `solana`, `somnia`, `somnia shannon testnet`, `sonic`, `sophon`, `starknet`, `story`, `story aeneid testnet`, `story iliad`, `sui`, `superposition`, `swellchain`, `syscoin`, `taraxa`, `telos`, `treasure`, `tron`, `unichain`, `vana`, `vector`, `velas`, `wanchain`, `world chain`, `xai`, `xdai`, `yominet`, `zircuit`, `zksync`, `zora`, `zyx`
    score_interval (str): Trending score time window. One of "5m", "1h", "4h", "12h", "24h". Default is "24h".
    limit (int): Number of trending coins to return. Default is 20, max 100.
    custom_filters (dict, optional): Custom filters to apply on top of trending tokens response. Defaults to None to use Codex's predefined trending filters.

        **Safety Floor Filters (always enforced):**
        The following minimum thresholds are always applied to prevent scam/honeypot tokens from appearing in results.
        They are enforced as minimum thresholds for each field:
        - `liquidity`: >= $100,000  (minimum pool liquidity)
        - `holders`: >= 50          (minimum unique holders)
        - `uniqueBuys24`: >= 30     (minimum unique buyers in 24h)
        - `uniqueSells24`: >= 10    (minimum unique sellers in 24h)
        You can set stricter values in `custom_filters`, but you cannot set lower minimums than these floors.

        When specified, custom_filters should be a dictionary with filter parameters. Supported filters include:

        **Time Interval Convention**:
        Field suffixes indicate time windows: `5m` = 5 minutes, `1` = 1 hour, `4` = 4 hours, `12` = 12 hours, `24` = 24 hours.
        For example, `volume5m` is volume in the past 5 minutes, `buyCount1` is buy count in the past hour, `change24` is price change over 24 hours.

        **Numeric Filters** (accept dict with operators or single value):

        *Timestamp Fields:*
        - `createdAt`: Unix timestamp for the creation of the token's first pair
        - `lastTransaction`: Unix timestamp for the token's last transaction

        *Price & Market Data:*
        - `priceUSD`: The token price in USD
        - `marketCap`: The market cap of circulating supply
        - `circulatingMarketCap`: The circulating market cap
        - `liquidity`: The amount of liquidity in the token's top pair

        *Volume (Total):*
        - `volume5m`: Trade volume in USD in the past 5 minutes
        - `volume1`: Trade volume in USD in the past hour
        - `volume4`: Trade volume in USD in the past 4 hours
        - `volume12`: Trade volume in USD in the past 12 hours
        - `volume24`: Trade volume in USD in the past 24 hours

        *Buy Volume:*
        - `buyVolume5m`: Buy volume in USD in the past 5 minutes
        - `buyVolume1`: Buy volume in USD in the past hour
        - `buyVolume4`: Buy volume in USD in the past 4 hours
        - `buyVolume12`: Buy volume in USD in the past 12 hours
        - `buyVolume24`: Buy volume in USD in the past 24 hours

        *Sell Volume:*
        - `sellVolume5m`: Sell volume in USD in the past 5 minutes
        - `sellVolume1`: Sell volume in USD in the past hour
        - `sellVolume4`: Sell volume in USD in the past 4 hours
        - `sellVolume12`: Sell volume in USD in the past 12 hours
        - `sellVolume24`: Sell volume in USD in the past 24 hours

        *Price Changes (decimal format, e.g., 0.5 for 50%):*
        - `change5m`: Percent price change in the past 5 minutes
        - `change1`: Percent price change in the past hour
        - `change4`: Percent price change in the past 4 hours
        - `change12`: Percent price change in the past 12 hours
        - `change24`: Percent price change in the past 24 hours

        *Volume Changes (decimal format):*
        - `volumeChange5m`: Percent volume change in the past 5 minutes
        - `volumeChange1`: Percent volume change in the past hour
        - `volumeChange4`: Percent volume change in the past 4 hours
        - `volumeChange12`: Percent volume change in the past 12 hours
        - `volumeChange24`: Percent volume change in the past 24 hours

        *High Prices:*
        - `high5m`: Highest price in USD in the past 5 minutes
        - `high1`: Highest price in USD in the past hour
        - `high4`: Highest price in USD in the past 4 hours
        - `high12`: Highest price in USD in the past 12 hours
        - `high24`: Highest price in USD in the past 24 hours

        *Low Prices:*
        - `low5m`: Lowest price in USD in the past 5 minutes
        - `low1`: Lowest price in USD in the past hour
        - `low4`: Lowest price in USD in the past 4 hours
        - `low12`: Lowest price in USD in the past 12 hours
        - `low24`: Lowest price in USD in the past 24 hours

        *Transaction Counts:*
        - `txnCount5m`: Number of transactions in the past 5 minutes
        - `txnCount1`: Number of transactions in the past hour
        - `txnCount4`: Number of transactions in the past 4 hours
        - `txnCount12`: Number of transactions in the past 12 hours
        - `txnCount24`: Number of transactions in the past 24 hours

        *Buy Counts:*
        - `buyCount5m`: Number of buys in the past 5 minutes
        - `buyCount1`: Number of buys in the past hour
        - `buyCount4`: Number of buys in the past 4 hours
        - `buyCount12`: Number of buys in the past 12 hours
        - `buyCount24`: Number of buys in the past 24 hours

        *Sell Counts:*
        - `sellCount5m`: Number of sells in the past 5 minutes
        - `sellCount1`: Number of sells in the past hour
        - `sellCount4`: Number of sells in the past 4 hours
        - `sellCount12`: Number of sells in the past 12 hours
        - `sellCount24`: Number of sells in the past 24 hours

        *Unique Transactions:*
        - `uniqueTransactions5m`: Unique number of transactions in the past 5 minutes
        - `uniqueTransactions1`: Unique number of transactions in the past hour
        - `uniqueTransactions4`: Unique number of transactions in the past 4 hours
        - `uniqueTransactions12`: Unique number of transactions in the past 12 hours
        - `uniqueTransactions24`: Unique number of transactions in the past 24 hours

        *Unique Buys:*
        - `uniqueBuys5m`: Unique number of buys in the past 5 minutes
        - `uniqueBuys1`: Unique number of buys in the past hour
        - `uniqueBuys4`: Unique number of buys in the past 4 hours
        - `uniqueBuys12`: Unique number of buys in the past 12 hours
        - `uniqueBuys24`: Unique number of buys in the past 24 hours

        *Unique Sells:*
        - `uniqueSells5m`: Unique number of sells in the past 5 minutes
        - `uniqueSells1`: Unique number of sells in the past hour
        - `uniqueSells4`: Unique number of sells in the past 4 hours
        - `uniqueSells12`: Unique number of sells in the past 12 hours
        - `uniqueSells24`: Unique number of sells in the past 24 hours

        *Wallet Statistics:*
        - `walletAgeAvg`: Average age of the wallets that traded in the last 24 hours
        - `walletAgeStd`: Standard deviation of age of the wallets that traded in the last 24 hours
        - `swapPct1dOldWallet`: Percentage of wallets that are less than 1 day old that have traded in the last 24 hours
        - `swapPct7dOldWallet`: Percentage of wallets that are less than 7 days old that have traded in the last 24 hours

        *Other Metrics:*
        - `holders`: Number of different wallets holding the token

        *Launchpad Metrics:*
        - `launchpadGraduationPercent`: The graduation percentage for the launchpad
        - `launchpadCompletedAt`: Unix timestamp when the launchpad was completed
        - `launchpadMigratedAt`: Unix timestamp when the launchpad was migrated

        **Numeric Filter Operators:**
        Numeric filters can be specified as:
        - Comparison dict: `{"priceUSD": {"gt": 0.001, "lt": 1}}`
        - Operators: `gt` (>), `gte` (>=), `lt` (<), `lte` (<=)

        **IMPORTANT: Filters compare against constant numeric values only, NOT against other fields.**
        - CORRECT: `{"buyCount24": {"gte": 100}}` - compares buyCount24 against the number 100
        - INCORRECT: `{"buyCount24": {"gt": "sellCount24"}}` - comparing against another field name is NOT supported

        **Handling "more buyers than sellers" or similar field-to-field comparisons:**
        For queries like "tokens with more buyers than sellers", you CANNOT use filters directly.
        Instead, fetch the data without such filters (buyCount24 and sellCount24 will be in the response),
        then compare the values in the returned tokens yourself to filter out tokens where buyCount24 <= sellCount24.

        **Boolean Filters:**
        - `potentialScam`: Filter tokens flagged as potential scams. Set to `True` to show only potential scams, `False` to exclude them
        - `includeScams`: Whether to include tokens that have been flagged as scams. Default is `False`
        - `isVerified`: Only include verified tokens when set to `True`. Not set by default. Use this only if explicitly mentioned in the user query.
        - `isTestnet`: Filter for tokens on testnet networks. `True` for testnet tokens only, `False` for mainnet tokens only, `None` (default) for both
        - `launchpadCompleted`: Filter tokens where the launchpad is completed
        - `launchpadMigrated`: Filter tokens where the launchpad has migrated
        - `freezable`: Filter tokens that are freezable
        - `mintable`: Filter tokens that are mintable

        **List Filters:**
        - `exchangeId`: List of exchange contract IDs to filter by. Applied in conjunction with network filter using an OR condition
        - `exchangeAddress`: List of exchange contract addresses to filter by
        - `launchpadProtocol`: List of launchpad protocols to filter by
        - `launchpadName`: List of launchpad names to filter by

        **String Filters:**
        - `creatorAddress`: Address of the token creator / dev to filter by

        Example usage:
        ```python
          custom_filters = {
              "priceUSD": {"gt": 0.0001, "lt": 1},  # Price between $0.0001 and $1
              "volume24": {"gte": 10000},            # 24h volume >= $10k
              "marketCap": {"gt": 100000, "lt": 10000000},  # Market cap $100k to $10M
              "change24": {"gt": 0.1},               # 24h price change > 10%
              "liquidity": {"gte": 50000},           # Liquidity >= $50k
              "buyCount24": {"gte": 100},            # At least 100 buys in last 24h
              "sellCount24": {"lte": 50},            # At most 50 sells in last 24h (more buyers than sellers)
              "holders": {"gte": 100},               # At least 100 holders
              "isVerified": True,                      # Only verified tokens
              "includeScams": False                    # Exclude scams
          }

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain_name` | `string` | No | Optional. The blockchain network name (e.g., 'solana', 'base', 'ethereum'). Empty string for cross-chain trending. |
| `score_interval` | `string` | No | Trending score time window: '5m', '1h', '4h', '12h', or '24h'. Default is '24h'. |
| `limit` | `integer` | No | Number of trending coins to return. Default is 20, max is 100. |
| `custom_filters` | `object` | No | Custom filters to apply. See get_trending_coins_description for full list of supported filters. |

**Returns**

```text
CryptocurrencyList: List of trending tokens with name, symbol, price, volume, market cap, and other metrics.

Fetch trending coins on a specific blockchain using Codex data.

Use for discovering trending tokens on a specific chain. Preferred over
merged_trending_coins when you want chain-specific trending data.

Args:
    chain_name: Blockchain name (e.g., 'solana', 'base', 'ethereum').
    score_interval: Time window for trending score ('5m', '1h', '4h', '12h', '24h').
    top_k: Number of trending coins to return (default 10, max 100).
    custom_filters: Optional filters for price, volume, liquidity, etc.

Returns:
    CryptocurrencyList: Trending coins with market data and metrics.

CryptocurrencyList: Trending coins with market data and metrics.

Fetch global market cap and volume. Uses the Coingecko Global Market Cap and Volume API to fetch relevant details for a given number of days.

Args:
  days: Get data for these many days. Default is 7.
  vs_currency: The base currency. Default is "usd".

Fetch historical prices for a list of tokens.

Contract addresses are the preferred method. For native tokens (BTC, ETH, SOL, etc.) that don't have contract addresses, use token_names instead.

Args:
  contract_addresses: List of token contract addresses (not pool addresses). Preferred method.
  token_names: List of token names for native tokens. Only used if contract_addresses is not provided.
  days: Number of days for which historical data to be fetched. Default is 7.

Returns:
  CryptocurrencyList with historical price data in historical_data field for each token.

CryptocurrencyList with historical price data in historical_data field for each token.

Fetch Trending coins (note that trending coins are not top coins by market cap) across chains, uses coingecko trending coins. Use `get_trending_coins_by_chain` tool only if user asks for trending on a specific chain.

Note: Trending coins are different from top coins. Trending coins are the coins that are currently trending on the market. Top coins are the coins that are the highest market cap coins.

Args:
  category_ids: List of Category ids to filter the trending coins on. Category id are often different from category name, due to similarity in names. Always confirm if you are using the correct category id by cross-referencing with the `available_cryptocurrency_categories_and_chains` tool.
  chain_id: Chain identifier (name or ID). None for all chains. Chain id are often different from chain name, due to similarity in names. Always confirm if you are using the correct chain id by cross-referencing with the `available_cryptocurrency_categories_and_chains` tool.
  include_attributes: Comma-separated attributes to include in API response
  fetch_all: Whether to fetch all available data

Search cryptocurrency by name and get relevant coins with thier coingecko coin id, coigecko symbol, market cap, liquidity, volume, etc.

RULE:
1. Whenever this tool is used, the chat must be terminated by asking the user which Contract Address they want to use.
0. This rule takes precedence over anything else.

Args:
  query: Coin name to search for. [Instructions and Rules for query parameter start] Users might refer to crypto currency as coin or token and the word coin / token might not be present in the name itself. For example if user says `give me analysis on xyz coin`, it means the query must be `xyz` and not `xyz coin`. Whereas for example if the user had said `give me analysis on xyzcoin` then the coin_name has to be `xyzcoin`. Rule: Never add 'coin' or 'token' after a space. If 'coin'/'token' is part of the name, it must be joined without a space. Before assigning the query, take a step back and understand the structure of user's query and then apply the instructions and rules specified above to assign an appropriate query.[Instructions and Rules for query parameter end]
  remove_optional: Remove optional fields like tickers and exchange info.
  top_k_results: The top k results you want from the search results. By defaults kept at 5

Returns:
  A list of crypto currency with its coingecko coin id market cap, liquidity, volume, etc relevant to the search query.
  If no relevant coins are found, returns None.

Note:
  Each coin result will also reveal it coingecko coin id and coigecko symbol which can be used to use other coingecko tools where coin id / symbol is required.

A list of crypto currency with its coingecko coin id market cap, liquidity, volume, etc relevant to the search query.
  If no relevant coins are found, returns None.

Note:
  Each coin result will also reveal it coingecko coin id and coigecko symbol which can be used to use other coingecko tools where coin id / symbol is required.

Search coins either by query or category (with optional filters).

Args:
  query: Optional list of coin names, symbols, or contract addresses. Contract addresses preferred.
  category: Optional list of category IDs from available_cryptocurrency_categories_and_chains (like memcoins, ai-tokens, stablecoins etc).
            If provided, searches for coins in these categories and returns a list of coins in that category sorted in descending order of score. Use category IDs, not names.
  filters: Optional filters for category search.
  include_exchange_info: If True, includes exchange tickers and token holders data.
            WARNING: Exchange ticker data can be large in volume (potentially MBs).
            Only request this data when you actually need exchange/pair information.
            Do not query just for the sake of more data. Defaults to False.

Returns:
  - Query mode: dict[str, CryptocurrencyList] mapping each query string to its search results
  - Category mode: CryptocurrencyList with filtered results, or error string if invalid categories provided

Returns market data, coin metadata, supply data, historical prices, and social metrics.
If include_exchange_info is True, also returns exchange tickers and token holders.

For category search, call available_cryptocurrency_categories_and_chains first to get valid category IDs.
Category IDs differ from names. Invalid categories are filtered with suggestions provided.

- Query mode: dict[str, CryptocurrencyList] mapping each query string to its search results
  - Category mode: CryptocurrencyList with filtered results, or error string if invalid categories provided

Returns market data, coin metadata, supply data, historical prices, and social metrics.
If include_exchange_info is True, also returns exchange tickers and token holders.

For category search, call available_cryptocurrency_categories_and_chains first to get valid category IDs.
Category IDs differ from names. Invalid categories are filtered with suggestions provided.

Fetch cryptocurrency coins/tokens present in a category or chain and get its market cap, liquidity, volume, etc. from CoinGecko (www.coingecko.com/category). Not meant for historical data analysis.

  Before calling this, make sure to choose one or more appropriate category or chain id from the `available_cryptocurrency_categories` tool.
  It only returns last 7 days data. For more than 7 days, use the token ids from this response in historical_prices_tool.

Note:
  1. There may be many categories which represent the same theme. You must pick all the categories in such cases to get a comprehensive list of tokens.
  2. Send the chain-id only when you believe it has been asked.

Args:
  categories: List of category ids. Category id are often different from category name, due to similarity in names. Always confirm if you are using the correct category id by cross-referencing with the `available_cryptocurrency_categories_and_chains` tool.
  chain_id (Optional): Chain id. Chain id are often different from chain name, due to similarity in names. Always confirm if you are using the correct chain id by cross-referencing with the `available_cryptocurrency_categories_and_chains` tool. Default is None.
  market_cap_min(Optional): Minimum market cap. Default is None.
  market_cap_max(Optional): Maximum market cap. Default is None.
  fdv_min(Optional): Minimum fdv. Default is None.
  fdv_max(Optional): Maximum fdv. Default is None.
  circulating_supply_percentage_min(Optional): Minimum circulating supply percentage. Default is None.
  circulating_supply_percentage_max(Optional): Maximum circulating supply percentage. Default is None.
  total_volume(Optional): Total volume traded. Default is None.
  order(Optional): Ordering of results. Default is "market_cap_desc".
  count(Optional): Count of results. Default is 10.
  price_change_percentage(Optional): Price change percentage duration. Default is "24h".
  sparkline(Optional): Show spark line. Default is False.

Returns:
  CryptocurrencyList: A list of cryptocurrencies with their market cap, liquidity, volume, etc. in that particular category.

CryptocurrencyList: A list of cryptocurrencies with their market cap, liquidity, volume, etc. in that particular category.

Get token holders for a given contract address.

Returns the top holders of a token with their balances and percentages.
Useful for analyzing token distribution and whale concentration.

Args:
    chain: Blockchain network (e.g., 'ethereum', 'base', 'polygon').
    contract_address: The token's contract address.
    total_supply: Total supply of the token.
    limit: Number of top holders to return (default 10).

Returns:
    dict: Token holders with addresses, balances, and ownership percentages.

dict: Token holders with addresses, balances, and ownership percentages.

Fetch trending pools for a given chain identifier or sorts by volume if not specified. Uses the Coingecko Trending Pools API to fetch relevant details for a given chain identifier.

Args:
  chain_id: Optional chain name or ID to filter pools for a specific blockchain network, pass empty string when not applicable
  include_attributes: Optional comma-separated string of attributes to include in response, e.g., 'base_token,quote_token,dex', pass empty string when not applicable
  count: Number of trending pools to return
  fetch_all: Fetch all pages if True; otherwise fetch only the first page

Calculate historical investment performance for a cryptocurrency.

Simulates what an investment would be worth if made X days ago.
Useful for backtesting and understanding historical returns.

Args:
    coin_id: CoinGecko coin ID (e.g., 'bitcoin', 'ethereum').
    vs_currency: Currency to calculate against (e.g., 'usd').
    initial_investment: Initial investment amount.
    duration: Number of days to look back.

Returns:
    Tuple of (final_value, profit_loss, percent_change, price_data) or None.

Tuple of (final_value, profit_loss, percent_change, price_data) or None.

Batch check token contract security using RugCheck (Solana) or Honeypot.is (EVM).

This tool validates token contract safety by checking for:
- Honeypot contracts (tokens you can buy but not sell)
- Extreme sell taxes (>30%)
- Low liquidity (<$50k)
- Known rug pull patterns (Solana via RugCheck)

Args:
  tokens: List of dicts with 'token_address' (str) and 'chain_id' (int or str)
          Chain IDs: 1=Ethereum, 8453=Base, 7565164=Solana, 42161=Arbitrum, etc.
          Chain names also accepted: 'ethereum', 'base', 'solana', 'arbitrum'

Returns JSON string with:
  - results: list of per-token results with fields:
      - token_address: str
      - chain_id: int
      - allowed: bool (whether token passed checks)
      - status: str (passed | failed | warning | api_unavailable | unsupported_chain | skipped)
      - reason: str | null (explanation of issues)
      - provider: str (rugcheck | honeypot_is)
      - risk_details: dict | null (full provider response)
  - summary: dict with counts:
      - total: int
      - passed: int
      - failed: int
      - warning: int
      - api_unavailable: int

Status guidance:
  - passed: Token is clean, include normally in analysis
  - failed: High risk/honeypot - exclude from recommendations
  - warning: Medium risk/low liquidity/high tax - include with warning
  - api_unavailable: Check couldn't run - include with note

Example:
  contract_security_check_tool([
    {"token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "chain_id": 8453},
    {"token_address": "So11111111111111111111111111111111111111112", "chain_id": "solana"}
  ])

Fetch OHLCV (Open, High, Low, Close, Volume) candle data.

Use when you need full candle data (not just close prices) — price
tables, wick/pattern analysis, backtests.

Args:
  token_identifier: Token name (``"ETH"``) or contract address.
  interval: Candle interval. One of ``"1"`` (1min), ``"5"``, ``"60"``,
    ``"240"``, ``"1D"`` (day). Defaults to ``"1D"``.
  limit: Number of candles to return (max 100). Defaults to 30.

Returns (dict) — already unwrapped and JSON-decoded when called via
``F.ohlcv_history_tool(...)``. The wrapper emits exactly two keys on
success — no ``token`` or ``interval`` echo, no extra metadata::

    {
      "count": 30,
      "candles": [
        {
          "timestamp": "1729000000",       # unix seconds, STRING
          "open": 3412.10,
          "high": 3478.55,
          "low": 3390.22,
          "close": 3456.78,
          "volume": 15234567.89,
        },
        ...
      ],
    }

On failure, the wrapper emits a dict with **only** ``{"error":
"<reason>"}`` and no ``candles`` key — guard with
``if "candles" in result`` before iterating.

Fetch OHLCV data and calculate technical indicators for a token.

Contract address is the preferred method. For native tokens (BTC, ETH, SOL, etc.) that don't have contract addresses, use token_name instead.

Parameters:
    contract_address (str, optional): The token contract address (not pool address). Preferred method.
    token_name (str, optional): Token name for native tokens (because contract_address are not available for native tokens).
    interval (str): Candle Interval. Available options are `15m`, `1hr`, `4hr`, `1day`. If not specified use `4hr` by default.
    indicators (list): list of indicators to calculate. By default ALL indicators are calculated for comprehensive analysis.

Fallback Mechanism:
      After retrieving OHLCV data points, if the data points are less than 50 for a particular interval, try the same with a adjancently lower / higher interval and give that annalysis if feasible

Comprehensive token risk analysis with multi-dimensional scoring.

Analyzes tokens across 6 risk dimensions and produces a composite
risk score (0-100):
- Contract Security (35%): honeypot, mintable, proxy, taxes via GoPlus
- Holder Concentration (20%): top-10 whale %, largest holder via Ankr
- Technical Structure (20%): swing points, break price, trend health
- Token Age (10%): maturity score based on trading history
- Volume Health (10%): spike/low volume anomaly detection
- Macro (5%): BTC regime (risk-on vs risk-off)

Risk levels: LOW (75-100), MEDIUM (50-75), HIGH (25-50), VERY_HIGH (0-25)

Use cases:
- "Analyze my holdings" -> analyzes all tokens (leave token_name empty)
- "Risk analysis for Useless" -> token_name="Useless"
- "How risky is official trump" -> token_name="Official Trump"

Args:
    user_id: User ID (always required for context).
    token_name: Token name to analyze. Leave empty for all holdings.

Returns:
    JSON string with risk scores, levels, breakdowns, and flags.

JSON string with risk scores, levels, breakdowns, and flags.

Get casts from a Farcaster channel.

Retrieves recent posts from a specific Farcaster channel.

Args:
    channel: Farcaster channel ID (e.g., 'ethereum', 'base').

Returns:
    SocialPosts: Casts from the channel with content and engagement.

SocialPosts: Casts from the channel with content and engagement.

Fetch casts from a Farcaster user.

Retrieves recent posts from a specific Farcaster username.

Args:
    username: Farcaster username.
    limit: Number of casts to fetch (default 50).

Returns:
    SocialPosts: Casts from the user with content and engagement.

SocialPosts: Casts from the user with content and engagement.

Performs keyword search for casts.

It prepends $ to the token name. It passes the original token list
and the updated token list to the farcaster function.

Search news for multiple keywords.

Performs semantic search for casts.

Get top creators/influencers for a topic on social platforms.

Find influential voices on a topic. Combine with tweets_from_users
to get their specific content.

Args:
    topic: Topic to search for (e.g., 'bitcoin', 'defi').
    social_network: Platform ('twitter', 'youtube', 'tiktok').

Returns:
    Creators: List of top creators with follower counts and influence metrics.

Creators: List of top creators with follower counts and influence metrics.

Get top tweets from Twitter/X for cryptocurrency tokens.

BATCH multiple tokens in single call for efficiency.
Example: ['BTC', 'ETH', 'SOL'] instead of separate calls.

Args:
    tokens: List of token symbols (e.g., ['BTC', 'ETH']).
    duration: Days to look back (-1 for all available time).

Returns:
    SocialPosts: Top tweets with content, author, engagement metrics.

SocialPosts: Top tweets with content, author, engagement metrics.

Get tweets from specific Twitter/X users.

Retrieve recent tweets from specified usernames.
Tries LunarCrush first; falls back to TwitterAPI.io
if LunarCrush returns no results.

Args:
    users: List of Twitter usernames (without @).

Returns:
    SocialPosts: Tweets from the users with content and engagement.

SocialPosts: Tweets from the users with content and engagement.

Perform a combined internet search and social media lookup.

This tool gathers web search results ranked by reasoning utility
along with social insights from Twitter and Farcaster when a subject
keyword is provided.

The search uses objective-based ranking: results are scored by how
useful they are to your stated research goal, not by keyword match.
Results are automatically deduplicated by URL.

Usage Guidelines:
-----------------
- The `objective` drives result ranking. Name the entity and aspect
  precisely — e.g. "Arbitrum Stylus smart contract performance" not
  "Arbitrum info". Specify source preferences and exclusions relevant
  to crypto research.

- The `query` list should cover 2-5 distinct angles. Each query should
  surface a different type of source or information. If you already have
  results for one angle, don't rephrase it — pick a new angle.

- If the queries involve a specific subject, include the subject in
  the `socials` parameter as a one-word keyword.
    - Example: `socials=["bitcoin"]`, `socials=["ethereum"]`.
  This will gather **both web results and social intelligence**.

- If no subject keyword is provided in `socials`, the tool will
  simply return **web search results**.

Returned Data:
--------------
- **Web Results**: Always included, deduplicated by URL.
- **Twitter Data**: Returned if `socials` is provided.
- **Farcaster Data**: Returned if `socials` is provided and relevant
  data is found; otherwise `None`.

Parameters:
-----------
objective : str
    Natural language description of your research goal.
query : list[str]
    2-5 search queries covering different angles of the objective.
socials : list, optional
    List of one-word keywords (cryptocurrency symbols or other
    subject names) for which social insights should be gathered.

Returns:
--------
InternetSearchResponse
    Structured response containing:
    - `web`: Web search results (deduplicated by URL)
    - `twitter`: Twitter data (if socials provided, else None)
    - `farcaster`: Farcaster data (if socials provided and found,
      else None)

--------
InternetSearchResponse
    Structured response containing:
    - `web`: Web search results (deduplicated by URL)
    - `twitter`: Twitter data (if socials provided, else None)
    - `farcaster`: Farcaster data (if socials provided and found,
      else None)

Generate an answer to a question using Exa Search API.

Find similar pages to the given URL using Exa Search API.

Perform a web search using Exa Search API.

Downloads a PDF from a URL and extracts the text content.

Args:
    url: The URL of the PDF file.

Returns:
    The extracted text from the PDF.

Raises:
    RuntimeError: If the downloaded file is not a valid PDF or other PDF
        processing errors (e.g. password-protected).

The extracted text from the PDF.

Raises:
    RuntimeError: If the downloaded file is not a valid PDF or other PDF
        processing errors (e.g. password-protected).

Scrape a web page with Firecrawl.

Args:
    urls: The list of URLs of the web pages to scrape
Returns:
    WebCrawlItems: The scraped web page

WebCrawlItems: The scraped web page

Web search with Parallel as primary, then Firecrawl, then Exa as fallback.

Run Aave operation, with runtime-injected user and context.

import fere_tools as F

result = F.aave_operation()
print(result)

Cancel an active limit order.

Args:
    limit_order_id (str): The unique identifier of the limit order to cancel.
    runtime: Runtime context automatically injected into tools.

Returns:
    dict: Result of the cancellation operation with status, message, and limit_order_id.

dict: Result of the cancellation operation with status, message, and limit_order_id.

import fere_tools as F

orders = F.get_limit_orders(status="active")
if orders:
    print(F.cancel_limit_order(limit_order_id=orders[0]["limit_order_id"]))

Create limit orders with auto-fetched holdings and balance validation.

This function improves upon the original create_limit_order by:
1. Automatically calling get_holdings
2. Extracting decimals from holdings
3. Validating balance before creating limit order
4. Returning actionable suggestions if validation fails
5. Supporting partial success - if one order fails, others can still succeed
6. Processing orders in parallel using ThreadPoolExecutor

Args:
    limit_order_request: LimitOrderToolRequest with limit order details
    runtime: Runtime context automatically injected into tools.

Returns:
    - On all success: {"status": "success", "task_ids": [...]}
    - On partial success: {"status": "partial_success", "task_ids": [...], "failed_orders": [...]}
    - On all failed: {"status": "all_failed", "failed_orders": [...]}
    - On error: {"status": "error", "message": ...}

- On all success: {"status": "success", "task_ids": [...]}
    - On partial success: {"status": "partial_success", "task_ids": [...], "failed_orders": [...]}
    - On all failed: {"status": "all_failed", "failed_orders": [...]}
    - On error: {"status": "error", "message": ...}

import fere_tools as F

resp = F.create_limit_order(
    limit_order_request={
        "limit_orders": [
            {
                "chain_id": 8453,
                "token_in": "usdc",
                "token_out": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
                "amount": "50",
                "amount_in_USD": True,
                "price_usd_trigger": 2500.0,
                "condition": "lte",
                "trigger_token_address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
                "trigger_token_chain": "base",
            }
        ]
    }
)
print(resp)

Convert ENS name to Ethereum wallet address.

Resolves an ENS domain (e.g., 'vitalik.eth') to its corresponding
Ethereum address. Only works on Ethereum mainnet.

Args:
    ens_name: ENS name to resolve (e.g., 'vitalik.eth').

Returns:
    str: The resolved Ethereum address (0x...).

str: The resolved Ethereum address (0x...).

import fere_tools as F

result = F.ens_to_address(ens_name=<...>)
print(result)

Get the holdings of a wallet on all supported chains.

Args:
    user_id: The ID of the user.
    wallet_address: Optional override — the address of the wallet to read.
        If omitted, the authenticated user's default wallet is used.

Returns (dict) — already unwrapped when called via ``F.get_holdings()``.
Each ``EVM`` / ``SOLANA`` entry is a ``HoldingItem`` (Pydantic model
in ``wallet_service/src/schemas/wallet.py``) serialized via
``model_dump(mode="json")``. The authoritative field list lives on
that model; these are the fields you'll usually index::

    {
      "EVM": [
        {
          "token_name": "Ether",
          "pool_name": null,
          "base_address": "0x0000000000000000000000000000000000000000",
          "protocol": null,
          "chain": "base",
          "chain_id": 8453,
          "value_usd": 1250.40
        },
        {
          "token_name": "USDC (Base)",
          "pool_name": "USDC Pool",
          "base_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "protocol": null,
          "chain": "base",
          "chain_id": 8453,
          "value_usd": 500.00
        }
      ],
      "SOLANA": [ ...same shape, chain="solana"... ],
    }

Edge cases — ``"EVM"`` and ``"SOLANA"`` always present (possibly empty)::

    {"status": "dry_run", "message": "...", "SOLANA": [], "EVM": []}
    {"status": "no_user_context", "message": "...", "SOLANA": [], "EVM": []}

import fere_tools as F

holdings = F.get_holdings()
print("chains", list(holdings.keys()) if isinstance(holdings, dict) else holdings)

Get all limit orders for a user, optionally filtered by status.

Args:
    status (str, optional): Filter by status ('active', 'executed', 'cancelled', 'expired').
                            If None, returns all limit orders.
    runtime: Runtime context automatically injected into tools.

Returns:
    list: List of limit order details including limit_order_id, status, tokens, amounts, and trigger prices.

list: List of limit order details including limit_order_id, status, tokens, amounts, and trigger prices.

import fere_tools as F

result = F.get_limit_orders()
print(result)

Get wallet positions for any wallet address.

Retrieves token holdings and positions for an external wallet.
Use when user provides a wallet address to analyze.
For user's own holdings, use get_holdings instead.

Args:
    wallet_address: Wallet address (0x... or ENS like vitalik.eth).

Returns:
    WalletPosition: Token holdings with balances and values.

WalletPosition: Token holdings with balances and values.

import fere_tools as F

result = F.get_wallet_positions(wallet_address=<...>)
print(result)

Poll and wait for blockchain transaction completion.

Call this AFTER trade_tokens, transfer_tokens, or create_limit_order
return task_ids. This tool blocks until all
transactions reach a terminal state (success/failure) or timeout.

Args:
    task_ids: Wallet-service task IDs to poll.
    runtime: Tool runtime (injected; not passed by caller).
    tool_name: Which tool produced the task_ids.
    timeout_seconds: Max wait time.
    not_found_grace_seconds: Grace period before treating missing task IDs as
        NOT_FOUND.

Returns:
    {"status": "success"|"partial"|"failed", "results": [...]}
    Each result has: task_id, status, success, txn_url, error.

{"status": "success"|"partial"|"failed", "results": [...]}
    Each result has: task_id, status, success, txn_url, error.

import fere_tools as F

poll = F.poll_transaction_status(
    task_ids=["<task_id_from_prior_write>"],
    tool_name="trade_tokens",
)
print(poll["status"], poll.get("results"))

Recharge user credits (product credits) by bridging tokens to fee wallet.

This function bridges native tokens from the user's wallet on the specified chain
to the fee wallet on Base chain in USDC to add product credits to the user's account.

Args:
    chain_id: Chain ID for the transfer
    amount_usd: Amount in USD — must be a valid pack: $5, $10, or $20
    runtime: Runtime context automatically injected into tools.

Returns:
    - On success: {"status": "success", "task_ids": [...], "message": "Recharge initiated successfully"}

- On success: {"status": "success", "task_ids": [...], "message": "Recharge initiated successfully"}

import fere_tools as F

result = F.recharge_user_credits()
print(result)

Set stop loss and take profit hooks for existing holdings.

Args:
    set_hooks_request (AgentSetHooksRequest): SetHooksRequest object.
    runtime: Runtime context automatically injected into tools.

Returns:
    dict: Result of the set hooks operation.

dict: Result of the set hooks operation.

import fere_tools as F

resp = F.set_hooks_for_holding(
    set_hooks_request={
        "chain": "base",
        "token_address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "stop_losses": [{"price_usd": 0.85, "sell_percentage": 100}],
    }
)
print(resp)

Stake or unstake ETH, with runtime-injected user and context.

import fere_tools as F

result = F.stake_tokens()
print(result)

Get the list of supported chains for swap/trade.

Returns:
    list[ChainfeatureMatrix]: List of supported chains.

list[ChainfeatureMatrix]: List of supported chains.

import fere_tools as F

result = F.supported_chains()
print(result)

This function returns the list of supported source and destination chains for bridging tokens.

Returns:
    dict: {
        "supported_source_chains": list of supported source chains,
        "supported_destination_chains": list of supported destination chains
    }

dict: {
        "supported_source_chains": list of supported source chains,
        "supported_destination_chains": list of supported destination chains
    }

import fere_tools as F

result = F.supported_chains_for_bridging()
print(result)

Trade tokens (swap or bridge) with auto-fetched holdings and balance validation.

Unified tool that handles both same-chain swaps and cross-chain
bridges via the wallet-service /swap/v4/ endpoint. All operations
are gasless.

- Same chain (chain_id_in == chain_id_out): swap
- Different chains: cross-chain bridge

Features:
1. Automatically calls get_holdings
2. Extracts decimals from holdings
3. Validates balance before attempting trade
4. Returns actionable bridge options if balance is insufficient
5. Supports partial success - if one trade fails, others succeed
6. Processes trades in parallel using ThreadPoolExecutor

Args:
    trade_request: TradeToolRequest with trade details
    runtime: Runtime context automatically injected into tools.

Returns:
    - On all success:
        {"status": "success", "task_ids": [...]}
    - On partial success:
        {"status": "partial_success", "task_ids": [...],
         "failed_trades": [...]}
    - On all failed:
        {"status": "all_failed", "failed_trades": [...]}
    - On error:
        {"status": "error", "message": ...}

- On all success:
        {"status": "success", "task_ids": [...]}
    - On partial success:
        {"status": "partial_success", "task_ids": [...],
         "failed_trades": [...]}
    - On all failed:
        {"status": "all_failed", "failed_trades": [...]}
    - On error:
        {"status": "error", "message": ...}

import fere_tools as F

resp = F.trade_tokens(
    trade_request={
        "trades": [
            {
                "chain_id_in": 8453,
                "chain_id_out": 8453,
                "token_in": "usdc",
                "token_out": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
                "amount": "25",
                "amount_in_USD": True,
            }
        ]
    }
)
if resp.get("task_ids"):
    print(F.poll_transaction_status(task_ids=resp["task_ids"], tool_name="trade_tokens"))

Transfer multiple tokens to multiple recipient wallet addresses on behalf of the user.

Args:
    to_address (list[str]): List of destination wallet addresses.
    token_address (list[str]): List of token addresses (standardized where needed).
    amount (list[str]): List of amounts to transfer.
    chain (str): The chain to transfer on.
    token_decimals (list[int]): List of decimals for each token.
    amount_in_USD (list[bool]): List indicating whether amounts are in USD or token units.
    runtime: Runtime context automatically injected into tools.

Returns:
    dict: Result of the transfer operation containing task IDs.

dict: Result of the transfer operation containing task IDs.

import fere_tools as F

resp = F.transfer_tokens(
    to_address=["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"],
    token_address=["0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"],
    amount=["10"],
    chain="base",
    token_decimals=[6],
    amount_in_USD=[True],
)
print(resp)

Gets wallet addresses for a user.

Args:
    user_id (UUID): The ID of the user.

Returns:
    dict: The wallet addresses for the user.

dict: The wallet addresses for the user.

import fere_tools as F

result = F.wallet_info()
print(result)