XudInit Service

var fs = require('fs');
var grpc = require('grpc');
var options = {
  convertFieldsToCamelCase: true,
  longsAsStrings: true,
};
var xudinitProto = grpc.load('opendexrpc.proto', 'proto', options);
var tlsCert = fs.readFileSync('path/to/tls.cert');
var sslCreds = grpc.credentials.createSsl(tlsCert);
var xudinitClient = new xudinitProto.XudInit(host + ':' + port, sslCreds);

# Python requires you to generate static protobuf code, see the following guide:
# https://grpc.io/docs/tutorials/basic/python.html#generating-client-and-server-code

import grpc
import opendexrpc_pb2 as xudinit, opendexrpc_pb2_grpc as xudinitrpc
cert = open('path/to/tls.cert', 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
channel = grpc.secure_channel(host + ':' + port, ssl_creds)
xudinit_stub = opendexrpc.XudInitStub(channel)

A service for interacting with a locked or uninitalized opendex node.

CreateNode

var request = {
  password: <string>,
};

xudinitClient.createNode(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "seedMnemonic": <string[]>,
//  "initializedLnds": <string[]>,
//  "initializedConnext": <bool>
// }

request = xudinit.CreateNodeRequest(
  password=<string>,
)
response = xudinitStub.CreateNode(request)
print(response)
# Output:
# {
#  "seed_mnemonic": <string[]>,
#  "initialized_lnds": <string[]>,
#  "initialized_connext": <bool>
# }

  opendex-cli create

Creates an opendex identity node key and underlying wallets. The node key and wallets are derived from a single seed and encrypted using a single password provided as a parameter to the call.

Request

Parameter	Type	Description
password	string	The password in utf-8 with which to encrypt the new opendex node key as well as any uninitialized underlying wallets.

Response

Parameter	Type	Description
seed_mnemonic	string array	The 24 word mnemonic to recover the opendex identity key and underlying wallets
initialized_lnds	string array	The list of lnd clients that were initialized.
initialized_connext	bool	Whether the connext wallet was initialized.

RestoreNode

var request = {
  seedMnemonic: <string[]>,
  password: <string>,
  lndBackups: <bytes>,
  xudDatabase: <bytes>,
};

xudinitClient.restoreNode(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "restoredLnds": <string[]>,
//  "restoredConnext": <bool>
// }

request = xudinit.RestoreNodeRequest(
  seed_mnemonic=<string[]>,
  password=<string>,
  lnd_backups=<bytes>,
  xud_database=<bytes>,
)
response = xudinitStub.RestoreNode(request)
print(response)
# Output:
# {
#  "restored_lnds": <string[]>,
#  "restored_connext": <bool>
# }

  opendex-cli restore [backup_directory]

Restores an opendex instance and underlying wallets from a seed.

Request

Parameter	Type	Description
seed_mnemonic	string array	The 24 word mnemonic to recover the opendex identity key and underlying wallets
password	string	The password in utf-8 with which to encrypt the restored opendex node key as well as any restored underlying wallets.
lnd_backups	map<string, bytes>	A map between the currency of the LND and its multi channel SCB
xud_database	bytes	The opendex database backup

Response

Parameter	Type	Description
restored_lnds	string array	The list of lnd clients that were initialized.
restored_connext	bool	Whether the connext wallet was initialized.

UnlockNode

var request = {
  password: <string>,
};

xudinitClient.unlockNode(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "unlockedLnds": <string[]>,
//  "lockedLnds": <string[]>
// }

request = xudinit.UnlockNodeRequest(
  password=<string>,
)
response = xudinitStub.UnlockNode(request)
print(response)
# Output:
# {
#  "unlocked_lnds": <string[]>,
#  "locked_lnds": <string[]>
# }

  opendex-cli unlock

Unlocks and decrypts the opendex node key and any underlying wallets.

Request

Parameter	Type	Description
password	string	The password in utf-8 with which to unlock an existing opendex node key as well as underlying client wallets such as lnd.

Response

Parameter	Type	Description
unlocked_lnds	string array	The list of lnd clients that were unlocked.
locked_lnds	string array	The list of lnd clients that could not be unlocked.

Xud Service

var fs = require('fs');
var grpc = require('grpc');
var options = {
  convertFieldsToCamelCase: true,
  longsAsStrings: true,
};
var xudProto = grpc.load('opendexrpc.proto', 'proto', options);
var tlsCert = fs.readFileSync('path/to/tls.cert');
var sslCreds = grpc.credentials.createSsl(tlsCert);
var xudClient = new xudProto.Xud(host + ':' + port, sslCreds);

# Python requires you to generate static protobuf code, see the following guide:
# https://grpc.io/docs/tutorials/basic/python.html#generating-client-and-server-code

import grpc
import opendexrpc_pb2 as xud, opendexrpc_pb2_grpc as xudrpc
cert = open('path/to/tls.cert', 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
channel = grpc.secure_channel(host + ':' + port, ssl_creds)
xud_stub = opendexrpc.XudStub(channel)

The primary service for interacting with a running opendex node.

AddCurrency

var request = {
  currency: <string>,
  swapClient: <SwapClient>,
  tokenAddress: <string>,
  decimalPlaces: <uint32>,
};

xudClient.addCurrency(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output: {}

request = xud.Currency(
  currency=<string>,
  swap_client=<SwapClient>,
  token_address=<string>,
  decimal_places=<uint32>,
)
response = xudStub.AddCurrency(request)
print(response)
# Output: {}

  opendex-cli addcurrency <currency> <swap_client> [decimal_places] [token_address]

Adds a currency to the list of supported currencies. Once added, the currency may be used for new trading pairs.

Request

Parameter	Type	Description
currency	string	The ticker symbol for this currency such as BTC, LTC, ETH, etc...
swap_client	SwapClient	The payment channel network client to use for executing swaps.
token_address	string	The contract address for layered tokens such as ERC20.
decimal_places	uint32	The number of places to the right of the decimal point of the smallest subunit of the currency. For example, BTC, LTC, and others where the smallest subunits (satoshis) are 0.00000001 full units (bitcoins) have 8 decimal places. ETH has 18. This can be thought of as the base 10 exponent of the smallest subunit expressed as a positive integer. A default value of 8 is used if unspecified.

Response

This response has no parameters.

AddPair

var request = {
  baseCurrency: <string>,
  quoteCurrency: <string>,
};

xudClient.addPair(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output: {}

request = xud.AddPairRequest(
  base_currency=<string>,
  quote_currency=<string>,
)
response = xudStub.AddPair(request)
print(response)
# Output: {}

  opendex-cli addpair <base_currency> <quote_currency>

Adds a trading pair to the list of supported trading pairs. The newly supported pair is advertised to peers so they may begin sending orders for it.

Request

Parameter	Type	Description
base_currency	string	The base currency that is bought and sold for this trading pair.
quote_currency	string	The currency used to quote a price for the base currency.

Response

This response has no parameters.

Ban

var request = {
  nodeIdentifier: <string>,
};

xudClient.ban(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output: {}

request = xud.BanRequest(
  node_identifier=<string>,
)
response = xudStub.Ban(request)
print(response)
# Output: {}

  opendex-cli ban <node_identifier>

Bans a node and immediately disconnects from it. This can be used to prevent any connections to a specific node.

Request

Parameter	Type	Description
node_identifier	string	The node pub key or alias of the node to ban.

Response

This response has no parameters.

ChangePassword

var request = {
  newPassword: <string>,
  oldPassword: <string>,
};

xudClient.changePassword(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output: {}

request = xud.ChangePasswordRequest(
  new_password=<string>,
  old_password=<string>,
)
response = xudStub.ChangePassword(request)
print(response)
# Output: {}

  opendex-cli changepass

Changes the opendex master password, including the wallet passwords for any underlying clients.

Request

Parameter	Type	Description
new_password	string
old_password	string

Response

This response has no parameters.

CloseChannel

var request = {
  nodeIdentifier: <string>,
  currency: <string>,
  force: <bool>,
  destination: <string>,
  amount: <uint64>,
  fee: <uint64>,
};

xudClient.closeChannel(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "transactionIds": <string[]>
// }

request = xud.CloseChannelRequest(
  node_identifier=<string>,
  currency=<string>,
  force=<bool>,
  destination=<string>,
  amount=<uint64>,
  fee=<uint64>,
)
response = xudStub.CloseChannel(request)
print(response)
# Output:
# {
#  "transaction_ids": <string[]>
# }

  opendex-cli closechannel <currency> [node_identifier ] [--force]

Closes any existing payment channels with a peer for the specified currency.

Request

Parameter	Type	Description
node_identifier	string	The node pub key or alias of the peer with which to close any channels with.
currency	string	The ticker symbol of the currency of the channel to close.
force	bool	Whether to force close the channel in case the peer is offline or unresponsive.
destination	string	The on-chain address to send funds extracted from the channel. If unspecified, the funds return to the default wallet for the client closing the channel.
amount	uint64	For Connext only - the amount to extract from the channel. If 0 or unspecified, the entire off-chain balance for the specified currency will be extracted.
fee	uint64	A manual fee rate set in sat/byte that should be used when crafting the closure transaction.

Response

Parameter	Type	Description
transaction_ids	string array	The id of the transaction per channel close.

Connect

var request = {
  nodeUri: <string>,
};

xudClient.connect(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output: {}

request = xud.ConnectRequest(
  node_uri=<string>,
)
response = xudStub.Connect(request)
print(response)
# Output: {}

  opendex-cli connect <node_uri>

Attempts to connect to a node. Once connected, the node is added to the list of peers and becomes available for swaps and trading. A handshake exchanges information about the peer's supported trading and swap clients. Orders will be shared with the peer upon connection and upon new order placements.

Request

Parameter	Type	Description
node_uri	string	The uri of the node to connect to in "[nodePubKey]@[host]:[port]" format.

Response

This response has no parameters.

WalletDeposit

var request = {
  currency: <string>,
};

xudClient.walletDeposit(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "address": <string>
// }

request = xud.DepositRequest(
  currency=<string>,
)
response = xudStub.WalletDeposit(request)
print(response)
# Output:
# {
#  "address": <string>
# }

  opendex-cli walletdeposit <currency>

Gets an address to deposit a given currency into the opendex wallets.

Request

Parameter	Type	Description
currency	string	The ticker symbol of the currency to deposit.

Response

Parameter	Type	Description
address	string	The address to use to deposit funds.

Deposit

var request = {
  currency: <string>,
};

xudClient.deposit(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "address": <string>
// }

request = xud.DepositRequest(
  currency=<string>,
)
response = xudStub.Deposit(request)
print(response)
# Output:
# {
#  "address": <string>
# }

  opendex-cli deposit <currency>

Gets an address to deposit a given currency directly into a channel.

Request

Parameter	Type	Description
currency	string	The ticker symbol of the currency to deposit.

Response

Parameter	Type	Description
address	string	The address to use to deposit funds.

DiscoverNodes

var request = {
  nodeIdentifier: <string>,
};

xudClient.discoverNodes(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "numNodes": <uint32>
// }

request = xud.DiscoverNodesRequest(
  node_identifier=<string>,
)
response = xudStub.DiscoverNodes(request)
print(response)
# Output:
# {
#  "num_nodes": <uint32>
# }

Discover nodes from a specific peer and apply new connections

Request

Parameter	Type	Description
node_identifier	string	The node pub key or alias of the peer to discover nodes from.

Response

Parameter	Type	Description
num_nodes	uint32

GetBalance

var request = {
  currency: <string>,
};

xudClient.getBalance(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "balances": <Balance>
// }

request = xud.GetBalanceRequest(
  currency=<string>,
)
response = xudStub.GetBalance(request)
print(response)
# Output:
# {
#  "balances": <Balance>
# }

  opendex-cli getbalance [currency]

Gets the total balance available across all payment channels and wallets for one or all currencies.

Request

Parameter	Type	Description
currency	string	The ticker symbol of the currency to query for, if unspecified then balances for all supported currencies are queried.

Response

Parameter	Type	Description
balances	map<string, Balance>	A map between currency ticker symbols and their balances.

GetInfo

var request = {};

xudClient.getInfo(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "version": <string>,
//  "nodePubKey": <string>,
//  "uris": <string[]>,
//  "numPeers": <uint32>,
//  "numPairs": <uint32>,
//  "orders": <OrdersCount>,
//  "lnd": <LndInfo>,
//  "alias": <string>,
//  "network": <string>,
//  "pendingSwapHashes": <string[]>,
//  "connext": <ConnextInfo>
// }

request = xud.GetInfoRequest()
response = xudStub.GetInfo(request)
print(response)
# Output:
# {
#  "version": <string>,
#  "node_pub_key": <string>,
#  "uris": <string[]>,
#  "num_peers": <uint32>,
#  "num_pairs": <uint32>,
#  "orders": <OrdersCount>,
#  "lnd": <LndInfo>,
#  "alias": <string>,
#  "network": <string>,
#  "pending_swap_hashes": <string[]>,
#  "connext": <ConnextInfo>
# }

  opendex-cli getinfo

Gets general information about this node.

Request

This request has no parameters.

Response

Parameter	Type	Description
version	string	The version of this instance of opendex.
node_pub_key	string	The node pub key of this node.
uris	string array	A list of uris that can be used to connect to this node. These are shared with peers.
num_peers	uint32	The number of currently connected peers.
num_pairs	uint32	The number of supported trading pairs.
orders	OrdersCount	The number of active, standing orders in the order book.
lnd	map<string, LndInfo>
alias	string	The alias of this instance of opendex.
network	string	The network of this node.
pending_swap_hashes	string array
connext	ConnextInfo

GetMnemonic

var request = {};

xudClient.getMnemonic(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "seedMnemonic": <string[]>
// }

request = xud.GetMnemonicRequest()
response = xudStub.GetMnemonic(request)
print(response)
# Output:
# {
#  "seed_mnemonic": <string[]>
# }

  opendex-cli getnemonic

Gets the master seed mnemonic .

Request

This request has no parameters.

Response

Parameter	Type	Description
seed_mnemonic	string array

GetNodeInfo

var request = {
  nodeIdentifier: <string>,
};

xudClient.getNodeInfo(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "reputationScore": <sint32>,
//  "banned": <bool>
// }

request = xud.GetNodeInfoRequest(
  node_identifier=<string>,
)
response = xudStub.GetNodeInfo(request)
print(response)
# Output:
# {
#  "reputationScore": <sint32>,
#  "banned": <bool>
# }

  opendex-cli getnodeinfo <node_identifier>

Gets general information about a node.

Request

Parameter	Type	Description
node_identifier	string	The node pub key or alias of the node for which to get information.

Response

Parameter	Type	Description
reputationScore	sint32	The node's reputation score. Points are subtracted for unexpected or potentially malicious behavior. Points are added when swaps are successfully executed.
banned	bool	Whether the node is currently banned.

ListOrders

var request = {
  pairId: <string>,
  owner: <Owner>,
  limit: <uint32>,
  includeAliases: <bool>,
};

xudClient.listOrders(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "orders": <Orders>
// }

request = xud.ListOrdersRequest(
  pair_id=<string>,
  owner=<Owner>,
  limit=<uint32>,
  include_aliases=<bool>,
)
response = xudStub.ListOrders(request)
print(response)
# Output:
# {
#  "orders": <Orders>
# }

  opendex-cli listorders [pair_id] [include_own_orders] [limit]

Gets orders from the order book. This call returns the state of the order book at a given point in time, although it is not guaranteed to still be vaild by the time a response is received and processed by a client. It accepts an optional trading pair id parameter. If specified, only orders for that particular trading pair are returned. Otherwise, all orders are returned. Orders are separated into buys and sells for each trading pair, but unsorted.

Request

Parameter	Type	Description
pair_id	string	The trading pair for which to retrieve orders.
owner	Owner	Whether only own, only peer or both orders should be included in result.
limit	uint32	The maximum number of orders to return from each side of the order book.
include_aliases	bool	Whether to include the node aliases of owners of the orders.

Response

Parameter	Type	Description
orders	map<string, Orders>	A map between pair ids and their buy and sell orders.

ListCurrencies

var request = {};

xudClient.listCurrencies(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "currencies": <Currency[]>
// }

request = xud.ListCurrenciesRequest()
response = xudStub.ListCurrencies(request)
print(response)
# Output:
# {
#  "currencies": <Currency[]>
# }

  opendex-cli listcurrencies

Gets a list of this node's supported currencies.

Request

This request has no parameters.

Response

Parameter	Type	Description
currencies	Currency array	The list of available currencies in the orderbook.

ListPairs

var request = {};

xudClient.listPairs(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "pairs": <string[]>
// }

request = xud.ListPairsRequest()
response = xudStub.ListPairs(request)
print(response)
# Output:
# {
#  "pairs": <string[]>
# }

  opendex-cli listpairs

Gets a list of this nodes suported trading pairs.

Request

This request has no parameters.

Response

Parameter	Type	Description
pairs	string array	The list of supported trading pair tickers in formats like "LTC/BTC".

ListPeers

var request = {};

xudClient.listPeers(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "peers": <Peer[]>
// }

request = xud.ListPeersRequest()
response = xudStub.ListPeers(request)
print(response)
# Output:
# {
#  "peers": <Peer[]>
# }

  opendex-cli listpeers

Gets a list of connected peers.

Request

This request has no parameters.

Response

Parameter	Type	Description
peers	Peer array	The list of connected peers.

OpenChannel

var request = {
  nodeIdentifier: <string>,
  currency: <string>,
  amount: <uint64>,
  pushAmount: <uint64>,
  fee: <uint64>,
};

xudClient.openChannel(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "transactionId": <string>
// }

request = xud.OpenChannelRequest(
  node_identifier=<string>,
  currency=<string>,
  amount=<uint64>,
  push_amount=<uint64>,
  fee=<uint64>,
)
response = xudStub.OpenChannel(request)
print(response)
# Output:
# {
#  "transaction_id": <string>
# }

  opendex-cli openchannel <currency> <amount> [node_identifier] [push_amount]

Opens a payment channel to a peer for the specified amount and currency.

Request

Parameter	Type	Description
node_identifier	string	The node pub key or alias of the peer with which to open channel with.
currency	string	The ticker symbol of the currency to open the channel for.
amount	uint64	The amount to be deposited into the channel denominated in satoshis.
push_amount	uint64	The balance amount to be pushed to the remote side of the channel denominated in satoshis.
fee	uint64	The manual fee rate set in sat/byte that should be used when crafting the funding transaction in the channel.

Response

Parameter	Type	Description
transaction_id	string	The id of the transaction that opened the channel.

OrderBook

var request = {
  pairId: <string>,
  precision: <int32>,
  limit: <uint32>,
};

xudClient.orderBook(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "price": <double>,
//  "quantity": <uint64>,
//  "sellBuckets": <Bucket[]>,
//  "buyBuckets": <Bucket[]>,
//  "buckets": <Buckets>
// }

request = xud.OrderBookRequest(
  pair_id=<string>,
  precision=<int32>,
  limit=<uint32>,
)
response = xudStub.OrderBook(request)
print(response)
# Output:
# {
#  "price": <double>,
#  "quantity": <uint64>,
#  "sell_buckets": <Bucket[]>,
#  "buy_buckets": <Bucket[]>,
#  "buckets": <Buckets>
# }

  opendex-cli orderbook [pair_id] [precision]

Gets an order book depth chart where orders are grouped into "buckets" according to their price rounded to a given level of precision.

Request

Parameter	Type	Description
pair_id	string	The trading pair for which to retrieve orders.
precision	int32	The number of digits to the right of the decimal point for each price bucket. A negative number rounds digits to the left of the decimal point, e.g. -2 would round to the hundreds place.
limit	uint32	The maximum number of price "buckets" to return, if zero or unspecified then no limit is imposed.

Response

Parameter	Type	Description
price	double	The rounded price of the bucket.
quantity	uint64	The total quantity for all orders that fall into this bucket.
sell_buckets	Bucket array	A sorted list of buckets for sell orders
buy_buckets	Bucket array	A sorted list of buckets for buy orders.
buckets	map<string, Buckets>	A map between currency tickers and sorted lists of order buckets

PlaceOrder

var request = {
  price: <double>,
  quantity: <uint64>,
  pairId: <string>,
  orderId: <string>,
  side: <OrderSide>,
  replaceOrderId: <string>,
  immediateOrCancel: <bool>,
};

var call = xudClient.placeOrder(request);
call.on('data', function (response) {
  console.log(response);
});
call.on('error', function (err) {
  console.error(err);
});
call.on('end', function () {
  // the streaming call has been ended by the server
});
// Output:
// {
//  "match": <Order>,
//  "swapSuccess": <SwapSuccess>,
//  "remainingOrder": <Order>,
//  "swapFailure": <SwapFailure>
// }

request = xud.PlaceOrderRequest(
  price=<double>,
  quantity=<uint64>,
  pair_id=<string>,
  order_id=<string>,
  side=<OrderSide>,
  replace_order_id=<string>,
  immediate_or_cancel=<bool>,
)
for response in stub.PlaceOrder(request):
  print(response)
# Output:
# {
#  "match": <Order>,
#  "swap_success": <SwapSuccess>,
#  "remaining_order": <Order>,
#  "swap_failure": <SwapFailure>
# }

Adds an order to the order book. If price is zero or unspecified a market order will get added.

Request

Parameter	Type	Description
price	double	The price of the order.
quantity	uint64	The quantity of the order denominated in satoshis.
pair_id	string	The trading pair that the order is for.
order_id	string	The local id to assign to the order.
side	OrderSide	Whether the order is a buy or sell.
replace_order_id	string	The local id of an existing order to be replaced. If provided, the order must be successfully found and removed before the new order is placed, otherwise an error is returned.
immediate_or_cancel	bool	Whether the order must be filled immediately and not allowed to enter the order book.

Response (Streaming)

Parameter	Type	Description
match	Order	An order (or portion thereof) that matched the newly placed order.
swap_success	SwapSuccess	A successful swap of a peer order that matched the newly placed order.
remaining_order	Order	The remaining portion of the order, after matches, that enters the order book.
swap_failure	SwapFailure	A swap attempt that failed.

PlaceOrderSync

var request = {
  price: <double>,
  quantity: <uint64>,
  pairId: <string>,
  orderId: <string>,
  side: <OrderSide>,
  replaceOrderId: <string>,
  immediateOrCancel: <bool>,
};

xudClient.placeOrderSync(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "internalMatches": <Order[]>,
//  "swapSuccesses": <SwapSuccess[]>,
//  "remainingOrder": <Order>,
//  "swapFailures": <SwapFailure[]>
// }

request = xud.PlaceOrderRequest(
  price=<double>,
  quantity=<uint64>,
  pair_id=<string>,
  order_id=<string>,
  side=<OrderSide>,
  replace_order_id=<string>,
  immediate_or_cancel=<bool>,
)
response = xudStub.PlaceOrderSync(request)
print(response)
# Output:
# {
#  "internal_matches": <Order[]>,
#  "swap_successes": <SwapSuccess[]>,
#  "remaining_order": <Order>,
#  "swap_failures": <SwapFailure[]>
# }

  opendex-cli buy <quantity> <pair_id> <price> [order_id] [stream]
opendex-cli sell <quantity> <pair_id> <price> [order_id] [stream]

The synchronous, non-streaming version of PlaceOrder.

Request

Parameter	Type	Description
price	double	The price of the order.
quantity	uint64	The quantity of the order denominated in satoshis.
pair_id	string	The trading pair that the order is for.
order_id	string	The local id to assign to the order.
side	OrderSide	Whether the order is a buy or sell.
replace_order_id	string	The local id of an existing order to be replaced. If provided, the order must be successfully found and removed before the new order is placed, otherwise an error is returned.
immediate_or_cancel	bool	Whether the order must be filled immediately and not allowed to enter the order book.

Response

Parameter	Type	Description
internal_matches	Order array	A list of own orders (or portions thereof) that matched the newly placed order.
swap_successes	SwapSuccess array	A list of successful swaps of peer orders that matched the newly placed order.
remaining_order	Order	The remaining portion of the order, after matches, that enters the order book.
swap_failures	SwapFailure array	A list of swap attempts that failed.

ExecuteSwap

var request = {
  orderId: <string>,
  pairId: <string>,
  peerPubKey: <string>,
  quantity: <uint64>,
};

xudClient.executeSwap(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "orderId": <string>,
//  "localId": <string>,
//  "pairId": <string>,
//  "quantity": <uint64>,
//  "rHash": <string>,
//  "amountReceived": <uint64>,
//  "amountSent": <uint64>,
//  "peerPubKey": <string>,
//  "role": <Role>,
//  "currencyReceived": <string>,
//  "currencySent": <string>,
//  "rPreimage": <string>,
//  "price": <double>
// }

request = xud.ExecuteSwapRequest(
  order_id=<string>,
  pair_id=<string>,
  peer_pub_key=<string>,
  quantity=<uint64>,
)
response = xudStub.ExecuteSwap(request)
print(response)
# Output:
# {
#  "order_id": <string>,
#  "local_id": <string>,
#  "pair_id": <string>,
#  "quantity": <uint64>,
#  "r_hash": <string>,
#  "amount_received": <uint64>,
#  "amount_sent": <uint64>,
#  "peer_pub_key": <string>,
#  "role": <Role>,
#  "currency_received": <string>,
#  "currency_sent": <string>,
#  "r_preimage": <string>,
#  "price": <double>
# }

Executes a swap on a maker peer order.

Request

Parameter	Type	Description
order_id	string	The order id of the maker order.
pair_id	string	The trading pair of the swap orders.
peer_pub_key	string	The node pub key of the peer which owns the maker order. This is optional but helps locate the order more quickly.
quantity	uint64	The quantity to swap denominated in satoshis. The whole order will be swapped if unspecified.

Response

Parameter	Type	Description
order_id	string	The global UUID for the order that was swapped.
local_id	string	The local id for the order that was swapped.
pair_id	string	The trading pair that the swap is for.
quantity	uint64	The order quantity that was swapped.
r_hash	string	The hex-encoded payment hash for the swap.
amount_received	uint64	The amount received denominated in satoshis.
amount_sent	uint64	The amount sent denominated in satoshis.
peer_pub_key	string	The node pub key of the peer that executed this order.
role	Role	Our role in the swap, either MAKER or TAKER.
currency_received	string	The ticker symbol of the currency received.
currency_sent	string	The ticker symbol of the currency sent.
r_preimage	string	The hex-encoded preimage.
price	double	The price used for the swap.

RemoveCurrency

var request = {
  currency: <string>,
};

xudClient.removeCurrency(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output: {}

request = xud.RemoveCurrencyRequest(
  currency=<string>,
)
response = xudStub.RemoveCurrency(request)
print(response)
# Output: {}

  opendex-cli removecurrency <currency>

Removes a currency from the list of supported currencies. Only currencies that are not in use for any currently supported trading pairs may be removed. Once removed, the currency can no longer be used for any supported trading pairs.

Request

Parameter	Type	Description
currency	string	The ticker symbol for this currency such as BTC, LTC, ETH, etc...

Response

This response has no parameters.

RemoveOrder

var request = {
  orderId: <string>,
  quantity: <uint64>,
};

xudClient.removeOrder(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "quantityOnHold": <uint64>,
//  "remainingQuantity": <uint64>,
//  "removedQuantity": <uint64>,
//  "pairId": <string>
// }

request = xud.RemoveOrderRequest(
  order_id=<string>,
  quantity=<uint64>,
)
response = xudStub.RemoveOrder(request)
print(response)
# Output:
# {
#  "quantity_on_hold": <uint64>,
#  "remaining_quantity": <uint64>,
#  "removed_quantity": <uint64>,
#  "pair_id": <string>
# }

  opendex-cli removeorder <order_id> [quantity]

Removes an order from the order book by its local id. This should be called when an order is canceled or filled outside of opendex. Removed orders become immediately unavailable for swaps, and peers are notified that the order is no longer valid. Any portion of the order that is on hold due to ongoing swaps will not be removed until after the swap attempts complete.

Request

Parameter	Type	Description
order_id	string	The local id of the order to remove.
quantity	uint64	The quantity to remove from the order denominated in satoshis. If zero or unspecified then the entire order is removed.

Response

Parameter	Type	Description
quantity_on_hold	uint64	Any portion of the order that was on hold due to ongoing swaps at the time of the request and could not be removed until after the swaps finish.
remaining_quantity	uint64	Remaining portion of the order if it was a partial removal.
removed_quantity	uint64	Successfully removed portion of the order.
pair_id	string	Removed order's pairId. (e.g. ETH/BTC)

RemoveAllOrders

var request = {};

xudClient.removeAllOrders(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "removedOrderIds": <string[]>,
//  "onHoldOrderIds": <string[]>
// }

request = xud.RemoveAllOrdersRequest()
response = xudStub.RemoveAllOrders(request)
print(response)
# Output:
# {
#  "removed_order_ids": <string[]>,
#  "on_hold_order_ids": <string[]>
# }

  opendex-cli removeallorders

Removes all orders from the order book. Removed orders become immediately unavailable for swaps, and peers are notified that the orders are no longer valid. Any portion of the orders that is on hold due to ongoing swaps will not be removed until after the swap attempts complete.

Request

This request has no parameters.

Response

Parameter	Type	Description
removed_order_ids	string array	The local order ids that were successfully removed.
on_hold_order_ids	string array	The local order ids that were on hold and failed to be removed.

RemovePair

var request = {
  pairId: <string>,
};

xudClient.removePair(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output: {}

request = xud.RemovePairRequest(
  pair_id=<string>,
)
response = xudStub.RemovePair(request)
print(response)
# Output: {}

  opendex-cli removepair <pair_id>

Removes a trading pair from the list of currently supported trading pair. This call will effectively cancel any standing orders for that trading pair. Peers are informed when a pair is no longer supported so that they will know to stop sending orders for it.

Request

Parameter	Type	Description
pair_id	string	The trading pair ticker to remove in a format such as "LTC/BTC".

Response

This response has no parameters.

SetLogLevel

var request = {
  logLevel: <LogLevel>,
};

xudClient.setLogLevel(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output: {}

request = xud.SetLogLevelRequest(
  log_level=<LogLevel>,
)
response = xudStub.SetLogLevel(request)
print(response)
# Output: {}

  opendex-cli loglevel <level>

Set the logging level.

Request

Parameter	Type	Description
log_level	LogLevel

Response

This response has no parameters.

Shutdown

var request = {};

xudClient.shutdown(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output: {}

request = xud.ShutdownRequest()
response = xudStub.Shutdown(request)
print(response)
# Output: {}

  opendex-cli shutdown

Begin gracefully shutting down opendex.

Request

This request has no parameters.

Response

This response has no parameters.

SubscribeOrders

var request = {
  existing: <bool>,
};

var call = xudClient.subscribeOrders(request);
call.on('data', function (response) {
  console.log(response);
});
call.on('error', function (err) {
  console.error(err);
});
call.on('end', function () {
  // the streaming call has been ended by the server
});
// Output:
// {
//  "order": <Order>,
//  "orderRemoval": <OrderRemoval>
// }

request = xud.SubscribeOrdersRequest(
  existing=<bool>,
)
for response in stub.SubscribeOrders(request):
  print(response)
# Output:
# {
#  "order": <Order>,
#  "order_removal": <OrderRemoval>
# }

Subscribes to orders being added to and removed from the order book. This call allows the client to maintain an up-to-date view of the order book. For example, an exchange that wants to show its users a real time view of the orders available to them would subscribe to this streaming call to be alerted as new orders are added and expired orders are removed.

Request

Parameter	Type	Description
existing	bool	Whether to transmit all existing active orders upon establishing the stream.

Response (Streaming)

Parameter	Type	Description
order	Order	An order that was added to the order book.
order_removal	OrderRemoval	An order (or portion thereof) that was removed from the order book.

SubscribeSwapFailures

var request = {
  includeTaker: <bool>,
};

var call = xudClient.subscribeSwapFailures(request);
call.on('data', function (response) {
  console.log(response);
});
call.on('error', function (err) {
  console.error(err);
});
call.on('end', function () {
  // the streaming call has been ended by the server
});
// Output:
// {
//  "orderId": <string>,
//  "pairId": <string>,
//  "quantity": <uint64>,
//  "peerPubKey": <string>,
//  "failureReason": <string>
// }

request = xud.SubscribeSwapsRequest(
  include_taker=<bool>,
)
for response in stub.SubscribeSwapFailures(request):
  print(response)
# Output:
# {
#  "order_id": <string>,
#  "pair_id": <string>,
#  "quantity": <uint64>,
#  "peer_pub_key": <string>,
#  "failure_reason": <string>
# }

Subscribes to failed swaps. By default, only swaps that are initiated by a remote peer are transmitted unless a flag is set to include swaps initiated by the local node. This call allows the client to get real-time notifications when swap attempts are failing. It can be used for status monitoring, debugging, and testing purposes.

Request

Parameter	Type	Description
include_taker	bool	Whether to include the results for swaps initiated via the PlaceOrder or ExecuteSwap calls. These swap results are also returned in the responses for the respective calls.

Response (Streaming)

Parameter	Type	Description
order_id	string	The global UUID for the order that failed the swap.
pair_id	string	The trading pair that the swap is for.
quantity	uint64	The order quantity that was attempted to be swapped.
peer_pub_key	string	The node pub key of the peer that we attempted to swap with.
failure_reason	string	The reason why the swap failed.

SubscribeSwaps

var request = {
  includeTaker: <bool>,
};

var call = xudClient.subscribeSwaps(request);
call.on('data', function (response) {
  console.log(response);
});
call.on('error', function (err) {
  console.error(err);
});
call.on('end', function () {
  // the streaming call has been ended by the server
});
// Output:
// {
//  "orderId": <string>,
//  "localId": <string>,
//  "pairId": <string>,
//  "quantity": <uint64>,
//  "rHash": <string>,
//  "amountReceived": <uint64>,
//  "amountSent": <uint64>,
//  "peerPubKey": <string>,
//  "role": <Role>,
//  "currencyReceived": <string>,
//  "currencySent": <string>,
//  "rPreimage": <string>,
//  "price": <double>
// }

request = xud.SubscribeSwapsRequest(
  include_taker=<bool>,
)
for response in stub.SubscribeSwaps(request):
  print(response)
# Output:
# {
#  "order_id": <string>,
#  "local_id": <string>,
#  "pair_id": <string>,
#  "quantity": <uint64>,
#  "r_hash": <string>,
#  "amount_received": <uint64>,
#  "amount_sent": <uint64>,
#  "peer_pub_key": <string>,
#  "role": <Role>,
#  "currency_received": <string>,
#  "currency_sent": <string>,
#  "r_preimage": <string>,
#  "price": <double>
# }

Subscribes to completed swaps. By default, only swaps that are initiated by a remote peer are transmitted unless a flag is set to include swaps initiated by the local node. This call allows the client to get real-time notifications when its orders are filled by a peer. It can be used for tracking order executions, updating balances, and informing a trader when one of their orders is settled through the Exchange Union network.

Request

Parameter	Type	Description
include_taker	bool	Whether to include the results for swaps initiated via the PlaceOrder or ExecuteSwap calls. These swap results are also returned in the responses for the respective calls.

Response (Streaming)

Parameter	Type	Description
order_id	string	The global UUID for the order that was swapped.
local_id	string	The local id for the order that was swapped.
pair_id	string	The trading pair that the swap is for.
quantity	uint64	The order quantity that was swapped.
r_hash	string	The hex-encoded payment hash for the swap.
amount_received	uint64	The amount received denominated in satoshis.
amount_sent	uint64	The amount sent denominated in satoshis.
peer_pub_key	string	The node pub key of the peer that executed this order.
role	Role	Our role in the swap, either MAKER or TAKER.
currency_received	string	The ticker symbol of the currency received.
currency_sent	string	The ticker symbol of the currency sent.
r_preimage	string	The hex-encoded preimage.
price	double	The price used for the swap.

SubscribeSwapsAccepted

var request = {};

var call = xudClient.subscribeSwapsAccepted(request);
call.on('data', function (response) {
  console.log(response);
});
call.on('error', function (err) {
  console.error(err);
});
call.on('end', function () {
  // the streaming call has been ended by the server
});
// Output:
// {
//  "orderId": <string>,
//  "localId": <string>,
//  "pairId": <string>,
//  "quantity": <uint64>,
//  "price": <double>,
//  "peerPubKey": <string>,
//  "rHash": <string>,
//  "amountReceiving": <uint64>,
//  "amountSending": <uint64>,
//  "currencyReceiving": <string>,
//  "currencySending": <string>
// }

request = xud.SubscribeSwapsAcceptedRequest()
for response in stub.SubscribeSwapsAccepted(request):
  print(response)
# Output:
# {
#  "order_id": <string>,
#  "local_id": <string>,
#  "pair_id": <string>,
#  "quantity": <uint64>,
#  "price": <double>,
#  "peer_pub_key": <string>,
#  "r_hash": <string>,
#  "amount_receiving": <uint64>,
#  "amount_sending": <uint64>,
#  "currency_receiving": <string>,
#  "currency_sending": <string>
# }

Subscribes to accepted swaps. This stream emits a message when the local opendex node accepts a swap request from a peer, but before the swap has actually succeeded.

Request

This request has no parameters.

Response (Streaming)

Parameter	Type	Description
order_id	string	The global UUID for the order that was accepted to be swapped.
local_id	string	The local id for the order that was accepted to be swapped.
pair_id	string	The trading pair that the swap is for.
quantity	uint64	The order quantity that was accepted to be swapped.
price	double	The price for the swap.
peer_pub_key	string	The node pub key of the peer that executed this order.
r_hash	string	The hex-encoded payment hash for the swap.
amount_receiving	uint64	The amount received denominated in satoshis.
amount_sending	uint64	The amount sent denominated in satoshis.
currency_receiving	string	The ticker symbol of the currency received.
currency_sending	string	The ticker symbol of the currency sent.

TradeHistory

var request = {
  limit: <uint32>,
};

xudClient.tradeHistory(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "trades": <Trade[]>
// }

request = xud.TradeHistoryRequest(
  limit=<uint32>,
)
response = xudStub.TradeHistory(request)
print(response)
# Output:
# {
#  "trades": <Trade[]>
# }

  opendex-cli tradehistory [limit]

Gets a list of completed trades.

Request

Parameter	Type	Description
limit	uint32	The maximum number of trades to return

Response

Parameter	Type	Description
trades	Trade array

TradingLimits

var request = {
  currency: <string>,
};

xudClient.tradingLimits(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "limits": <TradingLimits>
// }

request = xud.TradingLimitsRequest(
  currency=<string>,
)
response = xudStub.TradingLimits(request)
print(response)
# Output:
# {
#  "limits": <TradingLimits>
# }

  opendex-cli tradinglimits [currency]

Gets the trading limits for one or all currencies.

Request

Parameter	Type	Description
currency	string	The ticker symbol of the currency to query for, if unspecified then trading limits for all supported currencies are queried.

Response

Parameter	Type	Description
limits	map<string, TradingLimits>	A map between currency ticker symbols and their trading limits.

Unban

var request = {
  nodeIdentifier: <string>,
  reconnect: <bool>,
};

xudClient.unban(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output: {}

request = xud.UnbanRequest(
  node_identifier=<string>,
  reconnect=<bool>,
)
response = xudStub.Unban(request)
print(response)
# Output: {}

  opendex-cli unban <node_identifier> [reconnect]

Removes a ban from a node manually and, optionally, attempts to connect to it.

Request

Parameter	Type	Description
node_identifier	string	The node pub key or alias of the peer to unban.
reconnect	bool	Whether to attempt to connect to the peer after it is unbanned.

Response

This response has no parameters.

WalletWithdraw

var request = {
  currency: <string>,
  destination: <string>,
  amount: <uint64>,
  all: <bool>,
  fee: <uint32>,
};

xudClient.walletWithdraw(request, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(response);
  }
});
// Output:
// {
//  "transactionId": <string>
// }

request = xud.WithdrawRequest(
  currency=<string>,
  destination=<string>,
  amount=<uint64>,
  all=<bool>,
  fee=<uint32>,
)
response = xudStub.WalletWithdraw(request)
print(response)
# Output:
# {
#  "transaction_id": <string>
# }

  opendex-cli withdraw [amount] [currency] <destination> [fee]

Withdraws a given currency from the opendex wallets to a specified address.

Request

Parameter	Type	Description
currency	string	The ticker symbol of the currency to withdraw.
destination	string	The address to withdraw funds to.
amount	uint64	The amount to withdraw denominated in satoshis
all	bool	Whether to withdraw all available funds for this currency. If true, the amount field is ignored.
fee	uint32	The fee to use for the withdrawal transaction denominated in satoshis per byte.

Response

Parameter	Type	Description
transaction_id	string	The id of the withdrawal transaction.

Messages

AddCurrencyResponse

This message has no parameters.

AddPairRequest

Parameter	Type	Description
base_currency	string	The base currency that is bought and sold for this trading pair.
quote_currency	string	The currency used to quote a price for the base currency.

AddPairResponse

This message has no parameters.

Balance

Parameter	Type	Description
total_balance	uint64	Total balance denominated in satoshis.
channel_balance	uint64	Sum of confirmed channel balances denominated in satoshis.
pending_channel_balance	uint64	Sum of pending channel balances denominated in satoshis.
inactive_channel_balance	uint64	Sum of inactive channel balances denominated in satoshis.
wallet_balance	uint64	Confirmed wallet balance in satoshis.
unconfirmed_wallet_balance	uint64	Unconfirmed wallet balance in satoshis.

BanRequest

Parameter	Type	Description
node_identifier	string	The node pub key or alias of the node to ban.

BanResponse

This message has no parameters.

Chain

Parameter	Type	Description
chain	string	The blockchain the swap client is on (eg bitcoin, litecoin)
network	string	The network the swap client is on (eg regtest, testnet, mainnet)

Channels

Parameter	Type	Description
active	uint32	The number of active/online channels for this lnd instance that can be used for swaps.
inactive	uint32	The number of inactive/offline channels for this lnd instance.
pending	uint32	The number of channels that are pending on-chain confirmation before they can be used.
closed	uint32	The number of channels that have been closed.

ChangePasswordRequest

Parameter	Type	Description
new_password	string
old_password	string

ChangePasswordResponse

This message has no parameters.

CloseChannelRequest

Parameter	Type	Description
node_identifier	string	The node pub key or alias of the peer with which to close any channels with.
currency	string	The ticker symbol of the currency of the channel to close.
force	bool	Whether to force close the channel in case the peer is offline or unresponsive.
destination	string	The on-chain address to send funds extracted from the channel. If unspecified, the funds return to the default wallet for the client closing the channel.
amount	uint64	For Connext only - the amount to extract from the channel. If 0 or unspecified, the entire off-chain balance for the specified currency will be extracted.
fee	uint64	A manual fee rate set in sat/byte that should be used when crafting the closure transaction.

CloseChannelResponse

Parameter	Type	Description
transaction_ids	string array	The id of the transaction per channel close.

ConnectRequest

Parameter	Type	Description
node_uri	string	The uri of the node to connect to in "[nodePubKey]@[host]:[port]" format.

ConnectResponse

This message has no parameters.

CreateNodeRequest

Parameter	Type	Description
password	string	The password in utf-8 with which to encrypt the new opendex node key as well as any uninitialized underlying wallets.

CreateNodeResponse

Parameter	Type	Description
seed_mnemonic	string array	The 24 word mnemonic to recover the opendex identity key and underlying wallets
initialized_lnds	string array	The list of lnd clients that were initialized.
initialized_connext	bool	Whether the connext wallet was initialized.

Currency

Parameter	Type	Description
currency	string	The ticker symbol for this currency such as BTC, LTC, ETH, etc...
swap_client	SwapClient	The payment channel network client to use for executing swaps.
token_address	string	The contract address for layered tokens such as ERC20.
decimal_places	uint32	The number of places to the right of the decimal point of the smallest subunit of the currency. For example, BTC, LTC, and others where the smallest subunits (satoshis) are 0.00000001 full units (bitcoins) have 8 decimal places. ETH has 18. This can be thought of as the base 10 exponent of the smallest subunit expressed as a positive integer. A default value of 8 is used if unspecified.

DepositRequest

Parameter	Type	Description
currency	string	The ticker symbol of the currency to deposit.

DepositResponse

Parameter	Type	Description
address	string	The address to use to deposit funds.

DiscoverNodesRequest

Parameter	Type	Description
node_identifier	string	The node pub key or alias of the peer to discover nodes from.

DiscoverNodesResponse

Parameter	Type	Description
num_nodes	uint32

ExecuteSwapRequest

Parameter	Type	Description
order_id	string	The order id of the maker order.
pair_id	string	The trading pair of the swap orders.
peer_pub_key	string	The node pub key of the peer which owns the maker order. This is optional but helps locate the order more quickly.
quantity	uint64	The quantity to swap denominated in satoshis. The whole order will be swapped if unspecified.

GetBalanceRequest

Parameter	Type	Description
currency	string	The ticker symbol of the currency to query for, if unspecified then balances for all supported currencies are queried.

GetBalanceResponse

Parameter	Type	Description
balances	map<string, Balance>	A map between currency ticker symbols and their balances.

GetInfoRequest

This message has no parameters.

GetInfoResponse

Parameter	Type	Description
version	string	The version of this instance of opendex.
node_pub_key	string	The node pub key of this node.
uris	string array	A list of uris that can be used to connect to this node. These are shared with peers.
num_peers	uint32	The number of currently connected peers.
num_pairs	uint32	The number of supported trading pairs.
orders	OrdersCount	The number of active, standing orders in the order book.
lnd	map<string, LndInfo>
alias	string	The alias of this instance of opendex.
network	string	The network of this node.
pending_swap_hashes	string array
connext	ConnextInfo

GetMnemonicRequest

This message has no parameters.

GetMnemonicResponse

Parameter	Type	Description
seed_mnemonic	string array

GetNodeInfoRequest

Parameter	Type	Description
node_identifier	string	The node pub key or alias of the node for which to get information.

GetNodeInfoResponse

Parameter	Type	Description
reputationScore	sint32	The node's reputation score. Points are subtracted for unexpected or potentially malicious behavior. Points are added when swaps are successfully executed.
banned	bool	Whether the node is currently banned.

ListCurrenciesRequest

This message has no parameters.

ListCurrenciesResponse

Parameter	Type	Description
currencies	Currency array	The list of available currencies in the orderbook.

ListOrdersRequest

Parameter	Type	Description
pair_id	string	The trading pair for which to retrieve orders.
owner	Owner	Whether only own, only peer or both orders should be included in result.
limit	uint32	The maximum number of orders to return from each side of the order book.
include_aliases	bool	Whether to include the node aliases of owners of the orders.

ListOrdersResponse

Parameter	Type	Description
orders	map<string, Orders>	A map between pair ids and their buy and sell orders.

ListPairsRequest

This message has no parameters.

ListPairsResponse

Parameter	Type	Description
pairs	string array	The list of supported trading pair tickers in formats like "LTC/BTC".

ListPeersRequest

This message has no parameters.

ListPeersResponse

Parameter	Type	Description
peers	Peer array	The list of connected peers.

LndInfo

Parameter	Type	Description
status	string
channels	Channels
chains	Chain array
blockheight	uint32
uris	string array
version	string
alias	string

NodeIdentifier

Parameter	Type	Description
node_pub_key	string	The pub key of this node
alias	string	An alias for this node deterministically generated from the pub key

OpenChannelRequest

Parameter	Type	Description
node_identifier	string	The node pub key or alias of the peer with which to open channel with.
currency	string	The ticker symbol of the currency to open the channel for.
amount	uint64	The amount to be deposited into the channel denominated in satoshis.
push_amount	uint64	The balance amount to be pushed to the remote side of the channel denominated in satoshis.
fee	uint64	The manual fee rate set in sat/byte that should be used when crafting the funding transaction in the channel.

OpenChannelResponse

Parameter	Type	Description
transaction_id	string	The id of the transaction that opened the channel.

Order

Parameter	Type	Description
price	double	The price of the order.
quantity	uint64	The quantity of the order in satoshis.
pair_id	string	The trading pair that this order is for.
id	string	A UUID for this order.
node_identifier	NodeIdentifier	The identifier of the node that created this order.
local_id	string	The local id for this order, if applicable.
created_at	uint64	The epoch time in milliseconds when this order was created.
side	OrderSide	Whether this order is a buy or sell
is_own_order	bool	Whether this order is a local own order or a remote peer order.
hold	uint64	The quantity on hold pending swap execution.

OrderBookRequest

Parameter	Type	Description
pair_id	string	The trading pair for which to retrieve orders.
precision	int32	The number of digits to the right of the decimal point for each price bucket. A negative number rounds digits to the left of the decimal point, e.g. -2 would round to the hundreds place.
limit	uint32	The maximum number of price "buckets" to return, if zero or unspecified then no limit is imposed.

OrderBookResponse

Parameter	Type	Description
price	double	The rounded price of the bucket.
quantity	uint64	The total quantity for all orders that fall into this bucket.
sell_buckets	Bucket array	A sorted list of buckets for sell orders
buy_buckets	Bucket array	A sorted list of buckets for buy orders.
buckets	map<string, Buckets>	A map between currency tickers and sorted lists of order buckets

Bucket

Parameter	Type	Description
price	double	The rounded price of the bucket.
quantity	uint64	The total quantity for all orders that fall into this bucket.

Buckets

Parameter	Type	Description
sell_buckets	Bucket array	A sorted list of buckets for sell orders
buy_buckets	Bucket array	A sorted list of buckets for buy orders.

OrderRemoval

Parameter	Type	Description
quantity	uint64	The quantity removed from the order.
pair_id	string	The trading pair that the order is for.
order_id	string	The global UUID for the order.
local_id	string	The local id for the order, if applicable.
is_own_order	bool	Whether the order being removed is a local own order or a remote peer order.

Orders

Parameter	Type	Description
buy_orders	Order array	A list of buy orders sorted by descending price.
sell_orders	Order array	A list of sell orders sorted by ascending price.

OrdersCount

Parameter	Type	Description
peer	uint32	The number of orders belonging to remote opendex nodes.
own	uint32	The number of orders belonging to our local opendex node.

OrderUpdate

Parameter	Type	Description
order	Order	An order that was added to the order book.
order_removal	OrderRemoval	An order (or portion thereof) that was removed from the order book.

Peer

Parameter	Type	Description
address	string	The socket address with host and port for this peer.
node_pub_key	string	The node pub key to uniquely identify this peer.
lnd_pub_keys	map<string, string>	A map of ticker symbols to lnd pub keys for this peer
inbound	bool	Indicates whether this peer was connected inbound.
pairs	string array	A list of trading pair tickers supported by this peer.
xud_version	string	The version of opendex being used by the peer.
seconds_connected	uint32	The time in seconds that we have been connected to this peer.
alias	string	The alias for this peer's public key
currency	string	A map of ticker symbols to lnd uris for this peer
uri	string array
lnd_uris	LndUris array
connext_identifier	string	The connext identifier for this peer

LndUris

Parameter	Type	Description
currency	string
uri	string array

PlaceOrderRequest

Parameter	Type	Description
price	double	The price of the order.
quantity	uint64	The quantity of the order denominated in satoshis.
pair_id	string	The trading pair that the order is for.
order_id	string	The local id to assign to the order.
side	OrderSide	Whether the order is a buy or sell.
replace_order_id	string	The local id of an existing order to be replaced. If provided, the order must be successfully found and removed before the new order is placed, otherwise an error is returned.
immediate_or_cancel	bool	Whether the order must be filled immediately and not allowed to enter the order book.

PlaceOrderResponse

Parameter	Type	Description
internal_matches	Order array	A list of own orders (or portions thereof) that matched the newly placed order.
swap_successes	SwapSuccess array	A list of successful swaps of peer orders that matched the newly placed order.
remaining_order	Order	The remaining portion of the order, after matches, that enters the order book.
swap_failures	SwapFailure array	A list of swap attempts that failed.

PlaceOrderEvent

Parameter	Type	Description
match	Order	An order (or portion thereof) that matched the newly placed order.
swap_success	SwapSuccess	A successful swap of a peer order that matched the newly placed order.
remaining_order	Order	The remaining portion of the order, after matches, that enters the order book.
swap_failure	SwapFailure	A swap attempt that failed.

ConnextInfo

Parameter	Type	Description
status	string
address	string
version	string
chain	string

RemoveCurrencyRequest

Parameter	Type	Description
currency	string	The ticker symbol for this currency such as BTC, LTC, ETH, etc...

RemoveCurrencyResponse

This message has no parameters.

RemoveOrderRequest

Parameter	Type	Description
order_id	string	The local id of the order to remove.
quantity	uint64	The quantity to remove from the order denominated in satoshis. If zero or unspecified then the entire order is removed.

RemoveOrderResponse

Parameter	Type	Description
quantity_on_hold	uint64	Any portion of the order that was on hold due to ongoing swaps at the time of the request and could not be removed until after the swaps finish.
remaining_quantity	uint64	Remaining portion of the order if it was a partial removal.
removed_quantity	uint64	Successfully removed portion of the order.
pair_id	string	Removed order's pairId. (e.g. ETH/BTC)

RemoveAllOrdersRequest

This message has no parameters.

RemoveAllOrdersResponse

Parameter	Type	Description
removed_order_ids	string array	The local order ids that were successfully removed.
on_hold_order_ids	string array	The local order ids that were on hold and failed to be removed.

RemovePairRequest

Parameter	Type	Description
pair_id	string	The trading pair ticker to remove in a format such as "LTC/BTC".

RemovePairResponse

This message has no parameters.

RestoreNodeRequest

Parameter	Type	Description
seed_mnemonic	string array	The 24 word mnemonic to recover the opendex identity key and underlying wallets
password	string	The password in utf-8 with which to encrypt the restored opendex node key as well as any restored underlying wallets.
lnd_backups	map<string, bytes>	A map between the currency of the LND and its multi channel SCB
xud_database	bytes	The opendex database backup

RestoreNodeResponse

Parameter	Type	Description
restored_lnds	string array	The list of lnd clients that were initialized.
restored_connext	bool	Whether the connext wallet was initialized.

SetLogLevelRequest

Parameter	Type	Description
log_level	LogLevel

SetLogLevelResponse

This message has no parameters.

ShutdownRequest

This message has no parameters.

ShutdownResponse

This message has no parameters.

SubscribeOrdersRequest

Parameter	Type	Description
existing	bool	Whether to transmit all existing active orders upon establishing the stream.

SubscribeSwapsAcceptedRequest

This message has no parameters.

SubscribeSwapsRequest

Parameter	Type	Description
include_taker	bool	Whether to include the results for swaps initiated via the PlaceOrder or ExecuteSwap calls. These swap results are also returned in the responses for the respective calls.

SwapAccepted

Parameter	Type	Description
order_id	string	The global UUID for the order that was accepted to be swapped.
local_id	string	The local id for the order that was accepted to be swapped.
pair_id	string	The trading pair that the swap is for.
quantity	uint64	The order quantity that was accepted to be swapped.
price	double	The price for the swap.
peer_pub_key	string	The node pub key of the peer that executed this order.
r_hash	string	The hex-encoded payment hash for the swap.
amount_receiving	uint64	The amount received denominated in satoshis.
amount_sending	uint64	The amount sent denominated in satoshis.
currency_receiving	string	The ticker symbol of the currency received.
currency_sending	string	The ticker symbol of the currency sent.

SwapFailure

Parameter	Type	Description
order_id	string	The global UUID for the order that failed the swap.
pair_id	string	The trading pair that the swap is for.
quantity	uint64	The order quantity that was attempted to be swapped.
peer_pub_key	string	The node pub key of the peer that we attempted to swap with.
failure_reason	string	The reason why the swap failed.

SwapSuccess

Parameter	Type	Description
order_id	string	The global UUID for the order that was swapped.
local_id	string	The local id for the order that was swapped.
pair_id	string	The trading pair that the swap is for.
quantity	uint64	The order quantity that was swapped.
r_hash	string	The hex-encoded payment hash for the swap.
amount_received	uint64	The amount received denominated in satoshis.
amount_sent	uint64	The amount sent denominated in satoshis.
peer_pub_key	string	The node pub key of the peer that executed this order.
role	Role	Our role in the swap, either MAKER or TAKER.
currency_received	string	The ticker symbol of the currency received.
currency_sent	string	The ticker symbol of the currency sent.
r_preimage	string	The hex-encoded preimage.
price	double	The price used for the swap.

Trade

Parameter	Type	Description
maker_order	Order	The maker order involved in this trade.
taker_order	Order	The taker order involved in this trade. Note that when a trade occurs from a remote peer filling one of our orders, we do not receive the order (only a swap request) and this field will be empty.
r_hash	string	The payment hash involved in this trade.
quantity	uint64	The quantity transacted in this trade.
pair_id	string	The trading pair for this trade.
price	double	The price used for the trade.
role	Role	Our role in the trade.
executed_at	uint64	The epoch time in milliseconds that this trade was executed
side	OrderSide	Whether this node was on the buy or sell side of the trade - or both in case of internal trades.
counterparty	NodeIdentifier	The counterparty to this trade, if applicable.

TradeHistoryRequest

Parameter	Type	Description
limit	uint32	The maximum number of trades to return

TradeHistoryResponse

Parameter	Type	Description
trades	Trade array

TradingLimits

Parameter	Type	Description
max_sell	uint64	Maximum outbound limit for a sell order denominated in satoshis.
max_buy	uint64	Maximum inbound limit for a buy order denominated in satoshis.
reserved_sell	uint64	The outbound amount reserved for open sell orders.
reserved_buy	uint64	The inbound amount reserved for open buy orders.

TradingLimitsRequest

Parameter	Type	Description
currency	string	The ticker symbol of the currency to query for, if unspecified then trading limits for all supported currencies are queried.

TradingLimitsResponse

Parameter	Type	Description
limits	map<string, TradingLimits>	A map between currency ticker symbols and their trading limits.

UnbanRequest

Parameter	Type	Description
node_identifier	string	The node pub key or alias of the peer to unban.
reconnect	bool	Whether to attempt to connect to the peer after it is unbanned.

UnbanResponse

This message has no parameters.

UnlockNodeRequest

Parameter	Type	Description
password	string	The password in utf-8 with which to unlock an existing opendex node key as well as underlying client wallets such as lnd.

UnlockNodeResponse

Parameter	Type	Description
unlocked_lnds	string array	The list of lnd clients that were unlocked.
locked_lnds	string array	The list of lnd clients that could not be unlocked.

WithdrawRequest

Parameter	Type	Description
currency	string	The ticker symbol of the currency to withdraw.
destination	string	The address to withdraw funds to.
amount	uint64	The amount to withdraw denominated in satoshis
all	bool	Whether to withdraw all available funds for this currency. If true, the amount field is ignored.
fee	uint32	The fee to use for the withdrawal transaction denominated in satoshis per byte.

WithdrawResponse

Parameter	Type	Description
transaction_id	string	The id of the withdrawal transaction.

Enums

OrderSide

Enumeration	Value	Description
BUY	0
SELL	1
BOTH	2

Role

Enumeration	Value	Description
TAKER	0
MAKER	1
INTERNAL	2

LogLevel

Enumeration	Value	Description
ALERT	0
ERROR	1
WARN	2
INFO	3
VERBOSE	4
DEBUG	5
TRACE	6

SwapClient

Enumeration	Value	Description
LND	0
CONNEXT	1

Owner

Enumeration	Value	Description
BOTH	0
OWN	1
PEER	2