NAV Navbar
javascript shell

Introduction

This is the API definition for the Broker Daemon RPC Server.

The Broker (or Broker Daemon) is an open source piece of software that allows anyone to operate a node that keeps control of the private keys to their cryptocurrency (like Bitcoin and Litecoin) and use SparkSwap to trade those currencies.

The Broker runs as a daemon on a machine you control, and you direct it to take action through the RPC Server. The Broker is responsible for translating typical trading behavior (e.g. market buys) into actions on the SparkSwap Relayer (e.g. a BTC/LTC swap on the Lightning Network).

The Broker exposes a gRPC service which has support for client libraries in many languages.

The easiest way to interact with the Broker is through the Broker CLI.

For more information on the Broker, see:

For more information on SparkSwap as a whole, see:

Setting up to use the examples:

// This documentation makes use of the grpc and grpc-caller libraries on npm.
// The remainder of the docs assumes this setup step.
const grpc = require('grpc')
const PROTO_OPTIONS = {
  convertFieldsToCamelCase: true,
  binaryAsBase64: true,
  longsAsStrings: true,
  enumsAsStrings: true
}
const brokerProto = grpc.load('/path/to/broker.proto', 'proto', PROTO_OPTIONS)
> npm install -g https://github.com/sparkswap/broker-cli
> sparkswap -h

AdminService

The AdminService performs administrative tasks on the BrokerDaemon.

const address = 'localhost:27492'
const adminService = new brokerProto.AdminService(address, grpc.credentials.createInsecure())

HealthCheck

The HealthCheck returns a status of all of the components of the BrokerDaemon.

const deadline = new Date().setSeconds(new Date().getSeconds() + 5)
adminService.healthCheck({}, { deadline }, (err, { engineStatus, relayerStatus }) => {
  if (err) return console.error(err)
  console.log({ engineStatus, relayerStatus })
})
> sparkswap healthcheck

The above command will print:

{
  "engineStatus": [
    {
      "symbol": "BTC",
      "status": "OK"
    },
    {
      "symbol": "LTC",
      "status": "OK"
    },
  ],
  "relayerStatus": "OK"
}
HealthCheck: {
  "engines": {
    "BTC": "OK",
    "LTC": "OK"
  },
  "relayerStatus": "OK",
  "daemonStatus": "OK"
}

Unary RPC

Unary RPCs follow a simple request/response pattern familiar to users of HTTP APIs.

Request Type: google.protobuf.Empty

This message has no parameters.

Response Type: HealthCheckResponse

HealthCheckResponse provides information on the health of a BrokerDaemon.

Parameter Type Description
engine_status EngineStatus The status of every engine available on the BrokerDaemon.
relayer_status string The status of the relayer this BrokerDaemon is connected to, either 'OK' or the error message returned when connecting to it.

EngineStatus

EngineStatus provides the status of an engine for a currency.

Used in: HealthCheckResponse

Parameter Type Description
symbol string The common symbol that the engine is responsible for, e.g. BTC or LTC
status string The status of the engine, either 'OK' or the error message returned when accessing it.

OrderBookService

The OrderBookService is intended to update users on network activity and provide an up to date orderbook for the user.

It is the counterpoint to the OrderService in that it is read-only and deals with the wider network, never touching the Block Orders that the user creates and cancels.

const address = 'localhost:27492'
const orderBookService = new brokerProto.OrderBookService(address, grpc.credentials.createInsecure())

WatchMarket

WatchMarket opens a stream from the Broker with updates as to the current state of the orderbook. Those updates come in the form of ADDs and DELETEs, so by updating a UI with those changes, the user can see the current state of the orderbook.

Below is a simple example of a console-based UI for an orderbook:

const call = orderBookService.watchMarket(request)
const orders = new Map()
call.on('data', (update) => {
  const { orderId, side, price, amount } = update.marketEvent
  const { type } = update
  if (type === EVENT_TYPES.DELETE) {
    orders.delete(orderId)
  } else {
    orders.set(orderId, { price, amount })
  }
  console.clear()
  console.log(Array.from(orders.values()).sort(function (a, b) { return parseFloat(a) - parseFloat(b) }))
})
> sparkswap orderbook --market BTC/LTC

After an update, the UI would show something like this:

