Quick Start Guide

This guide will help you get a keeper bot running on Drift Protocol. We’ll start with a filler bot in dry-run mode, then move to production.

Make sure you’ve completed the Installation guide before proceeding.

Configure Your Bot

Set Required Environment Variables

Ensure your .env file has the four required variables:

# Bot wallet private key (base58 encoded)
BOT_PRIVATE_KEY="your_base58_private_key_here"

# Solana RPC endpoint
RPC_URL="https://your-rpc-provider.com/api-key"

# Drift gRPC configuration
GRPC_ENDPOINT="https://api.rpcpool.com"
GRPC_X_TOKEN="your_grpc_token_here"

The BOT_PRIVATE_KEY must be base58 encoded, not a JSON array. See the Installation guide for how to convert your keypair.

Verify Wallet Funding

Make sure your bot wallet has sufficient SOL for transaction fees:

# Check wallet balance (replace with your bot's public key)
solana balance <BOT_PUBLIC_KEY> --url mainnet-beta

Recommended minimums:

Filler bot: 0.5 SOL
Liquidator bot: 1-5 SOL (needs capital for taking positions)

Test Configuration (Dry Run)

Test your configuration without sending real transactions:

RUST_LOG=info cargo run --release -- --mainnet --filler --dry

Look for these log messages indicating success:

INFO bot started: authority=<YOUR_PUBKEY>, subaccount=0
INFO mainnet=true, markets=false
INFO gRPC subscriptions established
INFO metrics server listening on 0.0.0.0:9898

Press Ctrl+C to stop the dry run.

Run the Filler Bot

The filler bot matches orders and provides liquidity to earn fees.

Production Mode
Dry Run Mode
Custom Markets
Docker

Run the filler bot on mainnet with detailed logging:

RUST_LOG=filler=info,dlob=info,swift=info \
    cargo run --release -- --mainnet --filler

What This Command Does

RUST_LOG=filler=info,dlob=info,swift=info - Enables info-level logs for filler, DLOB, and swift order modules
cargo run --release - Runs the optimized release build
--mainnet - Uses mainnet-beta Solana network
--filler - Runs the perp filler bot

The bot will start filling orders immediately. Monitor the logs to see fills and transaction results.

Test your strategy without sending real transactions:

RUST_LOG=filler=info,dlob=info,swift=info \
    cargo run --release -- --mainnet --filler --dry

The --dry flag simulates all transactions without actually sending them to the network. This is useful for:

Testing your configuration
Analyzing market conditions
Estimating potential profitability
Debugging without spending SOL

Fill orders for specific markets only:

# Fill only SOL-PERP (market 0) and BTC-PERP (market 1)
RUST_LOG=filler=info,dlob=info \
    cargo run --release -- --mainnet --filler --market-ids="0,1"

Or fill for all available markets:

RUST_LOG=filler=info,dlob=info \
    cargo run --release -- --mainnet --filler --all-markets

Market IDs can also be set in your .env file with MARKET_IDS="0,1,2"

Run the filler bot in a Docker container:

docker run --env-file .env -p 9898:9898 keeprs --mainnet --filler

For detached mode with restart policy:

docker run -d \
  --name keeprs-filler \
  --restart unless-stopped \
  --env-file .env \
  -p 9898:9898 \
  keeprs --mainnet --filler

View logs:

docker logs -f keeprs-filler

Filler Bot Configuration Options

Customize the filler bot behavior with command-line flags:

RUST_LOG=filler=info cargo run --release -- \
    --mainnet \
    --filler \
    --market-ids="0,1,2" \
    --priority-fee=512 \
    --swift-cu-limit=364000 \
    --fill-cu-limit=256000

Flag	Description	Default
`--market-ids`	Comma-separated market indices to fill	`"0,1,2"`
`--all-markets`	Fill for all available markets	`false`
`--priority-fee`	Base priority fee in microlamports	`512`
`--swift-cu-limit`	Compute units for swift fills	`364000`
`--fill-cu-limit`	Compute units for regular fills	`256000`
`--dry`	Simulate without sending transactions	`false`

