Rotki API

Introduction

When the Rotki backend runs it exposes an HTTP Rest API that is accessed by either the electron front-end or a web browser. The endpoints accept and return JSON encoded objects. All queries have the following prefix: /api/<version>/ where version is the current version. The current version at the moment is 1.

Request parameters

All endpoints that take parameters accept a json body with said parameters. If the request is a GET request then it also accepts query parameters since for multiple implementations a JSON body will not work.

Response Format

All endpoints have their response wrapped in the following JSON object

{
    "result": 42,
    "message": ""
}

In the case of a succesful response the "result" attribute is populated and is not null and the "message" is empty.

{
    "result": null,
    "message": "An error happened"
}

In the case of a failed response the "result" attribute is going to be null and the "message" attribute will optionally contain information about the error.

Async Queries

Some endpoint queries can accept the argument "async_query": true. When that is done the query is no longer synchronous but will instead immediately return a task id in the following format:

{
    "result": {"task_id": 10},
    "message": ""
}

The consumer of the API can later query the ongoing backend task endpoint with that id and obtain the outcome of the task when it’s ready.

Endpoints

In this section we will see the information about the individual endpoints of the API and detailed explanation of how each one can be used to interact with Rotki.

Handling user creation, sign-in, log-out and querying

GET /api/(version)/users

By doing a GET at this endpoint you can see all the currently existing users and see who if any is logged in.

Example Request:

http

GET /api/1/users HTTP/1.1
Host: localhost:5042
Accept: application/json, text/javascript

curl

curl -i http://localhost:5042/api/1/users -H 'Accept: application/json, text/javascript'

wget

wget -S -O- http://localhost:5042/api/1/users --header='Accept: application/json, text/javascript'

httpie

http http://localhost:5042/api/1/users Accept:'application/json, text/javascript'

python-requests

requests.get('http://localhost:5042/api/1/users', headers={'Accept': 'application/json, text/javascript'})

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {"john": "loggedin", "maria": "loggedout"},
    "message": ""
}
Response JSON Object:
 
  • result (object) – The result of the users query. Each element has a username as a key and either "loggedin" or "loggedout" values
Status Codes:
PUT /api/(version)/users

By doing a PUT at this endpoint you can create a new user

Example Request:

http

PUT /api/1/users HTTP/1.1
Host: localhost:5042
Accept: application/json, text/javascript

{
      "name": "john",
      "password": "supersecurepassword",
      "premium_api_key": "dasdsda",
      "premium_api_secret": "adsadasd",
}

curl

curl -i -X PUT http://localhost:5042/api/1/users -H 'Accept: application/json, text/javascript' --data-raw '{

      "name": "john",

      "password": "supersecurepassword",

      "premium_api_key": "dasdsda",

      "premium_api_secret": "adsadasd",

}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/users --header='Accept: application/json, text/javascript' --body-data='{

      "name": "john",

      "password": "supersecurepassword",

      "premium_api_key": "dasdsda",

      "premium_api_secret": "adsadasd",

}'

httpie

echo '{

      "name": "john",

      "password": "supersecurepassword",

      "premium_api_key": "dasdsda",

      "premium_api_secret": "adsadasd",

}' | http PUT http://localhost:5042/api/1/users Accept:'application/json, text/javascript'

python-requests

requests.put('http://localhost:5042/api/1/users', headers={'Accept': 'application/json, text/javascript'}, data='{\r\n\n      "name": "john",\r\n\n      "password": "supersecurepassword",\r\n\n      "premium_api_key": "dasdsda",\r\n\n      "premium_api_secret": "adsadasd",\r\n\n}')
Request JSON Object:
 
  • name (string) – The name to give to the new user
  • password (string) – The password with which to encrypt the database for the new user
  • premium_api_key (string[optional]) – An optional api key if the user has a Rotki premium account.
  • premium_api_secret (string[optional]) – An optional api secret if the user has a Rotki premium account.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "exchanges": ["kraken", "poloniex", "binance"],
        "settings": {
            "have_premium": true,
            "version": "6",
            "last_write_ts": 1571552172,
            "premium_should_sync": true,
            "include_crypto2crypto": true,
            "anonymized_logs": true,
            "last_data_upload_ts": 1571552172,
            "ui_floating_precision": 2,
            "taxfree_after_period": 31536000,
            "balance_save_frequency": 24,
            "include_gas_costs": true,
            "historical_data_start": "01/08/2015",
            "eth_rpc_endpoint": "http://localhost:8545",
            "main_currency": "USD",
            "date_display_format": "%d/%m/%Y %H:%M:%S %Z",
            "last_balance_save": 1571552172
        }
    },
    "message": ""
}
Response JSON Object:
 
  • result (object) – For succesful requests, result contains the currently connected exchanges, and the user’s settings. For details on the user settings refer to the Getting or modifying settings section.
Status Codes:
PATCH /api/(version)/users/(username)

By doing a PATCH at this endpoint with action 'login' you can login to the user with username.

Example Request:

http

PATCH /api/1/users/john HTTP/1.1
Host: localhost:5042

{
    "action": "login"
    "password": "supersecurepassword",
    "sync_approval": "unknown",
}

curl

curl -i -X PATCH http://localhost:5042/api/1/users/john --data-raw '{

    "action": "login"

    "password": "supersecurepassword",

    "sync_approval": "unknown",

}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/users/john --body-data='{

    "action": "login"

    "password": "supersecurepassword",

    "sync_approval": "unknown",

}'

httpie

echo '{

    "action": "login"

    "password": "supersecurepassword",

    "sync_approval": "unknown",

}' | http PATCH http://localhost:5042/api/1/users/john

python-requests

requests.patch('http://localhost:5042/api/1/users/john', data='{\r\n\n    "action": "login"\r\n\n    "password": "supersecurepassword",\r\n\n    "sync_approval": "unknown",\r\n\n}')
Request JSON Object:
 
  • action (string) – The action to perform. Can only be one of "login" or "logout" and for the login case has to be "login"
  • password (string) – The password that unlocks the account
  • sync_approval (bool) – A string denoting if the user approved an initial syncing of data from premium. Valid values are "unknown", "yes" and "no". Should always be "unknown" at first and only if the user approves should a login with approval as "yes be sent. If he does not approve a login with approval as "no" should be sent. If there is the possibility of data sync from the premium server and this is "unknown" the login will fail with an appropriate error asking the consumer of the api to set it to "yes" or "no".

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "exchanges": ["kraken", "poloniex", "binance"],
        "settings": {
            "have_premium": true,
            "version": "6",
            "last_write_ts": 1571552172,
            "premium_should_sync": true,
            "include_crypto2crypto": true,
            "anonymized_logs": true,
            "last_data_upload_ts": 1571552172,
            "ui_floating_precision": 2,
            "taxfree_after_period": 31536000,
            "balance_save_frequency": 24,
            "include_gas_costs": true,
            "historical_data_start": "01/08/2015",
            "eth_rpc_endpoint": "http://localhost:8545",
            "main_currency": "USD",
            "date_display_format": "%d/%m/%Y %H:%M:%S %Z",
            "last_balance_save": 1571552172
        }
    },
    "message": ""
}
Response JSON Object:
 
  • result (object) – For succesful requests, result contains the currently connected exchanges,and the user’s settings. For details on the user settings refer to the Getting or modifying settings section.
Status Codes:
  • 200 OK – Logged in succesfully
  • 300 Multiple Choices – Possibility of syncing exists and the login was sent with sync_approval set to "unknown". Consumer of api must resend with "yes" or "no".
  • 400 Bad Request – Provided JSON is in some way malformed
  • 401 Unauthorized – Provided password is wrong for the user or some other authentication error.
  • 409 Conflict – Another user is already logged in. User does not exist. There was a fatal error during the upgrade of the DB.
  • 500 Internal Server Error – Internal Rotki error
PATCH /api/(version)/users/(username)

By doing a PATCH at this endpoint with action 'logout' you can logout from your currently logged in account assuming that is username. All user related data will be saved in the database, memory cleared and encrypted database connection closed.

Example Request:

http

PATCH /api/1/users/john HTTP/1.1
Host: localhost:5042

{
    "action": "logout"
}

curl

curl -i -X PATCH http://localhost:5042/api/1/users/john --data-raw '{

    "action": "logout"

}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/users/john --body-data='{

    "action": "logout"

}'

httpie

echo '{

    "action": "logout"

}' | http PATCH http://localhost:5042/api/1/users/john

python-requests

requests.patch('http://localhost:5042/api/1/users/john', data='{\r\n\n    "action": "logout"\r\n\n}')
Request JSON Object:
 
  • action (string) – The action to perform. Can only be one of "login" or "logout" and for the logout case has to be "logout"

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": true,
    "message": ""
}
Response JSON Object:
 
  • result (bool) – The result field in this response is a simple boolean value indicating success or failure.
Status Codes:
PATCH /api/(version)/users/(username)

By doing a PATCH at this endpoint without any action but by providing api_key and api_secret you can set the premium api key and secret pair for the user.

Example Request:

http

PATCH /api/1/users/john HTTP/1.1
Host: localhost:5042

{
    "premium_api_key": "dadsfasdsd",
    "premium_api_secret": "fdfdsgsdmf"
}

curl

curl -i -X PATCH http://localhost:5042/api/1/users/john --data-raw '{

    "premium_api_key": "dadsfasdsd",

    "premium_api_secret": "fdfdsgsdmf"

}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/users/john --body-data='{

    "premium_api_key": "dadsfasdsd",

    "premium_api_secret": "fdfdsgsdmf"

}'

httpie

echo '{

    "premium_api_key": "dadsfasdsd",

    "premium_api_secret": "fdfdsgsdmf"

}' | http PATCH http://localhost:5042/api/1/users/john

python-requests

requests.patch('http://localhost:5042/api/1/users/john', data='{\r\n\n    "premium_api_key": "dadsfasdsd",\r\n\n    "premium_api_secret": "fdfdsgsdmf"\r\n\n}')
Request JSON Object:
 
  • premium_api_key (string) – The new api key to set for Rotki premium
  • premium_api_secret (string) – The new api secret to set for Rotki premium

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": true,
    "message": ""
}
Response JSON Object:
 
  • result (bool) – The result field in this response is a simple boolean value indicating success or failure.
Status Codes:

Getting or modifying external services API credentials

GET /api/(version)/external_services

By doing a GET on the external services endpoint you can get all the credentials that the user has set for external services such as etherscan, cryptocompare e.t.c.

Entries are returned only for the services that have had an api key setup.

Example Request:

http

GET /api/1/external_services HTTP/1.1
Host: localhost:5042
Content-Type: application/json

curl

curl -i http://localhost:5042/api/1/external_services -H 'Content-Type: application/json'

wget

wget -S -O- http://localhost:5042/api/1/external_services --header='Content-Type: application/json'

httpie

http http://localhost:5042/api/1/external_services Content-Type:application/json

python-requests

requests.get('http://localhost:5042/api/1/external_services', headers={'Content-Type': 'application/json'})

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "etherscan": {"api_key": "foooooookey"},
        "cryptocompare": {"api_key": "boooookey"},
        "alethio": {"api_key": "goooookey"}
    },
    "message": ""
}
Response JSON Object:
 
  • result (object) – The result object contains as many entries as the external services. Each entry’s key is the name and the value is another object of the form {"api_key": "foo"}
Status Codes:
PUT /api/(version)/external_services

By doing a PUT on the external services endpoint you can save credentials for external services such as etherscan, cryptocompare e.t.c. If a credential already exists for a service it is overwritten.

Returns external service entries after the additions.

Example Request:

http

PUT /api/1/external_services HTTP/1.1
Host: localhost:5042
Content-Type: application/json

{
    "services": [{"name": "etherscan", "api_key": "goookey"}]
}

curl

curl -i -X PUT http://localhost:5042/api/1/external_services -H 'Content-Type: application/json' --data-raw '{"services": [{"name": "etherscan", "api_key": "goookey"}]}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/external_services --header='Content-Type: application/json' --body-data='{"services": [{"name": "etherscan", "api_key": "goookey"}]}'

httpie

echo '{
  "services": [
    {
      "api_key": "goookey",
      "name": "etherscan"
    }
  ]
}' | http PUT http://localhost:5042/api/1/external_services Content-Type:application/json

python-requests

requests.put('http://localhost:5042/api/1/external_services', headers={'Content-Type': 'application/json'}, json={'services': [{'name': 'etherscan', 'api_key': 'goookey'}]})
Request JSON Object:
 
  • services (list) – The services parameter is a list of services along with their api keys.
Request JSON Array of Objects:
 
  • name (string) – Each entry in the list should have a name for the service. Valid ones are "etherscan", "cryptocompare" and "alethio".
  • api_key (string) – Each entry in the list should have an api_key entry

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "etherscan": {"api_key": "goookey"},
        "cryptocompare": {"api_key": "boooookey"}
    },
    "message": ""
}
Response JSON Object:
 
  • result (object) – The result object contains as many entries as the external services. Each entry’s key is the name and the value is another object of the form {"api_key": "foo"}
Status Codes:
DELETE /api/(version)/external_services

By doing a DELETE on the external services endpoint you can delete credential entries for external services such as etherscan, cryptocompare e.t.c.