[
  {
    "side": "ASK",
    "price": "1.1",
    "amount": "0.0001"
  },
  {
    "side": "ASK",
    "price": "1.0",
    "amount": "0.0001"
  }
]
Market: BTC/LTC                                                                                                                            Ϟ SparkSwap Broker
                                                                                                                                          v0.1.0-alpha-preview
                                                                                                                                          http://sparkswap.com

┌──────────────────────────────────────────────────────────────────────────────┬──────────────────────────────────────────────────────────────────────────────┐
│ ASKS                                                                         │ BIDS                                                                         │
├──────────────────────────────────────────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────┤
│  Price                                Depth (BTC)                            │  Price                                Depth (BTC)                            │
│                                                                              │   1.2970000000000000                   0.0001000000000000                    │
│                                                                              │   1.2970000000000000                   0.0001000000000000                    │
│                                                                              │   1.1930000000000000                   0.0001000000000000                    │
│                                                                              │   1.1790000000000000                   0.0001300000000000                    │
│                                                                              │   1.1680000000000000                   0.0002000000000000                    │
│                                                                              │   1.1000000000000000                   0.0002000000000000                    │
└──────────────────────────────────────────────────────────────────────────────┴──────────────────────────────────────────────────────────────────────────────┘

Response Streaming RPC

Response Streaming RPCs take a single request message from the client, but the server responds with a stream of messages.

Request Type: WatchMarketRequest

Request for updates in a given market.

Parameter Type Description
market string Market to retrieve updates for, e.g. 'BTC/LTC'.

Response Type: WatchMarketResponse (Streaming)

An update to the watched market.

Parameter Type Description
type EventType Type of event this update is.
market_event MarketEvent The market update

EventType

Types of events, used to distinguish between adding orders to a market and removing them.

Used in: WatchMarketResponse

Name Number Description
ADD 0 Add an event to a market, typically due to an order being placed.
DELETE 1 Remove an event from the market, typically due to an order being cancelled or filled.

OrderService

The OrderService manages all trading activity on the Broker. It is the primary way that users interact with the Broker on a day-to-day basis.

The OrderService deals primarily with block orders, which are instructions given to the Broker by the end-user and are executed by the Broker on the SparkSwap Network. Brokers "work" block orders by breaking them into individual actions on the SparkSwap Relayer, namely placing limit orders and filling other participants' limit orders. This separation between block orders worked by the Broker and the underlying orders on the SparkSwap Relayer allows users to get access to the features of orders they are accustomed to (e.g. market orders) without placing additional trust in the Relayer or exposing themselves to front-running.

const address = 'localhost:27492'
const orderService = new brokerProto.OrderService(address, grpc.credentials.createInsecure())

CreateBlockOrder

CreateBlockOrder creates new block orders on the Broker. This is the only way to initiate a trade on the broker. Creating a block order returns a block order ID immediately, but that is not necessarily an indication that the block order has been successfully executed. The user should check on the block order's status after it is created to understand if it has been completed.

Placing a market order:

const deadline = new Date().setSeconds(new Date().getSeconds() + 5)
orderService.createBlockOrder(
  {
    market: 'BTC/LTC', // trading BTC and LTC
    side: 'BID', // Place a buy order
    amount: '0.0001', // 0.0001 BTC being traded
    isMarketOrder: true, // use the best available price
    timeInForce: 'GTC' // execute this order until I cancel it
  },
  { deadline },
  (err, { blockOrderId }) => {
    if (err) return console.error(err)
    console.log({ blockOrderId })
  }
)
> sparkswap buy 0.0001 --market BTC/LTC

The above command will create a market block order on the Broker and will print:

{ "blockOrderId": "vQPeeYWTlpTPreJxE3My_mpTBiYwYPnTkd6aU2XX" }
{ blockOrderId: 'vQPeeYWTlpTPreJxE3My_mpTBiYwYPnTkd6aU2XX' }

Placing a limit order:

const deadline = new Date().setSeconds(new Date().getSeconds() + 5)
orderService.createBlockOrder(
  {
    market: 'BTC/LTC', // trading BTC and LTC
    side: 'BID', // Place a buy order
    amount: '0.0001', // 0.0001 BTC being traded
    limitPrice: '1.1', // at a price no worse than 1.1 LTC per BTC
    timeInForce: 'GTC' // execute this order until I cancel it
  },
  { deadline },
  (err, { blockOrderId }) => {
    if (err) return console.error(err)
    console.log({ blockOrderId })
  }
)
> sparkswap buy 0.0001 1.1 --market BTC/LTC

