# Run the example bot

The package ships a complete example maker. It listens to the JitoSOL feed, bids, answers awards, journals every quote and reconciles fills on chain. Use it to learn the flow, then build your own or harden it.

> [!WARNING]
> It is an example, not a production maker. It has no inventory, cash or risk limits beyond what the program enforces, and its price is a stub.

## Settings

| Variable | Required | Meaning |
| --- | --- | --- |
| `GATEWAY_WS_URL` | yes | Gateway WebSocket URL from covr |
| `GATEWAY_TOKEN` | yes | Your bearer token |
| `RPC_URL` | yes | Your Solana RPC. It must serve finalized reads and full signature history for an address. |
| `SPREAD_BPS` | yes | Bid = reference price × (1 − SPREAD_BPS / 10,000) |
| `DRY_RUN` | no | `0` sends for real. Anything else, or unset, is a dry run. |
| `MAKER_QUOTE_KEY` | live only | Your registered quote key, 0x-hex |
| `NONCE_JOURNAL` | live only | Path of the append-only quote journal |
| `MIN_NONCE` | no | Extra floor for nonces. The bot also reads your on-chain `min_nonce` and uses the larger. |

## From dry run to practice mode

1. Finish [Register and fund](https://docs.covr.markets/guides/register-and-fund.md).
2. Replace `referencePremiumE18()` in `maker/index.ts` with your model.
3. Run with your quote key and a journal:

```sh
GATEWAY_WS_URL=wss://<provided by covr> GATEWAY_TOKEN=<your token> \
RPC_URL=https://<your rpc> SPREAD_BPS=500 \
MAKER_QUOTE_KEY=0x<your quote key> NONCE_JOURNAL=./quotes.jsonl \
DRY_RUN=0 npx tsx maker/index.ts
```

Today every desk's bid comes back as:

```text
Bid intent verified but not entered: this market does not list this maker yet
```

That means your token, signature, terms and asset all passed. Practice mode stops there: it never tests the bid deadline, awards, quotes, your journal or exercise. See [Practice mode](https://docs.covr.markets/concepts/how-it-works.md#practice-mode).

Desks cannot win customer orders yet. covr's gateway lists only covr's own maker on each market, and covr's customer page accepts quotes only from covr's maker. Letting other desks win is planned engineering work at covr, not a switch it can flip. Watch the [Changelog](https://docs.covr.markets/resources/changelog.md). Until then, test the parts practice mode cannot reach yourself.

## What it does for each RFQ

1. Reads `GET /api/rfqs/<id>` and checks the RFQ matches the feed.
2. Reads the market from your RPC, checks the owner and skips paused or stock markets.
3. Signs a bid intent in that market's domain and sends it.
4. On an award, checks the intent equals the one it signed. It declines at once if not, or if less than 500 ms of the award window is left.
5. Journals the nonce, the full quote terms and the cash at risk, and fsyncs. Only then it signs and sends the quote.
6. Every 5 seconds, checks each open quote on chain and journals the result.

## The journal and its lock

In live mode the bot writes one JSON line per event: `reserve`, `signed`, `sent`, `settled`. On restart it reads the journal back, lists every open quote and never reuses a nonce. A line it cannot read stops it.

It also takes `<NONCE_JOURNAL>.lock`. A second live bot on the same journal refuses to start. A clean stop (Ctrl-C or SIGTERM) removes the lock. After a crash the lock stays on purpose: make sure no other bot uses the journal, then delete it.

## Reconnects

The bot reconnects with capped exponential backoff and jitter: 1 second, doubling to 30. Bids from the old connection are dropped. Signed quotes keep being checked on chain.

---

Source: https://docs.covr.markets/guides/run-the-example-bot · Part of covr Docs, https://docs.covr.markets/llms.txt
