Protocol Documentation

Table of Contents

lssdrpc.proto

Top

AddCurrencyRequest

FieldTypeLabelDescription
currency string

the currency, like XSN or LTC

lndChannel string

the address:port allowing lssd to connect to this currency lnd, like "localhost:10001" right now, it is assumed that the bot runs on the same network than lssd, so, there is no support for authentication.

certPath string

the path to the tls certificate, if the certificate is stored on the same computer

rawCert string

the raw tls certificate represented as string

AddCurrencyResponse

BigInteger

A non-negative Big Integer represented as string, like "100000000"

FieldTypeLabelDescription
value string

CancelOrderRequest

FieldTypeLabelDescription
pairId string

orderId string

CancelOrderResponse

EnableTradingPairRequest

FieldTypeLabelDescription
pairId string

the trading pair to enable, like XSN_LTC

EnableTradingPairResponse

ListOrdersRequest

FieldTypeLabelDescription
pairId string

includeOwnOrders bool

skip uint32

limit uint32

ListOrdersResponse

FieldTypeLabelDescription
orders Order repeated

Order

FieldTypeLabelDescription
pairId string

orderId string

price BigInteger

The price of the order in satoshis.

funds BigInteger

The funds of the order in satoshis.

createdAt uint64

The epoch time when this order was created.

side OrderSide

Whether this order is a buy or sell

isOwnOrder bool

Whether this order is a local own order or a remote peer order.

OrderUpdate

FieldTypeLabelDescription
order Order

An order that was added to the order book.

orderRemoval Order

An order that was removed from the order book.

OrderbookFailure

FieldTypeLabelDescription
pairId string

funds BigInteger

failureReason string

requiredFee BigInteger

PlaceOrderFailure

FieldTypeLabelDescription
swapFailure SwapFailure

orderbookFalure OrderbookFailure

PlaceOrderRequest

FieldTypeLabelDescription
pairId string

side OrderSide

whether you are buying or selling

funds BigInteger

the funds you want to exchange

price BigInteger

missing on market orders

PlaceOrderResponse

Outcome of place order, three possible situations

1. Order was placed

2. Order was placed and matched without going to orderbook

3. Place order or swap has failed

FieldTypeLabelDescription
swapSuccess SwapSuccess

order Order

failure PlaceOrderFailure

SubscribeOrdersRequest

SubscribeSwapsRequest

SwapFailure

FieldTypeLabelDescription
orderId string

Order id assigned by orderbook

pairId string

The trading pair that the swap is for.

funds BigInteger

The order funds that was attempted to be swapped.

failureReason string

The reason why the swap failed.

SwapResult

FieldTypeLabelDescription
success SwapSuccess

failure SwapFailure

SwapSuccess

FieldTypeLabelDescription
orderId string

Order id assigned by orderbook

pairId string

The trading pair that the swap is for.

funds BigInteger

The order funds that was swapped.

rHash string

The hex-encoded payment hash for the swap.

amountReceived BigInteger

The amount received denominated in satoshis.

amountSent BigInteger

The amount sent denominated in satoshis.

role SwapSuccess.Role

Our role in the swap, either MAKER or TAKER.

currencyReceived string

The ticker symbol of the currency received.

currencySent string

The ticker symbol of the currency sent.

rPreimage string

The hex-encoded preimage.

price BigInteger

The price used for the swap.

OrderSide

NameNumberDescription
buy 0

sell 1

SwapSuccess.Role

NameNumberDescription
TAKER 0

MAKER 1

currencies

currencies

Method NameRequest TypeResponse TypeDescription
AddCurrency AddCurrencyRequest AddCurrencyResponse

before being able to enable a trading pair, you need to add the two involved currencies for example, for activating XSN_LTC, you will add the XSN currency, and the LTC currency. For now, only currencies supported by lnd (lightning network) work.

orders

orders

Method NameRequest TypeResponse TypeDescription
PlaceOrder PlaceOrderRequest PlaceOrderResponse

Places an order to the orderbook, you must have already enabled the involved trading pair. NOTE: After the order is matched, lssd will perform the swap automatically, so, your lnd needs to have a channel with enough coins to our hub.

CancelOrder CancelOrderRequest CancelOrderResponse

Cancels an existing order.

SubscribeOrders SubscribeOrdersRequest OrderUpdate stream

Susbcribe to events related to the orders in the orderbook.

ListOrders ListOrdersRequest ListOrdersResponse

List the available order on the orderbook.

swaps

swaps

Method NameRequest TypeResponse TypeDescription
SubscribeSwaps SubscribeSwapsRequest SwapResult stream

tradingPairs

trading pairs

Method NameRequest TypeResponse TypeDescription
EnableTradingPair EnableTradingPairRequest EnableTradingPairResponse

Enables the given trading pair, like XSN_LTC, before calling this method, you must have already added the involved currencies. After enabling a trading pair, lssd will download the existing orders form the orderbook, try waiting some seconds (5 should be enough) before performing any other operation, so that lssd has the time to sync because this is done in the background.

Scalar Value Types

.proto TypeNotesC++ TypeJava TypePython Type
double double double float
float float float float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long
uint32 Uses variable-length encoding. uint32 int int/long
uint64 Uses variable-length encoding. uint64 long int/long
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long
sfixed32 Always four bytes. int32 int int
sfixed64 Always eight bytes. int64 long int/long
bool bool boolean boolean
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode
bytes May contain any arbitrary sequence of bytes. string ByteString str