Introduction

Welcome to the LightCX API. You can use our API to access all the funtionality of our platform.

All communication with LCX takes place asynchronously over websocket. Everyone may subscribe to public websocket feeds. Authenticated users may subscribe to private feeds, and also submit commands to LCX.

All data sent and recived in a simple JSON format. Unless otherwise specified, all feeds will continue to stream data until you disconnect your client, or send an unsubscribe request.

All accounts are rate limited to one request per second, with the ability to burst up to 5 requests quickly.

Authentication

1) Get your access token from the authentication server:

Please see the shell code example

curl -n https://auth.light.cx/auth/realms/lightcx/protocol/openid-connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
--data "grant_type=password&client_id=direct&username=user1&password=abc1234"

2) Submit your access token to start an API session

curl -k https://api.light.cx/api/auth/direct \
-H "Content-Type: application/json" \
--data '{"access_token": "abc1234597890"}'

1. Get an access token from the authentication system

Light.CX maintains a segregated authentication system. You will first have to authenticate yourself to the auth server using your e-mail and password. Post an x-www-form-urlencoded message containing your username and password. The auth server will then give you an Access Token.

POST https://auth.light.cx/auth/realms/lightcx/protocol/openid-connect/token

Post Data Parameters

Parameter	Required	Description
username	Yes	The e-mail address associated with this account
password	Yes	The password for this account
grant_type	Yes	Must be "password"
client_id	Yes	Must be "direct"

2. Submit your Access Token to the api server

Submit your authentiation code, over websocket, to the Light.CX api. The API server will confirm the validity of your code, create a session for you, and then issue you a session token.

POST https://api.light.cx/api/auth/direct

Submit your session token to the websocket API. You'll then be connected to all the private data streams for your account.

'{"op":"auth", "token":"1234567890ABCDEF"}'

4. Include the session token in any private API requests

Be sure to include your current session token in any private API requests, in the "token" field of the JSON.

Public Feeds

All public data feeds are accessed by sending a subscribe or unsubscribe request. Specifics of data feeds are detailed in the sections below

Query Parameters

Parameter	Required	Description
op	yes	Operation requested
feed	yes	The feed requested
product	no	The product requeted

Time (Public Feed)

{
  "op" : "sub",
  "feed" : "time"
}

wscat -c wss://api.light.cx/api/ws \
-x '{"op": "sub", "feed": "time"}'

Response

Subscribes to the official time at our Exchange servers.

{"op": "sub", "feed": "time"}

Websocket Unsubscribe Request

{"op": "unsub", "feed": "time"}

products (Public Feed)

{
  "op" : "sub",
  "feed" : "products"
}

The product feed returns three types of messages:

A new derivative product is started

{
  "event":"product_add",
  "data": {
    "base":"usdt",
    "expire_text":"2020-01-23T03:00",
    "expire":1579748400,
    "indexprice":858072,
    "payout":10000,
    "period":"min5",
    "scale":100,
    "step_size":25,
    "strike":858500,
    "product":"btcusd_min5_2020-01-23T03:00_858500",
    "underlying":"btcusd"
  }
}

A product has stopped trading and has been settled

{
  "event":"product_settle",
  "data": {
    "expire":1579748400,
    "final_price":858536,
    "payout":10000,
    "period":"min5",
    "strike":858500,
    "product":"btcusd_min5_2020-01-23T03:00_858500",
    "time":1579748400
  }
}

A product has been deleted from the exchange

{
  "event":"product_delete",
  "data": {
    "period":"min5",
    "product":"btcusd_min5_2020-01-23T03:00_858500",
    "underlying":"btcusd"
  }
}

This endpoint subscribes or unsubscribes to streaming product information

{"op": "sub", "feed": "products"}

Websocket Unsubscribe Request

{"op": "unsub", "feed": "products"}

The product feed will transmit three kinds of messages. Please see explanation below and examples to the right.

Event	Explanation
product_add	A new product has been added to the board
product_settle	The product has been settled
product_del	A product has been deleted from the board

product response message fields

Field	Type	Description
base	string	The underlying pair for this derivative
expire_text	string	ISO text string of the expiration time
expire	int	UTC timestamp of derivative expiration
final_price	int	Official settlement price
indexprice	int	Official index price when derivative was first offered
payout	int	Derivative payout
period	string	Derivaitve lifespan. i.e. "min5" or "day3"
scale	int	Demonimator for units.
strike	int	Strike price
product	string	Official derivative product
time	int	Time of official settlement
underlying	string	The underlying pair for this derivative

Price Index (Public Feed)

{
  "op" : "sub",
  "feed" : "price_idx",
  "product": "btcusd"
}

This API subscription will return the following:

{
  "event":"price",
  "data": {
    "time":1579754956,
    "product":"btcusd",
    "price":857345}
}

This endpoint subscribes or unsubscribes to our official price index. Currently, the price index is updated once every six seconds.

{"op": "sub", "feed": "price_idx", "product": "btcusd"}

Websocket Unsubscribe Request

{"op": "unsub", "feed": "price_idx", "product": "btcusd"}

Price History (Public)

{
  "op": "get_idx_history",
  "product": "btcusd"
}

This API call will return the following:

This endpoint fetches the last 100 index price points

Websocket Single Request

{"op": "get_idx_history", "product": "btcusd"}

Tob of Book (Public Feed)

{
  "op":"sub",
  "feed":"tob"
}

The response

{
  "event":"tob",
  "data": {
    "t":1579754956,
    "s":"btcusd_min5_2020-01-23T14:15_830500",
    "b":{
      "q":20,
      "p":8020
    },
    "a":{
      "q":20,
      "p":8119
    }
  }
}

The Tob Of Book is streamed for all currently trading derivative products.

{"op": "sub", "feed": "tob"}

Websocket Unsubscribe Request

{"op": "unsub", "feed": "tob"}

Full Orderbook (Public Feed)

{
  "op":"sub",
  "feed":"orderbook",
  "product":"btcusd_min5_2020-01-23T03:00_858500",
}

The response is the full book, 5 levels deep

{
  "event":"book_depth",
  "data":{
    "t":1579754956,
    "s":"btcusd_min5_2020-01-23T14:15_830500",
    "b": [
        {"q":20,"p":8593},
        {"q":10,"p":8543},
        {"q":5,"p":8493},
        {"q":3,"p":8443},
        {"q":3,"p":8393}
      ],
    "a": [
      {"q":20,"p":8793},
      {"q":10,"p":8843},
      {"q":5,"p":8893},
      {"q":3,"p":8993}
    ]
  }
}

This endpoint allows you to subscribe to the full orderbook, with live level updates. Each message is a full aggregated orderbook, up to 5 levels deep. Remember that you need to devide the price by the product scale (from the products fee). i.e. with a product scale of 100, 8793 becomes $87.93

{"op": "sub", "feed": "orderbook", "product":"btcusd_min5_2020-01-23T03:00_858500",}

Websocket Unsubscribe Request

{"op": "unsub", "feed": "orderbook", "product":"btcusd_min5_2020-01-23T03:00_858500",}

Orderbook response message fields

Field	Type	Description
p	int	Price level
q	int	Number of contracts available at this level
product	string	Official derivative product
time	int	Time of official settlement

Private Feeds

Light.CX operates over an asynchronous websocket connect. Once you authentiate to the websocket, additional streams of relevant account data will automaticaly be sent to you. The detail of those streams are in the sub-sections below.

As all the information is streamed automaticaly, there are only two necessary actions for you to trade:

Submit order
Cancel order

Submitting orders

{
  "op":"order",
  "token":"11111111-2222-3333-4444-555555555555",
  "ticket":{
    "product": "btcusd_min5_2020-01-24T11:10_887500",
    "price": 2000,
    "size": 1,
    "side": "buy",
    "type": "limit"
  }
}

Orders are submitted by sending a ticket over the websocket.

We have self matching prevention
All orders are immeidately collateralized.
You may not offer any kind of order exeeding your funds available

Order Ticket Fields

Field	Type	Description
token	string	Your Authentication token
product	string	The product you are trading
price	int	The price of your bid or offer in CENTS
size	int	The number of contracts for this order
side	string	buy or sell
type	string	market or limit

Order types

Light.CX has both market and limit orders. The logic for each type is as follows:

Market: Attempt to fill your request at the best possible price. You will get filled quickly, but may have significant price slippage.
Limit:
- Attempt to fill your order Up to, but not worse than your limit price
- Any unfilled quantity is then placed in the orderbook waiting for another party to match