The above command will create a limit block order on the Broker and will print:

{ "blockOrderId": "o2tSlSibkCsw6zi4-mpVuMogeLaz_GZuGqJlhWVs" }
{ blockOrderId: 'o2tSlSibkCsw6zi4-mpVuMogeLaz_GZuGqJlhWVs' }

Unary RPC

Unary RPCs follow a simple request/response pattern familiar to users of HTTP APIs.

Request Type: CreateBlockOrderRequest

Parameters to create a block order on the Broker.

Parameter Type Description
market string The market to place the block order in, e.g. 'BTC/LTC'. Markets are always expressed as the combination of two common symbols, separated by a /.
side Side Side of the market that the user wishes to take.
amount string Amount, in common units for a currency (e.g. bitcoins for BTC) that is the size of the order. This field supports decimal representation of units but uses a string since protobuf lacks a decimal type (e.g. '0.16')
is_market_order bool Whether this order should be executed as a market order, i.e. at the best available price in the market. It is important to note that there is no concept of a Market Order in the underlying network. Instead, the Broker will simulate Market Order behavior by filling all orders in the market until the order is completely filled.
limit_price string Price at which this order should executed, represented as a decimal string due to lack of Protobuf decimal support (e.g. '1.05').
time_in_force TimeInForce Time restriction for this block order.

Response Type: CreateBlockOrderResponse

Response from the broker after creating a block order.

Parameter Type Description
block_order_id string The unique ID of the block order assigned by the broker. This is used to retrieve information about the order and to cancel it.

GetBlockOrder

GetBlockOrder returns information on a previously placed block order. It should be used to check on the status of placed block orders.

const deadline = new Date().setSeconds(new Date().getSeconds() + 5)
const blockOrder = orderService.getBlockOrder({ blockOrderId: 'vQPeeYWTlpTPreJxE3My_mpTBiYwYPnTkd6aU2XX' }, { deadline }, (err, blockOrder) => {
  if (err) return console.error(err)
  console.log(blockOrder)
})
> sparkswap order status vQPeeYWTlpTPreJxE3My_mpTBiYwYPnTkd6aU2XX

The above command will retrieve the block order on the Broker and will print:

{
  "status": "",
  "market": "BTC/LTC",
  "side": "BID",
  "amount": "0.0001",
  "isMarketOrder": true,
  "timeInForce": "GTC",
  "open_orders": [],
  "fills": []
}
{ price_restriction: 'isMarketOrder',
  status: 'ACTIVE',
  market: 'BTC/LTC',
  side: 'BID',
  amount: '0.0001000000000000',
  isMarketOrder: true,
  limitPrice: '',
  timeInForce: 'GTC',
  fillAmount: '',
  openOrders: [],
  fills: [] }

Unary RPC

Unary RPCs follow a simple request/response pattern familiar to users of HTTP APIs.

Request Type: GetBlockOrderRequest

Parameters to retrieve a previously placed block order.

Parameter Type Description
block_order_id string ID for the block order assigned by the Broker.

Response Type: GetBlockOrderResponse

Representation of a retrieved block order.

Parameter Type Description
status BlockOrderStatus Status of the block order.
market string The market that the block order is for, e.g. 'BTC/LTC'. Markets are always expressed as the combination of two common symbols, separated by a /.
side Side The side of the market that the block order is taking.
amount string Amount, in common units for a currency (e.g. bitcoins for BTC) that is the size of the order. This field supports decimal representation of units but uses a string since protobuf lacks a decimal type (e.g. '0.16')
is_market_order bool Whether this block order is/was executed as a market order, i.e. at the best available price in the market. It is important to note that there is no concept of a Market Order in the underlying network. Instead, the Broker will simulate Market Order behavior by filling all orders in the market until the order is completely filled.
limit_price string Price at which this order should executed, represented as a decimal string due to lack of Protobuf decimal support (e.g. '1.05').
time_in_force TimeInForce Time restriction for this block order.
fill_amount string Amount of the block order that has been filled, in common units for a currency (e.g. bitcoins for BTC) represented as a decimal string (e.g. '0.10')
open_orders Order All orders on the SparkSwap Relayer that were placed by the Broker in support of this block order.
fills Fill All fills of orders on the SparkSwap Relayer that were undertaken by the Broker in support of this block order.

CancelBlockOrder

