Intro

Connection will be terminated if request is invalid or unexpected (with fatal_error notification).
Server will terminate client connection if any protected request received before client is correctly authorized (with fatal_error notification).
If login failed, server will not close client session after sending login result.
Server will not close client connection after receiving logout request.
Connections could be temporary dropped at any moment due transitional network errors (without sending fatal_error message). Clients should be able restart connection and resume active session as needed.
Connections could be terminated at any moment due server errors (with fatal_error notification).
Logged-in client will receive associated session ID. Client could resume session from new connection at any moment using this session ID. Old active connection associated with this session will be logged out. If authorized client disconnected unexpectedly then session could be resumed within 60 seconds expiration period. New login will log out other active session for this user if exists.

Request/response schema also available as protobuf file. It could be used from statically compiled languages with Protobuf JSON encoder/decoder. For example with Go protojson could be used. All client's messages must be valid Request messages and all server's messages will be valid Response messages.

Staging end-point: wss://rollthecoin-staging.blocksettle.com:443 (staging Auth eID)

Testing end-point: wss://rollthecoin-test.blocksettle.com:443 (live Auth eID but does not require verified account)

Common types

Side

Side value	Description
1	Buy/bid
2	Sell/ask

Product type

Product type string	Description
`xbtusd_rf`	1day Cash settled Futures
`ethusd_rf`	1day Cash settled Futures

Order rollover type

Value	Description
0	Trade position. Not a rollover position
1	Normal rollover position
2	Rollover position with liquidation
3	Rollover position with default

Session revert scenario

Value	Description
0	Cancel all session trades
1	Complete trades and do payout

Withdraw status

Value	Description
0	failure - refused or failed
1	accepted for processing
2	waiting for batch to accumulate
3	pushed to blockchain
4	completed
5	cancelled
6	batched

All timestamps are sent as number of seconds since the Unix epoch (for example 1611910018.123).

Price Offering

Customer could submit prices to RFS stream. Most competitive prices will be delivered to customer and used to match market orders.

Prices could be sent to both price books or just to one.

Prices truncated to zero with 1/100th precision. Meaning that sending price 23456.789012 is the same as sending price 23456.78.

Price offerings life-cycle

Price offering for a book is considered as active as long as the following conditions fulfilled:

network connection is alive. All price offerings are pulled if dealing client is disconnected;
price offering was sent less than 15 seconds ago;
there were less than 3 trades matched on the last price offering;
dealing client has enough cash balance to cover IM ( DM ) 3 trades for a volume;
until prices explicitly pulled by dealer.

Public API

Connected/version string

Request server features, currently only version string is available.

Request

{
  "connected": {}
}

Response

{
  "connected": {
    "version": "<back-end version string>"
  }
}

Trading session info

Request

After requesting session_open server will respond with session_open subsequent session_closed notifications.

Name	Type	Description
product_type	string	Product type

{
  "session_open": {
    "product_type": "xbtusd_rf"
  }
}

Response

Name	Type	Description
product_type	string	Product type from the request
time_to_cut_off	number	Time to the next cut-off moment (in seconds)
cut_off_at	number	Timestamp for the next cut-off moment
last_cut_off_price	number	Last cut-off price
session_id	string	current session id
previous_session_id	string	session id of the preceding session

{
  "session_open": {
    "product_type"       : "xbtusd_rf",
    "time_to_cut_off"    : 925.058579,
    "cut_off_at"         : 1613556000,
    "last_cut_off_price" : "42265.03",
    "session_id"         : "12345678",
    "previous_session_id": "12345677",
    "healthy":           : true
  }
}

Trading session closing

Notification when trading day rolling start.

Notification

Name	Type	Description
product_type	string	Product type
session_id	string	current session id
previous_session_id	string	session id of the preceding session

{
  "session_closed": {
    "product_type"       : "xbtusd_rf",
    "session_id"         : "12345678",
    "previous_session_id": "12345677"
  }
}

Trading stats info

After sending the request client connection will be subscribed to the stats update notifications.

Request

Name	Type	Description
product_type	string	Product type

Empty

{
   "trading_stats": {
      "product_type": "xbtusd_rf"
   }
}

Response

Name	Type	Description
daily_volume	number	XBT amount traded since UTC midnight
open_interest	number	XBT amount of open interest in current session

{
   "trading_stats": {
      "daily_volume": "2.12345678",
      "open_interest": "0.12345678"
   }
}

Market data

OHLC stands for Open-High-Low-Close - a set of prices capable to draw a Japanese candle. Provided for the requested intervals.

Request

After requesting session_open server will respond with session_open subsequent session_closed notifications.

Name	Type	Description
product_type	string	Product type
interval	number	0=1min, 1=5min, 2=15min, 3=30min, 4=1h, 5=24h, 6=1w
count	number	number of candles to retrieve, no more than
timestamp_end	number	timestamp of the last interval to get, unixtime in seconds (current time if not set)
reference	string	optional request reference to match the reply

{
  "ohlc": {
    "product_type": "xbtusd_rf",
    "interval": 2,
    "count": 200,
    "timestamp_end": 1705939343,
    "reference": "<ref>"
  }
}

Response

Name	Type	Description
timestamp_start_db	number	timestamp of the first candle
trades	number	number of leverex trades within the candle
volume	number	total volume of all leverex trades within the candle

{
  "ohlc": {
    "product_type": "xbtusd_rf",
    "interval": 2,
    "timestamp_start_db": 1705759343,
    "candles": [{
       "timestamp": 1705759350,
       "open": 12345.67,
       "high": 12357.46,
       "low": 12340.75,
       "close": 12347.65,
       "trades": 123,
       "volume": 0.01234
    }, ...],
    "reference": "<ref>"
  }
}

Getting product fee

Name	Type	Description
product_type	string	Product type

Request

Empty

{
  "product_fee": {
    "product_type": "xbtusd_rf"
  }
}

Response

Name	Type	Description
success	bool	Whether or not request succeed
error_msg	string	Error message why request failed
product_type	string	Product type from the request
fee	string	Product fee per 1 bitcoin
fee_ccy	string	Fee currency
im	string	The cash amount per bitcoin needed to open a position

{
  "product_fee": {
    "success"           : true,
    "error_msg"         : "",
    "product_type"      : "xbtusd_rf",
    "fee"               : "35",
    "dealer_commission" : "-10",
    "fee_ccy"           : "USD",
    "im"                : "2904.39"
  }
}

Notification

Same as response.

Subscribing to price stream

Request

Name	Type	Description
product_type	string	Product type
reference	string	Free text supplied by client and returned in response

{
  "subscribe": {
    "product_type": "xbtusd_rf",
    "reference" : "ref_string"
  }
}

Response

Name	Type	Description
product_type	string	Product type from the request
success	bool	Subscribe result
error_msg	string	Error message if subscribe failed

{
  "subscribe": {
    "product_type": "xbtusd_rf",
    "reference" : "ref_string",
    "success": true,
    "error_msg": ""
  }
}

Notification

Name	Type	Description
product_type	string	Product type from the request
live_cutoff	string	Current value of cut-off price
items	array	List of price items
bid	string	Best Bid price
ask	string	Best Ask price

Best price for each side

{
  "market_data": {
    "product_type": "xbtusd_rf",
    "live_cutoff" : "28512.45",
    "ask"         : "43150",
    "bid"         : "43000"
  }
}

Subscribing to dealer offers

Request

Name	Type	Description
product_type	string	Product type
reference	string	Free text supplied by client and returned in response

{
  "subscribe_dealer_offers": {
    "product_type": "xbtusd_rf",
    "reference" : "reference_str"
  }
}

Response

Name	Type	Description
product_type	string	Product type from the request
success	bool	Subscribe result
reference	string	Free text supplied by client and returned in response
error_msg	string	Error message if subscribe failed

{
  "subscribe_dealer_offers": {
    "product_type": "xbtusd_rf",
    "success": true,
    "reference" : "reference_str",
    "error_msg": ""
  }
}

Notifications

Name	Type	Description
product_type	string	Product type from the request
timestamp	double	Timestamp of submission, TTL is 15s, should be calculated by client based on this field
offers	array	List of offers
side	int	Offer side
price	string	Offer price
volume	string	Max volume of the offer (user can match with less amount)
id	string	unique entry identifier
command	int	0=delete, 1=insert, 2=update

Full depth of dealers' offerings

{
  "dealer_offers" :
  {
     "product_type": "xbtusd_rf",
     "timestamp": 12345678.9,
     "offers": [
       {
          "id": "32ab45ef",
          "command": 0,
          "side": 2
       },
       {
          "id": "abcdef0123",
          "command": 1,
          "side": 1,
          "price" : "28512.45",
          "volume": "1.234567"
       },
       {
          "id": "abcdef2345",
          "command": 1,
          "side": 2,
          "price" : "28523.45",
          "volume": "2.345678"
       }
     ]
  }
}

Unsubscribing from price stream

Request

Name	Type	Description
product_type	string	Product type
reference	string	Free text supplied by client and returned in response

{
  "unsubscribe": {
    "product_type": "xbtusd_rf",
    "reference" : "reference_str"
  }
}

Response

Name	Type	Description
product_type	string	Product type from the request
success	bool	Subscribe result
error_msg	string	Error message if subscribe failed

{
  "unsubscribe": {
    "product_type": "xbtusd_rf",
    "reference" : "reference_str",
    "success": true,
    "error_msg": ""
  }
}

Unsubscribing from dealer offers

Request

Name	Type	Description
product_type	string	Product type
reference	string	Free text supplied by client and returned in response

{
  "unsubscribe_dealer_offers": {
    "product_type": "xbtusd_rf",
    "reference" : "reference_str"
  }
}

Response

Name	Type	Description
product_type	string	Product type from the request
success	bool	Subscribe result
reference	string	Free text supplied by client and returned in response
error_msg	string	Error message if subscribe failed

{
  "unsubscribe_dealer_offers": {
    "product_type": "xbtusd_rf",
    "success": true,
    "reference" : "reference_str",
    "error_msg": ""
  }
}

Authorize

This is the single entry point for logging in with existing user key or Auth eID device.

Request

Name	Type	Description
token	string	A token obtained from login server (independently on previous step)

{
  "authorize": {
    "token": "eyJhbGciOiJFUzI1NiJ9.Q0NERDA3Qz..."
  }
}

Response

Name	Type	Description
success	string	Whether or not session resumed successfully
validity	number	session validity in seconds
grant	string	user account characteristics (basic or upgraded)

{
  "authorize": {
    "success": true,
    "validity": 10,
    "grant": "basic"
  }
}

Disconnect notification

In case of major client or server errors the server will terminate connection with sending fatal_error notification.

Clients should apply exponential backoff with random delay before trying to reconnect.

Notification

Name	Type	Description
error_code	enum	Disconnect reason code
error_msg	string	Disconnect reason description

{
  "fatal_error": {
    "error_code": "ERROR_CODE_SERVER_ERROR",
    "error_msg": "server error"
  }
}

Disconnect reason codes:

Name	Description
`ERROR_CODE_SERVER_ERROR`	Unexpected server error.
`ERROR_CODE_INVALID_REQUEST`	Invalid or unexpected request received.

Session halt notification

Sent when admin requested to halt trading session.

Name	Type	Description
product_type	string	Product type
session_id	string	affected session id

{
  "session_halted": {
    "product_type" : "xbtusd_rf",
    "session_id"   : "12345678"
  }
}

Session revert notification

Sent when admin requested to revert trading session was requested.

Name	Type	Description
product_type	string	Product type
session_id	string	affected session id
revert_scenario	integer	Session revert scenario

{
  "session_reverted": {
    "product_type"    : "xbtusd_rf",
    "session_id"      : "12345678",
    "revert_scenario" : 0
  }
}

Chyrons

Responses can be unsolicited (e.g. when admin adds a new chyron), but always a full list of currently active items. If end_time is non-zero, FE should delete the item when it expires, as BE won't update in this case.

Request

{
  "get_chyrons": {}
}

Response

{
  "chyrons": {
    "items": [{
       "id": <id>,
       "priority": 0,
       "message": "chyron message text",
       "end_time": <unixtime seconds>
    }, ...]
  }
}

Authorized API

Sending market orders

Limits

Minimal amount in order is 0.0001 XBT.

Maximum amount in order is 100 XBT.

If user_expected_price is specified matched price should be better or worse within slippage_tolerance range.

Request

Name	Type	Description
amount	number	Order amount in bitcoins
user_expected_price	number	Expected price to be matched against
slippage_tolerance	number	Acceptable price worsening.
side	enum	Side
product_type	string	Product type
max_amount	bool	If set to `true` amount field is ignored and max amount is calculated server side
ttl	integer	Optional field. Max order TTL in milliseconds. If not set - defaulted to 100 ms. Max value - 3600000 ( 1 hour )

{
  "market_order": {
    "amount"               : "0.001",
    "user_expected_price"  : "19000",
    "slippage_tolerance"   : "20",
    "side"                 : "SIDE_BUY",
    "product_type"         : "xbtusd_rf",
    "max_amount"           : true,
    "ttl"                  : 200
  }
}

Response

Name	Type	Description
success	bool	Whether or not order created successfully
id	string	Market order ID
error_msg	string	Error text if order creation failed
price	number	Actual order price

{
  "market_order": {
    "success"     : true,
    "id"          : "<ORDER_ID>",
    "error_msg"   : "",
    "price"       : "19000"
  }
}

Limit orders

Request

Name	Type	Description
amount	number	Order amount in bitcoins
price	number	Price of execution
side	enum	Side
product_type	string	Product type
reference	string	Optional user-defined string to be returned in reply

{
  "limit_order": {
    "amount"               : "0.001",
    "price"                : "19000",
    "side"                 : "SIDE_BUY",
    "product_type"         : "xbtusd_rf",
    "reference"            : "<ref>"
  }
}

Response

Name	Type	Description
id	string	Order ID
status	number	1:Accepted, 2:Rejected, 3:Updated, 4:Cancelled, 5:Filled
amount	string	remaining quantity of the order
price	string	order price
error_msg	string	Error text for rejection
reference	string	opaque data from the request

{
  "limit_order": {
    "id"          : "<ORDER_ID>",
    "status"      : 1,
    "error_msg"   : "",
    "amount"      : "0.001",
    "price"       : "19000",
    "reference"   : "<ref>"
  }
}

Trade

Unsolicitedly emitted when a trade is performed on existing limit order.

{
  "trade_created": {
    "id"          : "<ORDER_ID>",
    "amount"      : "0.001",
    "price"       : "19001"
  }
}

Order cancel

Request

{
  "cancel_order": {
    "id"          : "<ORDER_ID>",
    "reference"   : "<ref>"
  }
}

Response

Regular limit order response, but with specific status (4=cancelled)

{
  "limit_order": {
     "id"            : "<ORDER_ID>",
     "status"       : 4,
     "reference"    : "<ref>"
  }
}

List orders

Request

Name	Type	Description
product_type	string	Product type