Run the Liquidator Bot

The liquidator bot protects the protocol by liquidating undercollateralized positions.

Perp + Spot Liquidations
Perp Only
Custom Threshold
Docker

Run the full liquidator with both perp and spot liquidations:

RUST_LOG=liquidator=info,dlob=info \
    cargo run --release -- --mainnet --liquidator

This is the recommended configuration. The bot will:

Monitor all user accounts for margin violations
Liquidate perp positions using the DLOB for fills
Liquidate spot borrows using Jupiter swaps
Track high-risk users for faster response

Run liquidator for perpetual positions only:

RUST_LOG=liquidator=info,dlob=info \
    cargo run --release -- --mainnet --liquidator --no-use-spot-liquidation

Use this if you only want to liquidate perp positions and avoid spot markets.

Set a minimum collateral threshold for liquidations:

RUST_LOG=liquidator=info \
    cargo run --release -- \
    --mainnet \
    --liquidator \
    --min-collateral=5000000

The --min-collateral flag (in micro-units) helps you avoid liquidating dust positions that may not be profitable.

Run the liquidator bot in Docker:

docker run -d \
  --name keeprs-liquidator \
  --restart unless-stopped \
  --env-file .env \
  -p 9898:9898 \
  keeprs --mainnet --liquidator

Liquidator bots need sufficient capital to take on positions during liquidation. Ensure your wallet has adequate funds beyond just transaction fees.

Liquidator Bot Configuration

RUST_LOG=liquidator=info cargo run --release -- \
    --mainnet \
    --liquidator \
    --min-collateral=1000000 \
    --use-spot-liquidation \
    --priority-fee=512

Flag	Description	Default
`--liquidator`	Run in liquidator mode	`false`
`--min-collateral`	Minimum collateral to liquidate (micro-units)	`1000000`
`--use-spot-liquidation`	Enable spot liquidations	`true`
`--priority-fee`	Base priority fee in microlamports	`512`
`--dry`	Simulate without sending transactions	`false`

Verify Your Bot is Working

Check Logs

Look for successful operations in the logs:Filler Bot:

INFO filler: attempting fill for order <ORDER_ID>
INFO filler: tx sent: <SIGNATURE>
INFO filler: fill confirmed, earned X SOL

Liquidator Bot:

INFO liquidator: found liquidatable user: <USER>
INFO liquidator: attempting liquidation
INFO liquidator: liquidation confirmed: <SIGNATURE>

Check Metrics Endpoint

Access the Prometheus metrics at http://localhost:9898/metrics:

curl http://localhost:9898/metrics

Key metrics to watch:

tx_sent_total - Total transactions sent
tx_confirmed_total - Total transactions confirmed
tx_failed_total - Total failed transactions
fills_total - Total fills executed (filler only)
liquidations_total - Total liquidations (liquidator only)

Check Health Endpoint

Verify the bot is healthy:

curl http://localhost:9898/health

A 200 OK response indicates the bot is running correctly.

View Dashboard (Optional)

Open the web dashboard in your browser:

http://localhost:9898/dashboard

The dashboard shows real-time bot status, recent transactions, and performance metrics.

Monitor Performance

Using Prometheus & Grafana

The metrics endpoint exposes data in Prometheus format. You can scrape it with Prometheus and visualize in Grafana:

# prometheus.yml
scrape_configs:
  - job_name: 'keeprs'
    static_configs:
      - targets: ['localhost:9898']

Using curl

Quick checks from the command line:

# Total transactions sent
curl -s http://localhost:9898/metrics | grep tx_sent_total

# Success rate
curl -s http://localhost:9898/metrics | grep tx_confirmed_total

# Current slot
curl -s http://localhost:9898/metrics | grep current_slot

Log Levels