CancelBlockOrder cancels a previously placed block order. If the block order is already completed, or consists only of orders that are already being filled (either by this Broker or a counterparty), this will have no effect, as the Broker is bound to complete those orders or else lose their deposit. If the block order is partially executed, the cancel will affect only future actions, the Broker will not attempt to roll back trades that have already been made.

const deadline = new Date().setSeconds(new Date().getSeconds() + 5)
orderService.getBlockOrder({ blockOrderId: 'vQPeeYWTlpTPreJxE3My_mpTBiYwYPnTkd6aU2XX' }, { deadline }, (err) => {
  if (err) return console.error(err)
})
> sparkswap order cancel vQPeeYWTlpTPreJxE3My_mpTBiYwYPnTkd6aU2XX

The above command will cancel the block order, but has no output.

Unary RPC

Unary RPCs follow a simple request/response pattern familiar to users of HTTP APIs.

Request Type: CancelBlockOrderRequest

Request to cancel a previously created block order.

Parameter Type Description
block_order_id string Unique ID for the block order as assigned by the Broker.

Response Type: google.protobuf.Empty

This message has no parameters.

GetBlockOrders

GetBlockOrders returns information on all of the block orders placed in a single market, like BTC/LTC. It does not include complete information, such as the underlying orders and fills on the SparkSwap Relayer, or the amount of the order that has been filled. For that, use GetBlockOrder.

const deadline = new Date().setSeconds(new Date().getSeconds() + 5)
orderService.getBlockOrders({ market: 'BTC/LTC' }, { deadline }, (err, { blockOrders }) => {
  if (err) return console.error(err)
  console.log(blockOrders)
})
> sparkswap order summary --market BTC/LTC

The above command will retrieve the block orders on the Broker and will print:

[
  {
    "status": "",
    "market": "BTC/LTC",
    "side": "BID",
    "amount": "0.0001",
    "isMarketOrder": true,
    "timeInForce": "GTC"
  },
  {
    "status": "",
    "market": "BTC/LTC",
    "side": "BID",
    "amount": "0.0001",
    "limitPrice": "1.1",
    "timeInForce": "GTC"
  }
]
┌─────────────────────────────────────────────┬───────┬──────────────────┬──────────────────┬──────┬──────────┐
│ Order ID                                    │ Side  │ Amount           │ Limit Price      │ Time │ Status   │
├─────────────────────────────────────────────┼───────┼──────────────────┼──────────────────┼──────┼──────────┤
│ o2tSlSibkCsw6zi4-mpVuMogeLaz_GZuGqJlhWVs    │ BID   │ 0.0001000000000… │ 1.1000000000000… │ GTC  │ ACTIVE   │
├─────────────────────────────────────────────┼───────┼──────────────────┼──────────────────┼──────┼──────────┤
│ vQPeeYWTlpTPreJxE3My_mpTBiYwYPnTkd6aU2XX    │ BID   │ 0.0001000000000… │ MARKET           │ GTC  │ ACTIVE   │
└─────────────────────────────────────────────┴───────┴──────────────────┴──────────────────┴──────┴──────────┘

Unary RPC

Unary RPCs follow a simple request/response pattern familiar to users of HTTP APIs.

Request Type: GetBlockOrdersRequest

Request to retrieve all block orders in a given market.

Parameter Type Description
market string Market for which to retrieve block orders, expressed as a string separating two common symbols with a '/', e.g. 'BTC/LTC'

Response Type: GetBlockOrdersResponse

All block orders in a given market.

Parameter Type Description
block_orders BlockOrder A list of all block orders in the market.

WalletService

The WalletService is for interacting with the wallets managed by the Broker on behalf of the user.

It is used primarily during set up (e.g. making deposits) of a Broker.

const address = 'localhost:27492'
const walletService = new brokerProto.WalletService(address, grpc.credentials.createInsecure())

NewDepositAddress

NewDepositAddress generates a new address for the user to deposit currency into to be used for trading. The address is managed by a wallet in an underlying Payment Channel Network node, and so should be considered a hot wallet.

const address = await walletService.newDepositAddress({ symbol: 'BTC' })
console.log(address)
> sparkswap wallet new-deposit-address BTC

The above command will print:

> TODO
sb1qsakedujs4exdq5dz2cpldcph6hlvf82l8mn8uk

Unary RPC

Unary RPCs follow a simple request/response pattern familiar to users of HTTP APIs.

Request Type: NewDepositAddressRequest

