-
Notifications
You must be signed in to change notification settings - Fork 140
Client control API
Bison Wallet (bisonw) can be controlled via its remote procedure call (RPC) interface.
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
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.
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. |
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. |
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". |
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. |
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". |
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". |
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". |
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 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. |
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. |
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. |
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 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 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 of Bison Wallet. Accepts no arguments.
Request route: logout
Response
The response will contain a message.
payload
| type | description |
|---|---|
| string | The message "goodbye" |
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. |
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. |
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".
An example of setting up both an https and wss connection to the RPC server can be found here