Accepts a list of names whose credentials to delete. If credentials do not exist for an entry then nothing happens and deletion for that entry is silently skipped.

Returns external service entries after the deletion.

Example Request:

http

DELETE /api/1/external_services HTTP/1.1
Host: localhost:5042
Content-Type: application/json

{
    "services": ["etherscan"]
}

curl

curl -i -X DELETE http://localhost:5042/api/1/external_services -H 'Content-Type: application/json' --data-raw '{"services": ["etherscan"]}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/external_services --header='Content-Type: application/json' --body-data='{"services": ["etherscan"]}'

httpie

echo '{
  "services": [
    "etherscan"
  ]
}' | http DELETE http://localhost:5042/api/1/external_services Content-Type:application/json

python-requests

requests.delete('http://localhost:5042/api/1/external_services', headers={'Content-Type': 'application/json'}, json={'services': ['etherscan']})
Request JSON Object:
 
  • services (list) – A list of service names to delete. The only possible names at the moment are "etherscan", "cryptocompare" and "alethio".

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "cryptocompare": {"api_key": "boooookey"}
    },
    "message": ""
}
Response JSON Object:
 
  • result (object) – The result object contains as many entries as the external services. Each entry’s key is the name and the value is another object of the form {"api_key": "foo"}
Status Codes:

Getting or modifying settings

GET /api/(version)/settings

By doing a GET on the settings endpoint you can get all the user settings for the currently logged in account

Example Request:

http

GET /api/1/settings HTTP/1.1
Host: localhost:5042
Content-Type: application/json

curl

curl -i http://localhost:5042/api/1/settings -H 'Content-Type: application/json'

wget

wget -S -O- http://localhost:5042/api/1/settings --header='Content-Type: application/json'

httpie

http http://localhost:5042/api/1/settings Content-Type:application/json

python-requests

requests.get('http://localhost:5042/api/1/settings', headers={'Content-Type': 'application/json'})

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "have_premium": false,
        "version": "6",
        "last_write_ts": 1571552172,
        "premium_should_sync": true,
        "include_crypto2crypto": true,
        "anonymized_logs": true,
        "last_data_upload_ts": 1571552172,
        "ui_floating_precision": 2,
        "taxfree_after_period": 31536000,
        "balance_save_frequency": 24,
        "include_gas_costs": true,
        "historical_data_start": "01/08/2015",
        "eth_rpc_endpoint": "http://localhost:8545",
        "main_currency": "USD",
        "date_display_format": "%d/%m/%Y %H:%M:%S %Z",
        "last_balance_save": 1571552172,
        "submit_usage_analytics": true
    },
    "message": ""
}
Response JSON Object:
 
  • version (int) – The database version
  • last_write_ts (int) – The unix timestamp at which an entry was last written in the database
  • premium_should_sync (bool) – A boolean denoting whether premium users database should be synced from/to the server
  • include_crypto2crypto (bool) – A boolean denoting whether crypto to crypto trades should be counted.
  • anonymized_logs (bool) – A boolean denoting whether sensitive logs should be anonymized.
  • last_data_upload_ts (int) – The unix timestamp at which the last data upload to the server happened.
  • ui_floating_precision (int) – The number of decimals points to be shown for floating point numbers in the UI. Can be between 0 and 8.
  • taxfree_after_period (int) – The number of seconds after which holding a crypto in FIFO order is considered no longer taxable. Must be either a positive number, or -1. 0 is not a valid value. The default is 1 year, as per current german tax rules. Can also be set to -1 which will then set the taxfree_after_period to null which means there is no taxfree period.
  • balance_save_frequency (int) – The number of hours after which user balances should be saved in the DB again. This is useful for the statistics kept in the DB for each user. Default is 24 hours. Can’t be less than 1 hour.
  • include_gas_costs (bool) – A boolean denoting whether gas costs should be counted as loss in profit/loss calculation.
  • historical_data_start (string) – A date in the DAY/MONTH/YEAR format at which we consider historical data to have started.
  • eth_rpc_endpoint (string) – A URL denoting the rpc endpoint for the ethereum node to use when contacting the ethereum blockchain. If it can not be reached or if it is invalid etherscan is used instead.
  • main_currency (string) – The FIAT currency to use for all profit/loss calculation. USD by default.
  • date_display_format (string) – The format in which to display dates in the UI. Default is "%d/%m/%Y %H:%M:%S %Z".
  • last_balance_save (int) – The timestamp at which the balances were last saved in the database.
  • submit_usage_analytics (bool) – A boolean denoting wether or not to submit anonymous usage analytics to the Rotki server.
Status Codes:
PUT /api/(version)/settings

By doing a PUT on the settings endpoint you can set/modify any settings you need. Look for possible modifiable settings below.

Example Request:

http

PUT /api/1/settings HTTP/1.1
Host: localhost:5042
Content-Type: application/json

{
    "ui_floating_precision": 4,
    "include_gas_costs": false
}

curl

curl -i -X PUT http://localhost:5042/api/1/settings -H 'Content-Type: application/json' --data-raw '{"include_gas_costs": false, "ui_floating_precision": 4}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/settings --header='Content-Type: application/json' --body-data='{"include_gas_costs": false, "ui_floating_precision": 4}'

httpie

echo '{
  "include_gas_costs": false,
  "ui_floating_precision": 4
}' | http PUT http://localhost:5042/api/1/settings Content-Type:application/json

python-requests

requests.put('http://localhost:5042/api/1/settings', headers={'Content-Type': 'application/json'}, json={'include_gas_costs': False, 'ui_floating_precision': 4})
Request JSON Object:
 
  • premium_should_sync (bool[optional]) – A boolean denoting whether premium users database should be synced from/to the server
  • include_crypto2crypto (bool[optional]) – A boolean denoting whether crypto to crypto trades should be counted.
  • anonymized_logs (bool[optional]) – A boolean denoting whether sensitive logs should be anonymized.
  • ui_floating_precision (int[optional]) – The number of decimals points to be shown for floating point numbers in the UI. Can be between 0 and 8.
  • balance_save_frequency (int[optional]) – The number of hours after which user balances should be saved in the DB again. This is useful for the statistics kept in the DB for each user. Default is 24 hours. Can’t be less than 1 hour.
  • include_gas_costs (bool[optional]) – A boolean denoting whether gas costs should be counted as loss in profit/loss calculation.
  • historical_data_start (string[optional]) – A date in the DAY/MONTH/YEAR format at which we consider historical data to have started.
  • eth_rpc_endpoint (string[optional]) – A URL denoting the rpc endpoint for the ethereum node to use when contacting the ethereum blockchain. If it can not be reached or if it is invalid etherscan is used instead.
  • main_currency (string[optional]) – The FIAT currency to use for all profit/loss calculation. USD by default.
  • date_display_format (string[optional]) – The format in which to display dates in the UI. Default is "%d/%m/%Y %H:%M:%S %Z".
  • submit_usage_analytics (bool[optional]) – A boolean denoting wether or not to submit anonymous usage analytics to the Rotki server.
Response JSON Object:
 
  • taxfree_after_period (int[optional]) – The number of seconds after which holding a crypto in FIFO order is considered no longer taxable. Must be either a positive number, or -1. 0 is not a valid value. The default is 1 year, as per current german tax rules. Can also be set to -1 which will then set the taxfree_after_period to null which means there is no taxfree period.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "have_premium": false,
        "version": "6",
        "last_write_ts": 1571552172,
        "premium_should_sync": true,
        "include_crypto2crypto": true,
        "anonymized_logs": true,
        "last_data_upload_ts": 1571552172,
        "ui_floating_precision": 4,
        "taxfree_after_period": 31536000,
        "balance_save_frequency": 24,
        "include_gas_costs": false,
        "historical_data_start": "01/08/2015",
        "eth_rpc_endpoint": "http://localhost:8545",
        "main_currency": "USD",
        "date_display_format": "%d/%m/%Y %H:%M:%S %Z",
        "last_balance_save": 1571552172,
        "submit_usage_analytics": true
    },
    "message": ""
}
Response JSON Object:
 
  • result (object) – Same as when doing GET on the settings
Status Codes:

Query the result of an ongoing backend task

GET /api/(version)/tasks

By querying this endpoint without any given task id a list of all pending/completed tasks is returned.

Example Request:

http

GET /api/1/tasks HTTP/1.1
Host: localhost:5042

curl

curl -i http://localhost:5042/api/1/tasks

wget

wget -S -O- http://localhost:5042/api/1/tasks

httpie

http http://localhost:5042/api/1/tasks

python-requests

requests.get('http://localhost:5042/api/1/tasks')

Example Response:

The following is an example response of querying pending/completed tasks

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": [4, 23],
    "message": ""
}
Response JSON Object:
 
  • result (list) – A list of integers representing the pending/completed task IDs.
Status Codes:
GET /api/(version)/tasks/(task_id)

By querying this endpoint with a particular task identifier you can get the result of the task if it has finished and the result has not yet been queried. If the result is still in progress or if the result is not found appropriate responses are returned.

Example Request:

http

GET /api/1/tasks/42 HTTP/1.1
Host: localhost:5042

curl

curl -i http://localhost:5042/api/1/tasks/42

wget

wget -S -O- http://localhost:5042/api/1/tasks/42

httpie

http http://localhost:5042/api/1/tasks/42

python-requests

requests.get('http://localhost:5042/api/1/tasks/42')

Example Completed Response:

The following is an example response of an async query to blockchain balances.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "status": "completed",
        "outcome": {
            "per_account": {"BTC": {
                "1Ec9S8KSw4UXXhqkoG3ZD31yjtModULKGg": {
                        "amount": "10",
                        "usd_value": "70500.15"
                    }
            }},
            "totals": {"BTC": {"amount": "10", "usd_value": "70500.15"}}
        }
    },
    "message": ""
}

Example Pending Response:

The following is an example response of an async query that is still in progress.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "status": "pending",
        "outcome": null
    },
    "message": ""
}

Example Not Found Response:

The following is an example response of an async query that does not exist.

HTTP/1.1 404 OK
Content-Type: application/json

{
    "result": {
        "status": "not-found",
        "outcome": null
    },
    "message": "No task with the task id 42 found"
}
Response JSON Object:
 
  • status (string) – The status of the given task id. Can be one of "completed", "pending" and "not-found".
  • outcome (any) – IF the result of the task id is not yet ready this should be null. If the task has finished then this would contain the original task response.
Status Codes:

Query the current fiat currencies exchange rate

GET /api/(version)/fiat_exchange_rates

Querying this endpoint with a list of strings representing FIAT currencies will return a dictionary of their current exchange rates compared to USD. If no list is given then the exchange rates of all currencies is returned. Providing an empty list is an error.

Note

This endpoint also accepts parameters as query arguments. List as a query argument here would be given as: ?currencies=EUR,CNY,GBP

Example Request:

http

GET /api/1/fiat_exchange_rates HTTP/1.1
Host: localhost:5042

{"currencies": ["EUR", "CNY", "GBP"]}

curl

curl -i http://localhost:5042/api/1/fiat_exchange_rates --data-raw '{"currencies": ["EUR", "CNY", "GBP"]}'

wget

wget -S -O- http://localhost:5042/api/1/fiat_exchange_rates --body-data='{"currencies": ["EUR", "CNY", "GBP"]}'

httpie

echo '{"currencies": ["EUR", "CNY", "GBP"]}' | http http://localhost:5042/api/1/fiat_exchange_rates

python-requests

requests.get('http://localhost:5042/api/1/fiat_exchange_rates', data='{"currencies": ["EUR", "CNY", "GBP"]}')
Query Parameters:
 
  • currencies (strings-list) – A comma separated list of fiat currencies to query. e.g.: /api/1/fiat_exchange_rates?currencies=EUR,CNY,GBP
Request JSON Object:
 
  • currencies (list) – A list of fiat currencies to query

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {"EUR": "0.8973438622", "CNY": "7.0837221823", "GBP": "0.7756191673"},
    "message": ""
}
Response JSON Object:
 
  • result (object) – A JSON object with each element being a FIAT currency symbol and each value its USD exchange rate.
Status Codes:

Get a list of setup exchanges

GET /api/(version)/exchanges

Doing a GET on this endpoint will return a list of which exchanges are currently setup for the logged in user.

Example Request:

http

GET /api/1/exchanges HTTP/1.1
Host: localhost:5042

curl

curl -i http://localhost:5042/api/1/exchanges

wget

wget -S -O- http://localhost:5042/api/1/exchanges

httpie

http http://localhost:5042/api/1/exchanges

python-requests

requests.get('http://localhost:5042/api/1/exchanges')

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": ["kraken", "binance"]
    "message": ""
}
Response JSON Object:
 
  • result (list) – A list of exchange names that have been setup for the logged in user.
Status Codes:

Setup or remove an exchange

PUT /api/(version)/exchanges

Doing a PUT on this endpoint with an exchange’s name, api key and secret will setup the exchange for the current user.

Example Request:

http

PUT /api/1/exchanges HTTP/1.1
Host: localhost:5042

{"name": "kraken", "api_key": "ddddd", "api_secret": "ffffff", "passphrase": "secret"}

curl

curl -i -X PUT http://localhost:5042/api/1/exchanges --data-raw '{"name": "kraken", "api_key": "ddddd", "api_secret": "ffffff", "passphrase": "secret"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/exchanges --body-data='{"name": "kraken", "api_key": "ddddd", "api_secret": "ffffff", "passphrase": "secret"}'

