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

# Quickstart

> Run the local API, web app, and runtime reads.

# Quickstart

Use this flow to start the local API and web app. This is the safe path for a
new checkout.

## 1. Prepare config

```bash theme={null}
cp .env.example .env
cp config.example.toml config.toml
```

Secrets stay in `.env`. Non-secret policy stays in `config.toml`.
The copied `.env` contains empty placeholders. They are harmless while protocol
workers are disabled, but live mode requires real values.

Default config uses:

* API bind: `127.0.0.1:5050`
* Solana cluster label: `mainnet-beta`
* assets: USDC, SOL, cbBTC
* small demo caps
* `runtime.enable_protocol_workers = false`

With protocol workers disabled, the backend serves health and runtime projection routes. Mutating RFQ and settlement routes return unavailable because the live orchestrator is not attached.

## 2. Start the backend

```bash theme={null}
cargo run
```

The backend starts the Axum API and runtime projection. With the default
`runtime.enable_protocol_workers = false`, it does not sign transactions or call
Jupiter/Circle.

## 3. Start the web app

```bash theme={null}
npm run dev
```

Open:

```text theme={null}
http://127.0.0.1:3000/app/
```

Runtime view:

```text theme={null}
http://127.0.0.1:3000/app/runtime
```

## 4. Start the API docs

```bash theme={null}
npm run docs:dev
```

Open the local docs URL printed by Mintlify. The Backend Reference pages include
an interactive Try it panel. It defaults to the deployed API at
`https://api.firmament.shaikazeem.com`. Choose the local `127.0.0.1:5050`
server in a local docs preview when testing against your own `cargo run`
backend.

## 5. Inspect public runtime routes

```bash theme={null}
curl http://127.0.0.1:5050/health
curl http://127.0.0.1:5050/v1/assets
curl http://127.0.0.1:5050/v1/pairs
curl http://127.0.0.1:5050/v1/runtime/state
curl http://127.0.0.1:5050/v1/runtime/events
curl http://127.0.0.1:5050/v1/runtime/ledger
curl 'http://127.0.0.1:5050/v1/runtime/trades?limit=10'
```

`/v1/runtime/trades` is the global recent-trades feed used by the Runtime tab.
Trade rows and active wallet-settlement state are durable SQLite records, so
terminal trades and resumable active settlements can survive a backend restart.
Pass `wallet=<address>` to scope the feed to the connected taker wallet, which
is what the swap page history drawer uses.

## 6. Request a friendly RFQ

The friendly request shape uses asset symbols and a decimal `amount`.
Asset identifiers are case-insensitive.

In default local mode this route returns `503 service_unavailable` because the
live orchestrator is not attached. That is expected. Use it to verify request
shape and error handling before enabling live maker mode.

```bash theme={null}
curl -X POST http://127.0.0.1:5050/v1/rfq \
  -H 'content-type: application/json' \
  -d '{
    "input_asset": "USDC",
    "output_asset": "SOL",
    "amount": "1.00",
    "taker_wallet": "11111111111111111111111111111111",
    "expiry_seconds": 30
  }'
```

Accepted responses include `pair`, `input`, `output`, and a `next_action`
hint pointing at `POST /v1/quotes/{quote_id}/wallet-settlement`. Rejected
responses include a user-facing `message` and a `suggested_action`.

The legacy mint/raw-amount request shape (`input_mint`, `output_mint`,
`input_amount_raw`) keeps working for existing API consumers.

During browser-wallet settlement, the app can recover an active trade with
`POST /v1/trades/{trade_id}/resume`. Before any on-chain lock signature, it can
abandon the unused settlement with `POST /v1/trades/{trade_id}/abandon` by
sending the browser-held `secret_hash`. Expired pre-lock settlements are marked
failed instead of receiving fresh lock transactions. After a locked settlement
expires, it can prepare and record a refund with
`POST /v1/trades/{trade_id}/taker-refund`.

## Live RFQ mode

To run live RFQ and settlement, follow [Maker setup](/maker-setup). At minimum,
configure:

* `SOLANA_RPC_URL`
* exactly one maker keypair source
* `JUPITER_API_KEY` when Jupiter is enabled
* `CIRCLE_GATEWAY_SOLANA_ADDRESS` when Gateway is enabled
* a verified Solana cbBTC mint in `config.toml`
* `runtime.enable_protocol_workers = true`

Keep the demo caps small before funding the maker wallet.