Request for a new address to send funds to for a given currency.

Parameter Type Description
symbol Symbol Currency for which to generate the address

Response Type: NewDepositAddressResponse

Created deposit address for a given currency.

Parameter Type Description
address string Address created.

GetBalances

GetBalances retrieves the balance in all currency in wallets managed by Payment Channel Network nodes for this Broker.

Balances are divided into uncommittedBalance, i.e. everything not in a channel, totalChannelBalance (i.e. everything in channels opened by the Payment Channel Network nodes), totalPendingChannelBalance, i.e. funds in channels that have finished the funding workflow and are waiting for confirmations for the funding txn, and uncommittedPendingBalance, i.e funds in channels that are pending closure or unconfirmed unspent outputs under control of the wallet.

const deadline = new Date().setSeconds(new Date().getSeconds() + 5)
walletService.getBalances({}, { deadline }, (err, { balances }) => {
  if (err) return console.error(err)
  console.log(balances)
})
> sparkswap wallet balance

The above command will print:

[
  {
    "symbol": "BTC",
    "uncommittedBalance": "1000000000",
    "totalChannelBalance": "16700000",
    "totalPendingChannelBalance": "10000",
    "uncommittedPendingBalance": "00000"
  },
  {
    "symbol": "LTC",
    "uncommittedBalance": "1000000000",
    "totalChannelBalance": "16700000",
    "totalPendingChannelBalance": "20000",
    "uncommittedPendingBalance": "00000"
  }
]
Wallet Balances
┌──────────┬──────────────────────────────────┬──────────────────────────────────┐
│          │ Committed (Pending)              │ Uncommitted (Pending)            │
├──────────┼──────────────────────────────────┼──────────────────────────────────┤
│ BTC      │ 0.1676816500000000 (0.00000000)  │ 9.8321513500000000 (0.00000000)  │
├──────────┼──────────────────────────────────┼──────────────────────────────────┤
│ LTC      │ 0.0000000000000000 (0.00000000)  │ 10.0000000000000000 (0.00000000) │
└──────────┴──────────────────────────────────┴──────────────────────────────────┘

Unary RPC

Unary RPCs follow a simple request/response pattern familiar to users of HTTP APIs.

Request Type: google.protobuf.Empty

This message has no parameters.

Response Type: GetBalancesResponse

All balances for a Broker.

Parameter Type Description
balances Balance Balances in all currencies available to this Broker.

CommitBalance

CommitBalance opens a channel with the Relayer with the given amount of currency on the Broker's side, and requests that the Relayer open a channel to the Broker with the inverse currency of equivalent amount on the Relayer's side. This allows the Broker to trade in the market, since it has an outgoing channel and an incoming channel.

For now, since we operate a single market, BTC/LTC, this "inverse currency" is selected automatically - if you commit LTC, the Broker will request a BTC channel from the Relayer.

Additionally, since the Network is in testing stages, rather than relying on the Network's exchange rate between BTC and LTC to determine how large of a channel to open, we use a set rate of 60 LTC to 1 BTC. This also has the property of matching the conversion used in LND, so that when we run into things like the max channel size (in place while LND is in Beta), we can be consistent with LTC and BTC.

The below command has no output, but will throw an error if one is encountered.

const deadline = new Date().setSeconds(new Date().getSeconds() + 5)
walletService.commitBalance(
  {
    // we are committing LTC to a channel.
    // The Broker will request a BTC channel be opened back to itself.
    symbol: 'LTC',
    // The amount (in Satoshis) to commit to the channel.
    // The Broker will request a BTC channel of size 16700000 / 60 be opened back to itself.
    balance: '16700000'
  },
  { deadline },
  (err) => {
    if (err) return console.error(err)
  }
)
> sparkswap wallet commit-balance LTC

Unary RPC

Unary RPCs follow a simple request/response pattern familiar to users of HTTP APIs.

Request Type: CommitBalanceRequest

Request to commit an amount of a given currency.

Parameter Type Description
symbol Symbol Currency of the balance to commit.
balance int64 Amount of the currency to commit. This is currently in base units (e.g. Satoshis/Litoshis)

Response Type: google.protobuf.Empty

This message has no parameters.

GetPaymentChannelNetworkAddress

GetPaymentChannelNetworkAddress retrieves the Payment Channel Network Address for the given currency.

