Kollider Docs (1.0.0)

Download OpenAPI specification:Download

Introduction

This is the official Kollider Api documentation. For code examples please head on over to our Github

Base Rest API Url: https://api.kollider.xyz/v1/
Base WS API Url: wss://api.kollider.xyz/v1/ws/

Authentication

You can authenticate using HMAC symmetric key signing. Every request you make to the api needs to contain the following header parameters.

Header Name Header Value
K-API-KEY Your API key
K-SIGNATURE HMAC Signature
K-TIMESTAMP Timestamp
K-PASSPHRASE Your Passphrase

Rate Limiting

We're currenlty limit the number of request a client can make to 20 requests/second.

Settlement

Kollider's technology allows users to choose between two different settlement types, namely Instant and Delayed. These parameters are passed into every Order or order manipulation action (Move or Cancel). Traders that select the Instant settlement type don't have to deposit funds prior to submitting an order. Instead when they submit an order, they will be prompted to pay a BTC Lighting invoice of exactly the margin requirement. When the payment is detected by the Kollider settlement engine, the order will be unlocked and it will be live in the order book. Conversely, when an order submitted by the trader decreases the size of a position and Instant settlement type is selected the trader will be prompted to generate a BTC Lightning invoice of the amount owed to them by the trading engine.

The Delayed settlement type behaves similar to traditional venues where settlements can be deffered to a later date. This type is recommended for HFT traders.

Products

Currently available products.

Get all tradable products

Responses

Request samples

curl https://api.kollider.xyz/v1/market/products

Response samples

Content type
application/json
{
  • "BTCUSD.PERP": {
    },
  • "LTCUSD.PERP": {
    }
}

Market

Market Data

Gets order book data.

query Parameters
level
integer

There are three levels of orderbook data.

symbol
string

The product symbol.

Responses

Request samples

curl https://api.kollider.xyz/v1/market/orderbook?symbol=BTCUSD.PERP&level=Level2&depth=9

Response samples

Content type
application/json
{
  • "level": 1,
  • "bids": [
    ],
  • "asks": [
    ]
}

Get price ticker for product.

The current trade price of a product.

query Parameters
symbol
string

The product symbol.

Responses

Request samples

curl https://api.kollider.xyz/v1/market/ticker?symbol=BTCUSD.PERP

Response samples

Content type
application/json
{
  • "best_bid": "12958.4",
  • "best_ask": "12972.2",
  • "mid": "12965.3",
  • "last_quantity": 1,
  • "last_price": 12958.4,
  • "last_side": "Ask",
  • "symbol": "BTCUSD.PERP"
}

Get hisotrical index prices.

For complete list of all indicies available, either check our website or query the products endpoint.

query Parameters
limit
integer

Max number of values to be returned.

symbol
string

The index symbol.

start
string

UNIX time since Epoch

end
string

UNIX time since Epoch

interval_size
string

5m, 15m, 1h, 1d

Responses

Request samples

curl https://api.kollider.xyz/v1/market/index_prices?symbol=.BTCUSD&offset_start='1h'

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get hisotrical funding rates.

Allows you to query a specific time range of funding rates.

query Parameters
symbol
string

The index symbol.

start
string

UNIX time since Epoch

end
string

UNIX time since Epoch

interval_size
string

5m, 15m, 1h, 1d

Responses

Request samples

curl https://api.kollider.xyz/v1/market/historical_funding_rate?symbol="BTCUSD.PERP"&start=1679656925000&interval_size=1h'

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Auth

Authenticate user.

Get lnurl auth.

This will return an lnurl auth string.

Responses

Request samples

curl -i -H Authorization: <JWT>  https://api.kollider.xyz/v1/auth/external/lnurl_auth

Response samples

Content type
application/json
{
  • "lnurl_auth": "lnurl1dp68gurn8ghj7ctsdyhxkmmvd35kgetj9eu8j730wccj7ct4w35z7etcw3jhymnpdshkcmjld3hkw6tw8a6xzeead3hkw6twye4nz0fk8y6njcm9v5mrgv3eve3rxdekxcmkxwpsv9jrxdmrxyungcnyxvmnzd3kxy6xvdf5xu6r2dpexgekverz8qenyv35v33r2vpkx5mrxgcv0mv"
}

Validate the signed login request.

query Parameters
sig
string

Signature of challenge.

key
string

