# Endpoint

<mark style="color:green;">`GET`</mark> [`https://pro.circular.fi/finder`](https://pro.circular.fi/documentation#tag/Finder)

Find trending tokens

**Parameters**

```json
{
  // =========================
  // TOKENS — what to return
  // Window used to RANK tokens and build Token → AMM → Pool rollups
  // =========================

  // REQUIRED. List of arbitrage base token mints (Base58). Example: 1..N addresses.
  "tokensMint": [
    "So11111111111111111111111111111111111111112",
    "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
  ], 

  // Optional. Exclude these mints. Example: USDT mint.
  "tokensExclude": [
    "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB"
  ], 

  "tokensMax": 1, // Max tokens to return (ranked by gross revenues). Min: 1, Max: 50. Example: 1.

  "tokensTimeRange": 3000, // Aggregation window (seconds) for ranking. Min: 0, Max: 86400. Examples: 300 (fresh), 3600, 14400.

  "tokensMinMarketCap": 50000,          // Optional. USD. Min: 0. Example: 50_000.
  "tokensMaxMarketCap": 1000000000000, // Optional. USD. Max practical example: 1_000_000_000_000 (set higher to disable).

  "tokensMinVolume": 100000,         // Optional. USD within tokensTimeRange. Example: 100_000.
  "tokensMaxVolume": 1000000000,    // Optional. USD. Example: 1_000_000_000 (set higher to disable).

  "tokensMinVolumeArbitrage": 100000,        // Optional. USD within tokensTimeRange for arbitrage. Example: 100_000.
  "tokensMaxVolumeArbitrage": 1000000000,    // Optional. USD for arbitrage. Example: 1_000_000_000

  "tokensMinVolumeTrade": 100000,           // Optional. USD within tokensTimeRange for trade. Example: 100_000.
  "tokensMaxVolumeTrade": 1000000000,        // Optional. USD for trade. Example: 1_000_000_000

  "tokensMinRevenues": 500,           // Optional. USD (gross arbitrage gains). Example: 500.
  "tokensMaxRevenues": 1000000000,  // Optional. USD. Example: 1_000_000_000.

  "tokensMinProfits": 250,            // Optional. USD (net gains). Example: 250.
  "tokensMaxProfits": 1000000000,   // Optional. USD. Example: 1_000_000_000.

  "tokensMinLiquidity": 10000,            // Optional. USD (token liquidity). Example: 10_000.
  "tokensMaxLiquidity": 10000000,   // Optional. USD. Example: 10_000_000.
  
  "tokensMinTransactions": 5,       // Optional. Min tx count in window. Min: 1. Example: 5.
  "tokensMaxTransactions": 100000000, // Optional. Max tx count. Example: 100_000_000.

  "tokensMinPool": 2, // Optional. Min pools returned per AMMs. Example: 2

  "tokensAMMS": [
    "LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo,2",
    "cpamdpZCGKUy5JxQXB4dcpGPiikHawvSWAd6mEn1sGG,1"
  ], // Optional. Format: "amm_address,<max_pools>". Cap per-AMM pools (Max per AMM: 10). Example: 2 and 1.


  // =========================
  // THRESHOLD — should I trade/arb now?
  // Independent decision window vs. tokensTimeRange
  // =========================

  "thresholdMaxTimeRange": 900,   // Optional. Seconds used for threshold decision. Min: 0, Max: 86400. Examples: 120, 900, 3600.
  "thresholdProfits": 200,          // Optional. USD net gains threshold. Example: 100.
  "thresholdRevenues": 200,         // Optional. USD gross gains threshold. Example: 500.
  "thresholdTransactions": 20,     // Optional. Tx count threshold. Example: 20.
  "thresholdProvider": "ALL",     // Optional. One of: FAST, TEMPORAL, JITO, NEXTBLOCK, BLOX, ASTRALANE, FLASHBLOCK, NODEONE, RAZOR, SENDER, STELLIUM, FALCON, ALL. Example: "JITO".
  "thresholdBot": "ALL",          // Optional. One of: SMB, NOTARB, ALL. Example: "ALL" or "SMB".

  // =========================
  // PERCENTILES — expected execution costs
  // Fees & tips percentiles RETURNED IN LAMPORTS
  // Independent stats window vs. the two above
  // =========================

  "percentilesFees": "p50",       // Optional. Percentile for fees. Examples: "p50", "p90", "50".
  "percentilesTips": "p50",       // Optional. Percentile for tips. Examples: "p50", "p95".
  "percentilesProvider": "ALL",   // Optional. One of: FAST, TEMPORAL, JITO, NEXTBLOCK, BLOX, ASTRALANE, FLASHBLOCK, NODEONE, RAZOR, SENDER, STELLIUM, FALCON, ALL. Example: "JITO".
  "percentilesBot": "ALL",        // Optional. One of: SMB, NOTARB, ALL. Example: "ALL" or "SMB".
  "percentilesTimeRange": 1800,    // Optional. Seconds. Min: 0, Max: 86400. Examples: 600, 1800, 3600.

  // Optional. List of signer wallets to track (Base58). Example: 0..N addresses. (If not specified, takes into account all transactions in the network)
  "wallets": [
    "RaVenxw8kykBbW7KGBaBsb7fDkkBYK4uJVDSFun6ZxR",
    "HxjwdF326ZunmUwC1iXhfgL3ku78YsksN6n7Rfxzwr6b",
    "7dGrdJRYtsNR8UYxZ3TnifXGjGc9eRYLq9sELwYpuuUu"
  ]
}

```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "tokens": [
        {
            "mint": "6DaSdWSu5NMtpFZkx8iBXUphCjPwPrSkXShbnqi9BAGS",
            "profits": 307.02,
            "revenues": 312.81,
            "transactions": 204,
            "volume": 629612.21,
            "volumeArbitrage": 50000.0,
            "volumeTrade": 579612.21, 
            "marketCap": 689198.38,
            "liquidity": 581606.27,
            "AMMs": [
                {
                    "address": "cpamdpZCGKUy5JxQXB4dcpGPiikHawvSWAd6mEn1sGG",
                    "profits": 159.29,
                    "revenues": 161.79,
                    "transactions": 145,
                    "volume": 629612.21,
                    "volumeArbitrage": 50000.0,
                    "volumeTrade": 579612.21, 
                    "pools": [
                        {
                            "address": "8FULEkMH1NkQjSoRxKHYwQSFfgL4R6soCzD91MvAyhBE",
                            "tokenA": "6DaSdWSu5NMtpFZkx8iBXUphCjPwPrSkXShbnqi9BAGS",
                            "tokenB": "So11111111111111111111111111111111111111112",
                            "profits": 147.01,
                            "revenues": 149.28,
                            "transactions": 81,
                            "volume": 629612.21,
                            "volumeArbitrage": 50000.0,
                            "volumeTrade": 579612.21, 
                            "lookupTable": "6SW4jjtXp4XosT3pRfaFbrn19UjPbcp8G8B4bksFyyJk"
                        }
                    ]
                },
                {
                    "address": "LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo",
                    "profits": 147.74,
                    "revenues": 151.02,
                    "transactions": 59,
                    "volume": 629612.21,
                    "volumeArbitrage": 50000.0,
                    "volumeTrade": 579612.21,
                    "pools": [
                        {
                            "address": "5d5JwWFvEfyAf24WYNAHUAsmduPhNbw5HxpoMDVq6upc",
                            "tokenA": "6DaSdWSu5NMtpFZkx8iBXUphCjPwPrSkXShbnqi9BAGS",
                            "tokenB": "So11111111111111111111111111111111111111112",
                            "profits": 77.3,
                            "revenues": 78.8,
                            "transactions": 29,
                            "volume": 629612.21,
                            "volumeArbitrage": 50000.0,
                            "volumeTrade": 579612.21,
                            "lookupTable": "4yRzzxU6brZsY9CTZ2Jp9QWhnRftYP6RyZ8FGugVEXN8"
                        },
                        {
                            "address": "8aLE5RQB2b2Bk7RbWZUPKLuA8ds3ZZ8aHNaLr7mEb91P",
                            "tokenA": "6DaSdWSu5NMtpFZkx8iBXUphCjPwPrSkXShbnqi9BAGS",
                            "tokenB": "So11111111111111111111111111111111111111112",
                            "profits": 68.05,
                            "revenues": 69.72,
                            "transactions": 21,
                            "volume": 629612.21,
                            "volumeArbitrage": 50000.0,
                            "volumeTrade": 579612.21,
                            "lookupTable": "4yRzzxU6brZsY9CTZ2Jp9QWhnRftYP6RyZ8FGugVEXN8"
                        }
                    ]
                }
            ]
        }
    ],
    "threshold": {
        "isArbitrageRecommended": true,
        "thresholdProfits": 100.0,
        "profits": 601.4300000000001,
        "thresholdRevenues": 500.0,
        "revenues": 1420.68,
        "thresholdTransactions": 20,
        "transactions": 138815,
        "timeRange": 900,
        "thresholdProvider": "ALL",
        "thresholdBot": "ALL"
    },
    "fees": {
        "percentile": "p50",
        "percentileInt": 50,
        "amount": 5150,
        "transactions": 22093,
        "timeRange": 1800
    },
    "tips": {
        "percentile": "p50",
        "percentileInt": 50,
        "amount": 0,
        "transactions": 22093,
        "timeRange": 1800
    },
    "filters": {
        "wallets": [
            "7dGrdJRYtsNR8UYxZ3TnifXGjGc9eRYLq9sELwYpuuUu",
            "HxjwdF326ZunmUwC1iXhfgL3ku78YsksN6n7Rfxzwr6b",
            "RaVenxw8kykBbW7KGBaBsb7fDkkBYK4uJVDSFun6ZxR"
        ],
        "tokensMint": [
            "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
            "So11111111111111111111111111111111111111112"
        ],
        "tokensExclude": [
            "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB"
        ],
        "tokensMax": 1,
        "tokensTimeRange": 3000,
        "tokensMinMarketCap": 50000.0,
        "tokensMaxMarketCap": 1000000000000.0,
        "tokensMinVolume": 100000.0,
        "tokensMaxVolume": 1000000000.0,
        "tokensMinVolumeArbitrage": 100000.0,
        "tokensMaxVolumeArbitrage": 1000000000.0,
        "tokensMinVolumeTrade": 100000.0,
        "tokensMaxVolumeTrade": 1000000000.0,
        "tokensMinRevenues": 200.0,
        "tokensMaxRevenues": 1000000000.0,
        "tokensMinProfits": 200.0,
        "tokensMaxProfits": 1000000000.0,
        "tokensMinTransactions": 5.0,
        "tokensMaxTransactions": 100000000.0,
        "thresholdMaxTimeRange": 900,
        "thresholdProfits": 100.0,
        "thresholdRevenues": 500.0,
        "thresholdTransactions": 20,
        "thresholdProvider": "ALL",
        "thresholdBot": "ALL",
        "percentilesFees": "p50",
        "percentilesTips": "p50",
        "percentilesProvider": "ALL",
        "percentilesBot": "ALL",
        "percentilesTimeRange": 1800,
        "tokensAMMS": {
            "LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo": 2,
            "cpamdpZCGKUy5JxQXB4dcpGPiikHawvSWAd6mEn1sGG": 1
        }
    }
}
```

{% endtab %}
{% endtabs %}

**Informations:**

* Requests per minute: Searcher 5 / Startup 60 / Pro 150
* More technical information [here](https://pro.circular.fi/documentation#tag/Finder)
