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 WhaleBooks Support to acquire the necessary API key.

• Next, authenticate using this API key by including it in the "X-Api-Key" header.

Examples:

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