Skip to content

Client control API

Brian Stafford edited this page Jul 27, 2024 · 2 revisions

Table of Contents

Bison Wallet (bisonw)

RPC

Bison Wallet (bisonw) can be controlled via its remote procedure call (RPC) interface.

HTTPS

All HTTP requests sent to the RPC server must contain basic auth with a user:password pair that the client's RPC interface will accept.

Communication is done using tls.

Requests must be constructed as specified in Message Protocol

Payload

All requests use the same payload structure. All individual arguments are strings. Return values vary.

payload

field type description
PWArgs [string] An array of password arguments. Can be null.
args [string] An array of arguments. Can be null.

Arguments in arrays are positional and must be placed in the order they appear here. If an argument is optional, but a placeholder is needed, an empty string "" can be used. Arguments have a pseudo-type. For example, if boolean, the argument must be the string representation of a truthy value. i.e. "true" or "1"

Returns will come with an error if there was a problem. If arguments could not be parsed, a help message for that specific route/command is returned.

Help

Print a help message.

Request route: help

args

name pseudo-type description
cmd string Optional. The command to print help for.
includePasswords bool Optional. Default is false. Whether to include password arguments in the returned help. Passwords are hidden when using bwctl.

Response

The response will contain a help message based on the arguments.

payload

type description
string The help message for command.

Version

Print the Bison Wallet rpcserver version. Accepts no arguments

Request route: version

Response

The response will contain the semver as a string. i.e. "1.0.0"

payload

type description
string The Bison Wallet rpcserver version.

Init

Initialize the client with a password.

Request route: init

PWArgs

name type description
appPass string The Bison Wallet password.

Response

The response will contain a message.

payload

type description
string The message "app initialized".

Get Fee

Print a help message.

Request route: getfee

args

name pseudo-type description
dex string The DEX address for which the registration fee should be retrieved.
cert string Optional. The TLS certificate path.

Response

The response will contain the fee.

payload

type description
object The getFee result.

JSON GetFeeResult object

field type description
fee int The DEX registration fee.

New Wallet

Connect to a new wallet.

Request route: newwallet

PWArgs

name type description
appPass string The Bison Wallet password.
walletPass string The wallet's password. The client will encrypt and store this.

args

name pseudo-type description
cmd string Optional. The command to print help for.
assetID int The asset's BIP-44 registered coin index. e.g. 42 for DCR. See slip0044
path string Optional. Text from a configuration file.
settings object Optional. A JSON-encoded string->string mapping of additional configuration settings. These settings take precedence over any settings parsed from file. e.g. '{"account":"default"}' for Decred accounts, and '{"walletname":""}' for the default Bitcoin wallet where bitcoind's listwallets RPC gives possible walletnames.

Response

The response will contain a message.

payload

type description
string The message "[coin symbol] wallet created and unlocked".

Open Wallet

Unlock an existing wallet for one year.

Request route: openwallet

PWArgs

name type description
appPass string The Bison Wallet password.

args

name pseudo-type description
assetID int The asset's BIP-44 registered coin index. e.g. 42 for DCR. See slip0044

Response

The response will contain a message.

payload

type description
string The message "[coin symbol] wallet unlocked".

Close Wallet

Lock an existing wallet.

Request route: lockwallet

args

name pseudo-type description
assetID int The asset's BIP-44 registered coin index. e.g. 42 for DCR. See slip0044

Response

The response will contain a message.

payload

type description
string The message "[coin symbol] wallet locked".

Wallets

Get information about all wallets registered with the client. Accepts no arguments.

Request route: wallets

Response

The response will contain an array of information for each wallet.

payload

type description
[object] A list of WalletInfo objects (described below).

JSON WalletInfo object

field type description
symbol string The coin symbol.
assetID int The asset's BIP-44 registered coin index. e.g. 42 for DCR. See slip0044
open bool Whether the wallet is unlocked.
running bool Whether the wallet is running.
updated int Unix time of last balance update. Seconds since 00:00:00 Jan 1 1970.
balance object A Balance object (described below).
address string A wallet address.
feerate int The fee rate.
units string Unit of measure for amounts.

JSON Balance object

field type description
available int The balance available for funding orders case.
immature int Balance that requires confirmations before use.
locked int The total locked balance.
stamp string Time stamp.

Register

Register for a DEX. An OK response does not mean that registration is complete. Registration is complete after the fee transaction has been confirmed.

Request route: register

PWArgs

name type description
appPass string The Bison Wallet password.

args

name pseudo-type description
addr string The DEX address to register for.
fee int The DEX fee.
cert string Optional. The TLS certificate.

Response

The response will contain a RegisterResult object.

payload

type description
object The RegisterResult (described below).

JSON RegisterResult object

field type description
feeID string The fee transaction's ID and output index.
reqConfirms int The number of confirmations required to start trading.

Exchanges

Detailed information about known exchanges and markets. Arguments not accepted.

Request route: exchanges

Response

The response will contain an Exchanges object.

payload

type description
object An Exchanges object (described below).

JSON Exchanges object

field type description
[DEX host] object Repeating. An Exchange object (described below)

JSON Exchange object

field type description
markets object A Markets object (described below).
assets object An Assets object (described below).
confsrequired int The number of confirmations needed for the registration fee payment.
confs int The current number of confirmations for the registration fee payment. This is only present during the registration process.

JSON Markets object

field type description
[assetSymbol-assetSymbol] object Repeating. A Market object (described below)

JSON Market object

field type description
baseid int The base asset ID.
basesymbol string The base ticker symbol.
quoteid int The quote asset ID.
quotesymbol string The quote asset ID symbol,
epochlen int Duration of a epoch in milliseconds.
startepoch int Time of start of the last epoch in milliseconds since 00:00:00 Jan 1 1970.
buybuffer float The minimum order size for a market buy order.

JSON Assets object

field type description
[assetID] object Repeating. An Asset object (described below)

JSON Asset object

field type description
symbol string The asset's coin symbol.
lotSize int The amount of units of a coin in one lot.
rateStep int the price rate increment in atoms.
feeRate int The transaction fee in atoms per byte.
swapSize int The size of a swap transaction in bytes.
swapSizeBase int The size of a swap transaction minus inputs in bytes.
swapConf int The number of confirmations needed to confirm trade transactions.

Login

Attempt to login to all registered DEX servers.

Request route: login

PWArgs

name type description
appPass string The Bison Wallet password.

Response

The response will contain a LoginResult.

payload

type description
object The LoginResult (described below).

JSON LoginResult object

field type description
notification [object] A list of Notification objects (described below).
dexes [object] A list of Dex objects (described below).

JSON Notification object

field type description
type string The notification type.
subject string A clarification of type.
details string The notification details.
severity int The importance of the notification on a scale of 0 through 5.
stamp int Unix time of the notification. Seconds since 00:00:00 Jan 1 1970.
acked bool Whether the notification was acknowledged.
id string A unique hex ID.

JSON DEX object

field type description
host string The DEX address.
acctID string A unique hex ID.
authed bool If successfully authenticated with the DEX.
autherr string Omitted if authed. If not authed, the reason.
tradeIDs [string] An array of active trade IDs.

Trade

Make an order to buy or sell an asset.

Request route: trade

PWArgs

name type description
appPass string The Bison Wallet password.

args

name pseudo-type description
host string The DEX to trade on.
isLimit bool Whether the order is a limit order.
sell bool Whether the order is selling.
base int The BIP-44 coin index for the market's base asset.
quote int The BIP-44 coin index for the market's quote asset.
qty int The number of units to buy/sell. Must be a multiple of the lot size.
rate int The atoms quote asset to pay/accept per unit base asset. e.g. 156000 satoshi/DCR for the DCR(base)_BTC(quote).
immediate bool Require immediate match. Do not book the order.

Response

The response will contain an OrderDetails.

payload

type description
object An OrderDetails object (describled below).

JSON OrderDetails object

field type description
orderid string The order's unique hex identifier.
sig string The DEX's signature of the order information.
stamp int The time the order was signed in milliseconds since 00:00:00 Jan 1 1970.

Cancel

Cancel an order.

Request route: cancel

PWArgs

name type description
appPass string The Bison Wallet password.

args

name pseudo-type description
orderID string The hex ID of the order to cancel.

Response

The response will contain a message.

payload

type description
string The message "canceled order [order ID]".

Withdraw

Withdraw value from an exchange wallet to address.

Request route: withdraw

PWArgs

name type description
appPass string The Bison Wallet password.

args

name pseudo-type description
assetID int The asset's BIP-44 registered coin index. Used to identify which wallet to withdraw from. e.g. 42 for DCR. See slip0044
value int The amount to withdraw in units of the asset's smallest denomination (e.g. satoshis, atoms, etc.)
address string The address to which withdrawn funds are sent.

Response

The response will contain coin ID of the withdraw transaction.

payload

type description
string "[coin ID]".

Logout

Logout of Bison Wallet. Accepts no arguments.

Request route: logout

Response

The response will contain a message.

payload

type description
string The message "goodbye"

Order Book

Retrieve all orders for a market.

Request route: orderbook

args

name pseudo-type description
host string The DEX to retrieve the order book from.
base int The BIP-44 coin index for the market's base asset.
quote int The BIP-44 coin index for the market's quote asset.
nOrders int Optional. Default is 0, which returns all orders. The number of orders from the top of buys and sells to return. Epoch orders are not truncated.

Response

The response will contain an OrderBook object.

payload

type description
object An OrderBook object (described below).

JSON OrderBook object

field type description
sells [object] An array of booked MiniOrder objects (described below).
buys [object] An array of booked buy MiniOrder objects.
epoch [object] An array of epoch MiniOrder objects. Epoch orders include all kinds of orders, even those that cannot or may not be booked. They are not truncated.

JSON MiniOrder object

field type description
qty float The number of coins base asset being bought or sold.
rate float The coins quote asset to accept per coin base asset.
sell bool Whether this order is a sell order.
token string The first 8 bytes of the order id, coded in hex.
epoch int Only present for epoch orders. The order's epoch.

My Orders

Fetch all active and recently executed orders belonging to the user.

Request route: myorders

args

name pseudo-type description
host string Optional. The DEX to show orders from.
base int Optional. The BIP-44 coin index for the market's base asset.
quote int Optional. The BIP-44 coin index for the market's quote asset.

Response

The response will contain a list of Order objects.

payload

type description
[object] A list of Order objects (described below).

JSON Order object

field type description
host string The DEX address.
marketName string The market's name. e.g. "DCR_BTC".
baseID int The market's base asset BIP-44 coin index. e.g. 42 for DCR.
quoteID int The market's quote asset BIP-44 coin index. e.g. 0 for BTC.
id string The order's unique hex ID.
type string The type of order. "limit", "market", or "cancel".
sell string Whether this order is selling.
stamp int Time the order was made in milliseconds since 00:00:00 Jan 1 1970.
age string The time that this order has been active in human readable form.
rate int The exchange rate limit. Limit orders only. Units: quote asset per unit base asset.
quantity int The amount being traded.
filled int The order quantity that has matched.
settled int The sum quantity of all completed matches.
status string The status of the order. "epoch", "booked", "executed", "canceled", or "revoked".
cancelling bool Whether this order is in the process of cancelling.
canceled bool Whether this order has been canceled.
tif string "immediate" if this limit order will only match for one epoch. "standing" if the order can continue matching until filled or cancelled.

WebSocket

A connection to the WebSocket server can be made through the RPC server. The websocket server server allows for notifications from a market and other long running operations.

Connect by providing proper credentials and a valid header when visiting "wss://[RPC Server Address]/ws".

Examples

An example of setting up both an https and wss connection to the RPC server can be found here