Skip to content
Branch: master
Find file Copy path
Find file Copy path
1 contributor

Users who have contributed to this file

390 lines (277 sloc) 23.9 KB

Auction Keeper Bot Setup Guide

Guide Agenda

This guide will show how to use the auction-keeper to interact with the Kovan deployment of the MCD smart contracts. More specifically, the guide will showcase how to go through the following stages of setting up and running an Auction Keeper bot:

  1. Introduction
  2. Bidding Models
    • Starting and stopping bidding models
    • Communicating with bidding models
  3. Setting up the Keeper Bot (Flip Auction Keeper)
    • Prerequisites
    • Installation
  4. Running your Keeper Bot (Usage)
    • Keeper Limitations
  5. Accounting
    • Getting MCD K-DAI
    • Getting MCD K-MKR
    • Getting MCD Collateral Tokens
  6. Testing
  7. Support

We are proud to say that since the Maker Protocol is an open-source platform, all of the code we have created to run the Keeper bot is free and accessible to all.

1. Introduction

Auction Keepers participate in auctions as a result of liquidation events and thereby acquire collateral at attractive prices. An auction-keeper can participate in three different types of auctions:

  1. Collateral Auction (flip)
  2. Surplus Auction (flap)
  3. Debt Auction (flop)

Auction Keepers have the unique ability to plug in external bidding models, which communicate information to the Keeper on when and how high to bid (these types of Keepers can be left safely running in the background). Shortly after an Auction Keeper notices or starts a new auction, it will spawn a new instance of a bidding model and act according to its specified instructions. Bidding models will be automatically terminated by the Auction Keeper the moment the auction expires.


Auction Keepers will automatically call deal (claiming a winning bid / settling a completed auction) if the Keeper's address won the auction.

Auction Keeper Architecture

As mentioned above, Auction Keepers directly interact with Flipper, Flapper and Flopper auction contracts deployed to the Ethereum mainnet. All decisions which involve pricing details are delegated to the bidding models. The Bidding models are simply executable strategies, external to the main auction-keeper process. This means that the bidding models themselves do not have to know anything about the Ethereum blockchain and its smart contracts, as they can be implemented in basically any programming language. However, they do need to have the ability to read and write JSON documents, as this is how they communicate/exchange with auction-keeper. It's important to note that as a developer running an Auction Keeper, it is required that you have basic knowledge on how to properly start and configure the auction-keeper. For example, providing startup parameters as keystore / password are required to setup and run a Keeper. Additionally, you should be familiar with the MCD system, as the model will receive auction details from auction-keeper in the form of a JSON message containing keys such as lot, beg, guy, etc.

Simple Bidding Model Example:

A simple bidding model could be a shell script which echoes a fixed price (further details below).

The Purpose of Auction Keepers

The main purpose of Auction Keepers are:

  • To discover new opportunities and start new auctions.
  • To constantly monitor all ongoing auctions.
  • To detect auctions started by other participants.
  • To Bid on auctions by converting token prices into bids.
  • To ensure that instances of bidding model are running for each auction type as well as making sure the instances match the current status of their auctions. This ensure that Keepers are bidding according to decisions outlined by the bidding model.

The auction discovery and monitoring mechanisms work by operating as a loop, which initiates on every new block and enumerates all auctions from 1 to kicks. When this occurs, even when the bidding model decides to send a bid, it will not be processed by the Keeper until the next iteration of that loop. It's important to note that the auction-keeper not only monitors existing auctions and discovers new ones, but it also identifies and takes opportunities to create new auctions.

2. Bidding Models

Starting and Stopping Bidding Models

Auction Keeper maintains a collection of child processes, as each bidding model is its own dedicated process. New processes (new bidding model instances) are spawned by executing a command according to the --model command-line parameter. These processes are automatically terminated (via SIGKILL) by the keeper shortly after their associated auction expires. Whenever the bidding model process dies, it gets automatically re-spawned by the Keeper.


bin/auction-keeper --model '../' [...]

Communicating with bidding models

Auction Keepers communicate with bidding models via their standard input/standard output. Once the process has started and every time the auction state changes, the Keeper sends a one-line JSON document to the standard input of the bidding model.

A sample JSON message sent from the keeper to the model looks like the:

{"id": "6", "flapper": " 0xf0afc3108bb8f196cf8d076c8c4877a4c53d4e7c ", "bid": "7.142857142857142857", "lot": "10000.000000000000000000", "beg": "1.050000000000000000", "guy": " 0x00531a10c4fbd906313768d277585292aa7c923a ", "era": 1530530620, "tic": 1530541420, "end": 1531135256, "price": "1400.000000000000000028"}

Glossary (Bidding Models):

  • id - auction identifier.
  • flipper - Ethereum address of the Flipper contract (only for flip auctions).
  • flapper - Ethereum address of the Flapper contract (only for flap auctions).
  • flopper - Ethereum address of the Flopper contract (only for flop auctions).
  • bid - current highest bid (will go up for flip and flap auctions).
  • lot - amount being currently auctioned (will go down for flip and flop auctions).
  • tab - bid value (not to be confused with the bid price) which will cause the auction to enter the dent phase (only for flip auctions).
  • beg - minimum price increment (1.05 means minimum 5% price increment).
  • guy - Ethereum address of the current highest bidder.
  • era - current time (in seconds since the UNIX epoch).
  • tic - time when the current bid will expire (None if no bids yet).
  • end - time when the entire auction will expire (end is set to 0 is the auction is no longer live).
  • price - current price being tendered (can be None if price is infinity).

Bidding models should never make an assumption that messages will be sent only when auction state changes. It is perfectly fine for the auction-keeper to periodically send the same message(s) to bidding models.

At the same time, the auction-keeper reads one-line messages from the standard output of the bidding model process and tries to parse them as JSON documents. It will then extract the two following fields from that document:

  • price - the maximum (for flip and flop auctions) or the minimum (for flap auctions) price the model is willing to bid.
  • gasPrice (optional) - gas price in Wei to use when sending a bid.

An example of a message sent from the Bidding Model to the Auction Keeper may look like:

    {"price": "150.0", "gasPrice": 7000000000}

In the case of when Auction Keepers and Bidding Models communicate in terms of prices, it is the MKR/DAI price (for flap and flop auctions) or the collateral price expressed in DAI for flip auctions (for example, OMG/DAI).

Any messages written by a Bidding Model to stderr (standard error) will be passed through by the Auction Keeper to its logs. This is the most convenient way of implementing logging from Bidding Models.

3. Setting up the Auction Keeper Bot (Installation)


  • Git
  • Python v3.6.6
  • virtualenv
    • This project requires virtualenv to be installed if you want to use Maker's python tools. This helps to ensure that you are running the right version of python as well as check that all of the pip packages that are installed in the are in the right place and have the correct versions.
  • X-code (for Macs)
  • Docker-Compose

Getting Started

Installation from source:

  1. Clone the auction-keeper repository:
git clone
  1. Switch into the auction-keeper directory:
cd auction-keeper
  1. Install required third-party packages:
git submodule update --init --recursive
  1. Set up the virtual env and activate it:
python3 -m venv _virtualenv
source _virtualenv/bin/activate

5. Install requirements:

pip3 install -r requirements.txt

Potential Errors:

  • Needing to upgrade pip version to 19.2.2:
    • Fix by running pip install --upgrade pip.

For other known Ubuntu and macOS issues please visit the pymaker README.

4. Running your Keeper Bot

1. Creating your bidding model (an example detailing the simplest possible bidding model)

The stdout (standard output) provides a price for the collateral (for flip auctions) or MKR (for flap and flop auctions). The sleep locks the price in place for a minute, after which the keeper will restart the price model and read a new price (consider this your price update interval).

The simplest possible bidding model you can set up is when you use a fixed price for each auction. For example:

    #!/usr/bin/env bash
    echo "{\"price\": \"150.0\"}" # put your desired fixed price amount here 
    sleep 60 # locking the price for a 60 seconds period

Once you have created your bidding model, save it as (or whatever name you feel seems appropriate).

2. Setting up an Auction Keeper for a Collateral (Flip) Auction

Collateral Auctions will be the most common type of auction that the community will want to create and operate Auction keepers for. This is due to the fact that Collateral auctions will occur much more frequently than Flap and Flop auctions.

Example (Flip Auction Keeper):

  • This example/process assumes that the user has an already existing shell script that manages their environment and connects to the Ethereum blockchain.
dir="$(dirname "$0")"

source  # Set the RPC host, account address, and keys.
source _virtualenv/bin/activate # Run virtual environment

# Allows keepers to bid different prices

bin/auction-keeper \
    --rpc-host ${SERVER_ETH_RPC_HOST:?} \
    --rpc-port ${SERVER_ETH_RPC_PORT?:} \
    --rpc-timeout 30 \
    --eth-from ${ACCOUNT_ADDRESS?:} \
    --eth-key ${ACCOUNT_KEY?:} \
    --type flip \ # type of auction the keeper will be working with
    --ilk ETH-A \
    --network kovan \
    --vat-dai-target 1000 \
    --model ${dir}/${MODEL} \
    2> >(tee -a ${LOGS_DIR?:}/auction-keeper-flip-ETH-A.log >&2)

