Local Development¶

This guide is for contributors and local server operators working from a repo checkout.

Prerequisites¶

uv sync --extra dev

This creates the local project environment from uv.lock, installs the package, and includes the dev extra for tests and docs work.

Use uv run ... for Python-side commands from the checkout instead of activating a manual venv.

Initialize the local config home first:

uv run tidal init

Put secrets in ~/.tidal/.env:

RPC_URL=https://...
TOKEN_PRICE_AGG_KEY=...
TIDAL_API_KEY=...

Put operational settings in ~/.tidal/config.yaml. The scaffold written by tidal init already includes:

SQLite path
role-labeled sections for shared defaults, server operator settings, and CLI client convenience values
scanner and API server defaults
transaction guardrails

Settings precedence is:

environment variables > ~/.tidal/config.yaml > Python defaults

See Configuration for the full schema.

uv run tidal-server db migrate

This applies Alembic migrations to the configured SQLite database.

If you want to exercise authenticated API flows locally:

uv run tidal-server auth create --label yourname

The command prints a plaintext key once. Keep it somewhere safe, then export it:

export TIDAL_API_KEY=<printed-key>

Run one scan:

uv run tidal-server scan run

Start the API:

uv run tidal-server api serve

By default the API listens on 0.0.0.0:8787. Override with TIDAL_API_HOST and TIDAL_API_PORT if needed.

export TIDAL_API_BASE_URL=http://127.0.0.1:8787

uv run tidal kick inspect
uv run tidal logs kicks
uv run tidal kick run

For broadcast flows you also need wallet flags such as:

cd ui
npm install
TIDAL_API_PROXY_TARGET=http://127.0.0.1:8787 npm run dev

Then open http://localhost:5173.

You can also point directly at a deployed API:

VITE_TIDAL_API_BASE_URL=https://api.tidal.wavey.info/api/v1/tidal npm run dev

If you want authenticated UI actions locally:

VITE_TIDAL_API_KEY=$TIDAL_API_KEY npm run dev

Python tests:

uv run pytest

You can also scope to unit, integration, or fork tests:

uv run pytest tests/unit
uv run pytest tests/integration
uv run pytest tests/fork

Contract tests:

cd contracts
MAINNET_URL=$RPC_URL forge test -vvv

uv run mkdocs serve

The local docs site will be available at http://127.0.0.1:8000.

If you are new to the repo, the fastest way to build context is: