This Quickstart will guide you through setting up and running [mango-explorer](https://github.com/blockworks-foundation/mango-explorer/) to run a marketmaker on [Mango Markets](https://mango.markets/) perps on devnet.
Devnet and [Mango’s Devnet Site](https://devnet.mango.markets) are test/development environments where it is safe to try things out without risking ‘live’ tokens. Tokens on devnet are purely for development and testing and have no value.
Throughout this guide you’ll see the private key, accounts and transaction IDs as well as the commands and parameters that are used. (This is a devnet account so no actual funds are required. And remember - sharing your private key is usually a Very Bad Idea!)
And all you need is a unix-type server (Unix, Linux or OS X etc.) with [docker](https://www.docker.com/) installed and configured. By the end of the guide you should have a marketmaker running against Mango’s BTC-PERP market on devnet.
This Quickstart was completed on a $5-per-month VPS on Vultr, so it doesn’t need high-spec hardware.
## 0.1 ☠️ Risks
Now is the time to question if you should really do this. No-one here is going to take any responsibility for your actions. It’s all on you. Are you certain you want to do this? Are you sure you want to run this code? Have you even checked it to make sure it’s not going to steal your money? Are you aware of the risks from markets in general, plus bugs, developer incompetence, malfeasance and lots of other bad stuff? This guide is for devnet-only but you’re still running software you didn’t create and that always involves risk.
This marketmaker has a very basic strategy that will likely lose money on trades over the long term. Liquidity incentives may make up for this to some extent, or they may not. Proceding is all at your own risk.
## 0.2 🦺 Prerequisites
To run this quickstart you’ll need:
* A unix-y server set up with [docker](https://www.docker.com/) installed and configured.
* Erm...
* That’s it
If you can successfully run `docker run hello-world`, you’re good to go!
## 0.3 🗓️ Comming Up
This Quickstart will guide you through the following sections:
* 1. ❓ Why Run A Marketmaker?
* 2. 📂 Directories And Files
* 3. 📜 ‘mango-explorer’ Alias
* 4. 👛 Create The Wallet
* 5. 🎱 6. 🎱 Common Command Parameters
* 6. 💰 Add Some SOL
* 7. ✅ Initialise Account
* 8. 💸 Add USDC
* 9. ⚖️ Deposit USDC
* 10. 🎬 A Bit About Marketmaking
* 11. 💸 Start The Marketmaker
* 12. ⚡ Really Start The Marketmaker
This Quickstart will use 10,000USDC (devnet, so not real) as the starting point. 10,000USDC seemed a nice starting point for this guide, but how much you use is up to you. Adjust the figures below where necessary.
# 1. ❓ Why Run A Marketmaker?
Traders buy and sell, but it helps when there are reliable entities for them to trade against. And while an individual trader may buy or sell, they typically aren’t doing both at the same time on the same symbol. In contrast, a marketmaker places both buy and sell orders for the same symbol, producing a valuation of the symbol and saying how much they’d be willing to pay for some quantity, and how much they’d ask to part with some quantity. They _literally make a market_ by always providing a price at which someone can buy and a price at which someone can sell, and profit by the difference between the buy and sell prices - the ‘spread’.
It takes a smart strategy to successfully run a marketmaker these days, and this code does not have a smart strategy. Unless there are other factors, expect this marketmaker to lose money in the medium and long term.
Our server needs at least one file - the `id.json` that holds the secret key - but it can be useful to keep all mango-explorer things together, away from any other files you may have.
So what we’ll do is create a directory called `mango-explorer` in your home directory, put the `id.json` file there, and leave it up to you if you want to put logfiles or anything else in there too.
Run the following commands to set up the necessary directories and files:
If you are running as `root`, there’s an additional step. Docker can’t write to that file now if you are `root` so you need to explicitly allow the container user access to that file by running:
```
# chown 1000:1000 ~/mango-explorer/id.json
```
You only need to run the `chown` command if you’re `root`. If you’re not `root`, that command is unnecessary and won’t work.
(/home/jovyan/work/id.json is not a typo in the command - it’s the path to the ID file in the docker container’s context - it’s mapped to the ~/mango-explorer/id.json file.)
This is what a successful run of the command looks like. It creates a Solana wallet and writes its secret key to ~/mango-explorer/id.json. **Looking after this file is entirely your responsibility. If you lose this file, you lose the private key for all the funds in the wallet. If you give it to someone else you give them the entire contents of your wallet.** This is not a big deal on devnet but it’s very important on mainnet.
-`--log-level LOG_LEVEL` - level of verbosity to log (possible values: DEBUG, INFO, WARNING, ERROR, CRITICAL)
-`--id-file ID_FILE` - file containing the JSON-formatted wallet private key
You can see exactly what parameters a command takes by passing just the `--help` parameter.
# 6. 💰 Add Some SOL
SOL tokens are needed for running operations on the Solana blockchain, similar to the way ether is used on Ethereum. Since this is devnet, you can just ask Solana itself for some tokens and it will put them in your account.
This will transfer 10 SOL to **6MEVCr816wapduGknarkNRwMFWvFQSNv5h7iQEGGx8uB**, the address shown above when creating the wallet. You should substitute the public key of the account you created. (You can run this command again and again to get more devnet SOL, should you ever need it.) You should see output like:
THE SOFTWARE 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.
This shows 10 SOL and no other tokens, as you’d expect (since we haven’t acquired any of those yet).
# 7. ✅ Initialise Account
Now let’s set up the Mango Account. The Mango Account is associated with a Mango Group, and it holds your tokens and allows you to trade that Group’s markets using margin.
THE SOFTWARE 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.
Waiting on transaction IDs: ['TJTBPUPv9tf7vgRUr27Jh8VeWNRGZfy8nkW1uEQhAYRLN8vpM4WboSHgeKGpJc25T4RnSYDFDsSy3fRn8TqKSYp']
2021-08-27 19:17:43 ⓘ BetterClient Waiting up to 60 seconds for ['TJTBPUPv9tf7vgRUr27Jh8VeWNRGZfy8nkW1uEQhAYRLN8vpM4WboSHgeKGpJc25T4RnSYDFDsSy3fRn8TqKSYp'].
2021-08-27 19:17:59 ⓘ BetterClient Confirmed TJTBPUPv9tf7vgRUr27Jh8VeWNRGZfy8nkW1uEQhAYRLN8vpM4WboSHgeKGpJc25T4RnSYDFDsSy3fRn8TqKSYp after 0:00:15.954582 seconds.
Now you need to get some devnet USDC. You only need USDC for marketmaking on BTC-PERP - you don’t need a stash of both base and quote tokens the way you would if you were marketmaking on, say, BTC/USDC. There’s a faucet to freely give out devnet USDC tokens at B87AhxX6BkBsj3hnyHzcerX2WxPoACC7ZyDr8E7H9geN. Instead of using the [faucet web site](https://www.spl-token-ui.com/#/token-faucets), just run the command:
THE SOFTWARE 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.
2021-08-30 11:03:09 ⓘ BetterClient Waiting up to 60 seconds for ['2pHzmyPVT1UaU13zyigjQRr1xLz8jExpbiAsFpxxMzjoTEbyxAbhvtfYmQ2oiqfLF5Y6U637EBbJh3Wi1i561z5A'].
2021-08-30 11:03:28 ⓘ BetterClient Confirmed 2pHzmyPVT1UaU13zyigjQRr1xLz8jExpbiAsFpxxMzjoTEbyxAbhvtfYmQ2oiqfLF5Y6U637EBbJh3Wi1i561z5A after 0:00:19.050797 seconds.
Airdropping 10000 USDC to CfWq8oFtsyWQ1eVaC3qW3ffCFjQHUd4QmVjW9L9EQrBL
THE SOFTWARE 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.
THE SOFTWARE 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.
THE SOFTWARE 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.
If you’ve read the [MarketMaking](MarketMaking.md) doc you’ll be well placed to understand the `marketmaker` output, but if you haven’t here’s a brief summary of what the `marketmaker` does:
The marketmaker keeps the group, price and account data up-to-date and passes this fresh state to every ‘pulse’.
A ‘chain’ of pluggable objects of type `ChainElement` look at the state every pulse and build a list of orders they would like to see on the orderbook.
Another pluggable object, this time of type `OrderReconciler` tries to reconcile the desired orders with the existing orders, and only cancel/replace where necessary.
## The Default ‘Chain’
Usually the head of the marketmaker ‘chain’ creates some desired orders, and they may be modified by subsequent elements in the chain.
The default chain is:
-`ConfidenceIntervalSpreadElement` - uses the ‘confidence interval’ in the oracle price to determine the spread. How aggressively this is used can be tuned by the `--confidence-interval-level` parameter.
A weighting to apply to the confidence interval from the oracle: e.g. 1 - use the oracle confidence interval as the spread, 2 (risk averse, default) - multiply the oracle confidence interval by 2 to get the spread, 0.5 (aggressive) halve the oracle confidence interval to get the spread.
The ‘confidence interval’ is Pyth’s expectation of how far from the current mid-price the next trade will occur. If you use a ‘confidence weighting’ parameter of 2, this confidence interval is doubled and then added to the mid-price to get the sell price for the order and subtracted from the mid-price to get the buy price for the order.
- Using a confidence weighting of 1 just uses the confidence interval to create the spread
- Using a confidence weighting of 2 (the default) doubles the width of the spread
- Using a confidence weighting of 0.5 halves the width of the spread (and so is more aggressive)
**Important note:** this can be specified multiple times on the command line, so you can have orders placed at, say, 1x, 2x and 5x the confidence interval, placing/checking 6 orders in total each pulse (3 BUYs, 3 SELLs).
-`BiasQuoteOnPositionElement` - can shift the price of orders based on how much inventory is held. Too much inventory: bias prices down (so it tends to buy less and sell more). Too little inventory: bias prices up (so it tends to buy more and sell less).
The default bias is 0, meaning no changes will be made to orders. You can change this using the `-quote-position-bias` parameter. This should be a small, positive number. I’m trialing 0.00003 and it shifts the price significantly.
-`MinimumChargeElement` - ensures that there’s a minimum value of spread to be paid by the taker.
It’s possible that the configuration may lead to too small a spread to be profitable. You can use the `--minimum-charge-ratio` parameter to enforce a minimum spread. The default of 0.0005 is 0.05%.
-`PreventPostOnlyCrossingBookElement` - ensures that POST_ONLY orders that would corss the orderbook (and so be cancelled instead of put on the book) are placed *just* inside the spread by 1 tick.
## Frequently-Used Marketmaker Parameters
Here are some parameters that are commonly passed to the `marketmaker`.
-`--name` You need to give this instance a name. This appears in some error messages and notifications, and can help track down which marketmaker is having problems if you end up running multiple instances.
-`--group` The name of the Mango Group you want to use. (Optional - will use the default group in the `ids.json` file in the container if none is specified.)
-`--market` The name of the market you want to use. (Required. Much be an exact match for one of the markets in the configured group in the `ids.json` file in the container.)
-`--oracle-provider`**** You can pick the oracle to use for price information. Pyth is a common choice because the other options don’t provide a ‘confidence value’. Options are:
- pyth
- serum
- ftx
-`--position-size-ratio` This is the portion of your funds to use for each order. 0.01 is 1%.
-`--existing-order-tolerance` The marketmaker examines existing orders and compares them with the desired orders. If an existing order is within tolerance of the price and quantity of a desired order, it is kept. If not, it’s cancelled and a new order is placed. 0.0001 is 0.01%.
-`--pulse-interval` This is the interval (in seconds) between each marketmaker iteration. Each iteration it examines state, cancels orders and places orders - the ‘pulse interval’ is the number of seconds to wait between these iterations.
OK, now we’re ready to try a test run of the marketmaker. This will be a ‘dry run’ so no orders will be placed or cancelled, but it will load the full data and calculate what orders it would have placed.
This is a long-running process, so we’ll need to use Control-C to cancel it when we’re done.
THE SOFTWARE 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.
* It outputs a **lot** of information. You can turn that down with the parameters `--log-level INFO` or `--log-level WARNING` when you’re confident of the marketmaker’s operation.
* It prints out some summary information about the current assets in the account.
* It pulses every 30 seconds, deciding which orders to place and which to cancel
* It sleeps between runs
# 12. ⚡ Really Start The Marketmaker
If you’ve got this far and you’re happy with the results, you can run the same command with the `--dry-run` parameter removed. That will start the marketmaker and have it place orders. This is all still on devnet, so no real funds are at stake.
Output should be broadly the same as the output for a ‘dry run’, but you’ll be able to see the orders appear on [Mango Devnet](https://devnet.mango.markets) and you’ll sometimes see errors from the chain or more detail from some of the transactions.