const { paymentChannelNetworkAddress } = await walletService.getPaymentChannelNetworkAddress({ symbol: 'BTC' })
console.log(paymentChannelNetworkAddress)
> sparkswap wallet network-address BTC

The above command will print:

> "025f08036e00e38468f52d68bb83939995440b72730bfaae99ace5630630997623@your.daemon:10113"
025f08036e00e38468f52d68bb83939995440b72730bfaae99ace5630630997623@your.daemon:10113

Unary RPC

Unary RPCs follow a simple request/response pattern familiar to users of HTTP APIs.

Request Type: GetPaymentChannelNetworkAddressRequest

Get the payment channel network address for a given currency.

Parameter Type Description
symbol Symbol Currency for which to retrieve the address

Response Type: GetPaymentChannelNetworkAddressResponse

Created deposit address for a given currency.

Parameter Type Description
payment_channel_network_address string Network Address retrieved

Message Reference

Balance

Balance in a currency in terms of what is committed in channels and total balance in wallets managed by this node.

Used in: GetBalancesResponse

Parameter Type Description
symbol string Currency of the balance.
uncommitted_balance int64 Total balance of the wallets managed by this node in this currency, including balance in channels. This is currently in base units (e.g. Satoshi/Litoshis)
total_channel_balance int64 Balance in the listed currency that is currently in channels. This is currently in base units (e.g. Satoshis/Litoshis)
total_pending_channel_balance int64 Balance in the listed currency that is currently in pending channels. This is currently in base units (e.g. Satoshis/Litoshis)
uncommitted_pending_balance int64 Balance in the listed currency that is currently in pending closing channels and unconfirmed wallet balance. This is currently in base units (e.g. Satoshis/Litoshis)

BlockOrder

An order placed by a user on a Broker. These are called Block Orders because they are for (relatively) large blocks that get broken up into individual Orders and Fills on the Relayer.

Used in: GetBlockOrdersResponse

Parameter Type Description
block_order_id string The unique ID for the block order assigned by the Broker.
market string The market that the block order is for, e.g. 'BTC/LTC'. Markets are always expressed as the combination of two common symbols, separated by a /.
side Side The side of the market that the block order is taking.
amount string Amount, in common units for a currency (e.g. bitcoins for BTC) that is the size of the order. This field supports decimal representation of units but uses a string since protobuf lacks a decimal type (e.g. '0.16')
is_market_order bool Whether this block order is/was executed as a market order, i.e. at the best available price in the market. It is important to note that there is no concept of a Market Order in the underlying network. Instead, the Broker will simulate Market Order behavior by filling all orders in the market until the order is completely filled.
limit_price string Price at which this order should executed, represented as a decimal string due to lack of Protobuf decimal support (e.g. '1.05').
time_in_force TimeInForce Time restriction for this block order.
status BlockOrderStatus Current status of the block order.

BlockOrderStatus

Status of the block order on the Broker.

Used in: BlockOrder, GetBlockOrderResponse

Name Number Description
ACTIVE 0 The block order is still being worked by the Broker.
CANCELLED 1 The block order was cancelled by the user.
COMPLETED 2 The block order has successfully completed execution.
FAILED 3 The block order has failed at some point and is no longer attempting execution.

CancelBlockOrderRequest

Request to cancel a previously created block order.

Used in: CancelBlockOrder

Parameter Type Description
block_order_id string Unique ID for the block order as assigned by the Broker.

CommitBalanceRequest

Request to commit an amount of a given currency.

Used in: CommitBalance

Parameter Type Description
symbol Symbol Currency of the balance to commit.
balance int64 Amount of the currency to commit. This is currently in base units (e.g. Satoshis/Litoshis)

CreateBlockOrderRequest

Parameters to create a block order on the Broker.

Used in: CreateBlockOrder

Parameter Type Description
market string The market to place the block order in, e.g. 'BTC/LTC'. Markets are always expressed as the combination of two common symbols, separated by a /.
side Side Side of the market that the user wishes to take.
amount string Amount, in common units for a currency (e.g. bitcoins for BTC) that is the size of the order. This field supports decimal representation of units but uses a string since protobuf lacks a decimal type (e.g. '0.16')
is_market_order bool Whether this order should be executed as a market order, i.e. at the best available price in the market. It is important to note that there is no concept of a Market Order in the underlying network. Instead, the Broker will simulate Market Order behavior by filling all orders in the market until the order is completely filled.
limit_price string Price at which this order should executed, represented as a decimal string due to lack of Protobuf decimal support (e.g. '1.05').
time_in_force TimeInForce Time restriction for this block order.

CreateBlockOrderResponse

Response from the broker after creating a block order.

Used in: CreateBlockOrder

Parameter Type Description
block_order_id string The unique ID of the block order assigned by the broker. This is used to retrieve information about the order and to cancel it.

Fill

A fill of an order on the SparkSwap Relayer.

Used in: GetBlockOrderResponse

Parameter Type Description
order_id string The Relayer-assigned unique ID of the order that this fill is for.
fill_id string The Relayer-assignded unique ID for this fill.
fill_status FillStatus Status of the fill on the Relayer.
amount string Amount of the order to fill, expressed in a decimal string of common units for a currency (e.g. bitcoins for BTC). This can be any amount greater than zero and less than or equal to the amount in the order.
price string Price at which the order was placed, expressed as a decimal string ratio between the common units of the currencies (e.g. litecoins to bitcoins, not litoshis to satoshis). All orders on the SparkSwap Relayer have prices.
fill_error string Any error messages related to the status of a REJECTED or FAILED fill

FillStatus

Status of the fill on the SparkSwap Relayer.

Used in: Fill

Name Number Description
CREATED 0 The fill has been created on the Relayer.
FILLED 1 The fill has been accepted as the fill for the given order.
EXECUTED 2 The swap has been executed on the Payment Channel Networks.
COMPLETED 3 The preimage has been returned to the Relayer by the Maker.
REJECTED 4 The fill has encountered a failure.

GetBalancesResponse

All balances for a Broker.

Used in: GetBalances

Parameter Type Description
balances Balance Balances in all currencies available to this Broker.

GetBlockOrderRequest

Parameters to retrieve a previously placed block order.

Used in: GetBlockOrder

Parameter Type Description
block_order_id string ID for the block order assigned by the Broker.

GetBlockOrderResponse

Representation of a retrieved block order.

Used in: GetBlockOrder

Parameter Type Description
status BlockOrderStatus Status of the block order.
market string The market that the block order is for, e.g. 'BTC/LTC'. Markets are always expressed as the combination of two common symbols, separated by a /.
side Side The side of the market that the block order is taking.
amount string Amount, in common units for a currency (e.g. bitcoins for BTC) that is the size of the order. This field supports decimal representation of units but uses a string since protobuf lacks a decimal type (e.g. '0.16')
is_market_order bool Whether this block order is/was executed as a market order, i.e. at the best available price in the market. It is important to note that there is no concept of a Market Order in the underlying network. Instead, the Broker will simulate Market Order behavior by filling all orders in the market until the order is completely filled.
limit_price string Price at which this order should executed, represented as a decimal string due to lack of Protobuf decimal support (e.g. '1.05').
time_in_force TimeInForce Time restriction for this block order.
fill_amount string Amount of the block order that has been filled, in common units for a currency (e.g. bitcoins for BTC) represented as a decimal string (e.g. '0.10')
open_orders Order All orders on the SparkSwap Relayer that were placed by the Broker in support of this block order.
fills Fill All fills of orders on the SparkSwap Relayer that were undertaken by the Broker in support of this block order.

GetBlockOrdersRequest

Request to retrieve all block orders in a given market.

Used in: GetBlockOrders

Parameter Type Description
market string Market for which to retrieve block orders, expressed as a string separating two common symbols with a '/', e.g. 'BTC/LTC'

GetBlockOrdersResponse

All block orders in a given market.

Used in: GetBlockOrders

Parameter Type Description
block_orders BlockOrder A list of all block orders in the market.

GetPaymentChannelNetworkAddressRequest

Get the payment channel network address for a given currency.

Used in: GetPaymentChannelNetworkAddress

Parameter Type Description
symbol Symbol Currency for which to retrieve the address

GetPaymentChannelNetworkAddressResponse

Created deposit address for a given currency.

Used in: GetPaymentChannelNetworkAddress

Parameter Type Description
payment_channel_network_address string Network Address retrieved

HealthCheckResponse

HealthCheckResponse provides information on the health of a BrokerDaemon.

Used in: HealthCheck

Parameter Type Description
engine_status EngineStatus The status of every engine available on the BrokerDaemon.
relayer_status string The status of the relayer this BrokerDaemon is connected to, either 'OK' or the error message returned when connecting to it.

