WebSocket API

Overview

The Public WebSocket API provides real-time data subscription functionality, supporting subscriptions for order books, K-lines, instrument information, portfolios, and more.

Connection URL

wss://api.monday.trade/v4/public/ws

Heartbeat Mechanism

Clients can send a "ping" string to keep the connection alive. The server will reply with "pong".

Message Format

Request Message Format

All request messages follow this format:

{
  "id": <number>,           // Request ID for matching responses
  "method": "SUBSCRIBE" | "UNSUBSCRIBE",
  "params": {
    // Specific parameters vary by subscription type
  }
}

Response Message Format

{
  "id": <number>,           // Corresponding request ID
  "result": "success"
}

Data Stream Message Format

{
  "stream": "<stream_type>",  // Stream type: orderBook, kline, instrument, portfolio, blockNumChanged, marketListChanged, marketPairInfoChanged
  "chainId": <number>,        // Optional: present for instrument-scoped streams (orderBook, kline, instrument, marketPairInfoChanged)
  "instrument": "<address>",  // Optional: present for instrument-scoped streams
  "expiry": <number>,         // Optional: present for instrument-scoped streams
  "data": {
    // Specific data varies by subscription type
  }
}

Subscription Types

1. K-line Data Subscription (kline)

Subscribe to K-line data updates for a specific instrument and interval.

{
  "id": 1,
  "method": "SUBSCRIBE",
  "params": {
    "chainId": 143,
    "instrument": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
    "expiry": 4294967295,
    "interval": "1m",
    "type": "kline"
  }
}

Unsubscribe Request

{
  "id": 1,
  "method": "UNSUBSCRIBE",
  "params": {
    "chainId": 143,
    "instrument": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
    "expiry": 4294967295,
    "interval": "1m",
    "type": "kline"
  }
}

Parameter Description

chainId (required): Chain ID
instrument (required): Instrument address (lowercase)
expiry (required): Expiry timestamp
interval (required): K-line interval. Supported values:
- 1m - 1 minute
- 5m - 5 minutes
- 15m - 15 minutes
- 30m - 30 minutes
- 1h - 1 hour
- 4h - 4 hours
- 8h - 8 hours
- 12h - 12 hours
- 1d - 1 day
- 1w - 1 week
- 1M - 1 month
type (required): Must be "kline"

Data Stream Message

{
  "stream": "kline",
  "chainId": 143,
  "instrument": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
  "expiry": 4294967295,
  "data": {
    "interval": "1m",
    "open": 1234.56,
    "high": 1250.00,
    "low": 1230.00,
    "close": 1245.00,
    "baseVolume": 1000.5,
    "quoteVolume": 1245000.0,
    "volumeUSD": 1245000.0,
    "timestamp": 1699000000,
    "startTime": 1699000000,
    "endTime": 1699000059
  }
}

2. Order Book Subscription (orderBook)

Subscribe to order book data updates for a specific instrument.

{
  "id": 2,
  "method": "SUBSCRIBE",
  "params": {
    "chainId": 143,
    "instrument": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
    "expiry": 4294967295,
    "type": "orderBook"
  }
}

Unsubscribe Request

{
  "id": 2,
  "method": "UNSUBSCRIBE",
  "params": {
    "chainId": 143,
    "instrument": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
    "expiry": 4294967295,
    "type": "orderBook"
  }
}

Parameter Description

chainId (required): Chain ID
instrument (required): Instrument address (lowercase)
expiry (required): Expiry timestamp
type (required): Must be "orderBook"

Data Stream Message