The public key of the private key that was used to sign the challenge

k1
string

The challenge that was signed.

Responses

Request samples

curl -i -H Authorization: <JWT>  https://api.kollider.xyz/v1/auth/external/lnurl_auth

Response samples

Content type
application/json
{
  • "status": "ok",
  • "token": "<JWT>",
  • "refresh": "<JWT-Refresh>"
}

Account

Access to user data.

Make a deposit.

Request Body schema: application/json

Make a BTC or LN deposit into your cash account.

type
string
amount
integer

Responses

Request samples

Content type
application/json
Example
{
  • "type": "Ln",
  • "amount": 1000
}

Response samples

Content type
application/json
Example
{
  • "payment_request": "lntb1u1pwz5w78pp5e8w8cr5c30xzws92v36sk45znhjn098rtc4pea6ertnmvu25ng3sdpywd6hyetyvf5hgueqv3jk6meqd9h8vmmfvdjsxqrrssy29mzkzjfq27u67evzu893heqex737dhcapvcuantkztg6pnk77nrm72y7z0rs47wzc09vcnugk2ve6sr2ewvcrtqnh3yttv847qqvqpvv398"
}

Make a withdrawal.

Request Body schema: application/json

Withdrawing funds from your exchange wallet into a wallet that is controlled by you.

One of
type
string
payment_request
string
amount
integer

Responses

Request samples

Content type
application/json
Example
{
  • "type": "Ln",
  • "payment_request": "lnbc500n1p0e5advpp5fa3uned6rykj40763speff24lpyazmdvl87edw93tuaqxkca9k6qdqqcqzpgxqyz5vqsp5a9lvhpjfs3mtseq60taerh3f4g80afwh87229c657eg9y48x2mks9qy9qsqvmgghwspk9zh8h0vptmw7ge2yyn5fx7u6d9k4y6q30ndjlq7qxxr0zyhlxvn40xxgqdc9cp7q3smfwh08gs2vpq0lp7cne3wz2cm9rspp2n0pc",
  • "amount": 100
}

Get account information.

header Parameters
Authorization
required
string

Responses

Request samples

curl -i -H Authorization: <JWT>  https://api.kollider.xyz/v1/user/account

Response samples

Content type
application/json
{
  • "created_at": {
    },
  • "email": "[email protected]",
  • "user_type": 1,
  • "username": "username",
  • "validated_email": false
}

Trading

Access to user data.

Get order fills.

query Parameters
symbol
string

Target symbol.

limit
integer

Max number of values to be returned.

start
string

Unix timestamp from epoch in millis

end
string

Unix timestamp from epoch in millis

Responses

Request samples

curl -i -H Authorization: <JWT> https://api.kollider.xyz/v1/user/fills&start=1622050159434&limit=2

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get historical orders.

query Parameters
symbol
string

The symbol for which to retrieve orders.

start
string

Unix timestamp from epoch in millis

end
string

Unix timestamp from epoch in millis

limit
string

The maximum number of results to return.

Responses

Request samples

curl -i -H Authorization: <JWT>  https://api.kollider.xyz/v1/orders

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Place new order

Request Body schema: application/json

Place a new order.

price
integer
order_type
string
side
string
quantity
integer
symbol
string
leverage
integer
margin_type
string
settlement_type
string

Responses

Request samples

Content type
application/json
{
  • "price": 100,
  • "order_type": "Limit",
  • "side": "Bid",
  • "quantity": 10,
  • "symbol": "BTCUSD.PERP",
  • "leverage": 100,
  • "margin_type": "Isolated",
  • "settlement_type": "Delayed"
}

Cancel an order.

Allows you to cancel an order with best effort.

query Parameters
order_id
integer

The order id of of the order to be cancelled.

symbol
string

The product symbol of the order to be cancelled.

Responses

Request samples

curl -X DELETE -i -H Authorization: <JWT>  https://api.kollider.xyz/v1/trading/orders?symbol='BTCUSD.CFD'&order_id=12122

Get open orders.

This will return all the open orders that are currently live in the orderbook

header Parameters
Authorization
required
string

Responses

Request samples

curl -i -H Authorization: <JWT>  https://api.kollider.xyz/v1/orders/open

Response samples

Content type
application/json
{
  • "ETHUSD.PERP": [
    ],
  • "BTCUSD.PERP": [
    ]
}

Get preflight order info.

Get margin and fee information on a staged order. This should be called before an order is submitted.

header Parameters
Authorization
required
string
Request Body schema: application/json

Get infor on a staged order.

symbol
string
quantity
integer
leverage
integer
side
integer
margin_type
integer
order_type
string
settlement_type
string
price
integer

Responses

Request samples

Content type
application/json
{
  • "symbol": "string",
  • "quantity": 0,
  • "leverage": 0,
  • "side": 0,
  • "margin_type": 0,
  • "order_type": "string",
  • "settlement_type": "string",
  • "price": 0
}

Response samples

Content type
application/json
{
  • "uid": 676,
  • "ext_id": "920783d7-9e71-4a4b-b4f7-8114eeafe247",
  • "margin_required": 1000000,
  • "value": "100000,",
  • "exchange_fee": 7.5,
  • "estimated_liquidation_price": 5001.2121,
  • "rejection_reason": null
}

Change the margin of a postion.

You can change the margin of a position by sending a change margin request.

header Parameters
Authorization
required
string
Request Body schema: application/json

Get infor on a staged order.

symbol
string
amount
number
action
string

Responses

Request samples

Content type
application/json
{
  • "symbol": "string",
  • "amount": 0,
  • "action": "string"
}

Response samples

Content type
application/json
{
  • "uid": 676,
  • "ext_id": "920783d7-9e71-4a4b-b4f7-8114eeafe247",
  • "symbol": "BTCUSD.PERP",
  • "amount": 100000
}

Get open positions.

This will return all positions currently held by user.

header Parameters
Authorization
required
string

Responses

Request samples

curl -i -H Authorization: <JWT>  https://api.kollider.xyz/v1/positions

Response samples

Content type
application/json
{
  • "BTCUSD.PERP": {
    }
}

Websockets

Root URL: wss://api.kollider.xyz/v1/ws/

The websocket api provides real time market data updates. While we provide some rudimentary message filtering, you're responsible to read and filter the messages relevant to your needs, independently. The websocket api is publicly available but we limit the number of connections to 5 connections per IP.

You can also create an authenticated connection in order to increase the details of the messages you receive. For a detailed explanation on how to authenticate, go to the User channel section.

Subscribe

To subscribe to a channel you have to send a subscribe message of the following format.

  {
    "type": "subscribe"
    "symbols": [".BTCUSD"]
    "channels": ["index_values"]
  } 

For some channels you can filter for a specific symbol, i.e. price or trade data. You can unsubscirbe by changing the type field to unsubscribe

  {
    "type": "subscribe"
    "symbols": [".BTCUSD"]
    "channels": ["index_values"]
  } 

Note: If you don't specify the symbols and the channel is able to filter for symbols you will receive messages for all symbols. Furthermore, if you don't subscribe to anything within 10s of connecting, we will disconnect from the client.

Channels

Subscribing to individual channels allows you to filter for specific market events. If you subscribe without specifying a channel you will receive all websocket data.

Index Values

This channel will send index value updates. Index values are used to price the products traded on this platform. You can find out what index prices what product by querying the /products endpoint of the rest api.

channel filter by symbol
index_values true

Example Message:

  {
    "type": "subscribe"
    "symbols": [".BTCUSD". ".ETHUSD"]
    "channels": ["index_values"]
  } 

Orderbook

To get access to orderbook data you have to subscribe to one of the following channels.

channel filter by symbol
orderbook_level1 true
orderbook_level2 true
orderbook_level3 true

If you subscribe to level_1 you will receive only the current best bid and ask level including the sum of all open interest on that level. If you subscribe to level_2 you will receive the best 50 levels including the sum of all open interests on these levels. If you subscribe to level_3 you will receive the entire orderbook in its most granular representation.

Example Message:

  {
    "type": "subscribe"
    "symbols": ["BTCUSD.PERP". "ETHUSD.PERP"]
    "channels": ["orderbook_level2"]
  } 

Example Response Message Orderbook Level 2:

  {
    "t": "OrderbookLevel2Snapshot",
    "sq": 8821,
    "symbol": "BTCUSD.P",
    "asks": [[132132, 54], [132133, 154], [132150, 773] ...],
    "bids": [[132131, 43], [132124, 993], [132113, 4552] ...],
  }
  {
    "t": "OrderbookDeltaLevel2",
    "sq": 8822,
    "symbol": "BTCUSD.P",
    "side": "Bid",
    "level": 544433
    "quantity": 345 
  } 

Example Response Message Orderbook Level 3:

  {
    "t": "OrderbookLevel2Snapshot",
    "sq": 8821,
    "symbol": "BTCUSD.P",
    "asks": [{order_id: 1, quantity: 102, price: 1221, filled: 30}, {order_id: 1, quantity: 42, price: 1221, filled: 0}, ...],
    "bids": [{order_id: 1, quantity: 102, price: 1210, filled: 43}, {order_id: 1, quantity: 882, price: 1210, filled: 0}, ...],
  }
  {
    "t": "OrderbookDeltaLevel2",
    "sq": 8822,
    "symbol": "BTCUSD.P",
    "side": "Bid",
    "level": 1021232
    "orders": [{order_id: 1, quantity: 102, price: 1021232, filled: 30}, {order_id: 1, quantity: 42, price: 1021232, filled: 0}]
  } 

Ticker

The ticker contains the best bid and ask as well as information about the last trade of a product.

channel filter by symbol
ticker true

Example Message:

  {
    "type": "subscribe"
    "symbols": ["BTCUSD.PERP". "ETHUSD.PERP"]
    "channels": ["ticker"]
  } 

Example Response Message Ticker:

  {
    "t": "ticker",
    "symbol": "BTCUSD.PERP",
    "best_bid": 132332.34,
    "best_ask": 132333.50,
    "last_price" 1323334.32,
    "last_volume": 23,
  }

Matches

Whenever a match occures between a maker and a taker a match message will be generated.

channel filter by symbol
matches true

Example Message:

  {
    "type": "subscribe"
    "symbols": ["BTCUSD.PERP". "ETHUSD.PERP"]
    "channels": ["matches"]
  } 

Example Response Message Ticker:

  {
    "t": "match",
    "symbol": "BTCUSD.P",
    "timestamp": 1594584985,
    "taker_uid": 32,
    "maker_uid": 1212,
    "price" 1323365.33,
    "quantity": 222,
  }

User

In order to receive user specific data such as detailed trade and match data you have to authenticate your session. In order to do that you have to generate an API token, which can be done through the rest api. Afterwards you can authenticate by sending following message.

  {
    "type": "authenticate",
    "token": "API_KEY",
    "passphrase": "API_PASSPHRASE",
    "signature": BASE64(HMAC_SHA256(timestamp + "authentication", API_SECRET))
    "timestamp": "TIMESTAMP",
  } 

Once authenticated you will automatically receive all user specific messages, including Matches, Fills, PositionStates and Balance updates.

Actions

Websocket actions allows you to interact with the platform. All actions require you to be authenticated. Check the User channel documentation for details.

Order

This action allows you to submit orders to the exchange.

  {
    "type": "order",
    "price": integer,
    "quantity": integer,
    "symbol": string,
    "leverage": integer,
    "side": string,
    "margin_type": string,
    "order_type": string,
    "settlement_type": string
    "ext_order_id": string
  }

If an order gets rejected because of insufficient funds on you wallet a payment request is automatically generated and send to you via the fund_trade message. As soon as this payment request is settled the order is resubmitted to our trading engine.

Note: If you submit a market order and you don't have any funds on your wallet then this market order becomes a limit order in order to avoid slippage. Similarly, limit orders become PostOnly limit orders for the same reason. Since some time can pass between receiving the payment request and the lightning payment being received by us, we protect your limit order from becoming a market order.

CancelOrder

This action allows you to cancel an order.

  {
    "type": "cancel_order",
    "order_id": integer,
    "symbol": string,
    "settlement_type": string,
  }

ChangeMargin

This action allows you to change the margin of a position. Because positions are grouped by symbol (one position per symbol) we identify the postion by the symbol.

  {
    "type": "change_margin",
    "amount": float,
    "symbol": string,
    "action": string,
  }

OpenOrders

This action allows users to get their currenlty open orders. You have to be authenticated to use this command.

  {
    "type": "fetch_open_orders"
  }

CurrentPositions

This action returns all open positions of a user account. You have to be authenticated to use this command.

  {
    "type": "fetch_positions"
  }

GetTicker

This action returns the current price ticker for a specific symbol.

  {
    "type": "fetch_ticker"
  }

TradableProducts

This action returns all the currently available product to trade.

  {
    "type": "fetch_tradable_products"
  }