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

# DexUtils Pro API Quickstart: Make Your First API Call

> Make your first DexUtils Pro API call in minutes: fetch a live token price, explore liquidity pools, query swap transactions, and run a batch lookup.

This guide walks you through your first Pro API calls from scratch. By the end, you'll have fetched a live token price for WETH on Ethereum, explored its top liquidity pools, drilled into a specific pool's swap transactions, run a batch price lookup, and searched across the platform — a complete pattern you can adapt to any token on any supported chain.

## Prerequisites

Before you begin, make sure you have:

* A DexUtils account with an active **Premium plan** or **Pro API subscription**
* A Pro API key ready to use (see [Authentication](/api/authentication) if you haven't generated one yet)
* `curl` available in your terminal, or your preferred HTTP client

<Steps>
  <Step title="Set your API key as an environment variable">
    Store your API key in an environment variable so you don't have to paste it into every command. Run the following in your terminal — replace the placeholder with your actual key:

    ```bash Set API Key theme={null}
    export DEXUTILS_API_KEY=your_api_key_here
    ```

    All subsequent `curl` commands in this guide reference `$DEXUTILS_API_KEY` automatically. For persistent storage across shell sessions, add this line to your `~/.bashrc`, `~/.zshrc`, or equivalent shell profile.
  </Step>

  <Step title="Fetch all supported networks">
    Start by listing every chain the Pro API supports. This call also confirms that your key is valid and your environment is configured correctly.

    ```bash Fetch Networks theme={null}
    curl https://api.dexutils.io/v1/networks \
      -H "Authorization: Bearer $DEXUTILS_API_KEY"
    ```

    A successful response returns an array of network objects. You'll use the `id` field (for example, `"ethereum"`) to scope subsequent requests to a specific chain.

    ```json Response theme={null}
    {
      "networks": [
        { "id": "ethereum", "name": "Ethereum", "native_token": "ETH", "chain_id": 1 },
        { "id": "solana",   "name": "Solana",   "native_token": "SOL", "chain_id": null },
        { "id": "bsc",      "name": "BNB Chain","native_token": "BNB", "chain_id": 56 }
      ]
    }
    ```

    If you receive a `401` or `403` error here, double-check that your key is set correctly and review the [Authentication](/api/authentication) page.
  </Step>

  <Step title="List DEX protocols on a network">
    Before looking up pools, fetch the DEX protocols available on Ethereum. This lets you filter pools by DEX in the next step.

    ```bash Fetch DEXes theme={null}
    curl "https://api.dexutils.io/v1/networks/ethereum/dexes" \
      -H "Authorization: Bearer $DEXUTILS_API_KEY"
    ```

    The response lists each DEX with its identifier, which you can pass as a filter to pool queries:

    ```json Response theme={null}
    {
      "dexes": [
        { "id": "uniswap_v3", "name": "Uniswap V3", "version": "3" },
        { "id": "uniswap_v2", "name": "Uniswap V2", "version": "2" },
        { "id": "curve",      "name": "Curve Finance", "version": null }
      ]
    }
    ```
  </Step>

  <Step title="Look up a token by contract address">
    With a network ID in hand, fetch token data by passing the contract address in the URL path. This example uses **WETH** on Ethereum — a reliable token to test with because it always has deep liquidity and a current USD price.

    ```bash Fetch Token theme={null}
    curl "https://api.dexutils.io/v1/networks/ethereum/tokens/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2" \
      -H "Authorization: Bearer $DEXUTILS_API_KEY"
    ```

    The response includes price, valuation metrics, and a summary of the token's trading activity in the last 24 hours:

    ```json Response theme={null}
    {
      "id": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      "name": "Wrapped Ether",
      "symbol": "WETH",
      "network": "ethereum",
      "price_usd": "3461.82",
      "fdv": "4158204000",
      "liquidity_usd": "892341200",
      "pools": 1274,
      "volume_24h_usd": "1134500000",
      "updated_at": "2024-11-01T12:00:01Z"
    }
    ```

    Key fields to note:

    | Field            | Description                                         |
    | ---------------- | --------------------------------------------------- |
    | `price_usd`      | Current token price in USD, updated sub-2 seconds   |
    | `fdv`            | Fully diluted valuation in USD                      |
    | `liquidity_usd`  | Total USD liquidity across all pools for this token |
    | `pools`          | Number of active trading pools                      |
    | `volume_24h_usd` | Rolling 24-hour swap volume in USD                  |
  </Step>

  <Step title="List and filter liquidity pools">
    Fetch all pools on Ethereum that include WETH, sorted by liquidity. Pass the token address as a filter and cap the result with `limit` — useful when a popular token like WETH has thousands of pools.

    ```bash Fetch Pools theme={null}
    curl "https://api.dexutils.io/v1/networks/ethereum/pools?token=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2&sort=liquidity&limit=5" \
      -H "Authorization: Bearer $DEXUTILS_API_KEY"
    ```

    The response returns a paginated list of pool objects. Each pool includes the paired token, DEX, and key liquidity metrics:

    ```json Response theme={null}
    {
      "pools": [
        {
          "id": "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
          "dex": "uniswap_v3",
          "base_token": { "symbol": "WETH", "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2" },
          "quote_token": { "symbol": "USDC", "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" },
          "fee_tier": "0.05%",
          "liquidity_usd": "312450000",
          "volume_24h_usd": "489200000",
          "price_usd": "3461.82"
        }
      ],
      "total": 1274,
      "page": 1,
      "limit": 5
    }
    ```

    Copy the pool `id` from the response — you'll use it in the next two steps.
  </Step>

  <Step title="Get details for a specific pool">
    Use the pool address you retrieved above to fetch its full statistics, including reserve balances and fee data.

    ```bash Fetch Pool Details theme={null}
    curl "https://api.dexutils.io/v1/networks/ethereum/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640" \
      -H "Authorization: Bearer $DEXUTILS_API_KEY"
    ```

    ```json Response theme={null}
    {
      "id": "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
      "dex": "uniswap_v3",
      "network": "ethereum",
      "base_token": { "symbol": "WETH", "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2" },
      "quote_token": { "symbol": "USDC", "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" },
      "fee_tier": "0.05%",
      "liquidity_usd": "312450000",
      "reserve_base": "90200.45",
      "reserve_quote": "312139800.00",
      "volume_24h_usd": "489200000",
      "volume_7d_usd": "3021000000",
      "price_usd": "3461.82",
      "created_at": "2021-05-05T00:00:00Z"
    }
    ```
  </Step>

  <Step title="Fetch swap transactions for the pool">
    Retrieve the most recent swap events for the WETH/USDC pool. Use the `limit` and `page` parameters to paginate through the full history.

    ```bash Fetch Transactions theme={null}
    curl "https://api.dexutils.io/v1/networks/ethereum/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640/transactions?limit=3" \
      -H "Authorization: Bearer $DEXUTILS_API_KEY"
    ```

    Each transaction record includes the swap direction, amounts, USD value, and the wallet that executed the trade:

    ```json Response theme={null}
    {
      "transactions": [
        {
          "tx_hash": "0xabc123...",
          "type": "buy",
          "amount_base": "1.5",
          "amount_quote": "5192.73",
          "price_usd": "3461.82",
          "value_usd": "5192.73",
          "wallet": "0xdef456...",
          "timestamp": "2024-11-01T12:00:00Z"
        }
      ],
      "total": 48291,
      "page": 1,
      "limit": 3
    }
    ```
  </Step>

  <Step title="Batch look up multiple token prices">
    When you need prices for several tokens at once — for example, to update a portfolio dashboard — use the `POST /tokens/batch` endpoint instead of making one call per token.

    ```bash Batch Token Lookup theme={null}
    curl -X POST "https://api.dexutils.io/v1/tokens/batch" \
      -H "Authorization: Bearer $DEXUTILS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "tokens": [
          { "network": "ethereum", "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2" },
          { "network": "ethereum", "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" },
          { "network": "bsc",      "address": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c" }
        ]
      }'
    ```

    The response returns a result for each requested token in the same order:

    ```json Response theme={null}
    {
      "tokens": [
        { "network": "ethereum", "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "symbol": "WETH", "price_usd": "3461.82" },
        { "network": "ethereum", "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "symbol": "USDC", "price_usd": "1.00" },
        { "network": "bsc",      "address": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c", "symbol": "WBNB", "price_usd": "312.44" }
      ]
    }
    ```
  </Step>

  <Step title="Search for tokens, pools, and DEXes">
    Use the `GET /search` endpoint to find any resource by name, symbol, or contract address in one unified call. This is the fastest way to discover a contract address before making targeted lookups.

    ```bash Search theme={null}
    curl "https://api.dexutils.io/v1/search?q=USDC&limit=3" \
      -H "Authorization: Bearer $DEXUTILS_API_KEY"
    ```

    The response groups results by type so you can see matching tokens, pools, and DEXes in a single response:

    ```json Response theme={null}
    {
      "tokens": [
        { "symbol": "USDC", "name": "USD Coin", "network": "ethereum", "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "price_usd": "1.00" }
      ],
      "pools": [
        { "id": "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640", "dex": "uniswap_v3", "base_token": "WETH", "quote_token": "USDC", "network": "ethereum" }
      ],
      "dexes": []
    }
    ```
  </Step>

  <Step title="Explore the full Endpoints Reference">
    You've now walked through every major resource in the API: networks, DEXes, tokens, pools, transactions, batch lookups, and search. The same patterns — discover, resolve, and drill down — apply across all supported chains.

    Head to the [Endpoints Reference](/api/networks) to explore the complete request and response schemas, all available query parameters, and pagination behaviour for each endpoint.
  </Step>
</Steps>

## Next Steps

<Note>
  If any API call returns an unexpected error code, the [Error Codes](/api/errors) reference documents every possible response, what triggers it, and how to handle it in your application.
</Note>

<Note>
  For large result sets, review the [Pagination](/api/pagination) guide to understand how to use `page`, `limit`, and cursor-based navigation across all list endpoints.
</Note>