Bitmymoney Bitcoinrekening

Websocket API

This document describes Bitmymoney's websocket API, which can be used by clients that keep a websocket open during a session.

Note that this describes the 'persistent websocket' API only, which is available on wss://www.bitmymoney.com/bmmws_v1, not the 'one-shot websocket' which is used on webpages (wss://www.bitmymoney.com/bmmws). For the latter, no documentation is available yet.

Connecting

To connect to the websocket, use wss://www.bitmymoney.com/bmmws_v1 as the endpoint for your client. The server follows the websocket standard without additional caveats, so any standard websocket client implementation should work.

All data sent to and from the server is in JSON format.

Commands

subscribe

To register to one or more channels, send a structure with the following format over the socket:
```
{"command": "subscribe",
    "channels": [<str>],
    "language": <str>, # optional
    "account_ids": [<int>], # optional
    "auth_token": <str>} # optional
```
The language key is optional, when provided any data pushed from the server is localized for the provided language code. Currently the only language codes supported are 'en' for english and 'nl' for dutch localization. Note that the language is set for the full session, so calling this method with a language provided will override any previous setting. The account_ids and auth_token keys are only required for channels that require authentication, note that both or neither should be provided. For details on how to acquire an auth_token, see Authentication below.

unsubscribe

Unsubscribe from receiving channel or account information. Format:

{"command": "unsubscribe",
    "channels": [<str>], # optional
    "account_ids": [<str>]} # optional

set_language

Sets the language and locale for the current connection. Format:
```
{"command": "set_language",
    "language": <str>}
```
Language can currently only be "en" for english or "nl" for dutch.
request_price

Request a price for an amount of currency. Format:
```
{"command": "request_price",
    "from_currency": <str>,
    "to_currency": <str>,
    "amount": <float>,
    "action": <str>}
```
Where from_currency and to_currency are currency codes - their values can be any of 'EUR', 'BTC', 'LTC' or 'ETH' depending on which action is performed ('from_currency' is

from_currency is 'EUR' when buying or selling and to_currency can be one of 'BTC', 'LTC' or 'ETH' at the moment - amount is the amount of to_currency for which the price is requested and action can be one of 'buy', 'sell', 'send' or 'deposit'.

Calling this will result in a message getting sent back (asynchronously) with the following format:
```
{"price": <decimal>,
    "hash": <str>,
    "timestamp": <int>}
```
which can be used to fill action forms, as described in the web api documentation.
request_amount

Request an amount of currency for a price in EUR. Format:
```
{"command": "request_amount",
    "from_currency": <str>,
    "to_currency": <str>,
    "price": <float>,
    "action": <str>}
```
Where from_currency and to_currency are currency codes - from_currency can currently only be 'EUR' and to_currency can be one of 'BTC', 'LTC' or 'ETH' at the moment - price is the amount of from_currency (EUR) for which the amount is requested and action can be one of 'buy', 'sell', 'send' or 'deposit'.

Calling this will result in a message getting sent back (asynchronously) with the following format:
```
{"amount": <decimal>,
    "hash": <str>,
    "timestamp": <int>}
```
which can be used to fill action forms, as described in the web api documentation.

Channels

Once a connection has been established, you will need to register to one or more 'channels' to get data pushed to the client. The available channels are:

market

Pushes market data, containing current price information for all crypto markets. New data is made available when prices change, updates are per market (currency). Authentication not required. For more information about the market data structure, see the /market/ web api call.
account

Pushes account data, new data is made available on changes to the account information (e.g. when the balance changes). Authentication required. For more information about the account structure, see the /account/<account_id>/ web api call.
transaction

Pushes transaction data, new data is made available when the transaction changes (mostly on status changes). Only transactions for the account for which the channel is registered are pushed. Authentication required. For more information about the transaction structure, see the /account/<account_id>/<transaction_id>/ web api call.

To subscribe to one or more channels, use the subscribe command as described above.

Authentication

Authentication requires providing a valid auth_token value to the server. Such tokens are returned by a REST call to /account/, the token is made available in the returned JSON structure using the key ws_auth_token. Note that in order to retrieve such a structure, the user must be authenticated, either using cookie authentication or (more likely) using the Bitmymoney ECDSA authentication mechanism (see the API key documentation for more details). Also note that the value of this key provided by other URLs are not appropriate for authenticating to the persistent websocket, these are used for the one-shot browser-specific websocket.

Data types

In our API, <decimal> is a structure (associative array) with the following format:

`{"type": "decimal", "value": <str>, "localized": <str>}`