The API is ideal for third-party applications that aim to record their clients' transactions in WhaleBooks while also retrieving their portfolio results.
Comprehensive API documentation can be found at: https://whalebooks.com/open-api .
First, contact General Bytes Support to acquire the necessary API key.
Next, authenticate using this API key by including it in the "X-Api-Key" header.
Suggested approaches:
1. Create a User
Using: POST /api/v2/users
If successful, you will receive a response containing the user and their ID.
If an HTTP 409 error is returned, the user already exists in our system, and you must first obtain their permission to write data to their account. To do this, redirect the user to:
https://whalebooks.com/allow-api?user=<USER_EMAIL>&subject-id=<YOUR_ID>.Once the user grants you access, you can resend the POST request and receive a user response that includes the userId.
2. Create Organization
Under an existing or new user, you’ll need to create an organization for which you will have write access.
Use: POST /api/v2/organizations and pass userId in request:
Example body:
{
"userId": 1,
"orgName": "fromAPI",
"displayName": "fromAPI",
"email": "fromAPI@api.com",
"taxResidency": "CZ",
"taxSubject": "NATURAL_PERSON"
}
3. Get the Organization vault-id
Use: GET /api/v2/organizations/{organization-id}/vaults
You will need vault-id in subsequent API calls.
4. Create portfolio
Under Organization create Portfolio. A Portfolio is required to obtain meaningful computation results.
Use: POST /api/v2/organizations/{organization-id}/vaults/{vault-id}/portfolios
Example body:
{
"name": "fromAPI1",
"currency": "USD",
"computationType": "FIFO",
"experimentalComputation": true,
"feeApplicationType": "AT_PROFIT_REALIZATION",
"initialState": null
}
5. Create transaction container
Transactions are grouped into transaction containers. 1 (per client) should suffice.
Use: POST /api/v2/organizations/{organization-id}/vaults/{vault-id}/containers
Example body:
{
"name": "fromAPI1",
"portfolioId": 1,
"type": "MANUAL" # you should always use type manual in this usecase
}
Create transactions
Use: POST /api/v2/organizations//vaults//containers/{container-id}/transactions
Example body:
{
"baseCurrency":"BTC",
"quoteCurrency":"USD",
"type":"BUY",
"timestamp":1675209600698,
"note":"",
"addresses":[],
"baseQuantity":"10",
"quoteQuantity":"",
"unitPrice":"25000"
}
Get portfolio calculations
Use: GET /api/v2/organizations/{organization-id}/vaults/{vault-id}/portfolios/{portfolio-id}/computation/dashboard