{
    "stream": "orderBook",
    "data": {
        "1": {
            "blockInfo": {
                "height": 41049956,
                "timestamp": 1765341076
            },
            "bids": [
                {
                    "tick": 114345,
                    "price": "92404255624567294332470",
                    "baseSize": "742737110457416",
                    "quoteSize": "68632069816559542183",
                    "baseSum": "742737110457416",
                    "quoteSum": "68632069816559542183"
                },
                {
                    "tick": 114344,
                    "price": "92395016122954998832587",
                    "baseSize": "629782107840742",
                    "quoteSize": "58188728007893940876",
                    "baseSum": "1372519218298158",
                    "quoteSum": "126820797824453483059"
                },
                {
                    "tick": 114343,
                    "price": "92385777545200478784708",
                    "baseSize": "629813596158946",
                    "quoteSize": "58185818789683115882",
                    "baseSum": "2002332814457104",
                    "quoteSum": "185006616614136598941"
                },
                {
                    "tick": 114342,
                    "price": "92376539891211357648943",
                    "baseSize": "629845086051526",
                    "quoteSize": "58182909716922241797",
                    "baseSum": "2632177900508630",
                    "quoteSum": "243189526331058840738"
                },
                {
                    "tick": 114341,
                    "price": "92367303160895268122131",
                    "baseSize": "629876577518562",
                    "quoteSize": "58180000789604165201",
                    "baseSum": "3262054478027192",
                    "quoteSum": "301369527120663005939"
                },
                {
                    "tick": 114340,
                    "price": "92358067354159852136918",
                    "baseSize": "629908070560131",
                    "quoteSize": "58177092007721455556",
                    "baseSum": "3891962548587323",
                    "quoteSum": "359546619128384461495"
                },
                {
                    "tick": 114339,
                    "price": "92348832470912760860832",
                    "baseSize": "629939565176313",
                    "quoteSize": "58174183371266959429",
                    "baseSum": "4521902113763636",
                    "quoteSum": "417720802499651420924"
                },
                {
                    "tick": 114338,
                    "price": "92339598511061654695362",
                    "baseSize": "629971061367187",
                    "quoteSize": "58171274880233431003",
                    "baseSum": "5151873175130823",
                    "quoteSum": "475892077379884851927"
                },
                {
                    "tick": 114337,
                    "price": "92330365474514203275034",
                    "baseSize": "630002559132831",
                    "quoteSize": "58168366534613532121",
                    "baseSum": "5781875734263654",
                    "quoteSum": "534060443914498384048"
                },
                {
                    "tick": 114336,
                    "price": "92321133361178085466488",
                    "baseSize": "630034058473324",
                    "quoteSize": "58165458334400016974",
                    "baseSum": "6411909792736978",
                    "quoteSum": "592225902248898401022"
                }
            ],
            "asks": [
                {
                    "tick": 114347,
                    "price": "92422737399734764037010",
                    "baseSize": "516732646566569",
                    "quoteSize": "47757845699491962224",
                    "baseSum": "516732646566569",
                    "quoteSum": "47757845699491962224"
                },
                {
                    "tick": 114348,
                    "price": "92431979673474737513413",
                    "baseSize": "629687652331602",
                    "quoteSize": "58203276280952663469",
                    "baseSum": "1146420298898171",
                    "quoteSum": "105961121980444625693"
                },
                {
                    "tick": 114349,
                    "price": "92441222871442084987165",
                    "baseSize": "629656170310117",
                    "quoteSize": "58206186372016220323",
                    "baseSum": "1776076469208288",
                    "quoteSum": "164167308352460846016"
                },
                {
                    "tick": 114350,
                    "price": "92450466993729229195663",
                    "baseSize": "629624689862616",
                    "quoteSize": "58209096608580782918",
                    "baseSum": "2405701159070904",
                    "quoteSum": "222376404961041628934"
                },
                {
                    "tick": 114351,
                    "price": "92459712040428602118583",
                    "baseSize": "629593210989018",
                    "quoteSize": "58212006990653412866",
                    "baseSum": "3035294370059922",
                    "quoteSum": "280588411951695041800"
                },
                {
                    "tick": 114352,
                    "price": "92468958011632644978795",
                    "baseSize": "629561733689247",
                    "quoteSize": "58214917518241634034",
                    "baseSum": "3664856103749169",
                    "quoteSum": "338803329469936675834"
                },
                {
                    "tick": 114353,
                    "price": "92478204907433808243293",
                    "baseSize": "483095232526072022",
                    "quoteSize": "44675779903350470364521",
                    "baseSum": "486760088629821191",
                    "quoteSum": "45014583232820407040355"
                },
                {
                    "tick": 114354,
                    "price": "92487452727924551624117",
                    "baseSize": "629498783810866",
                    "quoteSize": "58220739009993466206",
                    "baseSum": "487389587413632057",
                    "quoteSum": "45072803971830400506561"
                },
                {
                    "tick": 114355,
                    "price": "92496701473197344079279",
                    "baseSize": "629467311232099",
                    "quoteSize": "58223649974171662665",
                    "baseSum": "488019054724864156",
                    "quoteSum": "45131027621804572169226"
                },
                {
                    "tick": 114356,
                    "price": "92505951143344663813687",
                    "baseSize": "629435840226843",
                    "quoteSize": "58226561083894436352",
                    "baseSum": "488648490565090999",
                    "quoteSum": "45189254182888466605578"
                }
            ]
        },
        "10": {
            "blockInfo": {
                "height": 41049956,
                "timestamp": 1765341076
            },
            "bids": [
                {
                    "tick": 114330,
                    "price": "92265760063430564008054",
                    "baseSize": "551926552769675027",
                    "quoteSize": "50923922890483183852376",
                    "baseSum": "551926552769675027",
                    "quoteSum": "50923922890483183852376"
                },
                {
                    "tick": 114320,
                    "price": "92173545029243296272047",
                    "baseSize": "6303964206070403",
                    "quoteSize": "581058728610968257055",
                    "baseSum": "558230516975745430",
                    "quoteSum": "51504981619094152109431"
                },
                {
                    "tick": 114310,
                    "price": "92081422159392227716771",
                    "baseSize": "6307116818632902",
                    "quoteSize": "580768286385139112338",
                    "baseSum": "564537633794378332",
                    "quoteSum": "52085749905479291221769"
                },
                {
                    "tick": 114300,
                    "price": "91989391361763692258388",
                    "baseSize": "6310271007816974",
                    "quoteSize": "580477989336866616661",
                    "baseSum": "570847904802195306",
                    "quoteSum": "52666227894816157838430"
                },
                {
                    "tick": 114290,
                    "price": "91897452544336086836887",
                    "baseSize": "6313426774411090",
                    "quoteSize": "580187837393583996456",
                    "baseSum": "577161331576606396",
                    "quoteSum": "53246415732209741834886"
                },
                {
                    "tick": 114280,
                    "price": "91805605615179779403674",
                    "baseSize": "6316584119204110",
                    "quoteSize": "579897830482760262073",
                    "baseSum": "583477915695810506",
                    "quoteSum": "53826313562692502096959"
                },
                {
                    "tick": 114270,
                    "price": "91713850482457017001122",
                    "baseSize": "6319743042985293",
                    "quoteSize": "579607968531901091140",
                    "baseSum": "589797658738795799",
                    "quoteSum": "54405921531224403188099"
                },
                {
                    "tick": 114260,
                    "price": "91622187054421833933997",
                    "baseSize": "6322903546544290",
                    "quoteSize": "579318251468548148952",
                    "baseSum": "596120562285340089",
                    "quoteSum": "54985239782692951337051"
                },
                {
                    "tick": 114250,
                    "price": "91530615239419960032655",
                    "baseSize": "6326065630671149",
                    "quoteSize": "579028679220279511185",
                    "baseSum": "602446627916011238",
                    "quoteSum": "55564268461913230848236"
                },
                {
                    "tick": 114240,
                    "price": "91439134945888729007933",
                    "baseSize": "6329229296156312",
                    "quoteSize": "578739251714709352454",
                    "baseSum": "608775857212167550",
                    "quoteSum": "56143007713627940200690"
                }
            ],
            "asks": [
                {
                    "tick": 114350,
                    "price": "92450466993729229195663",
                    "baseSize": "2405701159070905",
                    "quoteSize": "222408195603460852770",
                    "baseSum": "2405701159070905",
                    "quoteSum": "222408195603460852770"
                },
                {
                    "tick": 114360,
                    "price": "92542959074529103335061",
                    "baseSize": "488760218088342376",
                    "quoteSize": "45231316859807387680103",
                    "baseSum": "491165919247413281",
                    "quoteSum": "45453725055410848532873"
                },
                {
                    "tick": 114370,
                    "price": "92635543689042314700804",
                    "baseSize": "6291369506280569",
                    "quoteSize": "582804434762962226909",
                    "baseSum": "497457288753693850",
                    "quoteSum": "46036529490173810759782"
                },
                {
                    "tick": 114380,
                    "price": "92728220929844227907110",
                    "baseSize": "6288224765012700",
                    "quoteSize": "583095895266615449923",
                    "baseSum": "503745513518706550",
                    "quoteSum": "46619625385440426209705"
                },
                {
                    "tick": 114390,
                    "price": "92820990889602824602835",
                    "baseSize": "6285081595643865",
                    "quoteSize": "583387501529669577070",
                    "baseSum": "510030595114350415",
                    "quoteSum": "47203012886970095786775"
                },
                {
                    "tick": 114400,
                    "price": "92913853661078796130199",
                    "baseSize": "6281939997388349",
                    "quoteSize": "583679253625018773734",
                    "baseSum": "516312535111738764",
                    "quoteSum": "47786692140595114560509"
                },
                {
                    "tick": 114410,
                    "price": "93006809337125636276206",
                    "baseSize": "6278799969460830",
                    "quoteSize": "583971151625593683546",
                    "baseSum": "522591335081199594",
                    "quoteSum": "48370663292220708244055"
                },
                {
                    "tick": 114420,
                    "price": "93099858010689734116866",
                    "baseSize": "6275661511076381",
                    "quoteSize": "584263195604361651214",
                    "baseSum": "528866996592275975",
                    "quoteSum": "48954926487825069895269"
                },
                {
                    "tick": 114430,
                    "price": "93192999774810466954296",
                    "baseSize": "6272524621450465",
                    "quoteSize": "584555385634326294222",
                    "baseSum": "535139521213726440",
                    "quoteSum": "49539481873459396189491"
                },
                {
                    "tick": 114440,
                    "price": "93286234722620293346799",
                    "baseSize": "6269389299798939",
                    "quoteSize": "584847721788527911431",
                    "baseSum": "541408910513525379",
                    "quoteSum": "50124329595247924100922"
                }
            ]
        },
        "100": {
            "blockInfo": {
                "height": 41049956,
                "timestamp": 1765341076
            },
            "bids": [
                {
                    "tick": 114200,
                    "price": "91074127158417919273011",
                    "baseSize": "634124442706498099",
                    "quoteSize": "57752330129312506367305",
                    "baseSum": "634124442706498099",
                    "quoteSum": "57752330129312506367305"
                },
                {
                    "tick": 114100,
                    "price": "90167969533010375525636",
                    "baseSize": "63593696973092379",
                    "quoteSize": "5734114531161287768499",
                    "baseSum": "697718139679590478",
                    "quoteSum": "63486444660473794135804"
                },
                {
                    "tick": 114000,
                    "price": "89270827878084283080996",
                    "baseSize": "63912445728648133",
                    "quoteSize": "5705516941909550512509",
                    "baseSum": "761630585408238611",
                    "quoteSum": "69191961602383344648313"
                },
                {
                    "tick": 113900,
                    "price": "88382612487697272539353",
                    "baseSize": "64232792138908745",
                    "quoteSize": "5677061976615979246474",
                    "baseSum": "825863377547147356",
                    "quoteSum": "74869023578999323894787"
                },
                {
                    "tick": 113800,
                    "price": "87503234548451611036505",
                    "baseSize": "64554744211750359",
                    "quoteSize": "5648748923976090676144",
                    "baseSum": "890418121758897715",
                    "quoteSum": "80517772502975414570931"
                },
                {
                    "tick": 113700,
                    "price": "86632606130613676526457",
                    "baseSize": "64878309995186756",
                    "quoteSize": "5620577076232870724260",
                    "baseSum": "955296431754084471",
                    "quoteSum": "86138349579208285295191"
                },
                {
                    "tick": 113600,
                    "price": "85770640179321790375594",
                    "baseSize": "65203497577570530",
                    "quoteSize": "5592545729159081927599",
                    "baseSum": "1020499929331655001",
                    "quoteSum": "91730895308367367222790"
                },
                {
                    "tick": 113500,
                    "price": "84917250505881529132184",
                    "baseSize": "65530315087795279",
                    "quoteSize": "5564654182039659656790",
                    "baseSum": "1086030244419450280",
                    "quoteSum": "97295549490407026879580"
                },
                {
                    "tick": 113400,
                    "price": "84072351779147645082192",
                    "baseSize": "65858770695498809",
                    "quoteSize": "5536901737654196085735",
                    "baseSum": "1151889015114949089",
                    "quoteSum": "102832451228061222965315"
                },
                {
                    "tick": 113300,
                    "price": "83235859516991733862444",
                    "baseSize": "66188872611267353",
                    "quoteSize": "5509287702259511219310",
                    "baseSum": "1218077887726216442",
                    "quoteSum": "108341738930320734184625"
                }
            ],
            "asks": [
                {
                    "tick": 114400,
                    "price": "92913853661078796130199",
                    "baseSize": "516312535111738766",
                    "quoteSize": "47972587330752703417124",
                    "baseSum": "516312535111738766",
                    "quoteSum": "47972587330752703417124"
                },
                {
                    "tick": 114500,
                    "price": "93847606494119620513813",
                    "baseSize": "62646957153760582",
                    "quoteSize": "5879266983020095213027",
                    "baseSum": "578959492265499348",
                    "quoteSum": "53851854313772798630151"
                },
                {
                    "tick": 114600,
                    "price": "94790743227610771373974",
                    "baseSize": "62334519734030217",
                    "quoteSize": "5908735454324894773770",
                    "baseSum": "641294011999529565",
                    "quoteSum": "59760589768097693403921"
                },
                {
                    "tick": 114700,
                    "price": "95743358166580887684040",
                    "baseSize": "62020422195522762",
                    "quoteSize": "5938043495908498783183",
                    "baseSum": "703314434195052327",
                    "quoteSum": "65698633264006192187104"
                },
                {
                    "tick": 114800,
                    "price": "96705546563792279898093",
                    "baseSize": "61707899182269422",
                    "quoteSize": "5967496117724755141307",
                    "baseSum": "765022333377321749",
                    "quoteSum": "71666129381730947328411"
                },
                {
                    "tick": 114900,
                    "price": "97677404629265333103373",
                    "baseSize": "61383719523456394",
                    "quoteSize": "5995802409541984386172",
                    "baseSum": "826406052900778143",
                    "quoteSum": "77661931791272931714583"
                },
                {
                    "tick": 115000,
                    "price": "98659029539898627206009",
                    "baseSize": "61061197647408249",
                    "quoteSize": "6024238502437238998320",
                    "baseSum": "887467250548186392",
                    "quoteSum": "83686170293710170712903"
                },
                {
                    "tick": 115100,
                    "price": "99650519449185736073925",
                    "baseSize": "60756668841774840",
                    "quoteSize": "6054433610085020702234",
                    "baseSum": "948223919389961232",
                    "quoteSum": "89740603903795191415137"
                },
                {
                    "tick": 115200,
                    "price": "100651973497029677227750",
                    "baseSize": "59483180716908374",
                    "quoteSize": "5987099529037288415526",
                    "baseSum": "1007707100106869606",
                    "quoteSum": "95727703432832479830663"
                },
                {
                    "tick": 115300,
                    "price": "101663491819655993434748",
                    "baseSize": "58864384365578322",
                    "quoteSize": "5984358858419057893535",
                    "baseSum": "1066571484472447928",
                    "quoteSum": "101712062291251537724198"
                }
            ]
        },
        "200": {
            "blockInfo": {
                "height": 41049956,
                "timestamp": 1765341076
            },
            "bids": [
                {
                    "tick": 114027,
                    "price": "89512172715234876662243",
                    "baseSize": "744342721720291569",
                    "quoteSize": "66627734265954749578528",
                    "baseSum": "744342721720291569",
                    "quoteSum": "66627734265954749578528"
                },
                {
                    "tick": 113828,
                    "price": "87748574654253713979118",
                    "baseSize": "127967525780051429",
                    "quoteSize": "11228967989230979551729",
                    "baseSum": "872310247500342998",
                    "quoteSum": "77856702255185729130257"
                },
                {
                    "tick": 113629,
                    "price": "86019723578250686574564",
                    "baseSize": "129247093979854215",
                    "quoteSize": "11117799297439247986300",
                    "baseSum": "1001557341480197213",
                    "quoteSum": "88974501552624977116557"
                },
                {
                    "tick": 113430,
                    "price": "84324934890779595671168",
                    "baseSize": "130539456791164615",
                    "quoteSize": "11007731194592692482577",
                    "baseSum": "1132096798271361828",
                    "quoteSum": "99982232747217669599134"
                },
                {
                    "tick": 113231,
                    "price": "82663537483537010645648",
                    "baseSize": "131844742149393700",
                    "quoteSize": "10898752784673678135780",
                    "baseSum": "1263941540420755528",
                    "quoteSum": "110880985531891347734914"
                },
                {
                    "tick": 113032,
                    "price": "81034873470614475063113",
                    "baseSize": "132545516391680978",
                    "quoteSize": "10740809149897124927385",
                    "baseSum": "1396487056812436506",
                    "quoteSum": "121621794681788472662299"
                },
                {
                    "tick": 112833,
                    "price": "79438297927986562539698",
                    "baseSize": "132858929655142002",
                    "quoteSize": "10554087236338579365429",
                    "baseSum": "1529345986467578508",
                    "quoteSum": "132175881918127052027728"
                },
                {
                    "tick": 112634,
                    "price": "77873178638131624010243",
                    "baseSize": "132776314924152472",
                    "quoteSize": "10339713691001347423840",
                    "baseSum": "1662122301391730980",
                    "quoteSum": "142515595609128399451568"
                },
                {
                    "tick": 112435,
                    "price": "76338895839684100438671",
                    "baseSize": "134080271148036646",
                    "quoteSize": "10235539853326570840658",
                    "baseSum": "1796202572539767626",
                    "quoteSum": "152751135462454970292226"
                }
            ],
            "asks": [
                {
                    "tick": 114425,
                    "price": "93146417250611925183865",
                    "baseSize": "532003650916187677",
                    "quoteSize": "49554234047088108573053",
                    "baseSum": "532003650916187677",
                    "quoteSum": "49554234047088108573053"
                },
                {
                    "tick": 114624,
                    "price": "95018502825765574670058",
                    "baseSize": "124204328419200691",
                    "quoteSize": "11801709330872136329774",
                    "baseSum": "656207979335388368",
                    "quoteSum": "61355943377960244902827"
                },
                {
                    "tick": 114823,
                    "price": "96928214157272996812499",
                    "baseSize": "122963583192003781",
                    "quoteSize": "11918640525180196800986",
                    "baseSum": "779171562527392149",
                    "quoteSum": "73274583903140441703813"
                },
                {
                    "tick": 115022,
                    "price": "98876307459251741911475",
                    "baseSize": "121688230626718655",
                    "quoteSize": "12032082905619768019852",
                    "baseSum": "900859793154110804",
                    "quoteSum": "85306666808760209723665"
                },
                {
                    "tick": 115221,
                    "price": "100863554144445168756571",
                    "baseSize": "119233252242804646",
                    "quoteSize": "12026289593410414764878",
                    "baseSum": "1020093045396915450",
                    "quoteSum": "97332956402170624488543"
                },
                {
                    "tick": 115420,
                    "price": "102890741129689138656109",
                    "baseSize": "116724515384243446",
                    "quoteSize": "12009871895888609743567",
                    "baseSum": "1136817560781158896",
                    "quoteSum": "109342828298059234232110"
                },
                {
                    "tick": 115619,
                    "price": "104958671147518073797084",
                    "baseSize": "115506207256623733",
                    "quoteSize": "12123378022945036168842",
                    "baseSum": "1252323768037782629",
                    "quoteSum": "121466206321004270400952"
                },
                {
                    "tick": 115818,
                    "price": "107068163064033770783505",
                    "baseSize": "114304579226183809",
                    "quoteSize": "12238381327554815155647",
                    "baseSum": "1366628347263966438",
                    "quoteSum": "133704587648559085556599"
                },
                {
                    "tick": 116017,
                    "price": "109220052203162840148564",
                    "baseSize": "113165407821661497",
                    "quoteSize": "12359931749874081088357",
                    "baseSum": "1479793755085627935",
                    "quoteSum": "146064519398433166644956"
                },
                {
                    "tick": 116216,
                    "price": "111415190677431172426332",
                    "baseSize": "112045051048387493",
                    "quoteSize": "12483520727018602022496",
                    "baseSum": "1591838806134015428",
                    "quoteSum": "158548040125451768667452"
                }
            ]
        }
    }
}