Canceling Orders

{
  "op":"order_cancel",
  "token":"11111111-2222-3333-4444-555555555555",
  "order_id":"809d147838734d848e64cd6741c34a72"
}

To cancel an order, simply send an order_cancel instruction along with your auth token and order_id.

Balance

Incomming messages only

{
  "event":"balance",
  "data":{
    "t":1579754956,
    "usdt":{
      "balance": 12345,
      "hold": 9876
    }
}

After you have authenticated, a balance message will be sent upon any change in your fund or held funds.

When you submit a limit order, we place a hold on funds required if your limit order is match. When you cancel the limit order, we release the funds.

Order Updates

Incomming messages only

{
  "event":"order",
  "data":{
    "type":"limit",
    "product":"btcusd_min5_2020-01-24T11:10_887500",
    "strike":887500,
    "status":"new",
    "side":"buy",
    "qty_remain":1,
    "qty_order":1,
    "qty_fill":0,
    "price":2000,
    "period":"min5",
    "orig_time":1579864046023,
    "order_id":"809d147838734d848e64cd6741c34a72",
    "expire_text":"2020-01-24T11:10",
    "expire":1579864200
  }
}

Whenever there is a change to the status of any order you have submitted, the system will send the full order, with an updated status field

Order Message Fields

Field	Description
expire	UTC timestamp when this derivative expires
expire_text	ISO text of expiration time
order_id	Unique order ID
orig_time	timestamp when order was submitted
period	time cycle for this derivative
price	Price ths order was offered at
qty_fill	How much of this order has been filled
qty_order	The original quantity ordered
qty_remain	Remaining, unfilled quantity
side	Buy or Sell
status	Current order status
strike	Strike price for this order
product	Derivative product
type	Limit or Market order

Possible Order Status

Status	Description
new	The order has been accepted into the orderbook
partial	The order has been partially filled
filled	The order has been completely filled
canceled	The order has been deleted from the orderbook
rejected	There was a problem with the order and it has been rejected

Contracts

{
  "contract_id": "11111111-2222-3333-4444-555555555555",
  "exec_time": 1579747400,
  "expire": 1579748400,
  "order_id":  "11111111-2222-3333-4444-555555555555",
  "payin": 75900,
  "payout": 1200,
  "price": 6325,
  "quantity": 12,
  "side": "buy",
  "strike": 858500,
  "product": "btcusd_min5_2020-01-23T03:00_858500",
  "underlying": "btcusd"
}

When your order is matched, a contract is created. Contracts will automatically settle when the derivative expires.

When you first authenticate to the private websocket, you will receive a list of all currently open contract. The websocket will then stream any new contract updates to you.

Contract Message Fields

Field	Description
contract_id	Unique contract ID
exec_time	Time this contract was entered
expire	UTC timestamp when this derivative expires
order_id	Unique order ID that was matched into this contract
payin	Amount your account paid in as collateral
payout	Amouth to be awarded if contract settles in your favor
price	Price ths contract was set at
quantity	Number of derivatives in this contract
side	Buy or Sell
strike	Strike price for this derivative
product	Derivative product
underlying	The underlying prodcut for this derivative

Errors

The Light.cx API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- Your request is not allowd
418	I'm a teapot.
429	Too Many Requests -- You're sending too many api requests! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Introduction

Authentication

1. Get an access token from the authentication system

Post Data Parameters

2. Submit your Access Token to the api server

3. Subscribe to Private Websocket Feeds

4. Include the session token in any private API requests

Public Feeds

Query Parameters

Time (Public Feed)

Websocket Subscribe Request

Websocket Unsubscribe Request

products (Public Feed)

Websocket Subscribe Request

Websocket Unsubscribe Request

product response message fields

Price Index (Public Feed)

Websocket Subscribe Request

Websocket Unsubscribe Request

Price History (Public)

Websocket Single Request

Tob of Book (Public Feed)

Websocket Subscribe Request

Websocket Unsubscribe Request

Full Orderbook (Public Feed)

Websocket Subscribe Request

Websocket Unsubscribe Request

Orderbook response message fields

Private Feeds

Submitting orders

Order Ticket Fields

Order types

Canceling Orders

Balance

Order Updates

Order Message Fields

Possible Order Status

Contracts

Contract Message Fields

Errors