Bitsquare API Specification

/api/account_list

Lists my accounts.

Sample Request

http://localhost/api/account_list

Sample Response

[ { "account_id": "c4e4645a-18e6-45be-8853-c7ebac68f0a4", "created": 1473010076100, "payment_method": { "payment_method_id": "SEPA", "lock_time": 0, "max_trade_period": 691200000, "max_trade_limit": { "value": 75000000, "positive": true, "zero": false, "negative": false } }, "account_name": "SEPA, EUR, BE, BE...", "trade_currencies": ['EUR'], "selected_trade_currency": 'EUR', "contract_data": { "payment_method_name": "SEPA", "contract_id": "c4e4645a-18e6-45be-8853-c7ebac68f0a4", "max_trade_period": 691200000, "country_code": "BE", "holder_name": "Mike Rosseel", "iban": "BE82063500018968", "bic": "GKCCBEBB", "accepted_country_codes": ["AT", "BE", "CY", "DE", "EE", "ES", "FI", "FR", "GR", "IE", "IT", "LT", "LU", "LV", "MC", "MT", "NL", "PT", "SI", "SK"], "payment_details": "SEPA - Holder name: Mike Rosseel, IBAN: BE82063500018968, BIC: GKCCBEBB, country code: BE", "payment_details_for_trade_popup": "Holder name: Mike Rosseel IBAN: BE82063500018968 BIC: GKCCBEBB Country of bank: Belgium (BE)" }, "country": { "code": "BE", "name": "Belgium", "region": { "code": "EU", "name": "Europe" } }, "accepted_country_codes": ["AT", "BE", "CY", "DE", "EE", "ES", "FI", "FR", "GR", "IE", "IT", "LT", "LU", "LV", "MC", "MT", "NL", "PT", "SI", "SK"], "bank_id": "GKCCBEBB", "iban": "BE82063500018968", "holder_name": "Mike Rosseel", "bic": "GKCCBEBB", "single_trade_currency": 'EUR', "payment_details": "SEPA - Holder name: Mike Rosseel, IBAN: BE82063500018968, BIC: GKCCBEBB, country code: BE" }, ... ]

Parameters

None

Notes

TODO: document which fields are constant for all account types.

/api/currency_list

Returns list of all currencies.

Sample Request

http://localhost/api/currency_list

Sample Response

[ { "symbol": "ETH", "name": "Ethereum", "type": "crypto", "precision": 8, "display_precision": 8 }, { "symbol": "EUR", "name": "Euro", "type": "fiat", "precision": 8, "display_precision": 2 }, ... ]

Parameters

None

/api/market_list

Returns list of all markets.

Sample Request

http://localhost/api/market_list

Sample Response

[ { "pair": "dash_btc", "lsymbol": "DASH", "rsymbol": "BTC", }, ... ]

Parameters

None

/api/offer_cancel

Cancels an existing offer

Sample Request

http://localhost/api/offer_cancel?offer_id=f6dab9d5-163f-4c2a-9c35-2d4c54da82e3

Sample Response

true

Parameters

param	type	desc	required	values	default
offer_id	string	Identifies offer to cancel	Yes

Notes

TBD: other info should be returned related to refund?

/api/offer_detail

Returns details of a specific offer.

Sample Request

http://localhost/api/offer_detail?offer_id=f6dab9d5-163f-4c2a-9c35-2d4c54da82e3

Sample Response

{ "offer_id": "f6dab9d5-163f-4c2a-9c35-2d4c54da82e3", "direction": "sell", "status": "live", "funding": { "deposit_amount": 0.01, "deposit_address": "14w4mZx4b6JjtEd9BZPnLCSXzbHjKH3Pn3", "tx-list": [ { "txid": "a8fe8f3f76cf28487be20fe5030243ac12348cd4033450414de7a4670bb0fb89", "confirmations": 3 } ] }, "btc_amount": 1.0, "min_btc_amount": 0.2, "other_amount": 230, "price": 232.3, "price-detail": { "type": "percentage", "percent": 0.01, "market-price": 230 }, "created": 1471632887, "deposit": 0.01, "offerer": "a2wt75feadp232wx.onion:9999", "arbitrators": [ "pkfcmj42c6es6tjt.onion:9999", "ntjhaj27rylxwvnp.onion:9999" ] }

Parameters

param	type	desc	required	values	default
offer_id	string	Identifies the offer	Yes

Notes

Returns an error if insufficient funds in wallet.

Sample Request

http://localhost/api/offer_list?market=xmr_btc&whose=mine

Sample Response

[ { "offer_id": "f6dab9d5-163f-4c2a-9c35-2d4c54da82e3", "direction": "sell", "status": "live", "funding": { "deposit_amount": 0.01, "deposit_address": "14w4mZx4b6JjtEd9BZPnLCSXzbHjKH3Pn3", "tx-list": [ { "txid": "a8fe8f3f76cf28487be20fe5030243ac12348cd4033450414de7a4670bb0fb89", "confirmations": 3 } ] }, "btc_amount": 1.0, "min_btc_amount": 0.2, "other_amount": 230, "price": 232.3, "price-detail": { "type": "percentage", "percent": 0.01, "market-price": 230 }, "created": 1471632887, "offerer": "a2wt75feadp232wx.onion:9999", "arbitrators": [ "pkfcmj42c6es6tjt.onion:9999", "ntjhaj27rylxwvnp.onion:9999" ] } ... ]

Parameters

param	type	desc	required	values	default
market	string	filter by market	No	\| "all"	all
status	string	filter by status	No	"unfunded" \| "live" \| "done" \| "cancelled" \| "all"	all
whose	string	filter by offer creator	No	"mine" \| "notmine" \| "all"	all
start	longint	find offers after start time. seconds since 1970.	No		0
end	longint	find offers before end time. seconds since 1970.	No		9223372036854775807
limit	int	max records to return	No		100

Notes

price-detail/type may be "percentage" or "fixed". If percentage, then the value of "price" may change from call-to-call depending on the current value of "market-price". If "fixed", then price is static and the price-detail/percent key will not be present.
when status == "done", there will now exist a trade with the same trade_id as the offer_id.
TBD: Can we give trade its own trade_id distinct from offer_id? seems cleaner.

Sample Request

http://localhost/api/offer_make?market=xmr_btc&direction=buy&amount=1.2&min_amount=0.25&price=0.01925

Sample Response

{ "offer_id": "f6dab9d5-163f-4c2a-9c35-2d4c54da82e3", "deposit_amount": "0.0107", "deposit_address": "14w4mZx4b6JjtEd9BZPnLCSXzbHjKH3Pn3", "detail": { "direction": "buy", "amount": "1.2", "min_amount": "0.25", "price": "0.01925", "security_deposit": "0.01", "trade_fee": "0.0005", "mining_fee": "0.0002", } }

Parameters

param	type	desc	required	values	default
market	string	identifies the market this offer will be placed in	Yes
account_id	string	identifies the account to which funds will be received once offer is executed.	Yes
direction	string	defines if this is an offer to buy or sell	Yes	sell \| buy
amount	real	amount to buy or sell, in terms of left side of market pair	Yes
min_amount	real	minimum amount to buy or sell, in terms of left side of market pair	Yes
price_type	string	defines if this is a fixed offer or a percentage offset from present market price.	No	fixed \| percentage	fixed
price	string	interpreted according to "price-type". Percentages should be expressed in decimal form eg 1/2 of 1% = "0.005" and must be positive	Yes

Notes

The offer must be funded before it will be placed in offer book
Funding can be done from Bitsquare internal wallet by calling wallet_fund_offer_internal, or from an external wallet by sending 'deposit_amount' to 'deposit_address'
full details about the offer can be retrieved with offer_detail.
'account_id' must refer to an account denominated in the same currency as 'market'

Sample Request

http://localhost/api/offer_take?offer_id=f6dab9d5-163f-4c2a-9c35-2d4c54da82e3&account_id=6d4c54da82e3&amount=0.55

Sample Response

{ "offer_id": "1345132452341234322341234", "deposit_amount": 1.0103, "deposit_address": "12gWwt6bRDDEa6BJPkWoYpn2aoq8ayhFe9", "detail": { "account_id": "6d4c54da82e3", "trade_amount": "0.55", "security_deposit": 0.01, "trade_fee": 0.0001, "mining_fee": 0.0002 } }

Parameters

param	type	desc	required
offer_id	string	Identifies the offer to accept	Yes
account_id	string	Identifies the payment account to receive funds into	Yes
amount	string	amount to spend	Yes

Notes

"trade_amount" may or may not be present depending on caller's trade direction. ( Present when buying BTC. Absent when selling. )
The trade can be funded by sending payment from an external wallet or by calling wallet_fund_offer_internal
The offer is not considered taken until funds are received.

