brokerize
brokerize API
The brokerize API allows clients to implement multi-brokerage with a unified interface. While our partner brokers have different feature sets and legal constraints, our abstractions make it easy to build a consistent trading experience for your users. We provide an accessible demo broker for development and quality assurance purposes that allows you to test the different behaviours without the need to log in to the actual brokers.
user accounts & temporary guest sessions
All API calls act on behalf of a specific end-user that interacts with your application. It is recommended to directly call the API from frontends (for web applications, this will involve a CORS configuration, which can be attached easily to your client id).
End users either have their own account at brokerize or create an ephemeral anonymous account while they use it. In the latter case, all data is deleted automatically when the session is terminated. If users decide to create a proper account, they can log in to brokerize any time with their credentials and keep their data stored as long as they wish.
After retrieving a token for the user, interaction with the API is the same for both cases. All features are available for guest and registered users.
connecting brokers and synchronizing data to brokerize
Users connect their brokerage accounts from either the official brokerize UI or from an app's interface using their broker credentials. To find out which brokers can be used for logging in, the GetBrokers endpoint must be used. An end user can add a login by calling AddSession. Note that brokerize never saves the login credentials, but only tokens / session ids that are issued by the brokers. Those are discarded as soon as the user logs out from the broker using LogoutSession.
As soon as users have connected one or more broker sessions, those sessions are synced into their user account. This means that the list of portfolios, positions and orders are stored in the brokerize database. All synchronized portfolios and their contents are accessible using the portfolio operations (e.g. GetPortfolios, GetPortfolioOrders etc.). Even after the user disconnects a session (or it times out at the broker etc.), the data remains available until actively deleted by the user (DeletePortfolio). This means that users can easily look at the last known state of each portfolio without needing to log in. As soon as they log in again via AddSession, the data is updated again (i.e. the synchronized portfolio gets connected to an "online session" again).
Data is automatically synchronized in the background, but clients can also request a sync using TriggerSessionSync.
performing actions in portfolios
See GetAuthInfo to get an overview on the available operations like creation, change and cancellation of orders. For an overview how the flow of the creation of a trade from start to finish looks, see the next section
trade flow
The following diagram tries to assist in unterstanding the flow that occurs, when a trade is performed. It shows an example of a trade flow. Details may vary depending the broker and connected requirements. For more in-depth information please have a look a look at the GetAuthInfo section.
rate limits
Currently a rate limit of 100 requests per 10 seconds per client/userId combination is implemented for all endpoints. The CreateGuestUser endpoint is accessible without a token, so for that endpoint an IP-based limiting (1 guest user creation per 10 seconds) is implemented. These rate limits are subject to change and will be refined in the future.
Clients should implement ways to deal with the http 429 status code and can inspect the Retry-After header to implement appropriate waiting behavior.
privileged clients with client secrets
Our API is designed to be publicly accessible in order to be used directly from browsers and apps. However this comes with relatively strict rate limiting (for example) for the guest user creation.
If a client only calls the API from a secured backend, the limit may be increased.
In order to authenticate as a priviliged client, the header x-brkrz-client-secret must be added to requests (a client secret is provided manually in that case).
request ids
The brokerize backend assigns a requestId to each request and returns it in the x-request-id header. The ID can be used to research error details, so it may be displayed to the user in the case of unexpected errors. In the case of internal server errors, the id will also be part of the JSON body; for example:
{
"message": "An internal server error occured.",
"requestId": "9KzqMpRvVrQHDkFo"
}
tradable securities
In this API, all tradable securities are identified by their ISIN. However, some securities do not have an ISIN. In these cases, we however still use the ISIN field for some special values. Currently frontends should manually map the securities to their security database if suitable.
The following special values for ISIN are currently supported (of course, the actual availability depends on the specific broker implementations):
ISIN | Description |
|---|---|
BTC | BTC/EUR |
ETH | ETH/EUR |
LTC | LTC/EUR |
XRP | XRP/EUR |
BCH | BCH/EUR |
EOS | EOS/EUR |
LINK | LINK/EUR |
XLM | XLM/EUR |
DOT | DOT/EUR |
UNI | UNI/EUR |
DOGE | DOGE/EUR |
ETC | ETC/EUR |
ADA | ADA/EUR |
SOL | SOL/EUR |
AAVE | AAVE/EUR |
ALGO | ALGO/EUR |
CRV | CRV/EUR |
LUNA | LUNA/EUR |
MANA | MANA/EUR |
POL | POL/EUR |
XTZ | XTZ/EUR |
AVAX | AVAX/EUR |
ENJ | ENJ/EUR |
FTM | FTM/EUR |
LRC | LRC/EUR |
MKR | MKR/EUR |
NEAR | NEAR/EUR |
QNT | QNT/EUR |
GRT | GRT/EUR |
HBAR | HBAR/EUR |
BAT | BAT/EUR |
GNO | GNO/EUR |
S | S/EUR |
1INCH | 1INCH/EUR |
ANKR | ANKR/EUR |
APE | APE/EUR |
ARB | ARB/EUR |
ATOM | ATOM/EUR |
AXS | AXS/EUR |
BNB | BNB/EUR |
BNT | BNT/EUR |
CAKE | CAKE/EUR |
CHZ | CHZ/EUR |
COMP | COMP/EUR |
CRO | CRO/EUR |
CVC | CVC/EUR |
CVX | CVX/EUR |
GALA | GALA/EUR |
HNT | HNT/EUR |
IMX | IMX/EUR |
INJ | INJ/EUR |
KSM | KSM/EUR |
LDO | LDO/EUR |
NMR | NMR/EUR |
ONDO | ONDO/EUR |
OP | OP/EUR |
POWR | POWR/EUR |
PYTH | PYTH/EUR |
REQ | REQ/EUR |
RUNE | RUNE/EUR |
SAND | SAND/EUR |
SNX | SNX/EUR |
STORJ | STORJ/EUR |
SUI | SUI/EUR |
SUSHI | SUSHI/EUR |
TON | TON/EUR |
TRX | TRX/EUR |
WOO | WOO/EUR |
YFI | YFI/EUR |
ZRX | ZRX/EUR |
Authentication
- API Key: clientId
- API Key: cookieAuth
- HTTP: Bearer Auth
The brokerize clientId provided to API customers. The clientId defines which origins are allowed for CORS and which URLs may be used for OAuth redirects.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | x-brkrz-client-id |
Requests are authenticated by providing an HTTP-Only cookie _id which is a JWT token stored in the browser by calling the /login endpoint. This allows clients to not have to care about authentication at all - it is provided by 3rd party cookies which are not visible to the frontend at all. However, this comes with limitations (e.g. some browsers do not send those cookies if they are under a 3rd party domain).
Security Scheme Type: | apiKey |
|---|---|
Cookie parameter name: | _id |
Requests are authenticated by providing either a header Authorization: Bearer <TOKEN> or a header x-access-token: <TOKEN> where <TOKEN> is a token retrieved either from the CreateGuestUser endpoint or retrieved for a user from the amazon cognito pool, or a Personal Access Token created in the brokerize admin interface.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |