npm package: @luagio/mango-client
Description: Client to interact with the Alphx program on Solana
Author: luagio
Latest version: 3.3.24

# Mango v3 Client Library

JavaScript client library for interacting with Mango Markets DEX v3.

[API Documentation](https://blockworks-foundation.github.io/mango-client-v3/)

## Installation

Using npm:

```
npm install @blockworks-foundation/mango-client
```

Using yarn:

```
yarn add @blockworks-foundation/mango-client
```

## Usage Example

This example assumes that you have a wallet that is already setup with devnet tokens. The private key should be stored in `~/.config/solana/devnet.json`. Visit https://v3.mango.markets/ and connect with the wallet to fund your margin account so that you can place orders. You can find the full source code in [example.ts](./src/example.ts).

```js
// Fetch orderbooks
const bids = await perpMarket.loadBids(connection);
const asks = await perpMarket.loadAsks(connection);

// L2 orderbook data
for (const [price, size] of bids.getL2(20)) {
  console.log(price, size);
}

// L3 orderbook data
for (const order of asks) {
  console.log(
    order.owner.toBase58(),
    order.orderId.toString('hex'),
    order.price,
    order.size,
    order.side, // 'buy' or 'sell'
  );
}

// Place order
await client.placePerpOrder(
  mangoGroup,
  mangoAccount,
  mangoGroup.mangoCache,
  perpMarket,
  owner,
  'buy', // or 'sell'
  39000,
  0.0001,
  'limit', // or 'ioc' or 'postOnly'
);

// retrieve open orders for account
const openOrders = await perpMarket.loadOrdersForAccount(
  connection,
  mangoAccount,
);

// cancel orders
for (const order of openOrders) {
  await client.cancelPerpOrder(
    mangoGroup,
    mangoAccount,
    owner,
    perpMarket,
    order,
  );
}

// Retrieve fills
for (const fill of await perpMarket.loadFills(connection)) {
  console.log(
    fill.owner.toBase58(),
    fill.maker ? 'maker' : 'taker',
    fill.baseChange.toNumber(),
    fill.quoteChange.toNumber(),
    fill.longFunding.toFixed(3),
    fill.shortFunding.toFixed(3),
  );
}
```


```
spl-token create-token

spl-token supply C9Gbj8yfWF82D5op3JWw3eW5147fzQ7jUnBisZXerzUE

spl-token mint C9Gbj8yfWF82D5op3JWw3eW5147fzQ7jUnBisZXerzUE 100
```

## CLI for testing

Create a new mango group on devnet:
```
init-group <group> <mangoProgramId> <serumProgramId> <quote_mint>
```

```




USDC
yarn cli init-group mango_test_v2.2 2UAVYadHHWpgtTJKboNXkCRZwryWztLGnaZXkjUR93YT DESVgJVGajEgKGXhb6XmqDHGz3VjdgP7rEVESBgxmroY 8FRFC6MoGGkMFQwngccyu69VnYbzykGeez7ignHVAFSN 3Noz2ztF7kKVa4bCqHyg1rRtrtpwYWMihBWnVoRX93YJ


ALPHAX
yarn cli init-group mango_test_v2.2 2UAVYadHHWpgtTJKboNXkCRZwryWztLGnaZXkjUR93YT DESVgJVGajEgKGXhb6XmqDHGz3VjdgP7rEVESBgxmroY C9Gbj8yfWF82D5op3JWw3eW5147fzQ7jUnBisZXerzUE 3WZYoYM1s4UdKDyNDQShqBEpFZQ7r5Pv92NzdKZBEnG7

yarn cli add-oracle mango_test_v2.2 ALPHAX

yarn cli add-spot-market mango_test_v2.2 ALPHAX C9Gbj8yfWF82D5op3JWw3eW5147fzQ7jUnBisZXerzUE --base_lot_size 100 --quote_lot_size 10

yarn cli add-perp-market mango_test_v2.2 ALPHAX



BTC
yarn cli init-group mango_test_v2.2 2UAVYadHHWpgtTJKboNXkCRZwryWztLGnaZXkjUR93YT DESVgJVGajEgKGXhb6XmqDHGz3VjdgP7rEVESBgxmroY 3UNBZ6o52WTWwjac2kPUb4FyodhU1vFkRJheu1Sh2TvU G1uCkGhymfD65etVpTQatWWFkkwpaafqubMR46KaxoJU

yarn cli add-oracle mango_test_v2.2 BTC

yarn cli add-spot-market mango_test_v2.2 BTC 3UNBZ6o52WTWwjac2kPUb4FyodhU1vFkRJheu1Sh2TvU --base_lot_size 100 --quote_lot_size 10

yarn cli add-perp-market mango_test_v2.2 BTC

ETH
yarn cli init-group alphax_dev 2UAVYadHHWpgtTJKboNXkCRZwryWztLGnaZXkjUR93YT DESVgJVGajEgKGXhb6XmqDHGz3VjdgP7rEVESBgxmroY Cu84KB3tDL6SbFgToHMLYVDJJXdJjenNzSKikeAvzmkA BtDK2E89DGj3f2wZzKEKoSDJuLMkyVWw1wszSD6Yhzm9

yarn cli add-oracle mango_test_v2.2 ETH

yarn cli add-spot-market mango_test_v2.2 ETH Cu84KB3tDL6SbFgToHMLYVDJJXdJjenNzSKikeAvzmkA --base_lot_size 100 --quote_lot_size 10

SOL
yarn cli init-group mango_test_v2.2 2UAVYadHHWpgtTJKboNXkCRZwryWztLGnaZXkjUR93YT DESVgJVGajEgKGXhb6XmqDHGz3VjdgP7rEVESBgxmroY So11111111111111111111111111111111111111112 45VsYbuHQ9xpaabTe2yPvMXDpsanGTinccxrh67TURBT

yarn cli add-oracle mango_test_v2.2 SOL

yarn cli add-spot-market mango_test_v2.2 SOL So11111111111111111111111111111111111111112  --base_lot_size 100 --quote_lot_size 10

USDT
yarn cli init-group mango_test_v2.2 2UAVYadHHWpgtTJKboNXkCRZwryWztLGnaZXkjUR93YT DESVgJVGajEgKGXhb6XmqDHGz3VjdgP7rEVESBgxmroY DAwBSXe6w9g37wdE2tCrFbho3QHKZi4PjuBytQCULap2 5yHxGL5yHZEfvLRXCYvLFhEY6etDjLJ1TkDatcJPkApv

yarn cli add-oracle mango_test_v2.2 USDT

yarn cli add-spot-market mango_test_v2.2 USDT DAwBSXe6w9g37wdE2tCrFbho3QHKZi4PjuBytQCULap2  --base_lot_size 100 --quote_lot_size 10


```


Create a new mango group on devnet with new USDC:
```
init-group <group> <mangoProgramId> <serumProgramId> <quote_mint>
```
```
yarn cli init-group mango_test_v3.1 Hm3U4wFaR66SmuXj66u9AuUNUqa6T8Ldb5D9uHBs3SHd DESVgJVGajEgKGXhb6XmqDHGz3VjdgP7rEVESBgxmroY 3u7PfrgTAKgEtNhNdAD4DDmNGfYfv5djGAPixGgepsPp
FUMVc6Y5zzBUGQSiRZgQZfCwB83fARuncRfgeRNqQAQb
```


Add a stub oracle:
```
add-oracle <group> <symbol>
```
```
yarn cli add-oracle mango_test_v2.2 BTC
```


Add a pyth oracle:
```
add-oracle <group> <symbol>
```
```
yarn cli add-oracle mango_test_v3.1 BTC --provider pyth
```


Set stub oracle value = base_price \* quote_unit / base_unit:
```
set-oracle <group> <symbol> <value>
```
```
yarn cli set-oracle mango_test_v2.2 BTC 40000
```


Add a spot-market with existing serum market
```
add-spot-market <group> <symbol> <mint_pk> --market_pk <market_pk>
```
```

4p1xR9W4A29k5zjimtFAUEsJR7A2WcM7DWUqzWComWKY
yarn cli add-spot-market mango_test_v2.2 BTC bypQzRBaSDWiKhoAw3hNkf35eF3z3AZCU8Sxks6mTPP --market_pk E1mfsnnCcL24JcDQxr7F2BpWjkyy5x2WHys8EL2pnCj9

yarn cli add-spot-market mango_test_v2.2 BTC bypQzRBaSDWiKhoAw3hNkf35eF3z3AZCU8Sxks6mTPP --market_pk E1mfsnnCcL24JcDQxr7F2BpWjkyy5x2WHys8EL2pnCj9
```

List and add a spot-market
```
add-spot-market <group> <symbol> <mint_pk> --base_lot_size <number> --quote_lot_size <number>
```
```
yarn cli add-spot-market mango_test_v2.2 BTC 3UNBZ6o52WTWwjac2kPUb4FyodhU1vFkRJheu1Sh2TvU --base_lot_size 100 --quote_lot_size 10
```

Enable a perp-maket
```
add-perp-market <group> <symbol>
```
```
yarn cli add-perp-market mango_test_v2.2 BTC
```

## Run the Keeper
1. Install Node.js and npm (https://nodejs.org/en/download/), and Git (https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
2. Open a new terminal window (if running Windows use Git Bash) and run `npm install -g yarn`
3. Run `git clone https://github.com/blockworks-foundation/mango-client-v3.git && cd mango-client-v3` to get the client source code
5. Run `yarn install` to install dependencies
6. Set the KEYPAIR env variable (e.g. `export KEYPAIR=$(cat ~/.config/solana/id.json)`, or copy from Sollet)
8. Run `yarn keeper` to start the Keeper

Example: 
```
KEYPAIR=[123, 456, 789, ...] yarn keeper
```

## Run the Market Maker
### Setup
To run the market maker you will need:
* A Solana account with some SOL deposited to cover transaction fees
* A Mango Account with some collateral deposited and a name (tip: use the UI)
* Your wallet keypair saved as a JSON file
* `node` and `yarn`
* A clone of this repository
* Dependencies installed with `yarn install`

### Environment Variables
| Variable | Default | Description |
| -------- | ------- | ----------- |
| `ENDPOINT_URL` | `https://mango.rpcpool.com` | Your RPC node endpoint |
| `KEYPAIR` | `${HOME}/.config/solana/id.json` | The location of your wallet keypair |
| `GROUP` | `mainnet.1` | Name of the group in ids.json |
| `INTERVAL` | `10000` | Milliseconds to wait before checking for sick accounts |
| `MANGO_ACCOUNT_NAME` | N/A | The MangoAccount name you input when initializing the MangoAccount via UI |
| `MANGO_ACCOUNT_PUBKEY` | N/A | If no MangoAccount name, just pass in the pubkey |
| `MARKET` | N/A | Market base symbol e.g. BTC |
| `SIZE_PERC` | `0.1` | The size of each order as a percentage of equity |
| `CHARGE` | `0.0010` | Half the quote width |
| `LEAN_COEFF` | `0.0005` | How much to move the quotes per unit size of inventory |
| `BIAS` | `0` | Fixed amount to bias. Negative values bias downward. e.g. -0.0005 biases down 5bps |

### Example
```shell
git clone https://github.com/blockworks-foundation/mango-client-v3.git
cd mango-client-v3
yarn install
KEYPAIR=~/.config/solana/id.json GROUP=mainnet.1 MANGO_ACCOUNT_NAME=mm MARKET=ADA INTERVAL=5000 SIZE_PERC=0.05 CHARGE=0.0015 LEAN_COEFF=0.00075 yarn mm
```


npm install -g foreman

nf start keeper

nf start crank

npm init --scope=@luagio -y

npm publish --access public















/*
TODO list
1. mark price
2. oracle
3. liquidator
4. order book
5. crank
6. market makers
7. insurance fund
8. Basic DAO
9. Token Sale
10.

Crank keeps the oracle prices updated
Make adding perp markets very easy

Designs
Single Margin-Perp Cross
A perp market crossed with the equivalent serum dex spot market with lending pools for margin

find a way to combine multiple of these into one cross margined group

Write an arbitrageur to transfer USDC between different markets based on interest rate



Multi Perp Cross
Multiple perp markets cross margined with each other
Pros:

Cons:
1. Have to get liquidity across all markets at once (maybe doable if limited to 6 markets)
2. Can't do the carry trade easily
3.

 */