Once finalized, you should save your script to run your Auction Keeper as (or something similar to identify that this Auction Keeper is for a Flip Auction).


  • All Collateral types (ilk's) combine the name of the token and a letter corresponding to a set of risk parameters. For example, as you can see above, the example uses ETH-A. Note that ETH-A and ETH-B are two different collateral types for the same underlying token (WETH) but have different risk parameters.
  • For the MCD addresses, we simply pass --network mainnet|kovan in and it will load the required JSON files bundled within auction-keeper (or pymaker).
    • If you pass in mainnet before MCD is released, it will fail with an appropriate error message.

3. Passing the bidding the model as an argument to the Keeper script

  1. Confirm that both your bidding model ( and your script ( to run your Auction Keeper are saved.
  2. The next step is to chmod +x both of them.
  3. Lastly, run to pass your bidding model into your Auction Keeper script.

Auction Keeper Arguments Explained

To participate in all auctions, a separate keeper must be configured for flip of each collateral type, as well as one for flap and another for flop.

  1. --type - the type of auction the keeper is used for. In this particular scenario, it will be set to flip.
  2. --ilk - the type of collateral.
  3. --addresses - .json of all of the addresses of the MCD contracts as well as the collateral types allowed/used in the system.
  4. --vat-dai-target - the amount of DAI which the keeper will attempt to maintain in the Vat, to use for bidding. It will rebalance it upon keeper startup and upon dealing an auction.
  5. --model - the bidding model that will be used for bidding.

Call bin/auction-keeper --help for a complete list of arguments.

Auction Keeper Limitations

  • If an auction starts before the auction Keeper has started, the Keeper will not participate in the auction until the next block has been mined.
  • Keepers do not explicitly handle global settlement (End). If global settlement occurs while a winning bid is outstanding, the Keeper will not request a yank to refund the bid. The workaround is to call yank directly using seth.
  • There are some Keeper functions that incur gas fees regardless of whether a bid is submitted. This includes, but is not limited to, the following actions:
    • Submitting approvals.
    • Adjusting the balance of surplus to debt.
    • Biting a CDP or starting a flap or flop auction, even if insufficient funds exist to participate in the auction.
  • The Keeper will not check model prices until an auction officially exists. As such, it will kick, flap, or flop in response to opportunities regardless of whether or not your DAI or MKR balance is sufficient to participate. This imposes a gas fee that must be paid.
    • After procuring more DAI, the Keeper must be restarted to add it to the Vat.

5. Accounting

The Auction contracts exclusively interact with DAI (for all auctions types) and collateral (for flip auctions) in the Vat. More explicitly speaking:

  • The DAI that is used to bid on auctions is withdrawn from the Vat.
  • The Collateral and surplus DAI won at auction end is placed in the Vat.

By default, all the DAI and collateral within your eth-from account is exit'ed from the Vat and added to your account token balance when the Keeper is shut down. Note that this feature may be disabled using the keep-dai-in-vat-on-exit and keep-gem-in-vat-on-exit switches, respectively. The use of an eth-from account with an open CDP is discouraged, as debt will hinder the auction contracts' ability to access your DAI, and the auction-keeper's ability to exit DAI from the Vat.

When running multiple Auction Keepers using the same account, the balance of DAI in the Vat will be shared across all of the Keepers. If using this feature, you should set --vat-dai-target to the same value for each Keeper, as well as sufficiently high in order to cover total desired exposure.


MKR used to bid on flap auctions is directly withdrawn from your token balance. The MKR won at flop auctions is directly deposited to your token balance.

Getting Kovan MCD DAI, MKR and other Collateral tokens

1. Getting MCD K-DAI (K-MCD 0.2.12 Release)

Contract address: 0xb64964e9c0b658aa7b448cdbddfcdccab26cc584

  1. Log into your MetaMask account from the browser extension. Add or confirm that the custom MCD K-DAI token is added to your list of tokens.

    • This done by selecting "Add Token" and then by adding in the details under the "Custom token" option.
  2. Head to the MCD CDP Portal here.

    • Confirm that you are in fact on the Kovan Network before proceeding.
  3. Select the "Borrow" option.

  4. Connect your MetaMask account to the CDP portal.

  5. Approve the MetaMask connection.

  6. Below the "Overview" button, find and select the plus sign button to start setting up your CDP.

  7. Select the collateral type you want to proceed with and click "Continue".

    • e.g. ETH-A
  8. Deposit your K-ETH and generate K-DAI by selecting and inputing an amount of K-ETH and the amount of K-DAI you would like to generate. To proceed, click "Continue".

    • e.g. Deposit 0.5 K-ETH and generate 100 DAI.
  9. Click on the checkbox to confirm that you have read and accepted the Terms of Service then click the "Create CDP" button.

  10. Approve the transaction in your MetaMask extension.

  11. Click the "Exit" button and wait for your CDP to be created.

After all of these steps have been completed, you will have the generated MCD K-DAI and it will be present within your wallet. You can easily payback your DAI or generate more.

2. Getting MCD K-MKR (K-MCD 0.2.12 Release)

Contract address: 0xaaf64bfcc32d0f15873a02163e7e500671a4ffcd

This requires familiarity with Seth as well as having the tool set up on your local machine. If unfamiliar, use this guide to install and set it up.

Run the following command in Seth:

seth send 0xcbd3e165ce589657fefd2d38ad6b6596a1f734f6 'gulp(address)' 0xaaf64bfcc32d0f15873a02163e7e500671a4ffcd

Address information:

  • The 0x94598157fcf0715c3bc9b4a35450cce82ac57b20 address is the faucet that issues 1 MKR per request.
  • The 0xaaf64bfcc32d0f15873a02163e7e500671a4ffcd address is that of the MCD K-MKR token. It will issue 1 MKR.

Important Note: The faucet address and token addresses often change with each dss deployment. The current addresses displayed above are from the 0.2.12 Release. Please visit for the most updated release version.

3. Getting MCD Collateral Tokens

There is a shell script which automates the calling of faucets for several tokens which are candidates for MCD collateral types. In order to use this script, read the following instructions:

  1. Save raw content from the gist to a file, and chmod +x it to make it executable.
  2. Install and configure seth as instructed above.
  3. Ensure environment variables at the top of the script are set appropriately, or uncomment them and set them within the script.
  4. Update the MOCKY URI on line 13 to the contracts.json for the desired release version.
  5. Execute the script, which will perform the following actions:
    1. Print the current token balances.
    2. Execute transactions to call the faucet for each token type.
    3. Print (hopefully) the updated token balances.

6. Testing your Keeper

Required for testing:

  • docker-compose
  • This project uses pytest for unit testing. Testing depends upon on a Dockerized local testchain that is included in lib\pymaker\tests\config.
  1. In order to be able to run tests, please install development dependencies first by executing:
    pip3 install -r requirements-dev.txt
  1. You can then run all the unit tests by running the following script:

Example Output

    ============================= test session starts ==============================
    platform darwin -- Python 3.6.6, pytest-3.3.0, py-1.8.0, pluggy-0.6.0
    rootdir: /Users/CP/auction-keeper, inifile:
    plugins: timeout-1.2.1, mock-1.6.3, cov-2.5.1, asyncio-0.8.0
    collected 94 items                                                             
    tests/ .........                                       [  9%]
    tests/ .                                                     [ 10%]
    tests/ ......                                              [ 17%]
    tests/ ....................                                  [ 38%]
    tests/ .........................                             [ 64%]
    tests/ ....................                                  [ 86%]
    tests/ .............                                      [100%]
    ---------- coverage: platform darwin, python 3.6.6-final-0 -----------
    Name                         Stmts   Miss  Cover
    auction_keeper/       0      0   100%
    auction_keeper/           11      0   100%
    auction_keeper/         52      0   100%
    auction_keeper/         328      0   100%
    auction_keeper/        135      0   100%
    auction_keeper/       87      0   100%
    auction_keeper/      94      0   100%
    TOTAL                          707      0   100%

Manual Testing

Within tests/manual resides a collection of python and shell scripts that may be used to test auction-keeper, pymaker's auction facilities, and relevant smart contracts in dss.

Testing Scenarios


    • Creates a single CDP close to the liquidation ratio, and then slightly drops the price of ETH such that the CDP becomes undercollateralized. If this test is run on an already-undercollateralized CDP, it will submit no transaction. In either case, it prints a message stating whether an action was performed. This may be used to test flip auctions as well as build debt for flop auctions.

    • Creates a CDP and then calls jug.drip to establish a surplus. The age of the test chain and the amount of collateral placed in this CDP determines how much surplus is generated.

    Provides status information based on the parameter passed:

    • --auctions prints the most recent bid for each active auction.
    • --balances shows the balance of surplus and debt.

    • Creates a CDP using another address and transfers DAI to the keeper account for bidding on flip and flop auctions. The amount of DAI to purchase is passed as the only argument.

    • Generates MKR tokens for bidding on flap auctions. The amount of MKR to mint is passed as the only argument.

For more information on how to perform manual testing on your keeper manually, click here.

7. Support

We welcome any questions or concerns about the Auction Keepers in the #keeper channel in the Maker Chat.


You (meaning any individual or entity accessing, using or both the software included in this Github repository) expressly understand and agree that your use of the software is at your sole risk. The software in this Github repository is provided “as is”, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software. You release authors or copyright holders from all liability for you having acquired or not acquired content in this GitHub repository. The authors or copyright holders make no representations concerning any content contained in or accessed through the service, and the authors or copyright holders will not be responsible or liable for the accuracy, copyright compliance, legality or decency of material contained in or accessed through this GitHub repository.

You can’t perform that action at this time.