Sample Request

http://localhost/api/trade_detail?trade_id=f6dab9d5-163f-4c2a-9c35-2d4c54da82e3

Sample Response

{ "trade_id": "5b6502f3-057e-454d-8ac5-8430f75b97c2", "market": "XMR/BTC", "direction": "BUY", "price": 2349100, "amount": 20000000, "trade_date": 1471701655737, "payment_method": "BLOCK_CHAINS", "offer_date": 1471689741937, "use_market_based_price": true, "market_price_margin": 0.015, "offer_amount": 20000000, "offer_min_amount": 20000000, "deposit_tx_id": "8e4801f91fea301740c35fe1dbce918d94510d33f8ca484652838bc76c687817", "offer_id": "3c6502f3-057e-454d-8ac5-8430f75b97c4", "status": { "maker": // TODO "taker": // TODO } }

Parameters

param	type	desc	required	values	default
trade_id	string	Identifies the trade	Yes

Notes

the status fields will be used for client's to poll while waiting for trade to complete. Possibly we could make a separate (faster) API for this purpose.

/api/wallet_addresses

Returns list of wallet addresses.

Sample Request

http://localhost/api/wallet_addresses?status=funded

Sample Response

[ { "address": "14w4mZx4b6JjtEd9BZPnLCSXzbHjKH3Pn3", "balance": 1.3453 }, ... ]

Parameters

param	type	desc	required	values	default
status	string	filter by wether each address has a non-zero balance or not	No	funded \| unfunded \| both	both
start	int	starting index, zero based	No		0
limit	int	max number of addresses to return.	No		100

/api/wallet_deposit_address

Returns a new, unused wallet address for deposit purposes.

Sample Request

http://localhost/api/wallet_deposit_address

Sample Response

"14w4mZx4b6JjtEd9BZPnLCSXzbHjKH3Pn3"

Parameters

param	type	desc	required	values	default
force_unique	bool	if true each address will be given out only once. else unused addresses may be given out multiple times to avoid hd-wallet gaps	No	true \| false	false

/api/wallet_detail

Returns wallet info. balance, etc.

Sample Request

http://localhost/api/wallet_detail

Sample Response

{ "available_balance": 1.5623, "reserved_balance": 0.32, "locked_balance": 0.0125 // TBD }

Parameters

None

/api/wallet_fund_offer_internal

Moves BTC funds from internal wallet to offer, at time of offer creation.

Sample Request

http://localhost/api/wallet_fund_offer?offer_id=f6dab9d5-163f-4c2a-9c35-2d4c54da82e3

Sample Response

{ "offer_id": "f6dab9d5-163f-4c2a-9c35-2d4c54da82e3", "funded": true, "funds_moved": 1.342, "source_address": "<btc addr>" }

Parameters

param	type	desc	required	values	default
offer_id	string	Identifies the offer to fund	Yes
source_address	string	identifies bitcoin source address for coin selection. if omitted, an address will be selected automatically.	No

Notes

Returns an error if insufficient funds in wallet.
TBD: mk mentioned something about states: undefined, fee_paid, available.

Sample Request

http://localhost/api/wallet_send?address=14w4mZx4b6JjtEd9BZPnLCSXzbHjKH3Pn3&amount=1.55

Sample Response

"<btc txid>"

Parameters

param	type	desc	required
address_payto	string	recipient address	Yes
amount	real	amount to send	Yes
address_sources	csvstring	one or more source addresses, for coin control. If omitted, addresses will be automatically chosen	No

Notes

a list of funded addresses is available via the wallet_addresses api

Sample Request

http://localhost/api/wallet_tx_list

Sample Response

{ "amount": 1.3453, "type": "send", "address": "14w4mZx4b6JjtEd9BZPnLCSXzbHjKH3Pn3", "time": <timestamp>, "confirmations": 5, "txid": "e169edeeb8fa2cfc6c341a0c3f0b8f505f3e1984c7de8c22ea047bcf074862fe", "detail": "Withdrawn from wallet" // TBD }

Parameters

param	type	desc	required	values	default
type	string	transaction type	No	send \| receive	0
start	longint	start of period	No		0
end	longint	end of period	No		INT_MAX
limit	int	max record to return	No		100

Authors:	Dan Libby <dan@osc.co.cr>, Mike Rosseel <mike.rosseel@gmail.com>, Manfred Karrer <manfred@bitsquare.io>
Created:	2016-08-19
Last Updated:	2016-08-19