This document contains generated API documentation for the web/REST API. Since it is generated automatically, the documentation should always be up-to-date and complete.
Note that some of the data from the calls described below is also exposed through our websockets, for documentation of the websocket meant for public use by persistent applications, see the websocket for apps documentation.
For information about how to register and use an API key, see /docs/apikey/.
All views can cause one or more of the following status codes to be returned:
On changes in the API, a new API version will be introduced. The current API version is passed to REST clients in the 'x-bitmm-api-version' response header and a previous API version can be used by passing a valid value as a request header of the same name 'x-bitmm-api-version'. Note that older API versions may be dropped if (almost) no requests are made for a longer period of time in order to keep the API clean. The current API version is 4, and we only supported versions starting at 2 currently. If no request header is passed, the latest API version (4) is used.
Note that in some cases, the web API behaves different depending on whether the user requests JSON or HTML (most notably, JSON requests often result in a 201 rather than a 302).
Actions can have the following statuses:
A mapping from the supported states and their human-readable label (which may be more explanatory) can be found in the REST representation of each of the actions. Note that a state name may be represented by a different label depending on action type.
The web api mostly returns basic data types such as <string>, <int>, etc. In addition, three types, `decimal`, `date` and `datetime` are provided, that contain a `value` key with the value, as string, usable for parsing and a `localized` key with the value, as string, in a form which can be presented to the user. The format is as follows:
{"type": "decimal", "value": <str>, "localized": <str>}{"type": "date", "value": <str>, "localized": <str>}{"type": "datetime", "value": <str>, "localized": <str>}Login form
Allows users to log in to the website using the cookie auth mechanism. As a side-effect, this allows registering an API key for the REST API, pass the key information along with the form and it will automatically be registered (see /apikey/register).
Note that this requires CAPTCHA and CSRF data to be passed on POST.
Register a new user
Presents and processes form for adding a new user. Note that an apikey can be passed, if that key was registered correctly (see /apikey/register/) it is verified if the registration process is successfully completed.
Note that this requires CAPTCHA and CSRF data to be passed on POST.
Activate a new user account.
Part of the registration process, this page is linked to from the confirmation email.
Reset the password of an existing user.
Note that this requires CAPTCHA and CSRF data to be passed on POST.
Password reset complete.
Display a list of all accounts
This returns the user's accounts for all currencies, including balance, but without transaction information.
Display a user account for a single currency
This returns account information, including balance and a list of transactions.
Can be called with query parameters offset and limit to restrict the amount of transactions returned, and with exclude_status to exclude one or more specific transaction statuses, separated using a pipe symbol |.
Generate a new deposit address for this account
Note that this fails when deposit is not yet enabled for the user (when the user has not yet registered a valid ID).
Display information for a single transaction
Cancel a queued (claimable) transfer
This can be used to cancel a queued transfer, which is a transfer to a user that does not yet have an account. Claiming the coins will no longer be possible, the coins will be refunded. Fails if the action is not of the correct type or if the coins are already claimed.
Cancel an unverified transfer
Only works for transactions that require 2FA verification (transfer and sell actions) and only if their status allows it (VERIFICATION_MAIL_SENT or VERIFICATION_TWO_FACTOR).
Re-send an email to claim a transfer
This can be used to re-send an email to a recipient of a queued transfer, which is a transfer to a user that does not yet have an account. The email contains a link to register and claim the coins. Fails if the action is not of the correct type or if the coins are already claimed.
Re-send a verification email
Only works for transactions that require email verification (transfer and sell actions) and only if their status allows it (VERIFICATION_MAIL_SENT).
Set the origin of a deposit (e.g. 'own wallet' or 'exchange').
Dutch law expects us to request the origin of each deposit, this action is used to store this information (as provided by the user).
Verify a 2FA email code
Only works for transactions that require 2FA verification (transfer and sell actions) and only if their status allows it (VERIFICATION_MAIL_SENT, which is only reached if the user does not have OTP set up).
Initiate 2-factor verification
Only works for transactions that require 2FA verification (transfer and sell actions) and only if their status allows it (VERIFICATION_TWO_FACTOR, which is only reached if the user has OTP set up).
Display an overview of amounts traded per year
Displays a deposit request
Deposit requests are used to request coins from another user. Create one using the payment deposit plugin. Note that this is a restricted plugin, request access at our support department.
Pay a deposit request
Deposit requests are used to request coins from another user. Create one using the payment deposit plugin. Note that this is a restricted plugin, request access at our support department.
Let the user pick a plugin and redirect to the plugin
This presents the first page of the actions, where the user picks the desired plugin to handle an action, though it implicitly redirects if there's only 1 plugin registered for the action.
Let the user pick a plugin and redirect to the plugin
This presents the first page of the actions, where the user picks the desired plugin to handle an action, though it implicitly redirects if there's only 1 plugin registered for the action.
Let the user pick a plugin and redirect to the plugin
This presents the first page of the actions, where the user picks the desired plugin to handle an action, though it implicitly redirects if there's only 1 plugin registered for the action.
Let the user pick a plugin and redirect to the plugin
This presents the first page of the actions, where the user picks the desired plugin to handle an action, though it implicitly redirects if there's only 1 plugin registered for the action.
Let the user pick a plugin and redirect to the plugin
This presents the first page of the actions, where the user picks the desired plugin to handle an action, though it implicitly redirects if there's only 1 plugin registered for the action.
Buy crypto with iDeal
This presents a form when called using GET, or redirects to the iDeal PSP when called using POST, unless there are form errors, in which case the form is presented again. (In other words, if this does not return a 302 on POST, there are errors in the form.)
On POST only the crypto_currency_amount and bank_id can be provided, in which case the aux_currency_amount is calculated on-the-fly, or all form fields can be filled in, with aux_currency_amount, timestamp and hash data provided by the market api for a pre-calculated price (this way the user can be presented with an 'offer price' beforehand). This data can be retrieved 'through the web' (see /market/buy_price and /market/sell_amount) or from the websockets (using the request_price/request_amount commands).
Buy crypto with Bancontact (aka Mister Cash)
This presents a form when called using GET, or redirects to the bancontact PSP when called using POST, unless there are form errors, in which case the form is presented again. (In other words, if this does not return a 302 on POST, there are errors in the form.)
On POST only the crypto_currency_amount and bank_id can be provided, in which case the aux_currency_amount is calculated on-the-fly, or all form fields can be filled in, with aux_currency_amount, timestamp and hash data provided by the market api for a pre-calculated price (this way the user can be presented with an 'offer price' beforehand). This data can be retrieved 'through the web' (see /market/buy_price and /market/sell_amount) or from the websockets (using the request_price/request_amount commands).
Sell crypto with SEPA
This presents a form when called using GET, creates a transfer and redirects to the account page or an OTP page when called using POST, unless there are form errors, in which case the form is presented again. (In other words, if this does not return a 302 on POST, there are errors in the form.)
On POST only the crypto_currency_amount and bank_id can be provided, in which case the aux_currency_amount is calculated on-the-fly, or all form fields can be filled in, with aux_currency_amount, timestamp and hash data provided by the market api for a pre-calculated price (this way the user can be presented with an 'offer price' beforehand). This data can be retrieved 'through the web' (see /market/sell_price and /market/sell_amount) or from the websockets (using the request_price/request_amount commands).
Send crypto to a Bitmymoney account
This allows sending to an account based on account/user-related information, such as email or phone number (at this moment only email is supported). If there's an existing account for the provided piece of information, we deposit immediately, if not we queue a transfer and send a message using the provided information (email to email address, sms to phone number) to allow claiming it.
This presents a form when called using GET, creates a transfer and redirects to the account page or an OTP page when called using POST, unless there are form errors, in which case the form is presented again. (In other words, if this does not return a 302 on POST, there are errors in the form.)
On POST only the crypto_currency_amount and bank_id can be provided, in which case the aux_currency_amount is calculated on-the-fly, or all form fields can be filled in, with aux_currency_amount, timestamp and hash data provided by the market api for a pre-calculated price (this way the user can be presented with an 'offer price' beforehand). This data can be retrieved 'through the web' (see /market/buy_price and /market/sell_amount) or from the websockets (using the request_price/request_amount commands).
Claim a queued transfer
This allows claiming a transfer that has been queued earlier, using claim info (combination of transfer id and some secret code). Note that this view does not explicitly require authentication, but behaves different if you're not logged in: if you are logged in as the receiver (so a new user with the to_email as registered email address), the transfer is executed, if not (also if you're logged in as a different user), a special claim/registration form is presented.
The secret can be passed as GET or POST parameter, on GET a form is presented, POST will perform the claim code.
Returns a 403 if the secret is not correct or not provided.
Request re-sending of an expired queued transfer
This can be called by the receiver of a queued transfer.
Cancel a queued transfer
This can be called by the receiver of the transfer, who identifies by passing the 'secret' as GET or POST parameter.
Returns a 403 if the secret is not correct or not provided.
Send crypto to a crypto address
This presents a form when called using GET, creates a transfer and redirects to the account page or an OTP page when called using POST, unless there are form errors, in which case the form is presented again. (In other words, if this does not return a 302 on POST, there are errors in the form.)
On POST only the crypto_currency_amount and bank_id can be provided, in which case the aux_currency_amount is calculated on-the-fly, or all form fields can be filled in, with aux_currency_amount, timestamp and hash data provided by the market api for a pre-calculated price (this way the user can be presented with an 'offer price' beforehand). This data can be retrieved 'through the web' (see /market/buy_price and /market/sell_amount) or from the websockets (using the request_price/request_amount commands).
Store crypto to a Bitmymoney giftcard which can be redeemed later
Presents the user's crypto address and deposit instructions
Note that this only works if deposit is allowed (which requires users to provide their ID).
Start a deposit request
Deposit requests are requests for crypto to another user. This presents a form to generate a payment page on GET and initializes a deposit request (which presents the payment page) on successful POSTs. If the POST was successful, the user is redirected to the payment page, if not (so if there are form errors), the form is presented again. (In other words, if a POST does not result in a 302, the form contains errors.)
The payment page allows another user to deposit crypto to the user's deposit address, presenting payment information, including a QR code.
Note that this is only accessible when the functionality is enabled for the account, contact support if you would like to use it.
Trade crypto for other crypto
This presents a form when called using GET, or trades crypto to crypto and redirects to the account page when called using POST, unless there are form errors, in which case the form is presented again. (In other words, if this does not return a 302 on POST, there are errors in the form.)
Note that the names of the form fields are somewhat confusing: a Trade should be considered a sale of the currency of the currently active account to another currency, making that crypto_currency is the currency of that account and aux_currency is the currency to trade for. (For instance, when trading BTC for ETH, this form is presented as part of the BTC account's views and crypto_currency_amount is the amount of BTC, while aux_currency_amount is the amount of LTC.)
On POST only the crypto_currency_amount and bank_id can be provided, in which case the aux_currency_amount is calculated on-the-fly, or all form fields can be filled in, with aux_currency_amount, timestamp and hash data provided by the market api for a pre-calculated price (this way the user can be presented with an 'offer price' beforehand). This data can be retrieved 'through the web' (see /market/sell_price and /market/sell_amount) or from the websockets (using the request_price/request_amount commands).
Set or edit the user's residential address
This returns a form and (if set) the current residential_address on GET, and a 302 or 201 with the created residential_address (depending on whether the client accepts JSON) on successful POSTs, and a 200 on unsuccessful ones (returning the form like for GET, but this time with error information added).
Service that returns address info for a postal_code
The service returns a JSON structure with street, city and province based on a Dutch postal_code and number.
It may return a 404 when there's no address data found (this means the postal_code/number combination is not in the Dutch postal code registry), a 400 if the data provided is incorrect (postal_code not in the format NNNNCC, where N is a number and C is a character, or number not an integer) or 500 if there's a problem connecting to the (third-party) postal code service we use.
Register an API key for a user
This is used to register a new API public key for ECDSA authentication. It may be used regardless of whether a user exists, when not, the data is stored and attached to the user after the user is registered (this to allow registering an API key before the user registers, allowing a more seamless registration process).
On GET this returns a form, POST allows registration of the provided public key (unless there are form errors, in which case the form is returned with error information). After a successful post, an email (depending on the value of auth_plugin this may be a different message type in the future, but at the moment only email is supported) is sent to the user if they're known to the system and login information is not provided, if the user is not yet known we assume an email is used (and verified) in the registration process and when the user is currently logged in, we assume they will know what to do (which is verify the API key from the user settings page).
Note that this returns the same information when a user exists as when there's no user found for the provided email address to avoid detection of whether an email address is registered.
Manage transfer addresses (addresses to deposit to)
Returns price and balance information for all currency pairs
The returned structure also includes information about action plugins.
Returns price and balance information for a specific currency pair
Returns the amount of from-currency you pay for an amount of to-currency
Returns the amount of to-currency you get for an amount of from-currency
Returns the amount of to-currency you pay for an amount of from-currency
Returns the amount of from-currency you get for an amount of to-currency
Returns the median of the current buy/sell price for a currency
Returns the mid price for an amount of crypto. This does not take plugin margins etc. into account.
Export account data in csv format
User dashboard
Delete an API key
Disable an api key
Enable an already verified API key
Verify an api key that was registered without authenticating
Cancel a new OTP registration
Re-send email to enable a new OTP installation
Set or edit the user's residential address
This returns a form and (if set) the current residential_address on GET, and a 302 or 201 with the created residential_address (depending on whether the client accepts JSON) on successful POSTs, and a 200 on unsuccessful ones (returning the form like for GET, but this time with error information added).
Service that returns address info for a postal_code
The service returns a JSON structure with street, city and province based on a Dutch postal_code and number.
It may return a 404 when there's no address data found (this means the postal_code/number combination is not in the Dutch postal code registry), a 400 if the data provided is incorrect (postal_code not in the format NNNNCC, where N is a number and C is a character, or number not an integer) or 500 if there's a problem connecting to the (third-party) postal code service we use.
Upload your id to Bitmymoney
Returns a form on GET and POSTs with errors, a 201 HTTP response with a message on successful POSTs (in which case the returned data is always JSON, in browsers POST is done using JS).
Uploaded images should be encrypted as a NaCL 'sealed box', using the public key returned as public_key on GET.