> ## Documentation Index
> Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Token Search Query

This GraphQL query lets you discover actively traded tokens that match a keyword or ticker symbol. Each result includes pricing, volume marketcap, and base/quote metadata. Use it to build comprehensive token search features.

<CardGroup cols={2}>
  <Card title="Credit Cost"> 1 per call </Card>

  <Card title="Supported Chains">
    * `BASE_MAINNET`
    * `BSC_MAINNET`
    * `ETH_MAINNET`
    * `MEGAETH_MAINNET`
    * `MONAD_MAINNET`
    * `POLYGON_MAINNET`
    * `SOLANA_MAINNET`
  </Card>
</CardGroup>

<Tip>
  Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fstreaming-api%2Fqueries%2Ftoken-search-query).
</Tip>

## Parameters

<ParamField body="query" type="string" required>
  Search query string - can be token name, symbol, or address. Empty string returns all tokens.
</ParamField>

<ParamField body="chain_name" type="enum" optional>
  Optional chain filter. When provided, only tokens on this chain are returned.

  Type: [`ChainName`](/api-reference/streaming-api/types/chain-name)
</ParamField>

## Query

You can query the `searchToken` endpoint with:

* Free text (e.g. `"skitten"`)
* Token contract address (e.g. `0x4B6104755AfB5Da4581B81C552DA3A25608c73B8`)
* Token pair address (e.g. `0xa46d5090499eFB9c5dD7d95F7ca69F996b9Fb761`)

The response is sorted in descending order by volume (in USD).

```graphql theme={null}
query {
  searchToken(
    query: "skitten"
    chain_name: BASE_MAINNET
  ) {
    volume
    chain_name
    base_token {
      contract_name
      contract_address
      contract_decimals
      contract_ticker_symbol
    }
    swap_count
    market_cap
    quote_rate
    volume_usd
    quote_token {
      contract_name
      contract_address
      contract_decimals
      contract_ticker_symbol
    }
    quote_rate_usd
    pair_address
  }
}
```

## Response Format

Here's an example of the response data structure:

```json theme={null}
{
  "data": {
    "searchToken": [
      {
        "pair_address": "0xa46d5090499efb9c5dd7d95f7ca69f996b9fb761",
        "chain_name": "BASE_MAINNET",
        "quote_rate": 2.3637041719e-7,
        "quote_rate_usd": 0.0007961152019156508,
        "volume": 19888966.385959223,
        "volume_usd": 15833.908490251517,
        "market_cap": 786165.7030043972,
        "base_token": {
          "contract_name": "Ski Mask Kitten",
          "contract_ticker_symbol": "SKITTEN",
          "contract_address": "0x4b6104755afb5da4581b81c552da3a25608c73b8",
          "contract_decimals": 18
        },
        "quote_token": {
          "contract_name": "Wrapped Ether",
          "contract_ticker_symbol": "WETH",
          "contract_address": "0x4200000000000000000000000000000000000006",
          "contract_decimals": 18
        }
      }
    ]
  }
}
```

### Field Descriptions

<ResponseField name="volume" type="float">
  24h trading volume for the pair in quote token units
</ResponseField>

<ResponseField name="chain_name" type="enum">
  The blockchain network where the token was created

  Type: [`ChainName`](/api-reference/streaming-api/types/chain-name)
</ResponseField>

<ResponseField name="base_token" type="object">
  Metadata for the searched token, including address, decimals, name, and ticker symbol

  Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata)

  <Expandable title="properties">
    <ResponseField name="contract_name" type="string">
      Name of the token contract
    </ResponseField>

    <ResponseField name="contract_address" type="string">
      Address of the token contract
    </ResponseField>

    <ResponseField name="contract_decimals" type="int">
      Number of decimal places for the token
    </ResponseField>

    <ResponseField name="contract_ticker_symbol" type="string">
      Ticker symbol of the token
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="swap_count" type="string">
  Number of swaps in the tracking period
</ResponseField>

<ResponseField name="market_cap" type="float">
  Estimated market capitalization in USD for the base token
</ResponseField>

<ResponseField name="quote_rate" type="float">
  Exchange rate between base and quote tokens
</ResponseField>

<ResponseField name="volume_usd" type="float">
  24h trading volume in USD
</ResponseField>

<ResponseField name="quote_token" type="object">
  Metadata for the paired quote asset

  Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata)

  <Expandable title="properties">
    <ResponseField name="contract_name" type="string">
      Name of the token contract
    </ResponseField>

    <ResponseField name="contract_address" type="string">
      Address of the token contract
    </ResponseField>

    <ResponseField name="contract_decimals" type="int">
      Number of decimal places for the token
    </ResponseField>

    <ResponseField name="contract_ticker_symbol" type="string">
      Ticker symbol of the token
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="quote_rate_usd" type="float">
  USD value of the quote rate
</ResponseField>

<ResponseField name="pair_address" type="string">
  Liquidity pool contract that backs the result token/quote pair
</ResponseField>