Order Book Data Structure:

chainId (top-level): Chain ID of the order book update
instrument (top-level): Instrument address corresponding to the update
expiry (top-level): Expiry timestamp
data: Map of order book entries, keyed by tick ID (string). Each entry contains:
- blockInfo: Block information
  - height: Block height
  - timestamp: Block timestamp
- bids: Buy order list (sorted by price from high to low)
- asks: Sell order list (sorted by price from low to high)
- Each order item contains:
  - tick: Price tick
  - price: Price (string format)
  - baseSize: Base asset quantity
  - quoteSize: Quote asset quantity
  - baseSum: Cumulative base asset quantity
  - quoteSum: Cumulative quote asset quantity

3. Instrument Information Subscription (instrument)

Subscribe to detailed instrument information updates.

{
  "id": 3,
  "method": "SUBSCRIBE",
  "params": {
    "chainId": 143,
    "instrument": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
    "expiry": 4294967295,
    "type": "instrument"
  }
}

Unsubscribe Request

{
  "id": 3,
  "method": "UNSUBSCRIBE",
  "params": {
    "chainId": 143,
    "instrument": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
    "expiry": 4294967295,
    "type": "instrument"
  }
}

Parameter Description

chainId (required): Chain ID
instrument (required): Instrument address (lowercase)
expiry (required): Expiry timestamp
type (required): Must be "instrument"

