This project is forked from https://github.com/tardis-dev/serum-vial
Start a local instance
npm run start:debug
Run the code snippet below in the browser Dev Tools directly or in Node.js (requires installation of ws
lib.
const ws = new WebSocket('ws://localhost:8000/v1/ws')
ws.onmessage = (message) => {
console.log(JSON.parse(message.data))
}
ws.onopen = () => {
const subscribeL2 = {
op: 'subscribe',
channel: 'level2',
markets: ['BTC-PERP']
}
ws.send(JSON.stringify(subscribeL2))
}
Since by default mango-vial uses confirmed
commitment level for getting accounts notification from RPC node, it may sometimes feel slightly lagged when it comes to order book updates vs default DEX UI which uses recent/processed
commitment.
For the best mango-vial data reliability it's advised to set up a dedicated Solana RPC node and connect mango-vial
to it instead of default https://solana-api.projectserum.com
which may rate limit or frequently restart Websocket RPC connections since it's a public node used by many.
Installs and starts mango-vial server running on port 8000
.
npx mango-vial
If you'd like to switch to different Solana RPC node endpoint like for example local one, change port or run with debug logs enabled, just add one of the available CLI options.
npx mango-vial --endpoint http://localhost:8090 --ws-endpoint-port 8899 --log-level debug --port 8900
Alternatively you can install mango-vial globally.
npm install -g mango-vial
mango-vial
name | default | description |
---|---|---|
port |
8000 | Port to bind server on |
endpoint |
https://solana-api.projectserum.com | Solana RPC node endpoint that mango-vial uses as a data source |
ws-endpoint-port |
- | Optional Solana RPC WS node endpoint port that mango-vial uses as a data source (if different than REST endpoint port) source |
log-level |
info | Log level, available options: debug, info, warn and error |
minions-count |
1 | Minions worker threads count that are responsible for broadcasting normalized WS messages to connected clients |
commitment |
confirmed | Solana commitment level to use when communicating with RPC node, available options: confirmed and processed |
markets-json |
@project-serum/serum markets.json file, but only non depreciated markets |
path to custom market.json definition file if one wants to run mango-vial for custom markets |
Run npx mango-vial --help
to see all available startup options.
Pulls and runs latest version of microwavedcola/mango-vial
Docker Image on port 8000
.
docker run -p 8000:8000 -d microwavedcola/mango-vial:latest
If you'd like to switch to different Solana RPC node endpoint, change port or run with debug logs enabled, just specify those via one of the available env variables.
docker run -p 8000:8000 -e "MV_LOG_LEVEL=debug" -d microwavedcola/mango-vial:latest
name | default | description |
---|---|---|
MV_PORT |
8000 | Port to bind server on |
MV_ENDPOINT |
https://solana-api.projectserum.com | Solana RPC node endpoint that mango-vial uses as a data source |
MV_WS_ENDPOINT_PORT |
- | Optional Solana RPC WS node endpoint port that mango-vial uses as a data source (if different than REST endpoint port) source |
MV_LOG_LEVEL |
info | Log level, available options: debug, info, warn and error |
MV_MINIONS_COUNT |
1 | Minions worker threads count that are responsible for broadcasting normalized WS messages to connected clients |
MV_COMMITMENT |
confirmed | Solana commitment level to use when communicating with RPC node, available options: confirmed and processed |
MV_MARKETS_JSON |
@project-serum/serum markets.json file, but only non depreciated markets |
path to custom market.json definition file if one wants to run mango-vial for custom markets |
mango-vial supports SSL/TLS but it's not enabled by default. In order to enable it you need to set CERT_FILE_NAME
env var pointing to the certificate file and KEY_FILE_NAME
pointing to private key of that certificate.
WebSocket API provides real-time market data feeds of Serum DEX and uses a bidirectional protocol which encodes all messages as JSON objects.
-
each WebSocket client is required to actively send native WebSocket pings to the server with interval less than 30 seconds, otherwise connection may be dropped due to inactivity
-
message compression is enabled for clients supporting
permessage-deflate
-
ws://localhost:8000/v1/ws - assuming mango-vial runs locally on default port without SSL enabled
-
wss://api.mango-vial.dev/v1/ws - demo mango-vial server endpoint
To begin receiving real-time market data feed messages, you must first send a subscribe message to the server indicating channels and markets for which you want the data for.
If you want to unsubscribe from channel and markets, send an unsubscribe message. The structure is equivalent to subscribe messages except op
field which should be set to "op": "unsubscribe"
.
{
"op": "subscribe" | "unsubscribe",
"channel": "level2" | "level1",
"markets": string[]
}
{
"op": "subscribe",
"channel": "level2",
"markets": ["BTC-PERP"]
}
Once a subscription (or unsubscription) request is processed by the server, it will push subscribed
(or unsubscribed
) confirmation message or error
if received request message was invalid.
{
"type": "subscribed" | "unsubscribed",
"channel": "level2" | "level1",
"markets": string[],
"timestamp": string
}
{
"type": "subscribed",
"channel": "level2",
"markets": ["BTC-PERP"],
"timestamp": "2021-03-23T17:06:30.010Z"
}
Error message is pushed for invalid subscribe/unsubscribe messages - non existing market, invalid channel name etc.
{
"type": "error",
"message": "string,
"timestamp": "string
}
{
"type": "error",
"message": "Invalid channel provided: 'levels1'.",
"timestamp": "2021-03-23T17:13:31.010Z"
}
When subscribed to the channel, server will push the data messages as specified below.
-
level1
-
level2
Markets supported by mango-vial server can be queried via GET /markets
HTTP endpoint ([].name
field).
-
type
is determining message's data type so it can be handled appropriately -
timestamp
when message has been received from node RPC API in ISO 8601 format with milliseconds, for example: "2021-03-23T17:03:03.994Z" -
slot
is a Solana's slot number for which message has produced -
version
of Serum DEX program layout (DEX version) -
price
andsize
are provided as strings to preserve precision
Pushed real-time for any change in best bid/ask price or size for a given market (decoded from the bids
and asks
accounts).
bestAsk
andbestBid
are tuples where first item is a price and second is a size of the best bid/ask level
{
"type": "quote",
"market": string,
"timestamp": string,
"slot": number,
"version": number,
"bestAsk": [price: string, size: string] | undefined,
"bestBid": [price: string, size: string] | undefined
}
{
"type": "quote",
"market": "BTC-PERP",
"timestamp": "2021-03-24T07:11:57.186Z",
"slot": 70544253,
"version": 3,
"bestAsk": ["55336.1", "5.0960"],
"bestBid": ["55285.6", "7.5000"]
}
Entire up-to-date order book snapshot with orders aggregated by price level pushed immediately after successful subscription confirmation.
-
asks
andbids
arrays contain tuples where first item of a tuple is a price level and second one is a size of the resting orders at that price level -
it can be pushed for an active connection as well when underlying server connection to the RPC node has been restarted, in such scenario locally maintained order book should be re-initialized with a new snapshot
-
together with
l2update
messages it can be used to maintain local up-to-date full order book state
{
"type": "l2snapshot",
"market": string,
"timestamp": string,
"slot": number,
"version": number,
"asks": [price: string, size: string][],
"bids": [price: string, size: string][]
}
{
"type": "l2snapshot",
"market": "BTC-PERP",
"timestamp": "2021-03-24T09:00:53.087Z",
"slot": 70555623,
"version": 3,
"asks": [
["56463.3", "8.6208"],
["56474.3", "5.8632"],
["56496.4", "3.7627"]
],
"bids": [
["56386.0", "4.8541"],
["56370.1", "6.8054"],
["56286.3", "8.6631"]
]
}
Pushed real-time for any change to the order book for a given market with updated price levels and sizes since the previous update (decoded from the bids
and asks
accounts).
-
together with
l2snapshot
,l2update
messages can be used to maintain local up-to-date full order book state -
asks
andbids
arrays contain updates which are provided as a tuples where first item is an updated price level and second one is an updated size of the resting orders at that price level (absolute value, not delta) -
if size is set to
0
it means that such price level does not exist anymore and shall be removed from locally maintained order book
{
"type": "l2update",
"market": string,
"timestamp": string,
"slot": number,
"version": number,
"asks": [price: string, size: string][],
"bids": [price: string, size: string][]
}
{
"type": "l2update",
"market": "BTC-PERP",
"timestamp": "2021-03-24T09:00:55.586Z",
"slot": 70555627,
"version": 3,
"asks": [["56511.5", "7.5000"]],
"bids": [
["56421.6", "0.0000"],
["56433.6", "5.9475"]
]
}
Returns Mango Perp markets list supported by mango-vial instance (it can be updated by providing custom markets.json file).
-
http://localhost:8000/v1/markets - assuming mango-vial runs locally on default port without SSL enabled
-
https://api.mango-vial.dev/v1/markets - demo mango-vial server endpoint
{
"name": string,
"address": string,
"programId": string,
}[]
[
{
"name": "BTC-PERP",
"address": "A8YFbxQYFVqKZaoYJLLUVcQiWP7G2MeEgW5wsAQgMvFw",
"programId": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
}
]