covr.Docs

Guides

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

VariableRequiredMeaning
GATEWAY_WS_URLyesGateway WebSocket URL from covr
GATEWAY_TOKENyesYour bearer token
RPC_URLyesYour Solana RPC. It must serve finalized reads and full signature history for an address.
SPREAD_BPSyesBid = reference price × (1 − SPREAD_BPS / 10,000)
DRY_RUNno0 sends for real. Anything else, or unset, is a dry run.
MAKER_QUOTE_KEYlive onlyYour registered quote key, 0x-hex
NONCE_JOURNALlive onlyPath of the append-only quote journal
MIN_NONCEnoExtra 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.
  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.

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