Data Stream Messages

When subscribing to instrument, you will receive two types of messages:

3.1 Instrument Information (instrument)

Complete instrument information update:

{
  "stream": "instrument",
  "chainId": 143,
  "instrument": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
  "expiry": 4294967295,
  "data": {
    "instrumentAddr": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
    "handler": "0x...",
    "symbol": "ETH/USD",
    "market": {
      "info": {
        "addr": "0x...",
        "type": "perp",
        "beacon": "0x..."
      },
      "config": {
        "dailyInterestRate": 1000,
        "feederSource": [
          {
            "baseSymbol": "ETH",
            "quoteSymbol": "USD",
            "ftype": 1,
            "aggregator0": "0x...",
            "heartBeat0": 3600,
            "aggregator1": "0x...",
            "heartBeat1": 3600
          }
        ]
      },
      "feeder": {
        "ftype": 1,
        "scaler0": "1.0",
        "aggregator0": "0x...",
        "heartBeat0": 3600,
        "scaler1": "1.0",
        "aggregator1": "0x...",
        "heartBeat1": 3600
      }
    },
    "condition": 1,
    "setting": {
      "initialMarginRatio": 1000,
      "maintenanceMarginRatio": 500,
      "quoteParam": {
        "minMarginAmount": "1000000000000000000",
        "tradingFeeRatio": 30,
        "protocolFeeRatio": 10,
        "qtype": 1,
        "tip": "0"
      }
    },
    "spotPrice": "2000.00",
    "amms": [
      {
        "expiry": 4294967295,
        "timestamp": 1699000000,
        "status": 1,
        "tick": 1000,
        "sqrtPX96": "1234567890123456789012345",
        "liquidity": "1000000000000000000",
        "totalLiquidity": "1000000000000000000",
        "totalShort": "500000000000000000",
        "openInterests": "1000000000000000000",
        "totalLong": "500000000000000000",
        "involvedFund": "2000000000000000000",
        "feeIndex": "1000000000000000000",
        "protocolFee": "100000000000000000",
        "longSocialLossIndex": "0",
        "shortSocialLossIndex": "0",
        "longFundingIndex": "1000000000000000000",
        "shortFundingIndex": "1000000000000000000",
        "insuranceFund": "1000000000000000000",
        "settlementPrice": "2000.00",
        "instrumentAddr": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
        "markPrice": "2000.50",
        "blockInfo": {
          "height": 12345678,
          "timestamp": 1699000000
        },
        "fairPrice": "2000.30"
      }
    ],
    "base": {
      "symbol": "ETH",
      "address": "0x...",
      "decimals": 18,
      "name": "Ethereum"
    },
    "quote": {
      "symbol": "USD",
      "address": "0x...",
      "decimals": 18,
      "name": "USD Coin"
    },
    "blockInfo": {
      "height": 12345678,
      "timestamp": 1699000000
    },
    "placePaused": false,
    "fundingHour": 24,
    "disableOrderRebate": false,
    "instrumentType": 1,
    "marketType": "perp",
    "minTradeValue": "100000000000000000",
    "minOrderValue": "100000000000000000",
    "minRangeValue": "100000000000000000",
    "displayBase": {
      "symbol": "ETH",
      "address": "0x...",
      "decimals": 18,
      "name": "Ethereum"
    },
    "displayQuote": {
      "symbol": "USD",
      "address": "0x...",
      "decimals": 18,
      "name": "USD Coin"
    },
    "minTickDelta": 1
  }
}

