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

# Catalogue

> Chains, tokens, DEXes and pools, and how they're discovered.

The catalogue is uatu's view of what is swappable where. It is populated by the
seeding CLI and read back through the `/blockchains` endpoints.

## The four objects

<AccordionGroup>
  <Accordion title="Chain" icon="link">
    A network uatu supports. Carries `name`, `slug`, `chainId`, `symbol`,
    `nativeToken`, `blockExplorer`, `rpcUrl`, `ecosystem` and `blockChainLogo`, plus
    the `tokens` and `dex` arrays embedded within it.

    `rpcUrl` comes back empty from the hosted API. The endpoint a deployment prices
    against is its own configuration, not public data.
  </Accordion>

  <Accordion title="Token" icon="coins">
    An ERC-20 or native asset: `address`, `symbol`, `name`, `slug`, `decimals`,
    `logo` and the `blockchainId` it belongs to. `decimals` is what converts between
    the integer and display amounts on a quote.
  </Accordion>

  <Accordion title="DEX" icon="arrows-split-up-and-left">
    A protocol deployment on one chain. Beyond `name`, `slug` and `version`, it holds
    the contract addresses uatu prices and encodes against: `v2FactoryAddress`,
    `v2RouterAddress`, `v3FactoryAddress`, `v3RouterAddress`, `v3QuoterAddress`,
    `universalRouterAddress`, `permit2Address` and `settlementAddress`.
  </Accordion>

  <Accordion title="Pool" icon="water">
    A discovered liquidity pool: `pairAddress`, `poolType`, `poolFee`, `tickSpacing`,
    the `baseToken` / `quoteToken` pair with their balances, `liquidity` and
    `liquidityInUsd` breakdowns, `marketCap` and `isActivePool`.
  </Accordion>
</AccordionGroup>

## Reading the catalogue

| Endpoint                  | Returns                                     | `chainId`             |
| ------------------------- | ------------------------------------------- | --------------------- |
| `GET /blockchains`        | Every chain, with embedded tokens and DEXes | n/a                   |
| `GET /blockchains/tokens` | Tokens; omit the filter for all chains      | optional              |
| `GET /blockchains/pools`  | Pools, optionally filtered by `dex` slug    | required              |
| `GET /blockchains/dex`    | One DEX and its contract addresses          | required, with `slug` |

`GET /blockchains/dex` needs both `chainId` and `slug`, because a slug identifies a
DEX only within a single chain. `uniswap` on Ethereum and `uniswap` on Base are
different deployments with different addresses.

## The response envelope

Every endpoint wraps its payload in the same shape:

```json theme={null}
{
  "code": 200,
  "message": "Blockchains fetched successfully",
  "data": []
}
```

`message` is always present and describes what was fetched, such as `Tokens fetched
successfully` or `Pools fetched successfully`. `data` holds the result, an object or
an array depending on the endpoint, and is absent on errors, where `message` carries
the reason and `code` mirrors the HTTP status.

## How pools get there

Chains, tokens and DEXes are declared in JSON definitions embedded into the binary at
build time. Pools are not: the `seed` command walks each chain's token list, queries
the v2 and v3 factories over RPC to find pools that actually exist, and persists what
it finds.

That means the catalogue reflects the last seed run against the RPC endpoints you
configured. See [Running](/self-hosting/running) for the seeding workflow.