EngineStatus

EngineStatus provides the status of an engine for a currency.

Used in: HealthCheckResponse

Parameter Type Description
symbol string The common symbol that the engine is responsible for, e.g. BTC or LTC
status string The status of the engine, either 'OK' or the error message returned when accessing it.

MarketEvent

Market events are events that change the orderbook for a given market. The are a combination of orders, fills, and cancels.

Used in: WatchMarketResponse

Parameter Type Description
order_id string The Relayer-assigned ID of the underlying order
amount string Amount of the order expressed in a decimal string of common units for a currency (e.g. bitcoins for BTC).
price string Price at which the order was placed, expressed as a decimal string ratio between the common units of the currencies (e.g. litecoins to bitcoins, not litoshis to satoshis). All orders on the SparkSwap Relayer have prices.
side Side Side that the order is taking

NewDepositAddressRequest

Request for a new address to send funds to for a given currency.

Used in: NewDepositAddress

Parameter Type Description
symbol Symbol Currency for which to generate the address

NewDepositAddressResponse

Created deposit address for a given currency.

Used in: NewDepositAddress

Parameter Type Description
address string Address created.

Order

An order on the SparkSwap Relayer.

Used in: GetBlockOrderResponse

Parameter Type Description
order_id string Unique ID assigned by the Relayer for this order.
order_status OrderStatus Status of the order on the Relayer.
amount string Amount of the order expressed in a decimal string of common units for a currency (e.g. bitcoins for BTC).
price string Price at which the order was placed, expressed as a decimal string ratio between the common units of the currencies (e.g. litecoins to bitcoins, not litoshis to satoshis). All orders on the SparkSwap Relayer have prices.
order_error string Any error messages related to the status of a REJECTED or FAILED order

OrderStatus

Status of an order on the SparkSwap Relayer.

Used in: Order

Name Number Description
CREATED 0 The order has been created on the Relayer.
PLACED 1 The order has been placed and communicated to other marker participants.
FILLED 2 The order has been filled by another market participant.
EXECUTED 3 The swap has been executed on the Payment Channel Networks
COMPLETED 4 The swap preimage has been returned to the Relayer.
REJECTED 5 The order has encountered a failure.

WatchMarketRequest

Request for updates in a given market.

Used in: WatchMarket

Parameter Type Description
market string Market to retrieve updates for, e.g. 'BTC/LTC'.

WatchMarketResponse

An update to the watched market.

Used in: WatchMarket

Parameter Type Description
type EventType Type of event this update is.
market_event MarketEvent The market update

EventType

Types of events, used to distinguish between adding orders to a market and removing them.

Used in: WatchMarketResponse

Name Number Description
ADD 0 Add an event to a market, typically due to an order being placed.
DELETE 1 Remove an event from the market, typically due to an order being cancelled or filled.

google

import "google/protobuf/empty.proto"; normally we would us the above import statement, but the node.js grpc doesn't import the standard types and so it throws an error message saying that it can't find google/protobuf.empty.proto Instead, we define our own Empty message that is equivalent.

Used in:

This message has no parameters.

google.protobuf

Used in:

This message has no parameters.

google.protobuf.Empty

Used in: HealthCheck, CancelBlockOrder, GetBalances, CommitBalance

This message has no parameters.

Side

Side is one of the two sides of any market.

Used in: BlockOrder, CreateBlockOrderRequest, GetBlockOrderResponse, MarketEvent

Name Number Description
BID 0 A BID is the buy side of a market.
ASK 1 An ASK is the sell side of a market.

Symbol

Symbol is the common representation of a given currency.

Used in: CommitBalanceRequest, GetPaymentChannelNetworkAddressRequest, NewDepositAddressRequest

Name Number Description
BTC 0 Bitcoin
LTC 1 Litecoin

TimeInForce

The time restriction for an order given by the user to the Broker. It is important to note that this time in force only controls the Broker's actions and does not correspond to a time-in-force on the underlying network.

Used in: BlockOrder, CreateBlockOrderRequest, GetBlockOrderResponse

Name Number Description
GTC 0 Good-til-cancelled, an order that remains in force until cancelled by the user
FOK 1 Fill-or-kill, an order that can be completely filled or will not be executed
IOC 2 Immediate-or-cancel, an order that will have as much filled immediately as possible with the remainder cancelled

Scalar Value Types

For more information, see the proto3 reference.

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