{
  "load_orders": {
    "product_type" : "xbtusd_rf"
  }
}

Response

Name	Type	Description
market_orders	array	List of active market orders
limit_orders	array	List of all limit orders, see `limit_order` response for fields
id	string	Market order ID
status	enum	See below
timestamp	number	Timestamp when order was created
product_type	string	Product type
side	enum	Side
quantity	number	Quantity in bitcoins
price	number	Order price
cut_off_price	number	Cut-off price for complete orders. Could be used for profit/loss calculation
trade_im	number	Trade IM reservation
rollover_type	bool	Type of roll-over (0 for non-rollover trade)

Order status

Value	Description
1	Active order
2	Complete order

Net bitcoin exposure could be calculated from the order list as the sum of quantity for the pending orders grouped by product_type.

{
  "load_orders": {
    "market_orders": [
      {
        "id"            : "<ORDER_ID>",
        "status"        : 1,
        "timestamp"     : 1608181225,
        "product_type"  : "xbtusd_rf",
        "side"          : "SIDE_BUY",
        "quantity"      : "0.001",
        "price"         : "18424.76",
        "cut_off_price" : "18321.09",
        "trade_im"      : "123",
        "rollover_type" : 0,
        "trade_pnl"     : ""
      }, ...
    ],
    "limit_orders": [{
        "id"       : "<ORDER_ID>",
        "status"   : 1,
        "amount"   : "0.01",
        "price"    : "19000",
        "reference": "<ref>"
    }, ...]
  }
}

Order update notifications

When there is blotter update event server broadcasts update notification (if client connected).

Notification

Name	Type	Description
order	object	Order. See List orders for details.

Action	Description
1	New order added
2	Existing order updated

{
  "order_update": {
    "order": {
      "id"              : "<ORDER_ID>",
      "status"          : 1,
      "timestamp"       : 1612275454,
      "product_type"    : "xbtusd_rf",
      "side"            : "SIDE_SELL",
      "quantity"        : "29.04394",
      "price"           : "29043.94",
      "cut_off_price"   : "18321.09",
      "trade_im"        : "123",
      "is_rollover"     : true,
      "session_id"      : "12345678",
      "is_taker"        : true,
      "trade_pnl"       : ""
    },
    "action": 1
  }
}

List balance

Request

Product name is now mandatory, as it now includes max amount for the specific session. Reference is optional

{
  "load_balance": {
     "product_type": "xbtusd_rf",
     "reference": "<ref_id>"
  }
}

Response

Name	Type	Description
balances	array	List of available balances
currency	string	Currency
balance	number	Actual balance
max amount qty	string	Trade quantity in XBT to trade the entire available balance (with respect to the fee)
max amount fee	string	Product fee calculated for a given qty

Initial margin (IM) balance is available here too. For example USDP for xbtusd_rf.

Balance updates are broadcast from the server the same way (without sending request first), but only for updated currencies (so there will be only one field).

{
  "load_balance": {
    "reference": "<ref_id>",
    "balances": [
      {
        "currency": "USD",
        "balance": 0
      },
      {
        "currency": "USDP",
        "balance": 13.8643
      }
    ],
    "max_amount_buy": {
       "fee": "0.0001",
       "qty": "1.2345"
    },
    "max_amount_sell": {...},
    "net_exposure": "0.12345"
  }
}

Getting expected IM change and fee

Request

Name	Type	Description
product_type	string	Product type
qty	string	Amount
side	enum	Side

{
  "estimate_im": {
    "product_type": "xbtusd_rf",
    "qty": "0.001",
    "side": "SIDE_BUY"
  }
}

Response

Name	Type	Description
success	bool	Whether or not order with the requested amount will succeed
error_msg	string	Error message why request failed (when `success` is `false`)
expected_im_reservation	string	Expected IM balance change for such order
fee_amount	string	Expected fee for such amount
product_type	string	Product type

{
  "estimate_im": {
    "success": true,
    "error_msg": "",
    "expected_im_reservation": "0",
    "fee_amount": "0.01",
    "product_type": "xbtusd_rf"
  }
}

Submit Prices

Dealing client could submit his price offering to a stream with submit_prices request.

Request

Name	Type	Description
product_type	string	Product type
prices	array	Array of price offerings

Price offerings

Name	Type	Description
volume	string	Max amount for a trade in base currency
ask	string	Ask price
bid	string	Bid price

{
   "submit_prices" : {
      "product_type" : "xbtusd_rf",
      "prices" : [
         {
            "volume" : "0.1",
            "ask"    : "43100",
            "bid"    : "43050"
         },
         {
            "volume" : "2.5",
            "ask"    : "43150"
         },
         {
            "volume" : "1",
            "bid"    : "43000"
         }
      ]
   }
}

Response

Response provide data on submit price.

Name	Type	Description
result	integer	Enum value SubmitPriceProcessingResult
reject_reason	integer	Enum value SubmitPriceRejectReason
rejected_price_data	object	Rejected price data. Same format as for submit_prices request

{
   "submit_prices" : {
      "product_type"    : "xbtusd_rf",
      "result"          : 2,
      "reject_reason"   : 5,
      "rejected_prices" : [
         {
            "volume" : "0.1",
            "ask"    : "43100",
         },
         {
            "volume" : "2.5",
            "ask"    : "43150",
            "bid"    : "43000"
         },
         {
            "volume" : "1",
            "bid"    : "43000"
         }
      ]
   }
}

Enum SubmitPriceProcessingResult

Value	Description
1	All price offerings accepted. rejected_prices empty.
2	Price offering partially accepted. Rejected offers are in rejected_prices array.
3	All prices rejected. rejected_prices empty.

Enum SubmitPriceRejectReason

Value	Description
1	System maintenance
2	Trading closed on a product
3	Invalid value for a volume used
4	Ill-formed price string
5	Insufficient balance to cover offer

Pull Prices Request

Dealing client could explicitly pull all price offerings with pull_prices request.

Name	Type	Description
product_type	string	Product type

{
   "pull_prices" : {
      "product_type": "xbtusd_rf"
   }
}

Submit withdraw address

User could have up to 3 withdraw addresses.

Request

Name	Type	Description
address	string	Native SegWit address
description	string	Address description. Length limited to 256 symbols

{
   "submit_address" : {
      "address" : "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
      "description" : "Main wallet address"
   }
}

Response

Name	Type	Description
address	string	Native SegWit address
description	string	Address description passed in submit_address request.
success	bool	Result of adding address
error_msg	string	Error text in case submit failed
added_timestamp	int	Timestamp of address submission.

{
   "submit_address" : {
      "address" : "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
      "description" : "Main wallet address",
      "success" : true,
      "error_msg" : "",
      "added_timestamp" : 1615281000
   }
}

Load withdraw addresses

Request

Name	Type	Description
reference	string	Free text supplied by client and returned in response

{
   "load_addresses" : {
      "reference" : "reference_str",
   }
}

Response

Name	Type	Description
addresses	array	List of all withdraw addresses
address	string	Native SegWit address
description	string	Address description. Length limited to 256 symbols
added_timestamp	int	Timestamp of address submission
reference	string	Free text supplied by client and returned in response

{
   "load_addresses" : {
      "reference" : "reference_str",
      "addresses" : [
         {
            "address" : "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
            "description" : "Main wallet address",
            "added_timestamp" : 1615281000
         },

      ]
   }
}

Revoke withdraw address

Request

Name	Type	Description
address	string	Whitelisted address
reference	string	Free text supplied by client and returned in response

{
   "revoke_address" : {
      "address" : "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
      "reference" : "reference_str",
   }
}

Response

Name	Type	Description
address	string	Native SegWit address
success	bool	Result of adding address
reference	string	Free text supplied by client and returned in response
error_msg	string	Error text in case submit failed

{
   "revoke_address" : {
      "address" : "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
      "success" : true,
      "reference" : "reference_str",
      "error_msg" : ""
   }
}

Get dedicated deposit address

Request

Name	Type	Description
reference	string	Free text supplied by client and returned in response

{
   "load_deposit_address" : {
      "reference" : "reference_str"
   }
}

Response

Name	Type	Description
reference	string	Free text supplied by client and returned in response
address	string	Unblinded address controlled by BlockSettle. Empty string if no deposit address was not created for a user
txs	array	list of funding TXs
tx_id	string	TX id of funding transaction
nb_conf	number	number of TX confirmations in blockchain
currency	string	Liquid currency
amount	string	TX amount in currency
unblinded_link	string	URL to track the transaction in the explorer

{
   "load_deposit_address" : {
      "reference" : "reference_str",
      "address" : "tlq1qqggjhwlj0uegut9cpquyatkuuqmq8xzy73ran3a27n5xlyswpdm38havjtdzgne8u3jql5ff4y9j34unw23rg7tc8wq3jwgmu",
      "txs": [{
         "tx_id": "<TX id>",
         "nb_conf": 2,
         "currency": "USDT",
         "amount": "123.45",
         "timestamp": 1641280623.0,
         "recv_address": "tlq1qqggjhwlj0uegut9cpquyatkuuqmq8xzy73ran3a27n5xlyswpdm38havjtdzgne8u3jql5ff4y9j34unw23rg7tc8wq3jwgmu",
         "unconf_address": "tex1qm7kf9k3yfun7geq06y56jzeg67fh9g35p6gnsa",
         "unblinded_link": "<URL>"
      }]
   }
}

New deposit TX event

When new deposit TX is detected, this notification is sent

Name	Type	Description
tx_id	string	TX id of funding transaction
nb_conf	number	number of TX confirmations in blockchain
currency	string	Liquid currency
amount	string	TX amount in currency
recv_address	string	deposit address
unconf_address	string	unconfidential deposit address
timestamp	string	TX timestamp
unblinded_link	string	URL to track the transaction in the explorer

{
   "new_deposit_tx" : {
         "tx_id": "<TX id>",
         "nb_conf": 2,
         "currency": "USDT",
         "amount": "123.45",
         "timestamp": 1641280623.0,
         "recv_address": "tlq1qqggjhwlj0uegut9cpquyatkuuqmq8xzy73ran3a27n5xlyswpdm38havjtdzgne8u3jql5ff4y9j34unw23rg7tc8wq3jwgmu",
         "unconf_address": "tex1qm7kf9k3yfun7geq06y56jzeg67fh9g35p6gnsa",
         "unblinded_link": "<URL>"
   }
}

Update Notification

Sent when nb_conf changes in blockchain (for any monitored transaction). Only nb_conf changes, so other fields can be ignored.

Name	Type	Description
tx_id	string	TX id of funding transaction
nb_conf	number	number of TX confirmations in blockchain
currency	string	Liquid currency
amount	string	TX amount in currency
unblinded_link	string	URL to track the transaction in the explorer

{
   "tx_update" : {
         "tx_id": "<TX id>",
         "nb_conf": 3,
         "currency": "USDT",
         "amount": "123.45",
         "unblinded_link": "<URL>"
   }
}

Withdraw to liquid wallet

If user was logged in with Auth eID then withdraw request must be signed with Auth eID.
If user session was started with API key no Auth eID sign required.

Request

Name	Type	Description
address	string	Whitelisted bitcoin address where bitcoins will be sent
amount	number	amount to withdraw in specified currency
currency	string	liquid withdrawal currency
price	number	Current conversion price (`sell_price` from update notification) - unused
fee_amount	number	Fixed network fee in bitcoins (`network_fee` from update notification) - unused

{
  "withdraw_liquid": {
    "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
    "currency": "USDT",
    "amount": "1000.00"
  }
}

Response

Name	Type	Description
status	number	Withdraw status
id	string	withdrawal id - assigned by server on submission
error_msg	string	Error message if withdraw failed

{
  "withdraw_liquid": {
    "status": <status>,
    "id": "<withdraw id>",
    "recv_address": "tlq1qqggjhwlj0uegut9cpquyatkuuqmq8xzy73ran3a27n5xlyswpdm38havjtdzgne8u3jql5ff4y9j34unw23rg7tc8wq3jwgmu",
    "amount": "123.45",
    "tx": {
         "tx_id": "<TX id>",
         "nb_conf": 0,
         "currency": "USDT",
         "amount": "123.45",
         "timestamp": 1641280623.0,
         "recv_address": "tlq1qqggjhwlj0uegut9cpquyatkuuqmq8xzy73ran3a27n5xlyswpdm38havjtdzgne8u3jql5ff4y9j34unw23rg7tc8wq3jwgmu",
         "unconf_address": "tex1qm7kf9k3yfun7geq06y56jzeg67fh9g35p6gnsa",
         "unblinded_link": "<URL>"
    },
    "success":true,
    "timestamp":123456789.0,
    "error_msg": null
  }
}

Cancel Withdraw

Request

Name	Type	Description
id	string	Withdraw id (previously returned by withdraw_liquid)

{
  "cancel_withdraw": {
    "id": "<WITHDRAW_ID>",
  }
}

Response

Name	Type	Description
status	number	Withdraw status: Cancelled or Failed
id	string	withdrawal id - assigned by server on submission
error_msg	string	Error message if withdraw failed

{
  "withdraw_liquid": {
    "status": 5,
    "id": "<withdraw id>",
    "error_msg": null
  }
}

Delivery obligation

User has obligations to deliver XBT or USD externally. If receiving XBT funds they will arrive to a whitelisted address. When sending XBT, they should go to BlockSettle delivery address (from external wallet).

Notification

Name	Type	Description
currency	string[3]	Currency to deliver (now USD or XBT)
amount	number	amount to deliver (in the currency above)
bs_address	string	BlockSettle address where XBT obligation should be sent

{
  "obligation_request": {
    "currency": "XBT",
    "amount": 0.123,
    "bs_address": "tb1q94skhxv3lqfp02x5wyhajw4ufy7v7defe3szz5"
  }
}

Historical profit & loss

Request

Name	Type	Description
product_type	string	Product type
start_time	number	Unix time in UTC seconds for the start of period
end_time	number	Unix time in UTC seconds for the end of period
reference	string	Free text supplied by client and returned in response

{
  "historical_profit_loss": {
    "product_type": "xbtusd_rf",
    "start_time": 1613556001,
    "end_time": 1613557001,
    "reference": "ref123"
  }
}

Response

Name	Type	Description
product_type	string	Product type
profit_loss	number	profit (positive) or loss (negative) for the requested period

Trade history

Load trading history on account. Maximum count of orders returned is limited to 100 entries per request.

Request

Name	Type	Description
limit	number	[optional] Limit number of results for pagination. Default 100.
offset	number	[optional] Offset results list from start for pagination
start_time	number	[optional] Unix time in UTC seconds for the start of period
end_time	number	[optional] Unix time in UTC seconds for the end of period

{
  "trade_history": {
    "limit"       : 20,
    "offset"      : 0,
    "start_time"  : 1613556001,
    "end_time"    : 1613557001,
    "reference"   : "<some ref>"
  }
}

Response

Name	Type	Description
loaded	bool	Whether or not request succeed
orders	array	List of results
count	number	Total number of results
id	string	Market order ID
status	enum	Order status (see `load_orders` for description)
timestamp	number	Timestamp when order was created
product_type	string	Product type
side	enum	Side
quantity	number	Quantity in bitcoins
price	number	Order price
cut_off_price	number	Cut-off price for complete orders. Could be used for profit/loss calculation.
trade_im	number	Trade IM reservation.
is_rollover	bool	Trade created during trade rolling.
trade_pnl	string	PnL for single trade entry. Only for settled trades
rollover_type	enum	Rollover type

{
  "trade_history": {
    "loaded": true,
    "orders": [
      {
        "id"            : "<ORDER_ID>",
        "status"        : 1,
        "timestamp"     : 1608181225,
        "product_type"  : "xbtusd_rf",
        "side"          : "SIDE_BUY",
        "quantity"      : "0.001",
        "price"         : "18424.76",
        "cut_off_price" : "18321.09",
        "trade_im"      : "123",
        "is_rollover"   : false,
        "trade_pnl"     : "",
        "rollover_type" : 0
      },
      {
        "id"            : "<ORDER_ID>",
        "status"        : 2,
        "timestamp"     : 1608181226,
        "product_type"  : "xbtusd_rf",
        "side"          : "SIDE_BUY",
        "quantity"      : "0.001",
        "price"         : "18424.76",
        "cut_off_price" : "18321.09",
        "trade_im"      : "123",
        "is_rollover"   : true,
        "trade_pnl"     : "-0.10367",
        "rollover_type" : 1
      }
    ],
    "reference"   : "<some ref>"
  }
}

Session history

Loads all sessions for a user and for a given interval

Request

product_type is optional, if not specified, then all products within the interval will be selected.

{
  "session_history": {
    "product_type": "xbtusd_rf",
    "start_time"  : 1613556001.0,
    "end_time"    : 1613557001.0,
    "reference"   : "<some ref>"
  }
}

Response

{
  "session_history": {
    "loaded": true,
    "sessions": [
      {
        "product_type": "xbtusd_rf",
        "rollover_type": 0,
        "has_default": true,
        "has_liquidation": false,
        "id": 24,
        "fee": "123.45",
        "volume": "0.05",
        "open":"29500.0",
        "nb_trades_buy":2,
        "nb_trades_sell":0,
        "time_start" : 1608181225,
        "time_end"   : 1608231225
      },
      {
        "product_type": "xbtusd_rf",
        "rollover_type": 0,
        "has_default": false,
        "has_liquidation": true,
        "id": 23,
        "fee": "23.45",
        "pnl": "1234.56",
        "volume": "0.07",
        "open":"29230.0",
        "close":"29500",
        "nb_trades_buy":0,
        "nb_trades_sell":3,
        "nb_rollover_trades":1,
        "time_start" : 1608101225,
        "time_end"   : 1608181225
      }
    ],
    "reference"   : "<some ref>"
  }
}

Trading days history

Loads sessions statistics grouped by a day.

Request

Mostly limit and offset are used, but filtering by time interval and by product type is supported.

{
  "trading_days_history": {
    "product_type": "xbtusd_rf",
    "offset"      : 0,
    "limit"       : 21,
    "start_time"  : 1613556001.0,
    "end_time"    : 1613557001.0,
    "reference"   : "<some ref>"
  }
}

Response

{
  "trading_days_history": {
    "loaded": true,
    "days": [
      {
        "id": 520220524,
        "rollover_type": 1,
        "has_default": false,
        "has_liquidation": false,
        "fee": "123.45",
        "volume": "0.05",
        "open":"29500.0",
        "nb_trades_buy":2,
        "nb_trades_sell":3,
        "nb_rollover_trades":1,
        "time_start" : 1608181225,
        "time_end"   : 1608231225
      },
      {
        "id": 520220523,
        "rollover_type": 0,
        "has_default": false,
        "has_liquidation": false,
        "fee": "23.45",
        "pnl": "1234.56",
        "volume": "0.07",
        "open":"29230.0",
        "close":"29500",
        "nb_trades_buy":3,
        "nb_trades_sell":1,
        "nb_rollover_trades":0,
        "time_start" : 1608101225,
        "time_end"   : 1608181225
      }
    ],
    "reference"   : "<some ref>"
  }
}

Statements

Pretty much the same as session history, but with additional fields for statements reporting.

Request

{
  "statements": {
    "product_type": "xbtusd_rf",
    "start_time"  : 1613556001.0,
    "end_time"    : 1613557001.0,
    "reference"   : "<some ref>"
  }
}

Response

