kuest-market-maker

Market maker keeper for the Kuest CLOB.

NOTE

This software is experimental and in active development. Use at your own risk.

Description

The keeper is a market maker for CLOB markets. Places and cancels orders to keep open orders near the midpoint price using the Bands strategy.

Requirements

• Python 3.10

Setup

• Run ./install.sh to set up the virtual environment and install depedencies.

• Create a .env file. See .env.example.

• Modify the entries in config.env.

• Modify config/market-maker.json if desired.

Amoy USDC

If you are running on Polygon Amoy and run out of test USDC, you can request more by typing /airdrop in the Kuest Discord: https://discord.gg/kuest

Usage

• Start the keeper with ./run-local.sh.

Usage with Docker

• To start the keeper with docker, run docker compose up.

Config

The config.env file defines 3 environment variables:

• CONDITION_ID, the condition id of the market in hex string format.
• STRATEGY, the strategy to use: "Bands" (case insensitive)
• CONFIG, the path to the strategy config file (defaults to config/market-maker.json).

The strategy config file contains the band definitions plus runtime settings like amountJitterPct, minOrderSize, minBalanceToOperate, split controls, and shutdown options like shutdownCancelAll and shutdownMergePositions.

Key settings:

• amountJitterPct: randomizes band amounts by +/- this percentage.
• minOrderSize: minimum order size; orders smaller than this are skipped.
• minBalanceToOperate: total balance threshold; below this the bot aborts the cycle.
• splitMinBalance: minimum balance per token (A/B); below this the bot may split collateral.
• splitCooldownSeconds: minimum time between split attempts.
• splitTargetCollateral: optional cap for split amount; if 0, derives a target from band max amounts.
• shutdownCancelAll: cancel all orders on shutdown when true.
• shutdownMergePositions: merge positions on shutdown when true.

Strategies

• Bands
• AMM strategy is not supported; only Bands is available.

Split and Merge

The app can automatically split collateral into conditional tokens when token balances are low. A split is attempted when either token A or B is below splitMinBalance, collateral is available, and the cooldown has elapsed. The split amount is the smaller of:

• splitTargetCollateral (if set), or
• sum of band maxAmount values, or
• a small fallback value.

On shutdown, the app can merge token A/B back into collateral when shutdownMergePositions is enabled.

Strategy Lifecycle

Every sync_interval (the default is 30s), the strategies do the following:

1. Fetch the current midpoint price from the CLOB
2. Compute expected orders.
3. Compare expected orders to open orders.
4. Compute open orders to cancel and new orders to place to achieve or approximate the expected orders.
5. Cancel orders.
6. Place new orders.

When the app receives a SIGTERM, all orders are cancelled and positions are merged by default. You can disable either behavior in config/market-maker.json.