httpie

echo '{"name": "kraken", "api_key": "ddddd", "api_secret": "ffffff", "passphrase": "secret"}' | http PUT http://localhost:5042/api/1/exchanges

python-requests

requests.put('http://localhost:5042/api/1/exchanges', data='{"name": "kraken", "api_key": "ddddd", "api_secret": "ffffff", "passphrase": "secret"}')
Request JSON Object:
 
  • name (string) – The name of the exchange to setup
  • api_key (string) – The api key with which to setup the exchange
  • api_secret (string) – The api secret with which to setup the exchange
  • passphrase (string) – An optional passphrase, only for exchanges, like coinbase pro, which need a passphrase.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": true
    "message": ""
}
Response JSON Object:
 
  • result (bool) – A boolean indicating success or failure
Status Codes:
  • 200 OK – The exchange has been sucesfully setup
  • 400 Bad Request – Provided JSON is in some way malformed
  • 409 Conflict – No user is logged in. The exchange has already been registered. The API key/secret is invalid or some other error.
  • 500 Internal Server Error – Internal Rotki error
DELETE /api/(version)/exchanges

Doing a DELETE on this endpoint for a particular exchange name will delete the exchange from the database for the current user.

Example Request:

http

DELETE /api/1/exchanges HTTP/1.1
Host: localhost:5042

{"name": "kraken"}

curl

curl -i -X DELETE http://localhost:5042/api/1/exchanges --data-raw '{"name": "kraken"}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/exchanges --body-data='{"name": "kraken"}'

httpie

echo '{"name": "kraken"}' | http DELETE http://localhost:5042/api/1/exchanges

python-requests

requests.delete('http://localhost:5042/api/1/exchanges', data='{"name": "kraken"}')
Request JSON Object:
 
  • name (string) – The name of the exchange to delete

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": true
    "message": ""
}
Response JSON Object:
 
  • result (bool) – A boolean indicating success or failure
Status Codes:

Querying the balances of exchanges

GET /api/(version)/exchanges/balances/(name)

Doing a GET on the appropriate exchanges balances endpoint will return the balances of all assets currently held in that exchange. If no name is provided then the balance of all exchanges is returned.

Note

This endpoint can also be queried asynchronously by using "async_query": true. Passing it as a query argument here would be given as: ?async_query=true.

Note

This endpoint uses a cache. If queried within the CACHE_TIME the cached value will be returned. If you want to skip the cache add the ignore_cache: true argument. Can also be passed as a query argument.

Example Request:

http

GET /api/1/exchanges/balances/binance HTTP/1.1
Host: localhost:5042

curl

curl -i http://localhost:5042/api/1/exchanges/balances/binance

wget

wget -S -O- http://localhost:5042/api/1/exchanges/balances/binance

httpie

http http://localhost:5042/api/1/exchanges/balances/binance

python-requests

requests.get('http://localhost:5042/api/1/exchanges/balances/binance')
Request JSON Object:
 
  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not
  • ignore_cache (bool) – Boolean denoting whether to ignore the cache for this query or not.
Parameters:
  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not
  • ignore_cache (bool) – Boolean denoting whether to ignore the cache for this query or not.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "BTC": {"amount": "1", "usd_value": "7540.15"},
        "ETH": {"amount": "10", "usd_value": "1650.53"}
    },
    "message": ""
}
Response JSON Object:
 
  • result (object) – If succesful contains the balances of each asset held in the exchange. Each key of the object is an asset’s symbol. Then the value is another object. In the "amount" key of that object is the amount held in the asset. And in the "usd_value" key is the equivalent $ value as of this moment.
Status Codes:
GET /api/(version)/exchanges/balances/

Doing a GET on the exchanges balances endpoint will return the balances of all assets currently held in all exchanges.

Note

This endpoint can also be queried asynchronously by using "async_query": true

Example Request:

http

GET /api/1/exchanges/balances HTTP/1.1
Host: localhost:5042

curl

curl -i http://localhost:5042/api/1/exchanges/balances

wget

wget -S -O- http://localhost:5042/api/1/exchanges/balances

httpie

http http://localhost:5042/api/1/exchanges/balances

python-requests

requests.get('http://localhost:5042/api/1/exchanges/balances')
Request JSON Object:
 
  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not
Parameters:
  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "kraken": {
            "BTC": {"amount": "1", "usd_value": "7540.15"},
            "ETH": {"amount": "10", "usd_value": "1650.53"}
        },
        "binance": {
            "ETH": {"amount": "20", "usd_value": "3301.06"},
        }
    },
    "message": ""
}
Response JSON Object:
 
  • result (object) – If succesful contains the balances of each asset held in the exchange. Each key of the object is an asset’s symbol. Then the value is another object. In the "amount" key of that object is the amount held in the asset. And in the "usd_value" key is the equivalent $ value as of this moment.
Status Codes:

Querying the trades history of exchanges

GET /api/(version)/exchanges/trades/(name)

Doing a GET on the appropriate exchanges trades endpoint will return the history of all trades performed at that exchange. If no name is provided then the balance of all exchanges is returned. Trade history can be further filtered by a timestamp range.

Note

This endpoint can also be queried asynchronously by using "async_query": true

Note

This endpoint also accepts parameters as query arguments.

Example Request:

http

GET /api/1/exchanges/trades/binance HTTP/1.1
Host: localhost:5042

{"from_timestamp": 1514764800, "to_timestamp": 1572080165}

curl

curl -i http://localhost:5042/api/1/exchanges/trades/binance --data-raw '{"from_timestamp": 1514764800, "to_timestamp": 1572080165}'

wget

wget -S -O- http://localhost:5042/api/1/exchanges/trades/binance --body-data='{"from_timestamp": 1514764800, "to_timestamp": 1572080165}'

httpie

echo '{"from_timestamp": 1514764800, "to_timestamp": 1572080165}' | http http://localhost:5042/api/1/exchanges/trades/binance

python-requests

requests.get('http://localhost:5042/api/1/exchanges/trades/binance', data='{"from_timestamp": 1514764800, "to_timestamp": 1572080165}')
Request JSON Object:
 
  • from_timestamp (int) – The timestamp from which and after to query for the trades. If not given 0 is the start.
  • to_timestamp (int) – The timestamp until which to query for the trades. If not given trades are queried until now.
  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not
Parameters:
  • from_timestamp (int) – The timestamp from which and after to query for the trades. If not given 0 is the start.
  • to_timestamp (int) – The timestamp until which to query for the trades. If not given trades are queried until now.
  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": [{
        "trade_id": "sdfhdjskfha",
        "timestamp": 1514764801,
        "location": "binance",
        "pair": "BTC_EUR",
        "trade_type": "buy",
        "amount": "1.5541",
        "rate": "8422.1",
        "fee": "0.55",
        "fee_currency": "EUR",
        "link": "Optional unique trade identifier"
        "notes": "Optional notes"
    }, {
        "trade_id": "binance",
        "timestamp": 1572080163,
        "location": "binance",
        "pair": "BTC_EUR",
        "trade_type": "buy",
        "amount": "0.541",
        "rate": "8432.1",
        "fee": "0.55",
        "fee_currency": "EUR",
        "link": "Optional unique trade identifier"
        "notes": "Optional notes"
    }],
    "message": ""
}
Response JSON Array of Objects:
 
  • trades – Each element of the result array is a JSON Object as defined in the this section.
Status Codes:
GET /api/(version)/exchanges/trades/

Doing a GET on the exchanges trades endpoint will return the history of all trades performed on all exchanges. Trade history can be further filtered by a timestamp range.

Note

This endpoint can also be queried asynchronously by using "async_query": true

Example Request:

http

GET /api/1/exchanges/trades HTTP/1.1
Host: localhost:5042

{"from_timestamp": 1514764800, "to_timestamp": 1572080165}

curl

curl -i http://localhost:5042/api/1/exchanges/trades --data-raw '{"from_timestamp": 1514764800, "to_timestamp": 1572080165}'

wget

wget -S -O- http://localhost:5042/api/1/exchanges/trades --body-data='{"from_timestamp": 1514764800, "to_timestamp": 1572080165}'

httpie

echo '{"from_timestamp": 1514764800, "to_timestamp": 1572080165}' | http http://localhost:5042/api/1/exchanges/trades

python-requests

requests.get('http://localhost:5042/api/1/exchanges/trades', data='{"from_timestamp": 1514764800, "to_timestamp": 1572080165}')
Request JSON Object:
 
  • from_timestamp (int) – The timestamp from which and after to query for the trades. If not given 0 is the start.
  • to_timestamp (int) – The timestamp until which to query for the trades. If not given trades are queried until now.
  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not
Parameters:
  • from_timestamp (int) – The timestamp from which and after to query for the trades. If not given 0 is the start.
  • to_timestamp (int) – The timestamp until which to query for the trades. If not given trades are queried until now.
  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "kraken": [{
            "trade_id": "sdfhdjskfha",
            "timestamp": 1514764801,
            "location": "kraken",
            "pair": "BTC_EUR",
            "trade_type": "buy",
            "amount": "1.5541",
            "rate": "8422.1",
            "fee": "0.55",
            "fee_currency": "EUR",
            "link": "Optional unique trade identifier"
            "notes": "Optional notes"
        }],
        "binance": [{
            "trade_id": "binance",
            "timestamp": 1572080163,
            "location": "binance",
            "pair": "BTC_EUR",
            "trade_type": "buy",
            "amount": "0.541",
            "rate": "8432.1",
            "fee": "0.55",
            "fee_currency": "EUR",
            "link": "Optional unique trade identifier"
            "notes": "Optional notes"
        }]
    },
    "message": ""
}
Response JSON Array of Objects:
 
  • trades – Each element of the result array is a JSON Object as defined in the this section.
Status Codes:

Querying tags

GET /api/(version)/tags

Doing a GET on the tags endpoint will query information about all the tags that are stored in the app

Example Request:

http

GET /api/1/tags/ HTTP/1.1
Host: localhost:5042

curl

curl -i http://localhost:5042/api/1/tags/

wget

wget -S -O- http://localhost:5042/api/1/tags/

httpie

http http://localhost:5042/api/1/tags/

python-requests

requests.get('http://localhost:5042/api/1/tags/')

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "hw": {
            "name": "hw",
            "description": "Accounts that are stored in hardware wallets",
            "background_color": "fafafa",
            "foreground_color": "ffffff"
        },
        "mobile": {
            "name": "mobile",
            "description": "Accounts that are stored in mobile devices",
            "background_color": "ffffff",
            "foreground_color": "fafafa"
       }},
    "message": ""
}
Request JSON Object:
 
  • result (object) – A mapping of tag names to tag data.
  • name (string) – The tag’s name. Is always lowercase.
  • description (string) – A description of what the tag is for.
Response JSON Object:
 
  • background_color (string) – The background color to render the tag in the frontend with.
  • foreground_color (string) – The foreground color to render the tag in the frontend with.
Status Codes:

Adding new tags

PUT /api/(version)/tags

Doing a PUT on the tags endpoint will add a new tag to the application

Example Request:

http

PUT /api/1/tags/ HTTP/1.1
Host: localhost:5042
Accept: application/json, text/javascript

{
      "name": "not public",
      "description": "Accounts that are not publically associated with me",
      "background_color": "f8f8f8",
      "foreground_color": "f1f1f1"
}

curl

curl -i -X PUT http://localhost:5042/api/1/tags/ -H 'Accept: application/json, text/javascript' --data-raw '{

      "name": "not public",

      "description": "Accounts that are not publically associated with me",

      "background_color": "f8f8f8",

      "foreground_color": "f1f1f1"

}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/tags/ --header='Accept: application/json, text/javascript' --body-data='{

      "name": "not public",

      "description": "Accounts that are not publically associated with me",

      "background_color": "f8f8f8",

      "foreground_color": "f1f1f1"

}'

httpie

echo '{

      "name": "not public",

      "description": "Accounts that are not publically associated with me",

      "background_color": "f8f8f8",

      "foreground_color": "f1f1f1"

}' | http PUT http://localhost:5042/api/1/tags/ Accept:'application/json, text/javascript'

python-requests

requests.put('http://localhost:5042/api/1/tags/', headers={'Accept': 'application/json, text/javascript'}, data='{\r\n\n      "name": "not public",\r\n\n      "description": "Accounts that are not publically associated with me",\r\n\n      "background_color": "f8f8f8",\r\n\n      "foreground_color": "f1f1f1"\r\n\n}')
Request JSON Object:
 
  • name (string) – The name to give to the new tag. The name of the tag (case insensitive check) must not already exist.
  • description (string) – The description for the new tag you are creating.
  • background_color (string) – The color with which the tag’s background will be rendered. Format is RGB hexstring.
  • foreground_color (string) – The color with which the tag’s foreground will be rendered. Format is RGB hexstring.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "hw": {
            "name": "hw",
            "description": "Accounts that are stored in hardware wallets",
            "background_color": "fafafa",
            "foreground_color": "ffffff"
        },
        "mobile": {
            "name": "mobile",
            "description": "Accounts that are stored in mobile devices",
            "background_color": "ffffff",
            "foreground_color": "fafafa"
       },
        "not public": {
            "name": "not public",
            "description": "Accounts that are not publically associated with me",
            "background_color": "f8f8f8",
            "foreground_color": "f1f1f1"
       }
    },
    "message": ""
}
Request JSON Object:
 
  • result (object) – A mapping of the tags Rotki knows about including our newly added tag. Explanation of the response format is seen here
Status Codes:

Editing a tag

PATCH /api/(version)/tags

Doing a PATCH on the tags endpoint will edit an already existing tag

Example Request:

http

PATCH /api/1/tags/ HTTP/1.1
Host: localhost:5042
Accept: application/json, text/javascript

{
      "name": "not public",
      "description": "Accounts that are private",
      "background_color": "f9f9f9",
      "foreground_color": "f2f2f2",
}

curl

curl -i -X PATCH http://localhost:5042/api/1/tags/ -H 'Accept: application/json, text/javascript' --data-raw '{

      "name": "not public",

      "description": "Accounts that are private",

      "background_color": "f9f9f9",

      "foreground_color": "f2f2f2",

}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/tags/ --header='Accept: application/json, text/javascript' --body-data='{

      "name": "not public",

      "description": "Accounts that are private",

      "background_color": "f9f9f9",

      "foreground_color": "f2f2f2",

}'

httpie

echo '{

      "name": "not public",

      "description": "Accounts that are private",

      "background_color": "f9f9f9",

      "foreground_color": "f2f2f2",

}' | http PATCH http://localhost:5042/api/1/tags/ Accept:'application/json, text/javascript'

python-requests

requests.patch('http://localhost:5042/api/1/tags/', headers={'Accept': 'application/json, text/javascript'}, data='{\r\n\n      "name": "not public",\r\n\n      "description": "Accounts that are private",\r\n\n      "background_color": "f9f9f9",\r\n\n      "foreground_color": "f2f2f2",\r\n\n}')
Request JSON Object:
 
  • name (string) – The name of the already existing tag. The name lookup will be a case-insensitive check.
  • description (string[optional]) – If given replaces the tag’s description.
  • background_color (string[optional]) – If given replaces the tag’s background color. Format is RGB hexstring.
  • foreground_color (string[optional) – If given replaces the tag’s background color. Format is RGB hexstring.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "hw": {
            "name": "hw",
            "description": "Accounts that are stored in hardware wallets",
            "background_color": "fafafa",
            "foreground_color": "ffffff"
        },
        "mobile": {
            "name": "mobile",
            "description": "Accounts that are stored in mobile devices",
            "background_color": "ffffff",
            "foreground_color": "fafafa"
       },
        "not public": {
            "name": "not public",
            "description": "Accounts that are private",
            "background_color": "f9f9f9",
            "foreground_color": "f2f2f2"
       }
    },
    "message": ""
}
Request JSON Object:
 
  • result (object) – A mapping of the tags Rotki knows about including our newley edited tag. Explanation of the response format is seen here
Status Codes:

Deleting a tag

DELETE /api/(version)/tags

Doing a DELETE on the tags endpoint will remove an existing tag

Example Request:

http

DELETE /api/1/tags/ HTTP/1.1
Host: localhost:5042
Accept: application/json, text/javascript

{
      "name": "not public",
}

curl

curl -i -X DELETE http://localhost:5042/api/1/tags/ -H 'Accept: application/json, text/javascript' --data-raw '{

      "name": "not public",

}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/tags/ --header='Accept: application/json, text/javascript' --body-data='{

      "name": "not public",

}'

httpie

echo '{

      "name": "not public",

}' | http DELETE http://localhost:5042/api/1/tags/ Accept:'application/json, text/javascript'

python-requests

requests.delete('http://localhost:5042/api/1/tags/', headers={'Accept': 'application/json, text/javascript'}, data='{\r\n\n      "name": "not public",\r\n\n}')
Request JSON Object:
 
  • name (string) – The name of the existing tag to remove. The name lookup will be a case-insensitive check.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "hw": {
            "name": "hw",
            "description": "Accounts that are stored in hardware wallets",
            "background_color": "fafafa",
            "foreground_color": "ffffff"
        },
        "mobile": {
            "name": "mobile",
            "description": "Accounts that are stored in mobile devices",
            "background_color": "ffffff",
            "foreground_color": "fafafa"
       }
    },
    "message": ""
}
Request JSON Object:
 
  • result (list) – A mapping of the tags Rotki knows about, now without the tag we just deleted. Explanation of the response format is seen here
Status Codes:

Querying onchain balances

GET /api/(version)/balances/blockchains/(blockchain_name)/

Doing a GET on the blockchains balances endpoint will query on-chain balances for the accounts of the user. Doing a GET on a specific blockchain name will query balances only for that chain. Available blockchain names are: btc and eth.

Note

This endpoint can also be queried asynchronously by using "async_query": true. Passing it as a query argument here would be given as: ?async_query=true.

Note

This endpoint uses a cache. If queried within the CACHE_TIME the cached value will be returned. If you want to skip the cache add the ignore_cache: true argument. Can also be passed as a query argument.

Example Request:

http

GET /api/1/balances/blockchains/ HTTP/1.1
Host: localhost:5042

curl

curl -i http://localhost:5042/api/1/balances/blockchains/

wget

wget -S -O- http://localhost:5042/api/1/balances/blockchains/

httpie

http http://localhost:5042/api/1/balances/blockchains/

python-requests

requests.get('http://localhost:5042/api/1/balances/blockchains/')
Request JSON Object:
 
  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not
  • ignore_cache (bool) – Boolean denoting whether to ignore the cache for this query or not.
Parameters:
  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not
  • ignore_cache (bool) – Boolean denoting whether to ignore the cache for this query or not.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "per_account": {
            "BTC": { "3Kb9QPcTUJKspzjQFBppfXRcWew6hyDAPb": {
                 "amount": "0.5", "usd_value": "3770.075"
             }, "33hjmoU9XjEz8aLxf44FNGB8TdrLkAVBBo": {
                 "amount": "0.5", "usd_value": "3770.075"
             }},
             "ETH": { "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B": {
                 "assets": {
                     "ETH": {"amount": "10", "usd_value": "1650.53"},
                     "DAI": {"amount": "15", "usd_value": "15.21"}
                 },
                 "total_usd_value": "1665.74",
            }}
        },
        "totals": {
            "BTC": {"amount": "1", "usd_value": "7540.15"},
            "ETH": {"amount": "10", "usd_value": "1650.53"},
            "DAI": {"amount": "15", "usd_value": "15.21"}
        }
    },
    "message": ""
}
resjson object per_account:
 The blockchain balances per account per asset. Each element of this object has an asset as its key. Then each asset has an address for that blockchain as its key and each address an object with the following keys: "amount" for the amount stored in the asset in the address and "usd_value" for the equivalent $ value as of the request.
resjson object total:
 The blockchain balances in total per asset. The format is the same as defined here.
statuscode 200:Balances succesfully queried.
statuscode 400:Provided JSON is in some way malformed
statuscode 409:User is not logged in. Invalid blockchain, or problems querying the given blockchain
statuscode 500:Internal Rotki error
statuscode 502:An external service used in the query such as etherscan or blockchain.info could not be reached or returned unexpected response.

Querying all balances

Note

This endpoint can also be queried asynchronously by using "async_query": true

Note

This endpoint also accepts parameters as query arguments.

Note

This endpoint uses a cache. If queried within the CACHE_TIME the cached value will be returned. If you want to skip the cache add the ignore_cache: true argument. Can also be passed as a query argument.

GET /api/(version)/balances/

Doing a GET on the balances endpoint will query all balances across all locations for the user. That is exchanges, blockchains and FIAT in banks. And it will return an overview of all queried balances.

Example Request:

http

GET /api/1/balances/ HTTP/1.1
Host: localhost:5042

{"async_query": true}

curl

curl -i http://localhost:5042/api/1/balances/ --data-raw '{"async_query": true}'

wget

wget -S -O- http://localhost:5042/api/1/balances/ --body-data='{"async_query": true}'

httpie

echo '{"async_query": true}' | http http://localhost:5042/api/1/balances/

python-requests

requests.get('http://localhost:5042/api/1/balances/', data='{"async_query": true}')
Request JSON Object:
 
  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not
  • ignore_cache (bool) – Boolean denoting whether to ignore the cache for this query or not.
Parameters:
  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not
  • ignore_cache (bool) – Boolean denoting whether to ignore the cache for this query or not.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "ETH": {
            "amount": "1",
            "percentage_of_net_value": "9.5%",
            "usd_value": "180"
         },
         "BTC": {
            "amount": "0.5",
            "percentage_of_net_value": "90%",
            "usd_value": "4000"
         },
         "EUR": {
            "amount": "2",
            "percentage_of_net_value": "0.5%",
            "usd_value": "2.8"
         }
         "location": {
             "banks": {
                 "percentage_of_net_value": "0.5%",
                 "usd_value": "2.8"
             },
             "binance": {
                 "percentage_of_net_value": "9.5%",
                 "usd_value": "180"
             },
             "blockchain": {
                 "percentage_of_net_value": "90%",
                 "usd_value": "4000"
             }
         }

    },
    "message": ""
}
Response JSON Object:
 
  • result (object) – Each key of the result object is an asset. Each asset’s value is another object with the following keys. "amount" is the amount owned in total for that asset. "percentage_of_net_value" is the percentage the user’s net worth that this asset represents. And finally "usd_value" is the total $ value this asset is worth as of this query. There is also a "location" key in the result. In there are the same results as the rest but divided by location as can be seen by the example response above.
Status Codes:

Querying FIAT balances

GET /api/(version)/balances/fiat/

Doing a GET on the FIAT balances endpoint will query the FIAT balances of the user.

Example Request:

http

GET /api/1/balances/fiat/ HTTP/1.1
Host: localhost:5042

curl

curl -i http://localhost:5042/api/1/balances/fiat/

wget

wget -S -O- http://localhost:5042/api/1/balances/fiat/

httpie

http http://localhost:5042/api/1/balances/fiat/

python-requests

requests.get('http://localhost:5042/api/1/balances/fiat/')

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "EUR": {"amount": "150", "usd_value": "166.21"},
        "CNY": {"amount": "10500", "usd_value": "1486.05"}
    },
    "message": ""
}
Response JSON Object:
 
  • result (object) – Each key of the result object is as defined here.
Status Codes:

Setting FIAT balances

PATCH /api/(version)/balances/fiat/

Doing a PATCH on the FIAT balances endpoint will edit the FIAT balances of the given currencies for the currently logged in user. If the balance for an asset is set to 0 then that asset is removed from the database. Negative balance is an error.

Example Request:

http

PATCH /api/1/balances/fiat/ HTTP/1.1
Host: localhost:5042

{"balances": {"EUR": "5000", "USD": "3000"}}

curl

curl -i -X PATCH http://localhost:5042/api/1/balances/fiat/ --data-raw '{"balances": {"EUR": "5000", "USD": "3000"}}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/balances/fiat/ --body-data='{"balances": {"EUR": "5000", "USD": "3000"}}'

httpie

echo '{"balances": {"EUR": "5000", "USD": "3000"}}' | http PATCH http://localhost:5042/api/1/balances/fiat/

python-requests

requests.patch('http://localhost:5042/api/1/balances/fiat/', data='{"balances": {"EUR": "5000", "USD": "3000"}}')
Request JSON Object:
 
  • balances (object) – An object with each key being a FIAT asset and each value the amount of that asset the user owns.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "EUR": {"amount": "5000", "usd_value": "6130"},
        "USD": {"amount": "3000", "usd_value": "3000"},
        "CNY": {"amount": "10500", "usd_value": "1486.05"}
    },
    "message": ""
}
Response JSON Object:
 
  • result (object) – Each key of the result object is as defined here.
Status Codes:

Querying owned assets

GET /api/(version)/assets/

Doing a GET on the assets endpoint will return a list of all assets ever owned.

Example Request:

http

GET /api/1/assets/ HTTP/1.1
Host: localhost:5042

curl

curl -i http://localhost:5042/api/1/assets/

wget

wget -S -O- http://localhost:5042/api/1/assets/

httpie

http http://localhost:5042/api/1/assets/

python-requests

requests.get('http://localhost:5042/api/1/assets/')

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": ["EUR", "USD", "ETH", "BTC"],
    "message": ""
}
Response JSON Object:
 
  • result (list) – A list of asset symbols owned by the user
Status Codes:

Statistics for netvalue over time

GET /api/(version)/statistics/netvalue/

Note

This endpoint is only available for premium users

Doing a GET on the statistics netvalue over time endpoint will return all the saved historical data points with user’s history

Example Request:

http

GET /api/1/statistics/netvalue/ HTTP/1.1
Host: localhost:5042

curl

curl -i http://localhost:5042/api/1/statistics/netvalue/

wget

wget -S -O- http://localhost:5042/api/1/statistics/netvalue/

httpie

http http://localhost:5042/api/1/statistics/netvalue/

python-requests

requests.get('http://localhost:5042/api/1/statistics/netvalue/')

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "times": [1571992200, 1572078657],
        "data": ["15000", "17541.23"]
    },
    "message": ""
}
Response JSON Object:
 
  • times (list[integer]) – A list of timestamps for the returned data points
  • data (list[string]) – A list of net usd value for the corresponding timestamps. They are matched by list index.
Status Codes:

Statistics for asset balance over time

GET /api/(version)/statistics/balance/(asset name)

Note

This endpoint is only available for premium users

Note

This endpoint also accepts parameters as query arguments.

Doing a GET on the statistics asset balance over time endpoint will return all saved balance entries for an asset. Optionally you can filter for a specific time range by providing appropriate arguments.

Example Request:

http

GET /api/1/statistics/balance/BTC HTTP/1.1
Host: localhost:5042

{"from_timestamp": 1514764800, "to_timestamp": 1572080165}

curl

curl -i http://localhost:5042/api/1/statistics/balance/BTC --data-raw '{"from_timestamp": 1514764800, "to_timestamp": 1572080165}'

wget

wget -S -O- http://localhost:5042/api/1/statistics/balance/BTC --body-data='{"from_timestamp": 1514764800, "to_timestamp": 1572080165}'

httpie

echo '{"from_timestamp": 1514764800, "to_timestamp": 1572080165}' | http http://localhost:5042/api/1/statistics/balance/BTC

python-requests

requests.get('http://localhost:5042/api/1/statistics/balance/BTC', data='{"from_timestamp": 1514764800, "to_timestamp": 1572080165}')
Request JSON Object:
 
  • from_timestamp (int) – The timestamp after which to return saved balances for the asset. If not given zero is considered as the start.
  • to_timestamp (int) – The timestamp until which to return saved balances for the asset. If not given all balances until now are returned.
Parameters:
  • from_timestamp (int) – The timestamp after which to return saved balances for the asset. If not given zero is considered as the start.
  • to_timestamp (int) – The timestamp until which to return saved balances for the asset. If not given all balances until now are returned.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": [{
        "time": 1571992200,
        "amount": "1.1",
        "usd_value": "8901.1"
        }, {
        "time": 15720001,
        "amount": "1.2",
        "usd_value": "9501.3"
    }],
    "message": ""
}
Response JSON Object:
 
  • result (list(object)) – A list of asset balance entries.
Response JSON Array of Objects:
 
  • time (integer) – The timestamp of the balance entry.
  • amount (number) – The amount of the balance entry.
  • usd_value (number) – The usd_value of the balance entry at the given timestamp.
Status Codes:
  • 200 OK – Single asset balance statistics succesfuly queried
  • 400 Bad Request – Provided JSON is in some way malformed or data is invalid.
  • 409 Conflict – No user is currently logged in or currently logged in user does not have a premium subscription.
  • 500 Internal Server Error – Internal Rotki error

Statistics for value distribution

GET /api/(version)/statistics/value_distribution/

Doing a GET on the statistics value distribution endpoint with the "distribution_by": "location" argument will return the distribution of netvalue across all locations.

Note

This endpoint is only available for premium users

Note

This endpoint also accepts parameters as query arguments.

Example Request:

http

GET /api/1/statistics/value_distribution/ HTTP/1.1
Host: localhost:5042

{"distribution_by": "location"}

curl

curl -i http://localhost:5042/api/1/statistics/value_distribution/ --data-raw '{"distribution_by": "location"}'

wget

wget -S -O- http://localhost:5042/api/1/statistics/value_distribution/ --body-data='{"distribution_by": "location"}'

httpie

echo '{"distribution_by": "location"}' | http http://localhost:5042/api/1/statistics/value_distribution/

python-requests

requests.get('http://localhost:5042/api/1/statistics/value_distribution/', data='{"distribution_by": "location"}')
Request JSON Object:
 
  • distribution_by (str) – The type of distribution to return. It can only be "location" or "asset".
Parameters:
  • distribution_by (str) – The type of distribution to return. It can only be "location" or "asset".

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": [{
        "time": 1571992200,
        "location": "kraken",
        "usd_value": "8901.1"
        }, {
        "time": 1571992200,
        "location": "binance",
        "usd_value": "9501.3"
    }],
    "message": ""
}
Response JSON Object:
 
  • result (list(object)) – A list of location data entries.
Response JSON Array of Objects:
 
  • time (integer) – The timestamp of the entry
  • location (string) – The location of the entry.
  • usd_value (string) – The value of the entry in $.
Status Codes:
  • 200 OK – Value distribution succesfully queried.
  • 400 Bad Request – Provided JSON is in some way malformed or data is invalid.
  • 409 Conflict – No user is currently logged in or currently logged in user does not have a premium subscription.
  • 500 Internal Server Error – Internal Rotki error.
GET /api/(version)/statistics/value_distribution/

Note

This endpoint is only available for premium users

Doing a GET on the statistics value distribution endpoint with the "distribution_by": "asset" argument will return the distribution of netvalue across all assets.

Example Request:

http

GET /api/1/statistics/value_distribution/ HTTP/1.1
Host: localhost:5042

{"distribution_by": "asset"}

curl

curl -i http://localhost:5042/api/1/statistics/value_distribution/ --data-raw '{"distribution_by": "asset"}'

wget

wget -S -O- http://localhost:5042/api/1/statistics/value_distribution/ --body-data='{"distribution_by": "asset"}'

httpie

echo '{"distribution_by": "asset"}' | http http://localhost:5042/api/1/statistics/value_distribution/

python-requests

requests.get('http://localhost:5042/api/1/statistics/value_distribution/', data='{"distribution_by": "asset"}')
Request JSON Object:
 
  • distribution_by (str) – The type of distribution to return. It can only be "location" or "asset".
Parameters:
  • distribution_by (str) – The type of distribution to return. It can only be "location" or "asset".

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": [{
        "time": 1571992200,
        "asset": "BTC",
        "amount": "1.2"
        "usd_value": "8901.1"
        }, {
        "time": 1571992200,
        "asset": "ETH",
        "amount": "80.44",
        "usd_value": "9501.3"
    }],
    "message": ""
}
Response JSON Object:
 
  • result (list(object)) – A list of asset balance data entries. Each entry contains the timestamp of the entry, the assets, the amount in asset and the equivalent usd value at the time.
Response JSON Array of Objects:
 
  • time (integer) – The timestamp of the balance entry.
  • asset (string) – The name of the asset for the balance entry.
  • amount (string) – The amount in asset for the balance entry.
  • usd_value (string) – The amount in $ for the balance entry at the time of query.
Status Codes:
  • 200 OK – Value distribution succesfully queried.
  • 400 Bad Request – Provided JSON is in some way malformed or data is invalid.
  • 409 Conflict – No user is currently logged in or currently logged in user does not have a premium subscription.
  • 500 Internal Server Error – Internal Rotki error.

Statistics rendering code

GET /api/(version)/statistics/renderer/

Doing a GET on the statistics renderer will return the code to render the statistics if the currently logged in user is a premium user.

Note

This endpoint is only available for premium users

Example Request:

http

GET /api/1/statistics/renderer/ HTTP/1.1
Host: localhost:5042

curl

curl -i http://localhost:5042/api/1/statistics/renderer/

wget

wget -S -O- http://localhost:5042/api/1/statistics/renderer/

httpie

http http://localhost:5042/api/1/statistics/renderer/

python-requests

requests.get('http://localhost:5042/api/1/statistics/renderer/')

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": "code goes here"
    "message": ""
}
Response JSON Object:
 
  • result (string) – The source code of the renderer.
Status Codes:
  • 200 OK – Rendering code succesfully returned.
  • 400 Bad Request – Provided JSON is in some way malformed.
  • 409 Conflict – No user is currently logged in or currently logged in user does not have a premium subscription. There is a problem reaching the Rotki server.
  • 500 Internal Server Error – Internal Rotki error.

Dealing with trades

GET /api/(version)/trades

Note

This endpoint also accepts parameters as query arguments.

Doing a GET on this endpoint will return all trades of the current user. They can be further filtered by time range and/or location.

Example Request:

http

GET /api/1/trades HTTP/1.1
Host: localhost:5042

{"from_timestamp": 1451606400, "to_timestamp": 1571663098, "location": "external"}

curl

curl -i http://localhost:5042/api/1/trades --data-raw '{"from_timestamp": 1451606400, "to_timestamp": 1571663098, "location": "external"}'

wget

wget -S -O- http://localhost:5042/api/1/trades --body-data='{"from_timestamp": 1451606400, "to_timestamp": 1571663098, "location": "external"}'

httpie

echo '{"from_timestamp": 1451606400, "to_timestamp": 1571663098, "location": "external"}' | http http://localhost:5042/api/1/trades

python-requests

requests.get('http://localhost:5042/api/1/trades', data='{"from_timestamp": 1451606400, "to_timestamp": 1571663098, "location": "external"}')
Request JSON Object:
 
  • from_timestamp (int) – The timestamp from which to query. Can be missing in which case we query from 0.
  • to_timestamp (int) – The timestamp until which to query. Can be missing in which case we query until now.
  • location (string) – Optionally filter trades by location. A valid location name has to be provided. If missing location filtering does not happen.
Parameters:
  • from_timestamp (int) – The timestamp from which to query. Can be missing in which case we query from 0.
  • to_timestamp (int) – The timestamp until which to query. Can be missing in which case we query until now.
  • location (string) – Optionally filter trades by location. A valid location name has to be provided. If missing location filtering does not happen.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": [{
        "trade_id": "dsadfasdsad",
        "timestamp": 1491606401,
        "location": "external",
        "pair": "BTC_EUR",
        "trade_type": "buy",
        "amount": "0.5541",
        "rate": "8422.1",
        "fee": "0.55",
        "fee_currency": "USD",
        "link": "Optional unique trade identifier"
        "notes": "Optional notes"
    }]
    "message": ""
}
Response JSON Object:
 
  • result (object) – An array of trade objects.
Response JSON Array of Objects:
 
  • trade_id (string) – The uniquely identifying identifier for this trade.
  • timestamp (int) – The timestamp at which the trade occured
  • location (string) – A valid location at which the trade happened
  • pair (string) – The pair for the trade. e.g. "BTC_EUR"
  • trade_type (string) – The type of the trade. e.g. "buy" or "sell"
  • amount (string) – The amount that was bought or sold
  • rate (string) – The rate at which 1 unit of base_asset was exchanges for 1 unit of quote_asset
  • fee (string) – The fee that was paid, if anything, for this trade
  • fee_currency (string) – The currency in which fee is denominated in
  • link (string) – Optional unique trade identifier or link to the trade. Can be an empty string
  • notes (string) – Optional notes about the trade. Can be an empty string
Status Codes:
PUT /api/(version)/trades

Doing a PUT on this endpoint adds a new trade to Rotki’s currently logged in user.

Example Request:

http

PUT /api/1/trades HTTP/1.1
Host: localhost:5042

{
    "timestamp": 1491606401,
    "location": "external",
    "pair": "BTC_EUR",
    "trade_type": "buy",
    "amount": "0.5541",
    "rate": "8422.1",
    "fee": "0.55",
    "fee_currency": "USD",
    "link": "Optional unique trade identifier"
    "notes": "Optional notes"
}

curl

curl -i -X PUT http://localhost:5042/api/1/trades --data-raw '{

    "timestamp": 1491606401,

    "location": "external",

    "pair": "BTC_EUR",

    "trade_type": "buy",

    "amount": "0.5541",

    "rate": "8422.1",

    "fee": "0.55",

    "fee_currency": "USD",

    "link": "Optional unique trade identifier"

    "notes": "Optional notes"

}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/trades --body-data='{

    "timestamp": 1491606401,

    "location": "external",

    "pair": "BTC_EUR",

    "trade_type": "buy",

    "amount": "0.5541",

    "rate": "8422.1",

    "fee": "0.55",

    "fee_currency": "USD",

    "link": "Optional unique trade identifier"

    "notes": "Optional notes"

}'

httpie

echo '{

    "timestamp": 1491606401,

    "location": "external",

    "pair": "BTC_EUR",

    "trade_type": "buy",

    "amount": "0.5541",

    "rate": "8422.1",

    "fee": "0.55",

    "fee_currency": "USD",

    "link": "Optional unique trade identifier"

    "notes": "Optional notes"

}' | http PUT http://localhost:5042/api/1/trades

python-requests

requests.put('http://localhost:5042/api/1/trades', data='{\r\n\n    "timestamp": 1491606401,\r\n\n    "location": "external",\r\n\n    "pair": "BTC_EUR",\r\n\n    "trade_type": "buy",\r\n\n    "amount": "0.5541",\r\n\n    "rate": "8422.1",\r\n\n    "fee": "0.55",\r\n\n    "fee_currency": "USD",\r\n\n    "link": "Optional unique trade identifier"\r\n\n    "notes": "Optional notes"\r\n\n}')
Request JSON Object:
 
  • timestamp (int) – The timestamp at which the trade occured
  • location (string) – A valid location at which the trade happened
  • pair (string) – The pair for the trade. e.g. "BTC_EUR"
  • trade_type (string) – The type of the trade. e.g. "buy" or "sell"
  • amount (string) – The amount that was bought or sold
  • rate (string) – The rate at which 1 unit of base_asset was exchanges for 1 unit of quote_asset
  • fee (string) – The fee that was paid, if anything, for this trade
  • fee_currency (string) – The currency in which fee is denominated in
  • link (string) – Optional unique trade identifier or link to the trade. Can be an empty string
  • notes (string) – Optional notes about the trade. Can be an empty string

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": [{
        "trade_id": "dsadfasdsad",
        "timestamp": 1491606401,
        "location": "external",
        "pair": "BTC_EUR",
        "trade_type": "buy",
        "amount": "0.5541",
        "rate": "8422.1",
        "fee": "0.55",
        "fee_currency": "USD",
        "link": "Optional unique trade identifier"
        "notes": "Optional notes"
    }]
    "message": ""
}
Response JSON Object:
 
  • result (object) – Array of trades with the same schema as seen in this section.