Instrument Information Data Structure

instrumentAddr: Instrument address
symbol: Trading pair symbol
market: Market information
- info: Market basic information (address, type, beacon)
- config: Market configuration (daily interest rate, feeder sources)
- feeder: Market feeder information (aggregators, heartbeats)
condition: Instrument condition status
setting: Instrument settings
- initialMarginRatio: Initial margin ratio
- maintenanceMarginRatio: Maintenance margin ratio
- quoteParam: Quote parameters (min margin amount, fee ratios, etc.)
spotPrice: Spot price
amms: Array of AMM states, containing:
- expiry: Expiry timestamp
- timestamp: Timestamp
- status: AMM status
- tick: Current tick
- sqrtPX96: Square root price in X96 format
- liquidity: Current liquidity
- totalLiquidity: Total liquidity
- totalShort: Total short positions
- openInterests: Open interest
- totalLong: Total long positions
- involvedFund: Involved fund amount
- feeIndex: Fee index
- protocolFee: Protocol fee
- longSocialLossIndex: Long social loss index
- shortSocialLossIndex: Short social loss index
- longFundingIndex: Long funding index
- shortFundingIndex: Short funding index
- insuranceFund: Insurance fund amount
- settlementPrice: Settlement price
- markPrice: Mark price
- fairPrice: Fair price
- blockInfo: Block information (height, timestamp)
base: Base token information (symbol, address, decimals, name)
quote: Quote token information (symbol, address, decimals, name)
blockInfo: Block information (height, timestamp)
placePaused: Whether placing orders is paused
fundingHour: Funding hour
disableOrderRebate: Whether order rebate is disabled
instrumentType: Instrument type
marketType: Market type (e.g., "perp")
minTradeValue: Minimum trade value
minOrderValue: Minimum order value
minRangeValue: Minimum range value
displayBase: Display base token information
displayQuote: Display quote token information
minTickDelta: Minimum tick delta

