Orderbook API

Overview

This documentation details the API endpoints for interacting with Polarity's Orderbook, catering to node implementations and developers seeking market data for Flashnet or broader applications.

API Endpoints

Market Data

Get the Orderbook

• GET /api/ordernook

• Response Schema:

  {
    "timestamp": 1708716254990,
    "bids": [
      ["52024.84", "10"]
    ],
    "asks": [
      ["52026.12", "100"]
    ]
  }

Get Recent Trades

• GET /api/trades

• Request Schema:

  {
    "limit": 50 // Default 50, max 1000
  }

• Response Schema:

  {
    "timestamp": 1708716254990,
    "trades": [
      {
        "id": 28457,
        "price": "52026.12",
        "qty": "0.832",
        "quoteQty": "3607.136",
        "isBuyerMaker": true
      }
    ]
  }

Get Order Info

• GET /api/trades/{orderId}

• Response Schema:

  {
    "timestamp": 1708716254990,
    "id": 28457,
    "price": "52026.12",
    "qty": "0.832",
    "quoteQty": "3607.136",
    "isBuyerMaker": true
  }

Candlestick Data

• GET /api/candles

• Request Schema:

  {
    "interval": "15m",
    "startTime": "1708316254990",  // milliseconds
    "endTime": "1708716254990",    // milliseconds
    "limit": 500
  }

• Response Schema:

  [
    [
      1708316254990,        // Start time in milliseconds
      "52026.12",           // Open
      "52132.36",           // High
      "51973.19",           // Low
      "52057.76",           // Close
      "15702316.87",        // Volume in quote asset
      1708317154990,        // Close time in milliseconds
      "302.1234",           // Volume
      1208                  // # of trades
    ]
  ]

Trading Endpoints

Create an Order

• POST /api/order/create

• Request Schema:

  {
    "asset": "string",
    "amount": "number",
    "price": "number",
    "orderType": "string",  // "LIMIT" or "MARKET"
    "side": "enum"          // buy or sell
  }

• Response Schema:

  {
    "orderId": "string",
    "status": "string",     // "CREATED" or "REJECTED"
    "timePlaced": "number"
  }

Cancel Order

• DELETE /api/order/cancel

• Request Schema:

  {
    "orderId": "string"
  }

• Response Schema:

  {
    "success": true
  }

Cancel All Open Orders

• DELETE /api/order/cancelAll

• Response Schema:

  {
    "success": true
  }

WebSocket Communication

WebSocket communication enables real-time data exchange between clients and the server, eliminating the need for polling the server for updates. This section describes how to adapt REST API functionalities to WebSocket communications for creating orders, matching orders, and exchanging invoices within the Flashnet Orderbook.

Establishing a WebSocket Connection

Clients must establish a WebSocket connection to the orderbook server using the WebSocket URL. Once connected, clients can subscribe to specific channels for updates and perform trading actions in real-time.

Websockets are P2P, the orderbook simply helps connect the peers together and monitors the information going through. Settlement happens trustlessly on the Lightning Network.

WebSocket Channels and Actions

Creating an Order

Order creation can happen via REST or WS

• Action: createOrder

• Request Schema:

  {
    "action": "createOrder",
    "data": {
      "asset": "string",
      "amount": "number",
      "price": "number",
      "orderType": "string",  // "LIMIT" or "MARKET"
      "side": "enum"          // buy or sell
    }
  }

• Response Schema:

  {
    "orderId": "string",
    "status": "string",   // "CREATED" or "REJECTED"
    "timePlaced": "number"
  }

Notification of Order Match

Upon a successful order match, both the maker and taker are notified through their WebSocket connection.

• Notification Schema:

  {
    "orderIds": [
      "makerOrderId": "string",
      "takerOrderId": "string",
    ],
    "matchStatus": "string",       // "MATCHED"
    "takerInvoice": "string",      // Empty on first notification
    "collateralInvoice": "string", // Empty on first notification
    "collateralHash": "string",
    "makerInvoice": "string"       // Empty on first notification
  }

Generating Invoices

Once notified of a match, the taker is expected to generate invoices immediately.

• Action: generateInvoices

• Request Schema:

  {
    "action": "generateTakerInvoices",
    "data": {
      "orderId": "string",
      "takerInvoice": "string",
      "collateralInvoice": "string"
    }
  }

• Response Schema:

  {
    "status": "string", // "INVOICES_GENERATED"
    "tradeInvoice": "string",
    "collateralInvoice": "string"
  }

Once notified of taker invoices, the maker is expected to generate invoices immediately.

• Action: generateInvoices

• Request Schema:

  {
    "action": "generateTakerInvoices",
    "data": {
      "orderId": "string",
      "makerInvoice": "string",
    }
  }

• Response Schema:

  {
    "status": "string", // "INVOICES_GENERATED"
    "tradeInvoice": "string",
    "collateralInvoice": "string"
    "makerInvoice": "string"
  }

The peers then pay each others invoices on the Lightning Network.

Completing the Trade

Upon settlement completion on the Lightning Network, the Taker is expected to settle on the LN (which instantly settle the maker invoices since they have the same hash) and signal the preimage of his invoices to the WS connection with the maker.

• Action: completeTrade

• Request Schema:

  {
    "action": "completeTrade",
    "data": {
      "orderId": "string",
      "preImage": "string"
    }
  }

• Response Schema:

  {
    "status": "string" // "TRADE_COMPLETED", "PREIMAGE_INVALID"
  }

The order is now considered closed and settled. This all happens in less than a second if actors are all working properly. If a pre-image is invalid, the orderbook releases the hash to the collateral invoice to the Taker, which he can use to claim the collateral punishing the Taker for cheating. There are some time based reasons for the collateral being released as well.

Websocket market data

The websockets can also be used to receive live updates on the orderbook, recent trades, or chart data.