Status Codes:
PATCH /api/(version)/trades

Doing a PATCH on this endpoint edits an existing trade in Rotki’s currently logged in user using the trade_identifier.

Example Request:

http

PATCH /api/1/trades HTTP/1.1
Host: localhost:5042

{
    "trade_id" : "dsadfasdsad",
    "timestamp": 1491606401,
    "location": "external",
    "pair": "BTC_EUR",
    "trade_type": "buy",
    "amount": "1.5541",
    "rate": "8422.1",
    "fee": "0.55",
    "fee_currency": "USD",
    "link": "Optional unique trade identifier"
    "notes": "Optional notes"
}

curl

curl -i -X PATCH http://localhost:5042/api/1/trades --data-raw '{

    "trade_id" : "dsadfasdsad",

    "timestamp": 1491606401,

    "location": "external",

    "pair": "BTC_EUR",

    "trade_type": "buy",

    "amount": "1.5541",

    "rate": "8422.1",

    "fee": "0.55",

    "fee_currency": "USD",

    "link": "Optional unique trade identifier"

    "notes": "Optional notes"

}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/trades --body-data='{

    "trade_id" : "dsadfasdsad",

    "timestamp": 1491606401,

    "location": "external",

    "pair": "BTC_EUR",

    "trade_type": "buy",

    "amount": "1.5541",

    "rate": "8422.1",

    "fee": "0.55",

    "fee_currency": "USD",

    "link": "Optional unique trade identifier"

    "notes": "Optional notes"

}'

httpie

echo '{

    "trade_id" : "dsadfasdsad",

    "timestamp": 1491606401,

    "location": "external",

    "pair": "BTC_EUR",

    "trade_type": "buy",

    "amount": "1.5541",

    "rate": "8422.1",

    "fee": "0.55",

    "fee_currency": "USD",

    "link": "Optional unique trade identifier"

    "notes": "Optional notes"

}' | http PATCH http://localhost:5042/api/1/trades

python-requests

requests.patch('http://localhost:5042/api/1/trades', data='{\r\n\n    "trade_id" : "dsadfasdsad",\r\n\n    "timestamp": 1491606401,\r\n\n    "location": "external",\r\n\n    "pair": "BTC_EUR",\r\n\n    "trade_type": "buy",\r\n\n    "amount": "1.5541",\r\n\n    "rate": "8422.1",\r\n\n    "fee": "0.55",\r\n\n    "fee_currency": "USD",\r\n\n    "link": "Optional unique trade identifier"\r\n\n    "notes": "Optional notes"\r\n\n}')
Request JSON Object:
 
  • trade_id (string) – The trade_id of the trade to edit
  • timestamp (int) – The new timestamp
  • location (string) – The new location
  • pair (string) – The new pair
  • trade_type (string) – The new trade type
  • rate (string) – The new trade rate
  • fee (string) – The new fee
  • fee_currency (string) – The new fee currency
  • link (string) – The new link attribute
  • notes (string) – The new notes attribute

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "trade_id": "sdfhdjskfha",
        "timestamp": 1491606401,
        "location": "external",
        "pair": "BTC_EUR",
        "trade_type": "buy",
        "amount": "1.5541",
        "rate": "8422.1",
        "fee": "0.55",
        "fee_currency": "USD",
        "link": "Optional unique trade identifier"
        "notes": "Optional notes"
    }
    "message": ""
}
Response JSON Object:
 
  • result (object) – A trade with the same schema as seen in this section.
Status Codes:
DELETE /api/(version)/trades

Doing a DELETE on this endpoint deletes an existing trade in Rotki’s currently logged in user using the trade_identifier.

Example Request:

http

DELETE /api/1/trades HTTP/1.1
Host: localhost:5042

{ "trade_id" : "dsadfasdsad"}

curl

curl -i -X DELETE http://localhost:5042/api/1/trades --data-raw '{ "trade_id" : "dsadfasdsad"}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/trades --body-data='{ "trade_id" : "dsadfasdsad"}'

httpie

echo '{ "trade_id" : "dsadfasdsad"}' | http DELETE http://localhost:5042/api/1/trades

python-requests

requests.delete('http://localhost:5042/api/1/trades', data='{ "trade_id" : "dsadfasdsad"}')
Request JSON Object:
 
  • trade_id (string) – The trade_id of the trade to delete.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": true,
    "message": ""
}
Response JSON Object:
 
  • result (bool) – Boolean indicating succes or failure of the request.
Status Codes:

Querying messages to show to the user

GET /api/(version)/messages/

Doing a GET on the messages endpoint will pop all errors and warnings from the message queue and return them. The message queue is a queue where all errors and warnings that are supposed to be see by the user are saved and are supposed to be popped and read regularly.

Example Request:

http

GET /api/1/messages/ HTTP/1.1
Host: localhost:5042

curl

curl -i http://localhost:5042/api/1/messages/

wget

wget -S -O- http://localhost:5042/api/1/messages/

httpie

http http://localhost:5042/api/1/messages/

python-requests

requests.get('http://localhost:5042/api/1/messages/')

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "errors": ["Something bad happened", "Another bad thing happened"],
        "warnings": ["An asset could not be queried", "Can not reach kraken"]
    },
    "message": ""
}
Response JSON Object:
 
  • errors (list[string]) – A list of strings denoting errors that need to be shown to the user.
  • warnings (list[string]) – A list of strings denoting warnings that need to be shown to the user.
Status Codes:

Querying complete action history

GET /api/(version)/history/

Note

This endpoint can also be queried asynchronously by using "async_query": true

Note

This endpoint also accepts parameters as query arguments.

Doing a GET on the history endpoint will trigger a query and processing of the history of all actions (trades, deposits, withdrawals, loans, eth transactions) within a specific time range. Passing them as a query arguments here would be given as: ?async_query=true&from_timestamp=1514764800&to_timestamp=1572080165.

Example Request:

http

GET /api/1/history/ HTTP/1.1
Host: localhost:5042

{"from_timestamp": 1514764800, "to_timestamp": 1572080165, "async_query": true}

curl

curl -i http://localhost:5042/api/1/history/ --data-raw '{"from_timestamp": 1514764800, "to_timestamp": 1572080165, "async_query": true}'

wget

wget -S -O- http://localhost:5042/api/1/history/ --body-data='{"from_timestamp": 1514764800, "to_timestamp": 1572080165, "async_query": true}'

httpie

echo '{"from_timestamp": 1514764800, "to_timestamp": 1572080165, "async_query": true}' | http http://localhost:5042/api/1/history/

python-requests

requests.get('http://localhost:5042/api/1/history/', data='{"from_timestamp": 1514764800, "to_timestamp": 1572080165, "async_query": true}')
Request JSON Object:
 
  • from_timestamp (int) – The timestamp after which to return action history. If not given zero is considered as the start.
  • to_timestamp (int) – The timestamp until which to return action history. If not given all balances until now are returned.
  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not
Parameters:
  • from_timestamp (int) – The timestamp after which to return action history. If not given zero is considered as the start.
  • to_timestamp (int) – The timestamp until which to return action history. If not given all balances until now are returned.
  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "overview": {
            "loan_profit": "1500",
            "margin_positions_profit_loss": "500",
            "settlement_losses": "200",
            "ethereum_transaction_gas_costs": "2.5",
            "asset_movement_fees": "3.45",
            "general_trade_profit_loss": "5002",
            "taxable_trade_profit_loss": "5002",
            "total_taxable_profit_loss": "6796.05",
            "total_profit_loss": "6796.05"
        },
        "all_events": [{
            "type": "buy",
            "paid_in_profit_currency": "4000",
            "paid_asset": "BTC",
            "paid_in_asset": "0.5",
            "taxable_amount": "not applicable",
            "taxable_bought_cost_in_profit_currency": "not applicable",
            "received_asset": "ETH",
            "taxable_received_in_profit_currency": "0",
            "received_in_asset": "24",
            "net_profit_or_loss": "0",
            "time": 1514765800,
            "is_virtual": false
        }, {
            "type": "sell",
            "paid_in_profit_currency": "0",
            "paid_asset": "BTC",
            "paid_in_asset": "0.2",
            "taxable_amount": "0.1",
            "taxable_bought_cost_in_profit_currency": "600",
            "received_asset": "EUR",
            "taxable_received_in_profit_currency": "800",
            "received_in_asset": "1600",
            "net_profit_or_loss": "200",
            "time": 1524865800,
            "is_virtual": false
        }],
    },
    "message": ""
}

The overview part of the result is a dictionary with the following keys:

Response JSON Object:
 
  • loan_profit (str) – The profit from loans inside the given time period denominated in the user’s profit currency.
  • margin_positions_profit_loss (str) – The profit/loss from margin positions inside the given time period denominated in the user’s profit currency.
  • settlement_losses (str) – The losses from margin settlements inside the given time period denominated in the user’s profit currency.
  • ethereum_transactions_gas_costs (str) – The losses from ethereum gas fees inside the given time period denominated in the user’s profit currency.
  • asset_movement_fees (str) – The losses from exchange deposit/withdral fees inside the given time period denominated in the user’s profit currency.
  • general_trade_profit_loss (str) – The profit/loss from all trades inside the given time period denominated in the user’s profit currency.
  • taxable_trade_profit_loss (str) – The portion of the profit/loss from all trades that is taxable and is inside the given time period denominated in the user’s profit currency.
  • total_taxable_profit_loss (str) – The portion of all profit/loss that is taxable and is inside the given time period denominated in the user’s profit currency.
  • total_profit_loss (str) – The total profit loss inside the given time period denominated in the user’s profit currency.

The all_events part of the result is a list of events with the following keys:

Response JSON Object:
 
  • type (str) – The type of event. Can be one of "buy", "sell", "tx_gas_cost", "asset_movement", "loan_settlement", "interest_rate_payment", "margin_position_close"
  • paid_in_profit_currency (str) – The total amount paid for this action in the user’s profit currency. This will always be zero for sells and other actions that only give profit.
  • paid_asset (str) – The asset that was paid for in this action.
  • paid_in_asset (str) – The amount of paid_asset that was used in this action.
  • taxable_amount (str) – For sells and other similar actions this is the part of the paid_in_asset that is considered taxable. Can differ for jurisdictions like Germany where after a year of holding trades are not taxable. For buys this will have the string "not applicable".
  • taxable_bought_cost_in_profit_currency (str) – For sells and other similar actions this is the part of the paid_in_asset that is considered taxable. Can differ for jurisdictions like Germany where after a year of holding trades are not taxable. For buys this will have the string "not applicable".
  • received_asset (str) – The asset that we received from this action. For buys this is the asset that we bought and for sells the asset that we got by selling.
  • taxable_received_in_profit_currency (str) – The taxable portion of the asset that we received from this action in profit currency. Can be different than the price of received_in_asset in profit currency if not the entire amount that was exchanged was taxable. For buys this would be 0.
  • received_in_asset (str) – The amount of received_asset that we received from this action.
  • net_profit_or_loss (str) – The net profit/loss from this action denoted in profit currency.
  • time (int) – The timestamp this action took place in.
  • is_virtual (bool) – A boolean denoting whether this is a virtual action. Virtual actions are special actions that are created to make accounting for crypto to crypto trades possible. For example, if you sell BTC for ETH a virtual trade to sell BTC for EUR and then a virtual buy to buy BTC with EUR will be created.
Status Codes:

Export action history to CSV

GET /api/(version)/history/export

Note

This endpoint also accepts parameters as query arguments.

Doing a GET on the history export endpoint will export the last previously queried history to CSV files and save them in the given directory. If history has not been queried before an error is returned.

Example Request:

http

GET /api/1/history/export HTTP/1.1
Host: localhost:5042

{"directory_path": "/home/username/path/to/csvdir"}

curl

curl -i http://localhost:5042/api/1/history/export --data-raw '{"directory_path": "/home/username/path/to/csvdir"}'

wget

wget -S -O- http://localhost:5042/api/1/history/export --body-data='{"directory_path": "/home/username/path/to/csvdir"}'

httpie

echo '{"directory_path": "/home/username/path/to/csvdir"}' | http http://localhost:5042/api/1/history/export

python-requests

requests.get('http://localhost:5042/api/1/history/export', data='{"directory_path": "/home/username/path/to/csvdir"}')
Request JSON Object:
 
  • directory_path (str) – The directory in which to write the exported CSV files
Parameters:
  • directory_path (str) – The directory in which to write the exported CSV files

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": true
    "message": ""
}
Response JSON Object:
 
  • result (bool) – Boolean denoting succes or failure of the query
Status Codes:
  • 200 OK – File were exported succesfully
  • 400 Bad Request – Provided JSON is in some way malformed or given string is not a directory.
  • 409 Conflict – No user is currently logged in. No history has been processed. No permissions to write in the given directory. Check error message.
  • 500 Internal Server Error – Internal Rotki error.

