> ## 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.

# Running

> Migrate, seed and start the service.

Three commands, in order. Migrations create the schema, seeding populates the
catalogue, then the server runs.

<Steps>
  <Step title="Create the schema">
    ```sh theme={null}
    go run ./cmd/cli migrate
    ```

    Safe to re-run, and a no-op when already up to date. Migrations live in
    `internal/storage/postgres/migrations` and are embedded into the binary, so
    `migrate` needs only `POSTGRES_DSN`: no source tree and no separate migration
    tool on the target machine.
  </Step>

  <Step title="Seed the catalogue">
    ```sh theme={null}
    go run ./cmd/cli seed
    ```

    Populates blockchains, tokens, DEXes and pools. This step makes live RPC calls
    across every configured chain, so it takes a while and logs non-fatal warnings for
    endpoints that don't respond.

    <Warning>
      Run `seed` against a clean database. Only the `blockchains` insert upserts; the
      other tables can produce duplicate-key errors on a re-run.
    </Warning>
  </Step>

  <Step title="Start the API server">
    ```sh theme={null}
    go run ./cmd
    ```

    Listens on `PORT`. Confirm it's up by hitting the catalogue:

    ```sh theme={null}
    curl http://localhost:8080/blockchains
    ```
  </Step>
</Steps>

## Building binaries

```sh theme={null}
go build -o bin/uatu     ./cmd
go build -o bin/uatu-cli ./cmd/cli
```

## Repository layout

```
cmd/                          HTTP server entrypoint
cmd/cli/                      Cobra CLI (database seeding)
config/                       Viper config loading
swagger/                      generated API spec (swag), committed, do not hand-edit
server/                       chi routes, handlers, OpenTelemetry setup
internal/blockchains/         chain definitions (JSON, embedded at build time)
internal/contracts/           generated Uniswap v2/v3 + Permit2 bindings
internal/dex/                 on-chain pool and quote lookups
internal/storage/postgres/    bun repositories and SQL migrations
```

Domain models (`Chain`, `Token`, `Dex`, `Pool`, `Quote`) live in the root `uatu`
package.

## The API spec

Swagger UI is served at `/swagger/` and the raw spec at `/swagger/doc.json`.

Regenerate the spec after changing any handler annotation:

```sh theme={null}
go generate ./...
```

<Note>
  The spec in `swagger/` is generated and committed, so don't hand-edit it. The
  [API reference](/api-reference) on this site is built from that same spec.
</Note>