3.2 Market Pair Info Changed (marketPairInfoChanged)

Market pair information update (prices, volumes, etc.):

{
  "stream": "marketPairInfoChanged",
  "chainId": 143,
  "instrument": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
  "expiry": 4294967295,
  "data": {
    "instrumentAddr": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
    "expiry": 4294967295,
    "symbol": "ETH/USD",
    "fullSymbol": "ETH/USD-PERP",
    "baseToken": {
      "symbol": "ETH",
      "address": "0x...",
      "decimals": 18,
      "price": 2000.0,
      "image": "https://..."
    },
    "quoteToken": {
      "symbol": "USD",
      "address": "0x...",
      "decimals": 18,
      "price": 1.0,
      "image": "https://..."
    },
    "markPrice": "2000.50",
    "fairPrice": "2000.30",
    "spotPrice": "2000.00",
    "fairPriceChange24h": "2.5",
    "baseVolume24h": "1000.5",
    "quoteVolume24h": "2000000.0",
    "volume24hUsd": "2000000.0",
    "openInterests": "1000000000000000000",
    "openInterestsUsd": "2000000.0",
    "tvl": "2000000000000000000",
    "tvlUsd": "4000000.0",
    "longOi": "500000000000000000",
    "shortOi": "500000000000000000",
    "periods1hFunding": {
      "long": "0.0001",
      "short": "-0.0001"
    },
    "last1hFunding": {
      "long": "0.0001",
      "short": "-0.0001"
    },
    "fundingRatePerHour": "0.0001",
    "poolFee24h": "1000.0",
    "maxLeverage": 100,
    "updateTime": 1699000000,
    "marketType": "perp",
    "condition": 1,
    "ammStatus": 1
  }
}

Note: This message is sent when market pair information (prices, volumes, etc.) changes. It provides a lightweight update focused on market data, while the instrument message provides complete instrument state information.

Market Pair Info Changed Data Structure

instrumentAddr: Instrument address
expiry: Expiry timestamp
symbol: Trading pair symbol (e.g., "ETH/USD")
fullSymbol: Full trading pair symbol with expiry (e.g., "ETH/USD-PERP")
baseToken: Base token information
- symbol: Token symbol
- address: Token address
- decimals: Token decimals
- price: Current token price
- image: Token image URL
quoteToken: Quote token information
- symbol: Token symbol
- address: Token address
- decimals: Token decimals
- price: Current token price
- image: Token image URL
markPrice: Mark price (string)
fairPrice: Fair price (string)
spotPrice: Spot price (string)
fairPriceChange24h: Fair price change percentage over 24 hours (string)
baseVolume24h: Base token volume over 24 hours (string)
quoteVolume24h: Quote token volume over 24 hours (string)
volume24hUsd: Total volume in USD over 24 hours (string)
openInterests: Open interest amount (string)
openInterestsUsd: Open interest in USD (string)
tvl: Total value locked (string)
tvlUsd: Total value locked in USD (string)
longOi: Long open interest (string)
shortOi: Short open interest (string)
periods1hFunding: 1-hour periods funding rate
- long: Long funding rate
- short: Short funding rate
last1hFunding: Last 1-hour funding rate
- long: Long funding rate
- short: Short funding rate
fundingRatePerHour: Funding rate per hour (string)
poolFee24h: Pool fee over 24 hours (string)
maxLeverage: Maximum leverage (number)
updateTime: Last update timestamp (number)
marketType: Market type (e.g., "perp")
condition: Instrument condition status (number)
ammStatus: AMM status (number)

4. Portfolio Subscription (portfolio)

Subscribe to portfolio update notifications for a specific user address.

{
  "id": 4,
  "method": "SUBSCRIBE",
  "params": {
    "chainId": 143,
    "userAddress": "0xafdf17420b93db5b5badfd74cb503da099d18071",
    "type": "portfolio"
  }
}