Querying periodic data

GET /api/(version)/periodic/

Doing a GET on the periodic data endpoint will return data that would be usually frequently queried by an application. Check the example response to see what these data would be.

Example Request:

http

GET /api/1/periodict/ HTTP/1.1
Host: localhost:5042

curl

curl -i http://localhost:5042/api/1/periodict/

wget

wget -S -O- http://localhost:5042/api/1/periodict/

httpie

http http://localhost:5042/api/1/periodict/

python-requests

requests.get('http://localhost:5042/api/1/periodict/')

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "last_balance_save": 1572345881,
        "eth_node_connection": true,
        "history_process_start_ts": 1572325881,
        "history_process_current_ts": 1572345881
    }
    "message": ""
}
Response JSON Object:
 
  • last_balance_save (int) – The last time (unix timestamp) at which balances were saved in the database.
  • eth_node_connection (bool) – A boolean denoting if the application is connected to an ethereum node. If false that means we fall back to etherscan.
  • history_process_start_ts (int) – A unix timestamp indicating the time that the last history processing started. Meant to be queried frequently so that a progress bar can be provided to the user.
  • history_process_current_ts (int) – A unix timestamp indicating the current time as far as the last history processing is concerned. Meant to be queried frequently so that a progress bar can be provided to the user.
Status Codes:

Getting information about ETH tokens

GET /api/(version)/blockchains/ETH/tokens

Doing a GET on the eth tokens endpoint will return a list of all known ETH tokens and a list of the currently owned ETH tokens.

Example Request:

http

GET /api/1/blockchains/ETH/tokens HTTP/1.1
Host: localhost:5042

curl

curl -i http://localhost:5042/api/1/blockchains/ETH/tokens

wget

wget -S -O- http://localhost:5042/api/1/blockchains/ETH/tokens

httpie

http http://localhost:5042/api/1/blockchains/ETH/tokens

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/tokens')

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "all_eth_tokens": [{
            "address": "0x6810e776880C02933D47DB1b9fc05908e5386b96",
            "symbol": "GNO",
            "name": "Gnosis token",
            "decimal": 18
        }, {
            "address": "0x255Aa6DF07540Cb5d3d297f0D0D4D84cb52bc8e6",
            "symbol": "RDN",
            "name": "Raiden Network Token",
            "decimal": 18
        }],
        "owned_eth_tokens": ["RDN", "DAI"]
    },
    "message": ""
}
Response JSON Object:
 
  • all_eth_tokens (list[object]) – A list of token information for all tokens that Rotki knows about. Each entry contains the checksummed address of the token, the symbol, the name and the decimals.
  • owned_eth_tokens (list[string]) – A list of the symbols of all the tokens the user tracks/owns.

Each token in "all_eth_tokens" contains the following keys:

Response JSON Array of Objects:
 
  • address (string) – The address of the token’s contract.
  • symbol (string) – The symbol of the ethereum token.
  • name (string) – The name of the token
  • decimals (integer) – The number of decimals the token uses.
Status Codes:

Adding owned ETH tokens

PUT /api/(version)/blockchains/ETH/tokens

Note

This endpoint can also be queried asynchronously by using "async_query": true

Doing a PUT on the eth tokens endpoint with a list of tokens to add will add new ethereum tokens for tracking to the currently logged in user. It returns the updated blockchain per account and totals balances after the additions

Example Request:

http

PUT /api/1/blockchains/ETH/tokens HTTP/1.1
Host: localhost:5042

{"eth_tokens": ["RDN", "GNO"]}

curl

curl -i -X PUT http://localhost:5042/api/1/blockchains/ETH/tokens --data-raw '{"eth_tokens": ["RDN", "GNO"]}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/blockchains/ETH/tokens --body-data='{"eth_tokens": ["RDN", "GNO"]}'

httpie

echo '{"eth_tokens": ["RDN", "GNO"]}' | http PUT http://localhost:5042/api/1/blockchains/ETH/tokens

python-requests

requests.put('http://localhost:5042/api/1/blockchains/ETH/tokens', data='{"eth_tokens": ["RDN", "GNO"]}')
Request JSON Object:
 
  • eth_tokens (list) – A list of ethereum token symbols to add
  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "per_account": {
            "BTC": { "3Kb9QPcTUJKspzjQFBppfXRcWew6hyDAPb": {
                 "amount": "0.5", "usd_value": "3770.075"
             }, "33hjmoU9XjEz8aLxf44FNGB8TdrLkAVBBo": {
                 "amount": "0.5", "usd_value": "3770.075"
             }},
             "ETH": { "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B": {
                 "assets": {
                     "ETH": {"amount": "10", "usd_value": "1755.53"},
                     "GNO": {"amount": "1", "usd_value": "50"},
                     "RDN": {"amount": "1", "usd_value": "1.5"}
                 },
                 "total_usd_value": "1807.03",
            }}
        },
        "totals": {
            "BTC": {"amount": "1", "usd_value": "7540.15"},
            "ETH": {"amount": "10", "usd_value": "1650.53"},
            "RDN": {"amount": "1", "usd_value": "1.5"},
            "GNO": {"amount": "1", "usd_value": "50"}
        }
    },
    "message": ""
}
Response JSON Object:
 
  • result (object) – An object containing the "per_account" and "totals" keys as also defined here.
Status Codes:
  • 200 OK – Tokens succesfully added.
  • 400 Bad Request – Provided JSON or data is in some way malformed.
  • 409 Conflict – User is not logged in. There was some problem with querying balances after token addition. Check the message.
  • 500 Internal Server Error – Internal Rotki error
  • 502 Bad Gateway – Error occured with some external service query such as Etherscan. Check message for details.

Removing owned ETH tokens

DELETE /api/(version)/blockchains/ETH/tokens

Note

This endpoint can also be queried asynchronously by using "async_query": true

Doing a DELETE on the eth tokens endpoint with a list of tokens to delete will remove the given ethereum tokens from tracking for the currently logged in user. It returns the updated blockchain per account and totals balances after the deletions.

Example Request:

http

DELETE /api/1/blockchains/ETH/tokens HTTP/1.1
Host: localhost:5042

{"eth_tokens": ["RDN", "GNO"]}

curl

curl -i -X DELETE http://localhost:5042/api/1/blockchains/ETH/tokens --data-raw '{"eth_tokens": ["RDN", "GNO"]}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/blockchains/ETH/tokens --body-data='{"eth_tokens": ["RDN", "GNO"]}'

httpie

echo '{"eth_tokens": ["RDN", "GNO"]}' | http DELETE http://localhost:5042/api/1/blockchains/ETH/tokens

python-requests

requests.delete('http://localhost:5042/api/1/blockchains/ETH/tokens', data='{"eth_tokens": ["RDN", "GNO"]}')
Request JSON Object:
 
  • eth_tokens (list) – A list of ethereum token symbols to delete
  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "per_account": {
            "BTC": { "3Kb9QPcTUJKspzjQFBppfXRcWew6hyDAPb": {
                 "amount": "0.5", "usd_value": "3770.075"
             }, "33hjmoU9XjEz8aLxf44FNGB8TdrLkAVBBo": {
                 "amount": "0.5", "usd_value": "3770.075"
             }},
             "ETH": { "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B": {
                 "assets": {
                     "ETH": {"amount": "10", "usd_value": "1755.53"}
                 },
                 "total_usd_value": "1755.53",
            }}
        },
        "totals": {
            "BTC": {"amount": "1", "usd_value": "7540.15"},
            "ETH": {"amount": "10", "usd_value": "1650.53"},
        }
    },
    "message": ""
}
Response JSON Object:
 
  • result (object) – An object containing the "per_account" and "totals" keys as also defined here.
Status Codes:
  • 200 OK – Tokens succesfully deleted.
  • 400 Bad Request – Provided JSON or data is in some way malformed.
  • 409 Conflict – User is not logged in. There was some problem with querying balances after token deletion. Check the message.
  • 500 Internal Server Error – Internal Rotki error
  • 502 Bad Gateway – Error occured with some external service query such as Etherscan. Check message for details.

Getting blockchain account data

GET /api/(version)/blockchains/(name)/

Doing a GET on the blokchcains endpoint with a specific blockchain queries account data information for that blockchain.

Example Request:

http

GET /api/1/blockchains/ETH/ HTTP/1.1
Host: localhost:5042

curl

curl -i http://localhost:5042/api/1/blockchains/ETH/

wget

wget -S -O- http://localhost:5042/api/1/blockchains/ETH/

httpie

http http://localhost:5042/api/1/blockchains/ETH/

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/')

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result" : [{
        "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",
        "label": "my new metamask",
        "tags": ["public", "metamask"]
     }, {
        "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b",
        "label": null,
        "tags": ["private"]
     }],
     "message": "",
}
Response JSON Object:
 
  • result (list) – A list with the account data details
Response JSON Array of Objects:
 
  • address (string) – The address, which is the unique identifier of each account
  • label (string) – The label to describe the account. Can also be null.
  • tags (list) – A list of tags associated with the account. Can also be null.
Status Codes:

Getting current ethereum MakerDAO DSR balance

GET /api/(version)/blockchains/ETH/modules/makerdao/dsrbalance

Doing a GET on the makerdao dsrbalance resource will return the current balance held in DSR by any of the user’s accounts that ever had DAI deposited in the DSR and also the current DSR percentage.

Note

This endpoint can also be queried asynchronously by using "async_query": true

Note

This endpoint also accepts parameters as query arguments.

Example Request:

http

GET /api/1/blockchains/ETH/modules/makerdao/dsrbalance HTTP/1.1
Host: localhost:5042

curl

curl -i http://localhost:5042/api/1/blockchains/ETH/modules/makerdao/dsrbalance

wget

wget -S -O- http://localhost:5042/api/1/blockchains/ETH/modules/makerdao/dsrbalance

httpie

http http://localhost:5042/api/1/blockchains/ETH/modules/makerdao/dsrbalance

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/modules/makerdao/dsrbalance')
Request JSON Object:
 
  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "current_dsr": "8.022774065220581075333120100",
        "balances": {
            "0xA0B6B7fEa3a3ce3b9e6512c0c5A157a385e81056": "125.24423",
            "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237": "346.43433"
          }
    },
    "message": ""
}
Response JSON Object:
 
  • result (object) – A mapping of accounts to the number of DAI they have locked in DSR. If an account is not in the mapping Rotki does not see anything locked in DSR for it.
Status Codes:

Getting ethereum MakerDAO DSR historical report

GET /api/(version)/blockchains/ETH/modules/makerdao/dsrhistory

Note

This endpoint is only available for premium users

Doing a GET on the makerdao dsrhistory resource will return the history of deposits and withdrawals of each account to the DSR along with the amount of DAI gained at each step and other information

Note

This endpoint can also be queried asynchronously by using "async_query": true

Note

This endpoint also accepts parameters as query arguments.

Example Request:

http

GET /api/1/blockchains/ETH/modules/makerdao/dsrhistory HTTP/1.1
Host: localhost:5042

curl

curl -i http://localhost:5042/api/1/blockchains/ETH/modules/makerdao/dsrhistory

wget

wget -S -O- http://localhost:5042/api/1/blockchains/ETH/modules/makerdao/dsrhistory

httpie

http http://localhost:5042/api/1/blockchains/ETH/modules/makerdao/dsrhistory

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/modules/makerdao/dsrhistory')
Request JSON Object:
 
  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "0xA0B6B7fEa3a3ce3b9e6512c0c5A157a385e81056": {
            "movements": [{
                "movement_type": "deposit",
                "gain_so_far": "0",
                "amount": "350",
                "block_number": 9128160,
                "timestamp": 1582706553
            }, {
                "movement_type": "deposit",
                "gain_so_far": "0.875232",
                "amount": "50",
                "block_number": 9129165,
                "timestamp": 1582806553
            }, {
                "movement_type": "withdrawal",
                "gain_so_far": "1.12875932",
                "amount": "350",
                "block_number": 9149160,
                "timestamp": 1592706553
            }, {
            }],
            "gain_so_far": "1.14875932"
        },
        "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237": {
            "movements": [{
                "movement_type": "deposit",
                "gain_so_far": "0",
                "amount": "550",
                "block_number": 9128174,
                "timestamp": 1583706553
            }],
            "gain_so_far": "0.953423"
        }
    },
    "message": ""
}
Response JSON Object:
 
  • result (object) – A mapping of accounts to the DSR history report of each account. If an account is not in the mapping Rotki does not see anything locked in DSR for it.
  • movements (object) – A list of deposits/withdrawals to/from the DSR for each account.
  • gain_so_far (string) – The total gain so far from the DSR for this account.
Response JSON Array of Objects:
 
  • movement_type (string) – The type of movement involving the DSR. Can be either “deposit” or “withdrawal”.
  • gain_so_far (string) – The amount of DAI gained for this account in the DSR up until the moment of the given deposit/withdrawal.
  • amount (string) – The amount of DAI deposited or withdrawn from the DSR.
  • block_number (int) – The block number at which the deposit or withdrawal occured.
  • block_number – The timestamp of the block number at which the deposit or withdrawal occured.
