mango-explorer-v4

Python client library for interacting with Mango Markets V4.

Installation

mango-explorer-v4 is available as a Python package on PyPI and can be installed as:

pip install mango-explorer-v4

Usage

Assuming that you have a SOL wallet already set up, visit https://app.mango.markets to create a Mango account and fund it so that you can place orders.

import asyncio
from mango_explorer_v4.mango_client import MangoClient
from solana.keypair import Keypair
from base58 import b58decode

async def main():
    mango_client = await MangoClient.connect()
    
    # General data functions:
    print(mango_client.symbols())
    
    print(await mango_client.orderbook_l2('SOL/USDC'))
    
    print(await mango_client.fills('SOL-PERP'))
    
    # It is possible to livestream both orderbook & fills, look for incremental_*.py in the examples folder

    # Fill in your Mango account public key e.g 9XJt2tvSZghsMAhWto1VuPBrwXsiimPtsTR8XwGgDxK2 
    mango_account = await mango_client.get_mango_account('PUBLIC_KEY')

    # You can look up any Mango account using
    # https://app.mango.markets/?address=9XJt2tvSZghsMAhWto1VuPBrwXsiimPtsTR8XwGgDxK2
 
    print(await mango_client.balances(mango_account))
    
    print(await mango_client.equity(mango_account)) # Account Value
    
    # Fill in output from Phantom's "Export Private Key" e.g 2pvKRVh ... 1fL5qGq
    keypair = Keypair.from_secret_key(b58decode('SECRET_KEY'))
    
    # Place a limit order
    print(await mango_client.place_order(mango_account, keypair, 'SOL/USDC', 'bid', 10, 0.1, 'limit'))
    
    # Place an oracle pegged perp order: https://docs.mango.markets/mango-markets/oracle-peg-orders
    print(
        await mango_client.place_perp_pegged_order(
            mango_account,
            keypair,
            'SOL-PERP',
            'bid',
            price_offset=-5, # Will always be $5 under oracle price
            peg_limit=10, # If the oracle price moves $10 or more, the order will expire
            quantity=1
        )
    )
    
    # Cancel all orders
    print(
        await mango_client.cancel_all_orders(
            mango_account,
            keypair,
            'SOL-PERP'
        )
    )
    
    # There's a simple quoter, using atomic cancel-replace in examples/market_maker.py

asyncio.run(main())

Running the examples

Please make sure you're running mango-explorer-v4@0.7.3 or above - these instructions don't apply to older versions.

You can find a collection of example code here. These are to be run as command-line tools, with the simplest being the symbols retrieval function, executable as:

python -m mango_explorer_v4.examples.symbols
# Output:
# [
#     {
#         'name': 'SOL/USDC',
#         'type': 'spot',
#         'base_currency': 'SOL',
#         'quote_currency': 'USDC',
#         'maker_fees': ...,
#         'taker_fees': ...
#     }
#     ... all order symbols
# ]

Examples may take arguments, which are specified in their source files. The equity function for example, takes a Mango account primary key, whilst the order book retrieval takes a symbol & (optional) depth. These can be specified in the shell like this:

python -m mango_explorer_v4.examples.equity --mango-account 9XJt2tvSZghsMAhWto1VuPBrwXsiimPtsTR8XwGgDxK2
# Outputs the Account Balance at https://app.mango.markets/?address=9XJt2tvSZghsMAhWto1VuPBrwXsiimPtsTR8XwGgDxK2

python -m mango_explorer_v4.examples.orderbook_l2 --symbol SOL-PERP --depth 5
# Outputs the first 5 orders in the book at https://app.mango.markets/trade?name=SOL-PERP

Some transactions, like order placement, require a keypair. On Phantom wallet it can be fetched as follows:

https://user-images.githubusercontent.com/28162761/233431861-5db448c1-fdf9-4dd0-8df9-156b131dfd71.mov

With the keypair at hand you can place orders using:

python -m mango_explorer_v4.examples.place_order \
    --keypair [KEYPAIR] \
    --mango-account [MANGO_ACCOUNT] \
    --symbol SOL-PERP \
    --side bids \
    --price 1 \
    --size 0.1

And cancel them later as:

python -m mango_explorer_v4.examples.cancel_all_orders \
    --keypair [KEYPAIR] \
    --mango-account [MANGO_ACCOUNT] \
    --symbol SOL-PERP

Support

Support is available on the Mango Markets Discord server - post in the #dev-discussion channel for any questions or feature requests.