{
  "statements": {
    "loaded": true,
    "sessions": [
      {
        "product_type": "xbtusd_rf",
        "rollover_type": 0,
        "has_default": true,
        "has_liquidation": false,
        "id": 24,
        "fee": "123.45",
        "volume": "0.05",
        "open":"29500.0",
        "nb_trades_buy":2,
        "nb_trades_sell":0,
        "time_start" : 1608181225,
        "time_end"   : 1608231225
      },
      {
        "product_type": "xbtusd_rf",
        "rollover_type": 0,
        "has_default": false,
        "has_liquidation": true,
        "id": 23,
        "fee": "23.45",
        "pnl": "1234.56",
        "volume": "0.07",
        "open":"29230.0",
        "close":"29500",
        "nb_trades_buy":0,
        "nb_trades_sell":3,
        "nb_rollover_trades":1,
        "time_start" : 1608101225,
        "time_end"   : 1608181225
      }
    ],
    "orders": [{
        "product_type": "xbtusd_rf",
        "quantity": "0.123",
        "price": "34567.89",
        "side": 1,
        "fee": 1.23,
        "timestamp": 1608101225
    }, ...],
    "deposits": [{
        "tx_id": "<TXid>",
        "recv_address": "<address>",
        "nb_conf": 50,
        "outputs": [ {
           "currency": "USDT",
           "amount": "123.450000"
        } ],
        "timestamp": 1641280609.0,
        "unblinded_link": "<URL>"
    }, ...],
    "withdrawals": [{
        "tx_id": "a75cea1ebc67014ba170f1f44fcf2b9220883b6fe27c1c678390c99beae23b1e",
        "recv_address": "tlq1qqggjhwlj0uegut9cpquyatkuuqmq8xzy73ran3a27n5xlyswpdm38havjtdzgne8u3jql5ff4y9j34unw23rg7tc8wq3jwgmu",
        "unconf_address": "tex1qm7kf9k3yfun7geq06y56jzeg67fh9g35p6gnsa",
        "nb_conf": 5,
        "status": <withdraw_status>,
        "currency": "USDT",
        "amount": "200.000000",
        "timestamp_submitted": 1641280609.0,
        "timestamp_finalized": 1641280699.0,
        "unblinded_link": "<URL>"
    }, ...],
    "opening_balance": "123.45",
    "closing_balance": "234.56",
    "opening_exposure": "0.012345",
    "closing_exposure": "0.023456",
    "reference"   : "<some ref>"
  }
}

Withdrawals history

Request

Any or all fields below can be missing or set to 0 - this will mean getting all entries.

{
  "load_withdrawals": {
     "reference": "<reference>",
     "limit": <limit>,
     "offset": <offset>,
     "start_time": 1608101225.0,
     "end_time": 1680101225.0
  }
}

Response

Name	Type	Description
tx_id	string	TX identifier in blockchain
recv_address	string	Long confidential address
unconf_address	string	Short unconfidential address
nb_conf	number	Number of TX confirmations in blockchain
currency	string	Transaction currency
amount	string	Transaction amount
timestamp_submitted	number	Timestamp of submission/ACK
timestamp_finalized	number	Timestamp of settlement or cancellation
unblinded_link	string	URL that allows to track transaction in blockchain explorer

{
  "load_withdrawals": {
    "reference": "<reference>",
    "withdrawals": [
      {
        "tx_id": "a75cea1ebc67014ba170f1f44fcf2b9220883b6fe27c1c678390c99beae23b1e",
        "recv_address": "tlq1qqggjhwlj0uegut9cpquyatkuuqmq8xzy73ran3a27n5xlyswpdm38havjtdzgne8u3jql5ff4y9j34unw23rg7tc8wq3jwgmu",
        "unconf_address": "tex1qm7kf9k3yfun7geq06y56jzeg67fh9g35p6gnsa",
        "nb_conf": 5,
        "status": <withdraw_status>,
        "currency": "USDT",
        "amount": "200.000000",
        "timestamp_submitted": 1641280609.0,
        "timestamp_finalized": 1641280699.0,
        "unblinded_link": "<URL>"
      }
    ]
  }
}

status	Description
0	Error/failure
1	Accepted
2	Pending
3	Broadcasted
4	Completed
5	Cancelled
6	Batched
7	Unknown

Deposits history

Request

Any or all fields below can be missing or set to 0 - this will mean getting all entries.

{
  "load_deposits": {
     "reference": "<reference>",
     "limit": <limit>,
     "offset": <offset>,
     "start_time": 1608101225.0,
     "end_time": 1680101225.0
  }
}

Response

Name	Type	Description
tx_id	string	TX identifier in blockchain
recv_address	string	Long confidential address
unconf_address	string	Short unconfidential address
nb_conf	number	Number of TX confirmations in blockchain
currency	string	Transaction currency
amount	string	Transaction amount
timestamp	number	Transaction timestamp
unblinded_link	string	URL that allows to track transaction in blockchain explorer

{
  "load_deposits": {
    "reference": "<reference>",
    "deposits": [
      {
        "tx_id": "<TXid>",
        "recv_address": "<address>",
        "nb_conf": 5000,
        "outputs": [ {
           "currency": "USDT",
           "amount": "123.450000"
        } ],
        "timestamp": 1641280609.0,
        "unblinded_link": "<URL>"
      }
    ]
  }
}

Fees history

Request

{
  "fees_history": {
    "product_type": "xbtusd_rf",
     "reference": "<reference>",
     "start_time": 1608101225.0,
     "end_time": 1680101225.0
  }
}

Response

{
  "fees_history": {
    "reference": "<reference>",
    "fees": "123.45",
    "product_type": "xbtusd_rf"
  }
}