Unsubscribe Request

{
  "id": 4,
  "method": "UNSUBSCRIBE",
  "params": {
    "chainId": 143,
    "userAddress": "0xafdf17420b93db5b5badfd74cb503da099d18071",
    "type": "portfolio"
  }
}

Parameter Description

chainId (required): Chain ID
userAddress (required): User address (lowercase)
type (required): Must be "portfolio"

Data Stream Message

{
  "stream": "portfolio",
  "data": {
    "type": "order" | "range" | "position" | "gate",
    "userAddress": "0xafdf17420b93db5b5badfd74cb503da099d18071",
    "instrument": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
    "expiry": "4294967295"
  }
}

Portfolio Update Description:

This message is pushed when a user's orders, range orders, positions, or gates change
The type field indicates the change type:
- order: Order change
- range: Range order change
- position: Position change
- gate: Gate change
After receiving this message, clients should call the corresponding REST API to fetch the latest portfolio details

5. Common Subscription (common)

Subscribe to chain-level common events, including block number changes and market list changes.

{
  "id": 5,
  "method": "SUBSCRIBE",
  "params": {
    "chainId": 143,
    "type": "common"
  }
}

Unsubscribe Request

{
  "id": 5,
  "method": "UNSUBSCRIBE",
  "params": {
    "chainId": 143,
    "type": "common"
  }
}

Parameter Description

chainId (required): Chain ID
type (required): Must be "common"

Data Stream Message Types

5.1 Block Number Changed (blockNumChanged)

{
  "stream": "blockNumChanged",
  "data": {
    "chainId": 143,
    "blockNum": 12345678,
    "blockTime": 1699000000
  }
}

5.2 Market List Changed (marketListChanged)

{
  "stream": "marketListChanged",
  "data": [
    {
      "instrumentAddr": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
      "expiry": 4294967295,
      "symbol": "ETH/USD",
      "baseToken": {
        "symbol": "ETH",
        "address": "0x...",
        "decimals": 18,
        "price": 2000.0,
        "image": "https://..."
      },
      "quoteToken": {
        "symbol": "USD",
        "address": "0x...",
        "decimals": 18,
        "price": 1.0,
        "image": "https://..."
      },
      "fairPrice": "2000.30",
      "markPrice": "2000.50",
      "fairPriceChange24h": "2.5",
      "baseVolume24h": "1000.5",
      "openInterests": "1000000000000000000",
      "tvl": "2000000000000000000",
      "volume24hUsd": "2000000.0",
      "tvlUsd": "4000000.0",
      "openInterestsUsd": "2000000.0",
      "longOi": "500000000000000000",
      "shortOi": "500000000000000000",
      "periods1hFunding": {
        "long": "0.0001",
        "short": "-0.0001"
      },
      "last1hFunding": {
        "long": "0.0001",
        "short": "-0.0001"
      },
      "fundingRatePerHour": "0.0001",
      "quoteVolume24h": "2000000.0",
      "fullSymbol": "ETH/USD",
      "updateTime": 1699000000,
      "marketType": "perp",
      "poolFee24h": "1000.0",
      "maxLeverage": 100,
      "spotPrice": "2000.00",
      "condition": 1,
      "ammStatus": 1
    }
  ]
}

Note: To receive individual market pair information updates (marketPairInfoChanged), you need to subscribe to the instrument type instead. The common subscription only provides blockNumChanged and marketListChanged messages.

6. Instrument Basic Info Subscription (instrumentBasicInfo)

Subscribe to basic instrument information updates.

{
  "id": 6,
  "method": "SUBSCRIBE",
  "params": {
    "chainId": 143,
    "instrument": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
    "expiry": 4294967295,
    "type": "instrumentBasicInfo"
  }
}

Unsubscribe Request

{
  "id": 6,
  "method": "UNSUBSCRIBE",
  "params": {
    "chainId": 143,
    "instrument": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
    "expiry": 4294967295,
    "type": "instrumentBasicInfo"
  }
}

Parameter Description

chainId (required): Chain ID
instrument (required): Instrument address (lowercase)
expiry (required): Expiry timestamp
type (required): Must be "instrumentBasicInfo"

Note: This subscription type is defined in the code, but the current implementation returns immediately without sending data stream messages.

Error Handling

Connection Errors

If the connection fails, the WebSocket will trigger an error event. Clients should implement a reconnection mechanism.

Common connection issues:

Connection Timeout:
- Check your network connection and firewall settings
- Verify the WebSocket URL is correct
Unexpected Server Response:
- Ensure you're using the correct protocol (wss:// for secure connections)
- Verify the server endpoint is accessible

Message Format Errors

If the message format is incorrect, the server may not respond or return an error. Please ensure:

JSON format is correct
All required parameters are provided
Parameter types are correct (e.g., chainId is a number, instrument is a string)

Best Practices

Connection Management
- Implement automatic reconnection mechanism
- Use heartbeat to keep connection alive
- Handle network interruptions
Subscription Management
- Subscribe to required data streams immediately after connection is established
- Unsubscribe from all subscriptions before disconnecting
- Use unique request IDs to track subscription status
Data Processing
- Validate received data format
- Handle data update frequency to avoid excessive UI refreshes
- For portfolio subscriptions, actively fetch the latest data after receiving notifications
Performance Optimization
- Only subscribe to needed data streams
- Unsubscribe from unnecessary subscriptions promptly
- Use data caching appropriately

Example Code

Browser JavaScript Example

// Browser WebSocket automatically sets Origin and User-Agent headers
const ws = new WebSocket('wss://api.monday.trade/v4/public/ws');

