MAX Exchange WebSocket API

# PROVENANCE
# generated: '2026-08-25'
# method: generated
# source: https://maicoin.github.io/max-websocket-docs/ (README.md, authentication.md,
#   public_channels.md, public_ticker.md, public_trade.md, public_orderbook.md, public_kline.md,
#   public_market_status.md, public_mwallet_pool_quota.md, private_channels.md,
#   private_channels_mwallet.md, changelog.md)
# NOT PROVIDER-PUBLISHED. MaiCoin ships no AsyncAPI document. This document was generated by
# API Evangelist from MaiCoin's own published WebSocket channel documentation. Every channel,
# event name, field abbreviation and enum below is transcribed from that documentation; nothing
# is invented. Field names use MaiCoin's abbreviated wire keys, with the documented meaning in
# each description.
asyncapi: 3.0.0
info:
  title: MAX Exchange WebSocket API
  version: '25.25.0'
  description: >-
    Real-time streaming for MAX Exchange (MaiCoin). One WebSocket endpoint carries both public
    market-data channels and, after authentication, private account channels. Field names are
    abbreviated on the wire to reduce payload size; the alias table is published in the docs.
    Clients must send a ping frame at least every 130 seconds or the server closes the connection.
  contact:
    name: MAX Exchange
    email: max@maicoin.com
    url: https://maicoin.github.io/max-websocket-docs/
  externalDocs:
    url: https://maicoin.github.io/max-websocket-docs/
servers:
  production:
    host: max-stream.maicoin.com
    pathname: /ws
    protocol: wss
    description: >-
      Production WebSocket endpoint. Rate limited to 20 request messages per second, 200 per minute,
      600 connections per hour per IP and 1440 connections per day per IP. A 429 triggers an
      automatic IP ban and carries a Retry-After header holding a Unix timestamp in seconds.
channels:
  book:
    address: book
    title: Order book
    description: >-
      Order book snapshot on subscribe, then incremental updates. Optional depth parameter accepts
      1, 5, 10, 20 or 50 (default 50). Carries first-id, last-id and version fields for verifying
      update continuity (added 2024-10-22).
    messages:
      bookEvent:
        $ref: '#/components/messages/BookEvent'
  trade:
    address: trade
    title: Public trades
    messages:
      tradeEvent:
        $ref: '#/components/messages/PublicTradeEvent'
  ticker:
    address: ticker
    title: Ticker
    messages:
      tickerEvent:
        $ref: '#/components/messages/TickerEvent'
  kline:
    address: kline
    title: Candlesticks
    description: 'Resolution accepts 1m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 12h or 1d. Default 1m.'
    messages:
      klineEvent:
        $ref: '#/components/messages/KlineEvent'
  market_status:
    address: market_status
    title: Market status
    description: Platform-wide market status, precision and minimum-amount rules.
    messages:
      marketStatusEvent:
        $ref: '#/components/messages/MarketStatusEvent'
  pool_quota:
    address: pool_quota
    title: M-wallet pool quota
    description: Total available loan quota for a currency in the m-wallet lending pool.
    messages:
      poolQuotaEvent:
        $ref: '#/components/messages/PoolQuotaEvent'
  user:
    address: user
    title: Private account channel
    description: >-
      Requires authentication. Which events arrive is selected by the `filters` array supplied on
      the auth command; the default is [order, trade, account].
    messages:
      orderEvent:
        $ref: '#/components/messages/OrderEvent'
      tradeEvent:
        $ref: '#/components/messages/PrivateTradeEvent'
operations:
  subscribePublic:
    action: send
    channel:
      $ref: '#/channels/book'
    title: Subscribe to public channels
    description: 'Send {"action": "sub", "subscriptions": [...], "id": "..."}. Server replies with a `subscribed` event echoing the subscription list.'
  unsubscribePublic:
    action: send
    channel:
      $ref: '#/channels/book'
    title: Unsubscribe from public channels
    description: 'Send {"action": "unsub", "subscription": [...], "id": "..."}. Server replies with an `unsubscribed` event.'
  authenticate:
    action: send
    channel:
      $ref: '#/channels/user'
    title: Authenticate for private channels
    description: >-
      Send {"action": "auth", "apiKey": "...", "nonce": <ms>, "signature": "...", "filters": [...],
      "id": "..."}. The signature is the hex HMAC-SHA256 of the NONCE STRING alone, keyed by the API
      secret — this differs from the REST signing scheme. Server replies with an `authenticated`
      event. Nonce must be within 30 seconds of server time and may be used only once.
  receiveOrders:
    action: receive
    channel:
      $ref: '#/channels/user'
    title: Receive order snapshots and updates
components:
  messages:
    BookEvent:
      name: bookEvent
      payload:
        type: object
        properties:
          c: {type: string, description: 'channel — "book"'}
          e: {type: string, enum: [snapshot, update], description: event}
          M: {type: string, description: market}
          a: {type: array, description: 'asks, array of [price, volume] string pairs'}
          b: {type: array, description: 'bids, array of [price, volume] string pairs'}
          T: {type: integer, description: 'at — Unix timestamp in milliseconds'}
          fi: {type: integer, description: first update id in event}
          li: {type: integer, description: last update id in event}
          v: {type: integer, description: event version}
    PublicTradeEvent:
      name: publicTradeEvent
      payload:
        type: object
        properties:
          c: {type: string, description: 'channel — "trade"'}
          e: {type: string, enum: [snapshot, update]}
          M: {type: string, description: market}
          t:
            type: array
            description: trades
            items:
              type: object
              properties:
                p: {type: string, description: price}
                v: {type: string, description: volume}
                T: {type: integer, description: timestamp in milliseconds}
                tr: {type: string, description: trend}
          T: {type: integer}
    TickerEvent:
      name: tickerEvent
      payload:
        type: object
        properties:
          c: {type: string, description: 'channel — "ticker"'}
          e: {type: string, enum: [snapshot, update]}
          M: {type: string, description: market}
          tk:
            type: object
            description: ticker
            properties:
              M: {type: string, description: market}
              O: {type: string, description: open}
              H: {type: string, description: high}
              L: {type: string, description: low}
              C: {type: string, description: close}
              v: {type: string, description: volume}
              V: {type: string, description: volume in BTC}
          T: {type: integer}
    KlineEvent:
      name: klineEvent
      payload:
        type: object
        properties:
          c: {type: string, description: 'channel — "kline"'}
          e: {type: string, enum: [snapshot, update]}
          M: {type: string, description: market}
          k:
            type: object
            description: kline
            properties:
              ST: {type: integer, description: start time in milliseconds}
              ET: {type: integer, description: end time in milliseconds}
              M: {type: string, description: market}
              R: {type: string, description: resolution}
              O: {type: string, description: open}
              H: {type: string, description: high}
              L: {type: string, description: low}
              C: {type: string, description: close}
              v: {type: string, description: volume}
              ti: {type: integer, description: last trade id}
              x: {type: boolean, description: closed}
          T: {type: integer}
    MarketStatusEvent:
      name: marketStatusEvent
      payload:
        type: object
        properties:
          c: {type: string, description: 'channel — "market_status"'}
          e: {type: string, enum: [snapshot, update]}
          ms:
            type: array
            description: market status
            items:
              type: object
              properties:
                M: {type: string, description: market}
                st: {type: string, enum: [active, suspended, cancel-only], description: status}
                bu: {type: string, description: base unit}
                bup: {type: integer, description: base unit precision}
                mba: {type: number, description: minimal base amount}
                qu: {type: string, description: quote unit}
                qup: {type: integer, description: quote unit precision}
                mqa: {type: number, description: minimal quote amount}
                mws: {type: boolean, description: m-wallet supported}
          T: {type: integer}
    PoolQuotaEvent:
      name: poolQuotaEvent
      payload:
        type: object
        properties:
          c: {type: string, description: 'channel — "pool_quota"'}
          e: {type: string, enum: [snapshot, update]}
          qta:
            type: object
            properties:
              cu: {type: string, description: currency}
              av: {type: string, description: available quota}
              TU: {type: integer, description: updated at}
          T: {type: integer}
    OrderEvent:
      name: orderEvent
      description: 'Private. Events: order_snapshot, order_update, mwallet_order_snapshot, mwallet_order_update.'
      payload:
        type: object
        properties:
          c: {type: string, description: 'channel — "user"'}
          e:
            type: string
            enum: [order_snapshot, order_update, mwallet_order_snapshot, mwallet_order_update]
          o:
            type: array
            description: orders
            items:
              type: object
              properties:
                i: {type: integer, description: id}
                sd: {type: string, enum: [bid, ask], description: side}
                ot: {type: string, enum: [limit, market, stop_limit, stop_market, post_only, ioc_limit], description: order type}
                p: {type: string, description: price}
                sp: {type: string, description: stop price, nullable: true}
                ap: {type: string, description: average price}
                v: {type: string, description: volume}
                rv: {type: string, description: remaining volume}
                ev: {type: string, description: executed volume}
                S: {type: string, description: state}
                M: {type: string, description: market}
                tc: {type: integer, description: trade count}
                T: {type: integer, description: created at in milliseconds}
                TU: {type: integer, description: updated at in milliseconds}
                gi: {type: integer, description: group order id, nullable: true}
                ci: {type: string, description: client specific order id, nullable: true}
          T: {type: integer}
    PrivateTradeEvent:
      name: privateTradeEvent
      description: 'Private. Events: trade_snapshot, trade_update, mwallet_trade_snapshot, mwallet_trade_update. The trade snapshot returns the last 100 trades.'
      payload:
        type: object
        properties:
          c: {type: string, description: 'channel — "user"'}
          e:
            type: string
            enum: [trade_snapshot, trade_update, mwallet_trade_snapshot, mwallet_trade_update]
          t:
            type: array
            description: trades
            items:
              type: object
              properties:
                i: {type: integer, description: id}
                M: {type: string, description: market}
                sd: {type: string, enum: [bid, ask], description: side}
                p: {type: string, description: price}
                v: {type: string, description: volume}
                f: {type: string, description: fee}
                fc: {type: string, description: fee currency}
                fd: {type: boolean, description: fee discounted}
                fn: {type: string, description: funds, the quote balance used in this trade}
                T: {type: integer, description: created at in milliseconds}
                TU: {type: integer, description: updated at in milliseconds}
                m: {type: boolean, description: maker}
                oi: {type: integer, description: order id}
          T: {type: integer}
    ErrorEvent:
      name: errorEvent
      payload:
        type: object
        properties:
          e: {type: string, description: 'event — "error"'}
          E:
            type: array
            description: 'errors, each formatted "E-<code>: <message>"'
            items: {type: string}
          i: {type: string, description: client id}
          T: {type: integer}