API for requesting user details and buying/selling cryptocurrency on BTC Direct's platform.

Click on one of the sections below to read more about that topic:

Client authentication ▼

In order to work with our API, you need to request a JWT token using your login details, via the /api/v1/authenticate endpoint. This will return an authorization token, as well as a refresh token. When you have retrieved your token, you need to add it as a header to your requests:

Authorization: Bearer {token}

Tokens are valid for 1 hour. If your token has expired (or is about to expire), you can request a new one by sending the refresh token to the following endpoint: /api/v1/refresh. This will return a new authorization token which you can use in your requests. The refresh token will remain valid for 1 month, but that time will be reset as soon as you use it to request a new token.

User authentication ▼

There are two options of authenticating a user to be able to use endpoint which require a logged in user. You can either request a User-Authorization by letting users send their e-mail address and password to the /api/v1/user/login endpoint (more details below), or pass a unique wallet identifier header, such as an XPUB (more on this below as well).

In order to work with endpoints which require a logged in user, you need to let the user login to their account via the /api/v1/user/login endpoint. You will be given another authorization (and refresh) token, which you also need to add as a header to your requests:

User-Authorization: Bearer {token}

This token is also valid for 1 hour. Similar to the base authorization token, this token can be refreshed by sending the refresh token to /api/v1/refresh.

If you want to enable the user to log out of our API, which in fact will render the user authorization token invalid, you can do so by calling the /api/v1/user/logout endpoint.

You can also send a user identifier header along with your request to authenticate a user. This needs to be a unique identifier, it could for example be a hashed XPUB key.

The header can be sent as such:

User-Identifier: {userIdentifier}

You can use this identifier in all requests requiring a logged-in user, but in order to be able to confirm quotes and do other user-related operations (such as requesting the users' info), you will need to link this identifier to an existing (or new) user account.

In order to link a user identifier to a user account, you can call the /api/v1/user/register-identifier endpoint. This will either return a URL to the registration flow, where the user can sign up or log in to their account, or a URL to their account dashboard if the user identifier is already known.

Quote system security ▼

To place an order, first a quote needs to be requested from our API using one of the quote endpoints; there's one for selling and buying crypto currencies. An offer will be returned containing what the user would receive for the given amount and (among other things) how long the quote is valid, along with an encrypted string containing this quote plus some additional information intended to be used by our API. See for more information the quote endpoints below.

Note: the quote string in the example is a lot shorter than the actual string, but has been abbreviated for readability.

If the user agrees to the price and wants to actually initiate the trade, you will need to send this quote string back to our API, to one of the confirm endpoints, depending on whether the user wants to buy or sell.

The API then validates this quote, whether it has been tampered with or not, if it is not expired, if the quote belongs to the wallet address provided, and if the quote belongs to the API client and logged in user.
If all of these variables are valid, the quote is accepted and the trade is made.

The quote is actually a JWE token, encrypted using the strongest encryption available, ensuring integrity, authenticity and confidentiality. It is virtually tamper-proof, in fact, even if it would be decrypted (which is impossible without the secret key), modified and re-encrypted, our systems perform additional checks to further validate the quote.

In short, it is impossible to alter the quote in order to 'trick' our API.

Rate limits ▼

Why do we have rate limits?

We have implemented rate limits for several reasons, including but not limited to:

Preventing abuse of the API.
Ensuring that no single party degrades the API performance for other users.

What happens when the limit is exceeded?

If you exceed the rate limit, you will receive an error response with status code 429 and error code 920.

How can I avoid exceeding the limit?

If you are concerned about approaching the rate limit, please contact your integration manager for assistance.