ws.onopen = () => {
  console.log('WebSocket connected');
  
  // Subscribe to K-line data
  ws.send(JSON.stringify({
    id: 1,
    method: 'SUBSCRIBE',
    params: {
      chainId: 143,
      instrument: '0x73ada1ea346cc3908f41cf67a040f0acd7808be0',
      expiry: 4294967295,
      interval: '1m',
      type: 'kline'
    }
  }));
  
  // Subscribe to order book
  ws.send(JSON.stringify({
    id: 2,
    method: 'SUBSCRIBE',
    params: {
      chainId: 143,
      instrument: '0x73ada1ea346cc3908f41cf67a040f0acd7808be0',
      expiry: 4294967295,
      type: 'orderBook'
    }
  }));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  
  if (message.id) {
    // Subscription response
    console.log('Subscription response:', message);
  } else if (message.stream) {
    // Data stream message
    console.log('Stream update:', message.stream, message.data);
    
    switch (message.stream) {
      case 'kline':
        // Handle K-line data
        break;
      case 'orderBook':
        // Handle order book data
        break;
      case 'instrument':
        // Handle instrument information
        break;
      case 'portfolio':
        // Handle portfolio notifications
        break;
      case 'blockNumChanged':
        // Handle block number changes
        break;
      case 'marketListChanged':
        // Handle market list changes
        break;
    }
  } else if (event.data === 'pong') {
    // Heartbeat response
    console.log('Heartbeat received');
  }
};

// Send heartbeat
setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send('ping');
  }
}, 30000);

Node.js TypeScript Example

import WebSocket from 'ws';

// Extract origin from URL for Origin header
const url = 'wss://api.monday.trade/v4/public/ws';
const urlObj = new URL(url);
const origin = `${urlObj.protocol}//${urlObj.host}`;

const ws = new WebSocket(url, {
  headers: {
    'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
    'Origin': origin,
  }
});

ws.on('open', () => {
  console.log('WebSocket connected');
  
  // Subscribe to K-line data
  ws.send(JSON.stringify({
    id: 1,
    method: 'SUBSCRIBE',
    params: {
      chainId: 143,
      instrument: '0x73ada1ea346cc3908f41cf67a040f0acd7808be0',
      expiry: 4294967295,
      interval: '1m',
      type: 'kline'
    }
  }));
  
  // Subscribe to order book
  ws.send(JSON.stringify({
    id: 2,
    method: 'SUBSCRIBE',
    params: {
      chainId: 143,
      instrument: '0x73ada1ea346cc3908f41cf67a040f0acd7808be0',
      expiry: 4294967295,
      type: 'orderBook'
    }
  }));
});

ws.on('message', (data: Buffer) => {
  const message = JSON.parse(data.toString());
  
  if (message.id) {
    // Subscription response
    console.log('Subscription response:', message);
  } else if (message.stream) {
    // Data stream message
    console.log('Stream update:', message.stream, message.data);
    
    switch (message.stream) {
      case 'kline':
        // Handle K-line data
        break;
      case 'orderBook':
        // Handle order book data
        break;
      case 'instrument':
        // Handle instrument information
        break;
      case 'portfolio':
        // Handle portfolio notifications
        break;
      case 'blockNumChanged':
        // Handle block number changes
        break;
      case 'marketListChanged':
        // Handle market list changes
        break;
    }
  } else if (data.toString() === 'pong') {
    // Heartbeat response
    console.log('Heartbeat received');
  }
});

// Send heartbeat
setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send('ping');
  }
}, 30000);

Changelog

Support for K-line, order book, instrument information, portfolio, and common event subscriptions
Heartbeat mechanism support
Multi-chain subscription support

PreviousError Codes

Last updated 25 days ago

hashtagOverview

hashtagConnection URL

hashtagHeartbeat Mechanism

hashtagMessage Format

hashtagRequest Message Format

hashtagResponse Message Format

hashtagSubscribe/Unsubscribe Response

hashtagData Stream Message Format

hashtagSubscription Types

hashtag1. K-line Data Subscription (kline)

hashtagSubscribe Request

hashtagUnsubscribe Request

hashtagParameter Description

hashtagData Stream Message

hashtag2. Order Book Subscription (orderBook)

hashtagSubscribe Request

hashtagUnsubscribe Request

hashtagParameter Description

hashtagData Stream Message

hashtag3. Instrument Information Subscription (instrument)

hashtagSubscribe Request

hashtagUnsubscribe Request

hashtagParameter Description

hashtagData Stream Messages

hashtag4. Portfolio Subscription (portfolio)

hashtagSubscribe Request

hashtagUnsubscribe Request

hashtagParameter Description

hashtagData Stream Message

hashtag5. Common Subscription (common)

hashtagSubscribe Request

hashtagUnsubscribe Request

hashtagParameter Description

hashtagData Stream Message Types

hashtag6. Instrument Basic Info Subscription (instrumentBasicInfo)

hashtagSubscribe Request

hashtagUnsubscribe Request

hashtagParameter Description

hashtagError Handling

hashtagConnection Errors

hashtagMessage Format Errors

hashtagBest Practices

hashtagExample Code

hashtagBrowser JavaScript Example

hashtagNode.js TypeScript Example

hashtagChangelog

Overview

Connection URL

Heartbeat Mechanism

Message Format

Request Message Format

Response Message Format

Subscribe/Unsubscribe Response

Data Stream Message Format

Subscription Types

1. K-line Data Subscription (kline)

Subscribe Request

Unsubscribe Request

Parameter Description

Data Stream Message

2. Order Book Subscription (orderBook)

Subscribe Request

Unsubscribe Request

Parameter Description

Data Stream Message

3. Instrument Information Subscription (instrument)

Subscribe Request

Unsubscribe Request

Parameter Description

Data Stream Messages

4. Portfolio Subscription (portfolio)

Subscribe Request

Unsubscribe Request

Parameter Description

Data Stream Message

5. Common Subscription (common)

Subscribe Request

Unsubscribe Request

Parameter Description

Data Stream Message Types

6. Instrument Basic Info Subscription (instrumentBasicInfo)

Subscribe Request

Unsubscribe Request

Parameter Description

Error Handling

Connection Errors

Message Format Errors

Best Practices

Example Code

Browser JavaScript Example

Node.js TypeScript Example

Changelog