Adjust logging verbosity with RUST_LOG:

# Minimal logging
RUST_LOG=error cargo run --release -- --mainnet --filler

# Standard logging
RUST_LOG=info cargo run --release -- --mainnet --filler

# Detailed logging
RUST_LOG=debug cargo run --release -- --mainnet --filler

# Module-specific logging
RUST_LOG=filler=debug,dlob=info,swift=debug cargo run --release -- --mainnet --filler

Transaction History Tool

Keep-rs includes a utility to analyze your bot’s transaction history:

RUST_LOG=info cargo run --release --bin=tx_history <BOT_PUBKEY> --rpc-url <RPC_URL>

This prints statistics about recent transactions including:

Success rate
Average priority fees paid
Compute units used
Total fees spent

Troubleshooting

Bot Not Sending Transactions

Check wallet balance

solana balance <YOUR_BOT_PUBKEY> --url mainnet-beta

Ensure you have at least 0.1 SOL for transaction fees.

Verify RPC connection

Check that your RPC endpoint is responding:

curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}' <YOUR_RPC_URL>

Check gRPC credentials

Ensure GRPC_ENDPOINT and GRPC_X_TOKEN are correct. Look for connection errors in logs:

ERROR failed to connect to gRPC

Verify bot is finding opportunities

Increase log level to see if crosses are being detected:

RUST_LOG=filler=debug cargo run --release -- --mainnet --filler

Look for “found cross” or “attempting fill” messages.

High Transaction Failure Rate

Increase priority fees: Use --priority-fee=1000 or higher
Adjust compute units: Increase --fill-cu-limit if hitting CU limits
Check competition: Other bots may be faster - optimize your RPC latency
Review logs: Look for specific error messages in transaction confirmations

No Liquidations Found

This is normal during low volatility periods
The liquidator runs continuously waiting for opportunities
Check http://localhost:9898/metrics - users_monitored should be > 0
Use RUST_LOG=liquidator=debug to see margin checks

Next Steps

Configuration Guide

Learn about all configuration options and optimization strategies

Monitoring & Metrics

Set up comprehensive monitoring with Prometheus and Grafana

Performance Optimization

Optimize your bot for maximum performance

Troubleshooting

Common issues and how to resolve them

Get Started

Bot Operations

Architecture

Deployment

Advanced

Quick Start

Quick Start Guide

Configure Your Bot

Run the Filler Bot

What This Command Does

Filler Bot Configuration Options

Run the Liquidator Bot

Liquidator Bot Configuration

Verify Your Bot is Working

Monitor Performance

Using Prometheus & Grafana

Using curl

Log Levels

Transaction History Tool

Troubleshooting

Bot Not Sending Transactions

High Transaction Failure Rate

No Liquidations Found

Next Steps

Configuration Guide

Monitoring & Metrics

Performance Optimization

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Bot Operations

Architecture

Deployment

Advanced

​Quick Start Guide

​Configure Your Bot

​Run the Filler Bot

​What This Command Does

​Filler Bot Configuration Options

​Run the Liquidator Bot

​Liquidator Bot Configuration

​Verify Your Bot is Working

​Monitor Performance

​Using Prometheus & Grafana

​Using curl

​Log Levels

​Transaction History Tool

​Troubleshooting

​Bot Not Sending Transactions

​High Transaction Failure Rate

​No Liquidations Found

​Next Steps

Configuration Guide

Monitoring & Metrics

Performance Optimization

Troubleshooting

Build docs developers (and LLMs) love

Quick Start Guide

Configure Your Bot

Run the Filler Bot

What This Command Does

Filler Bot Configuration Options

Run the Liquidator Bot

Liquidator Bot Configuration

Verify Your Bot is Working

Monitor Performance

Using Prometheus & Grafana

Using curl

Log Levels

Transaction History Tool

Troubleshooting

Bot Not Sending Transactions

High Transaction Failure Rate

No Liquidations Found

Next Steps