Status Codes:
  • 200 OK – DSR history succesfully queried.
  • 409 Conflict – No user is currently logged in or currently logged in user does not have a premium subscription.
  • 500 Internal Server Error – Internal Rotki error
  • 502 Bad Gateway – An external service used in the query such as etherscan could not be reached or returned unexpected response.

Adding blockchain accounts

PUT /api/(version)/blockchains/(name)/

Note

This endpoint can also be queried asynchronously by using "async_query": true

Doing a PUT on the the blockchains endpoint with a specific blockchain URL and a list of account data in the json data will add these accounts to the tracked accounts for the given blockchain and the current user. The updated balances after the account additions are returned. If one of the given accounts to add is invalid the entire request will fail.

Example Request:

http

PUT /api/1/blockchains/ETH/ HTTP/1.1
Host: localhost:5042

{
    "accounts": [{
            "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",
            "label": "my new metamask",
            "tags": ["public", "metamask"]
        }, {
            "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b
        }]
}

curl

curl -i -X PUT http://localhost:5042/api/1/blockchains/ETH/ --data-raw '{

    "accounts": [{

            "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",

            "label": "my new metamask",

            "tags": ["public", "metamask"]

        }, {

            "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b

        }]

}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/blockchains/ETH/ --body-data='{

    "accounts": [{

            "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",

            "label": "my new metamask",

            "tags": ["public", "metamask"]

        }, {

            "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b

        }]

}'

httpie

echo '{

    "accounts": [{

            "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",

            "label": "my new metamask",

            "tags": ["public", "metamask"]

        }, {

            "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b

        }]

}' | http PUT http://localhost:5042/api/1/blockchains/ETH/

python-requests

requests.put('http://localhost:5042/api/1/blockchains/ETH/', data='{\r\n\n    "accounts": [{\r\n\n            "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",\r\n\n            "label": "my new metamask",\r\n\n            "tags": ["public", "metamask"]\r\n\n        }, {\r\n\n            "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b\r\n\n        }]\r\n\n}')
Request JSON Object:
 
  • accounts (list[object]) – A list of account data to add for the given blockchain
  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not
Request JSON Array of Objects:
 
  • address (string) – The address of the account to add
  • label (string[optional]) – An optional label to describe the new account
  • tags (list[optional]) – An optional list of tags to attach to the new account

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "per_account": {
            "BTC": { "3Kb9QPcTUJKspzjQFBppfXRcWew6hyDAPb": {
                 "amount": "0.5", "usd_value": "3770.075"
             }, "33hjmoU9XjEz8aLxf44FNGB8TdrLkAVBBo": {
                 "amount": "0.5", "usd_value": "3770.075"
             }},
             "ETH": { "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B": {
                 "assets": {
                     "ETH": {"amount": "10", "usd_value": "1755.53"},
                     "GNO": {"amount": "1", "usd_value": "50"},
                     "RDN": {"amount": "1", "usd_value": "1.5"}
                 },
                 "total_usd_value": "1807.03",
            }}
        },
        "totals": {
            "BTC": {"amount": "1", "usd_value": "7540.15"},
            "ETH": {"amount": "10", "usd_value": "1650.53"},
            "RDN": {"amount": "1", "usd_value": "1.5"},
            "GNO": {"amount": "1", "usd_value": "50"}
    },
    "message": ""
}
Response JSON Object:
 
  • result (object) – An object containing the "per_account" and "totals" keys as also defined here.
Status Codes:
  • 200 OK – Accounts succesfully added
  • 400 Bad Request – Provided JSON or data is in some way malformed. The accounts to add contained invalid addresses or were an empty list.
  • 409 Conflict – User is not logged in. Some error occured when re-querying the balances after addition. Provided tags do not exist. Check message for details.
  • 500 Internal Server Error – Internal Rotki error
  • 502 Bad Gateway – Error occured with some external service query such as Etherscan. Check message for details.

Editing blockchain account data

PATCH /api/(version)/blockchains/(name)/

Doing a PATCH on the the blockchains endpoint with a specific blockchain URL and a list of accounts to edit will edit the label and tags for those accounts.

Example Request:

http

PATCH /api/1/blockchains/ETH/ HTTP/1.1
Host: localhost:5042

{
    "accounts": [{
        "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",
        "label": "my new metamask",
        "tags": ["public", metamask"]
        }, {
        "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b,
        "label": "my hardware wallet"
        }]
}

curl

curl -i -X PATCH http://localhost:5042/api/1/blockchains/ETH/ --data-raw '{

    "accounts": [{

        "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",

        "label": "my new metamask",

        "tags": ["public", metamask"]

        }, {

        "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b,

        "label": "my hardware wallet"

        }]

}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/blockchains/ETH/ --body-data='{

    "accounts": [{

        "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",

        "label": "my new metamask",

        "tags": ["public", metamask"]

        }, {

        "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b,

        "label": "my hardware wallet"

        }]

}'

httpie

echo '{

    "accounts": [{

        "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",

        "label": "my new metamask",

        "tags": ["public", metamask"]

        }, {

        "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b,

        "label": "my hardware wallet"

        }]

}' | http PATCH http://localhost:5042/api/1/blockchains/ETH/

python-requests

requests.patch('http://localhost:5042/api/1/blockchains/ETH/', data='{\r\n\n    "accounts": [{\r\n\n        "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",\r\n\n        "label": "my new metamask",\r\n\n        "tags": ["public", metamask"]\r\n\n        }, {\r\n\n        "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b,\r\n\n        "label": "my hardware wallet"\r\n\n        }]\r\n\n}')
Request JSON Object:
 
  • accounts (list[object]) – A list of account data to edit for the given blockchain
Request JSON Array of Objects:
 
  • address (string) – The address of the account to add
  • label (string[optional]) – An optional label to edit for the account
  • tags (list[optional]) – An optional list of tags to attach to the account

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result" : [{
        "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",
        "label": "my new metamask",
        "tags": ["public", "metamask"]
     }, {
        "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b",
        "label": "my hardware wallet",
        "tags": null
     }],
     "message": "",
}
Response JSON Object:
 
  • result (list) – A list containing the blockchain account data as also defined here.
Status Codes:
  • 200 OK – Accounts succesfully edited
  • 400 Bad Request – Provided JSON or data is in some way malformed. Given list to edit is empty.
  • 409 Conflict – User is not logged in. An account given to edit does not exist or a given tag does not exist.
  • 500 Internal Server Error – Internal Rotki error

Removing blockchain accounts

DELETE /api/(version)/blockchains/(name)/

Note

This endpoint can also be queried asynchronously by using "async_query": true

Doing a DELETE on the the blockchains endpoint with a specific blockchain URL and a list of accounts in the json data will remove these accounts from the tracked accounts for the given blockchain and the current user. The updated balances after the account deletions are returned.
If one of the given accounts to add is invalid the entire request will fail.

Example Request:

http

DELETE /api/1/blockchains/ETH/tokens HTTP/1.1
Host: localhost:5042

{"accounts": ["0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B"]}

curl

curl -i -X DELETE http://localhost:5042/api/1/blockchains/ETH/tokens --data-raw '{"accounts": ["0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B"]}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/blockchains/ETH/tokens --body-data='{"accounts": ["0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B"]}'

httpie

echo '{"accounts": ["0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B"]}' | http DELETE http://localhost:5042/api/1/blockchains/ETH/tokens

python-requests

requests.delete('http://localhost:5042/api/1/blockchains/ETH/tokens', data='{"accounts": ["0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B"]}')
Request JSON Object:
 
  • accounts (list[string]) – A list of accounts to delete for the given blockchain
  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "per_account": {
            "BTC": { "3Kb9QPcTUJKspzjQFBppfXRcWew6hyDAPb": {
                 "amount": "0.5", "usd_value": "3770.075"
             }, "33hjmoU9XjEz8aLxf44FNGB8TdrLkAVBBo": {
                 "amount": "0.5", "usd_value": "3770.075"
             }},
        },
        "totals": {
            "BTC": {"amount": "1", "usd_value": "7540.15"},
        }
    },
    "message": ""
}
Response JSON Object:
 
  • result (object) – An object containing the "per_account" and "totals" keys as also defined here.
Status Codes:
  • 200 OK – Accounts succesfully deleted
  • 400 Bad Request – Provided JSON or data is in some way malformed. The accounts to remove contained invalid addresses or were an empty list.
  • 409 Conflict – User is not logged in. Some error occured when re-querying the balances after addition. Check message for details.
  • 500 Internal Server Error – Internal Rotki error
  • 502 Bad Gateway – Error occured with some external service query such as Etherscan. Check message for details.

Dealing with ignored assets

GET /api/(version)/assets/ignored/

Doing a GET on the ignored assets endpoint will return a list of all assets that the user has set to have ignored.

Example Request:

http

GET /api/1/assets/ignored HTTP/1.1
Host: localhost:5042

curl

curl -i http://localhost:5042/api/1/assets/ignored

wget

wget -S -O- http://localhost:5042/api/1/assets/ignored

httpie

http http://localhost:5042/api/1/assets/ignored

python-requests

requests.get('http://localhost:5042/api/1/assets/ignored')

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": ["1ST", "DAO"]
    "message": ""
}
Response JSON Object:
 
  • result (list) – A list of asset names that are currently ignored.
Status Codes:
PUT /api/(version)/assets/ignored/

Doing a PUT on the ignored assets endpoint will add new assets to the ignored assets list. Returns the new list with the added assets in the response.

Example Request:

http

PUT /api/1/assets/ignored HTTP/1.1
Host: localhost:5042

{"assets": ["GNO"]}

curl

curl -i -X PUT http://localhost:5042/api/1/assets/ignored --data-raw '{"assets": ["GNO"]}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/assets/ignored --body-data='{"assets": ["GNO"]}'

httpie

echo '{"assets": ["GNO"]}' | http PUT http://localhost:5042/api/1/assets/ignored

python-requests

requests.put('http://localhost:5042/api/1/assets/ignored', data='{"assets": ["GNO"]}')
Request JSON Object:
 
  • assets (list) – A list of asset symbols to add to the ignored assets.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": ["1ST", "DAO", "GNO"]
    "message": ""
}
Response JSON Object:
 
  • result (list) – A list of asset names that are currently ignored.
Status Codes:
DELETE /api/(version)/assets/ignored/

Doing a DELETE on the ignored assets endpoint will remove the given assets from the ignored assets list. Returns the new list without the removed assets in the response.

Example Request:

http

DELETE /api/1/assets/ignored HTTP/1.1
Host: localhost:5042

{"assets": ["DAO"]}

curl

curl -i -X DELETE http://localhost:5042/api/1/assets/ignored --data-raw '{"assets": ["DAO"]}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/assets/ignored --body-data='{"assets": ["DAO"]}'

httpie

echo '{"assets": ["DAO"]}' | http DELETE http://localhost:5042/api/1/assets/ignored

python-requests

requests.delete('http://localhost:5042/api/1/assets/ignored', data='{"assets": ["DAO"]}')
Request JSON Object:
 
  • assets (list) – A list of asset symbols to remove from the ignored assets.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": ["1ST"]
    "message": ""
}
Response JSON Object:
 
  • result (list) – A list of asset names that are currently ignored.
Status Codes:

Querying the version

GET /api/(version)/version

Doing a GET on the version endpoint will return information about the version of Rotki. If there is a newer version then "download_url" will be populated. If not then only "our_version" and "latest_version" will be. There is a possibility that latest version may not be populated due to github not being reachable.

Example Request:

http

GET /api/1/version HTTP/1.1
Host: localhost:5042

curl

curl -i http://localhost:5042/api/1/version

wget

wget -S -O- http://localhost:5042/api/1/version

httpie

http http://localhost:5042/api/1/version

python-requests

requests.get('http://localhost:5042/api/1/version')

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": {
        "our_version": "1.0.3",
        "latest_version": "1.0.4",
        "download_url": "https://github.com/rotki/rotki/releases/tag/v1.0.4"
    },
    "message": ""
}
Response JSON Object:
 
  • our_version (str) – The version of Rotki present in the system
  • latest_version (str) – The latest version of Rotki available
  • url (str) – URL link to download the latest version
Status Codes:

Data imports

GET /api/(version)/import

Doing a PUT on the data import endpoint will facilitate importing data from external sources. The arguments are the source of data import and the filepath to the data for importing.

Example Request:

http

PUT /api/1/import HTTP/1.1
Host: localhost:5042

{"source": "cointracking.info", "filepath": "/path/to/data/file"}

curl

curl -i -X PUT http://localhost:5042/api/1/import --data-raw '{"source": "cointracking.info", "filepath": "/path/to/data/file"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/import --body-data='{"source": "cointracking.info", "filepath": "/path/to/data/file"}'

httpie

echo '{"source": "cointracking.info", "filepath": "/path/to/data/file"}' | http PUT http://localhost:5042/api/1/import

python-requests

requests.put('http://localhost:5042/api/1/import', data='{"source": "cointracking.info", "filepath": "/path/to/data/file"}')
Request JSON Object:
 
  • source (str) – The source of the data to import. Valid values are "cointracking.info"
  • filepath (str) – The filepath to the data for importing

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": true,
    "message": ""
}
Response JSON Object:
 
  • result (bool) – The result field in this response is a simple boolean value indicating success or failure.
Status Codes: