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.
These are some simple examples of how to use the mango-explorer library.
Each example aims to be as simple as possible for a given piece of functionality. The mango-explorer project itself has more realistic usage (for example, commands in the /bin directory), with parameters and error handling.
These examples are all in Jupyter Notebooks and can be run in your browser (no installation necessary!) on Binder.
All these examples run on Solana devnet, so no real tokens are used and no tokens have any value.
The private key for the account is shown below, and in many samples. It's hard-coded to simplify the examples as well as make it obvious how keys are used.
Account: DeekipCw5jz7UgQbtUbHQckTYGKXWaPQV4xY93DaiM6h
Key: [67,218,68,118,140,171,228,222,8,29,48,61,255,114,49,226,239,89,151,110,29,136,149,118,97,189,163,8,23,88,246,35,187,241,107,226,47,155,40,162,3,222,98,203,176,230,34,49,45,8,253,77,136,241,34,4,80,227,234,174,103,11,124,146]
Please don't drain tokens from this account. Devnet tokens are already freely available and it just makes things more difficult for beginners.
If you find that the examples don't work because there's no SOL in the devnet account, you can 'airdrop' 1 SOL into it with the Solana CLI command:
solana airdrop 10 DeekipCw5jz7UgQbtUbHQckTYGKXWaPQV4xY93DaiM6h --url devnet
All the code here and in mango-explorer assumes Python 3. Where you see commands running python
, you may need to instead explicitly run python3
(depending on your system).
The Context
is heavily used to provide access to Solana, Mango Groups and Accounts. This example shows you how to create a Context
object.
A Mango Group
allows cross-margining of assets and holds details of spot and perp markets. This example shows you how to access a group and show its details.
A Wallet
holds the keys to access specific Solana data. This example shows how to instantiate a wallet from existing data.
Wallets hold 'SPL' tokens. This example shows how to fetch the token balance for Wrapped SOL in the current wallet.
A Mango Account
holds details of a user's balances and positions. This example shows you how to access an account and show its details.
Account
s have a lot of details. This example shows you how to access the net balances of all the tokens it contains.
Account
s have a lot of details. This example shows you how to access the balance of one specific token.
Sometimes you just want to know the price of an asset. This example shows you how to fetch the current price from three different Oracle
s.
What if you want to watch the price update in real-time? This example shows you how to stream prices from an Oracle
.
A Market
is an abstract entity to gather together access to the 3 specific market types that mango-explorer supports: Serum, Spot and Perp. This example shows you how to access different market types and show their details.
Once you have access to a Market
you can show its OrderBook
. This example shows you how.
If you have a Market
and you have tokens, you can place and cancel Order
s. This example shows you how.
Often you just want to work with your own orders. This example shows you how to retrieve only your own Order
s from a Market
.
Sometimes - for example when hedging - you just want to place a 'take' Order
with some assurance that it will be filled quickly within a specific slippage. For example, you might want to BUY 100 SOL at a price up to 2% higher than the current market price. 'Immediate Or Cancel' (IOC) orders allow you to always 'take' from the orderbook (they will never be on the book themselves), and the 'up to 2%' above is called the 'slippage'. This example shows you an easy way to submit IOC orders with slippage.
Tracking down details of token transfers across Serum accounts can be tricky. One place that's hard to check sometimes is the OpenOrders
account. This example shows you how to fetch and print an account's Serum OpenOrders
.
Mango spot OpenOrders
accounts are very similar to Serum OpenOrders
, but are fetched slightly differently. This example shows you how to fetch and print an Account
's Spot OpenOrders
.
Perp OpenOrders
are a little difference from Spot and Serum OpenOrders
, in that they are contained directly inside the Account
and have no independent address. This example shows you how to fetch and print an account's perp OpenOrders
.
The PerpEventQueue
holds PerpFillEvent
s, PerpOutEvent
a and PerpLiquidateEvent
s, as they are processed. This example shows you how to fetch and print all PerpEventQueue
events.
What if you want to watch the events appear in real-time? This example shows you how to stream all perp events from a PerpEventQueue
.
Mango provides on-chain incentives for providing liquidity on perp markets. This example shows you how to view the current state of the liquidity incentives, how much has been given out already in the current period, how much remains to be given out, what the threshold is, and an estimate of when the current period will end.
CombinableInstructions
are unique to mango-explorer
(as far as I know) and they aim to make code efficinet and clear at the same time. They're used frequently throughout mango-explorer
code and allow operations like:
(signers + do_something + do_something_else + cleanup).execute(context)
This example shows this pattern in practice by placing an order, cranking the market and settling any fill in one transaction.
Depositing and withdrawing are non-market operations, so don't fit into the MarketOperations
paradigm. They are still possible using CombinableInstruction
s though! This example shows how to deposit and then withdraw Wrapped SOL to and from a Mango Account
.
Integration with other systems sometimes requires working with Solana's own Transaction
s and TransactionInstruction
s. mango-explorer
uses CombinableInstructions
as its native format, so this example shows you how to extract the raw TransactionInstruction
s and keypair
s from the CombinableInstructions
and run them in a raw Solana Transaction
.
Now that you can fetch prices and place and cancel orders, this example shows a simple marketmaker. This example is a slightly-reduced version of the SimpleMarketMaker
in mango-explorer
, and it follows the same principles but allows you to run the code entirely in your browser.
This much-more complete example shows how to build and run the more-complete MarketMaker
.
It walks through creating a custom OrderChain
, how to add (and configure) specific Element
s to the OrderChain
, and how to build the ModelState
for every 'pulse'.
It will then load and run the MarketMaker
, with a fresh 'pulse' every 30 seconds. It will place Order
s, cancel existing Order
s, or leaving suitable Order
s as they are.
This is the full MarketMaker
, the same one run via the marketmaker
command in the Quickstart, but with a custom (editable!) configuration, running in your browser.
This spot-market example builds on the previous perp-market example to show how to run a marketmaker against a spot market and - importantly - show what similarities and differences there are.
The bulk of the code is the same, but spot markets use different mechanisms to load the ModelState
and a different CollateralCalculator
.
🥭 Mango Markets: https://mango.markets
📄 Documentation: https://docs.mango.markets/
💬 Discord: https://discord.gg/67jySBhxrg
🐦 Twitter: https://twitter.com/mangomarkets
🚧 Github: https://github.com/blockworks-foundation
📧 Email: mailto:hello@blockworks.foundation