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,
            "submit_usage_analytics": true,
            "kraken_account_type": "intermediate",
            "active_modules": ["makerdao_dsr", "makerdao_vaults"]
        }
    },
    "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 – Adding the new user was succesful

  • 400 Bad Request – Provided JSON is in some way malformed

  • 409 Conflict – User already exists. Another user is already logged in. Given Premium API credentials are invalid. Permission error while trying to access the directory where Rotki saves data.

  • 500 Internal Server Error – Internal Rotki error

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,
            "submit_usage_analytics": true,
            "kraken_account_type": "intermediate"
            "active_modules": ["makerdao_dsr", "makerdao_vaults"]
        }
    },
    "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. Permission error while trying to access the directory where Rotki saves data.

  • 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
DELETE /api/(version)/users/(username)/premium

By doing a DELETE at this endpoint you can delete the premium api key and secret pair for the logged-in user.

Example Request:

http

DELETE /api/1/users/john/premium HTTP/1.1
Host: localhost:5042

curl

curl -i -X DELETE http://localhost:5042/api/1/users/john/premium

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/users/john/premium

httpie

http DELETE http://localhost:5042/api/1/users/john/premium

python-requests

requests.delete('http://localhost:5042/api/1/users/john/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
  • 200 OK – API key/secret deleted succesfully

  • 400 Bad Request – Provided call is in some way malformed. For example a user who is not logged in has been specified.

  • 409 Conflict – User is not logged in, or user does not exist, or db operation error

  • 500 Internal Server Error – Internal Rotki error

Modify user password

PATCH /api/(version)/users/(username)/password

By doing a PATCH at this endpoint you can change the specific user’s password as long as that user is logged in.

Example Request:

http

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

{
    "current_password": "supersecret"
    "new_password": "evenmoresecret",
}

curl

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

    "current_password": "supersecret"

    "new_password": "evenmoresecret",

}'

wget

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

    "current_password": "supersecret"

    "new_password": "evenmoresecret",

}'

httpie

echo '{

    "current_password": "supersecret"

    "new_password": "evenmoresecret",

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

python-requests

requests.patch('http://localhost:5042/api/1/users/john/password', data='{\r\n\n    "current_password": "supersecret"\r\n\n    "new_password": "evenmoresecret",\r\n\n}')

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,
        "kraken_account_type": "intermediate",
        "active_modules": ["makerdao_dsr", "makerdao_vaults"]
    },
    "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.

  • kraken_account_type (string) – The type of the user’s kraken account if he has one. Valid values are “starter”, “intermediate” and “pro”.

  • active_module (list) – A list of strings denoting the active modules with which Rotki is running.

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.

  • active_module (list) – A list of strings denoting the active modules with which Rotki should run.

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,
        "kraken_account_type": "intermediate",
        "active_modules": ["makerdao_dsr", "makerdao_vaults"]
    },
    "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)/

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 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.

  • save_data (bool) – Boolean denoting whether to force save data even if the balance save frequency has not lapsed (see here ).

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.

  • save_data (bool) – Boolean denoting whether to force save data even if the balance save frequency has not lapsed (see here ).

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 all supported assets

GET /api/(version)/assets/all

Doing a GET on the all assets endpoint will return a mapping of all supported assets and their details. The keys are the unique symbol identifier and the values are the details for each asset.

The details of each asset can contain the following keys:

  • type: The type of asset. Valid values are ethereum token, own chain, omni token and more. For all valid values check here: https://github.com/rotki/rotki/blob/develop/rotkehlchen/assets/resolver.py#L7

  • started: An optional unix timestamp denoting where we know price data for the asset started

  • ended: If an asset is no longer in circulation this value should denote the unix timestamp after which price data is no longer available

  • name: The long name of the asset. Does not need to be the same as the unique symbol identifier

  • forked: An optional attribute representing another asset out of which this asset forked from. For example ETC would have ETH here.

  • swapped_for: An optional attribute representing another asset for which this asset was swapped for. For example VEN tokens were at some point swapped for VET tokens.

  • symbol: The symbol used for this asset. This is not guaranteed to be unique. Unfortunately some assets use the same symbol as others.

  • ethereum_address: If the type is ethereum_token then this will be the hexadecimal address of the token’s contract.

  • ethereum_token_decimals: If the type is ethereum_token then this will be the number of decimals the token has

    Example Request:

    http

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

    curl

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

    wget

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

    httpie

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

    python-requests

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

    Example Response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "result": {
            "0xBTC": {
                "ethereum_address": "0xB6eD7644C69416d67B522e20bC294A9a9B405B31",
                "ethereum_token_decimals": 8,
                "name": "0xBitcoin",
                "started": 1517875200,
                "symbol": "0xBTC",
                "type": "ethereum token"
            },
            "DCR": {
                "name": "Decred",
                "started": 1450137600,
                "symbol": "DCR",
                "type": "own chain"
            },
            "DDF": {
                "active": false,
                "ended": 1542153600,
                "ethereum_address": "0xcC4eF9EEAF656aC1a2Ab886743E98e97E090ed38",
                "ethereum_token_decimals": 18,
                "name": "DigitalDevelopersFund",
                "started": 1498504259,
                "symbol": "DDF",
                "type": "ethereum token"
            },
            "ETC": {
                "forked": "ETH",
                "name": "Ethereum classic",
                "started": 1469020840,
                "symbol": "ETC",
                "type": "own chain"
            },
            "KRW": {
                "name": "Korean won",
                "symbol": "KRW",
                "type": "fiat"
            },
            "VEN": {
                "active": false,
                "ended": 1533254400,
                "ethereum_address": "0xD850942eF8811f2A866692A623011bDE52a462C1",
                "ethereum_token_decimals": 18,
                "name": "Vechain Token",
                "started": 1503360000,
                "swapped_for": "VET",
                "symbol": "VEN",
                "type": "ethereum token"
            },
        },
        "message": ""
    }
    
    resjson object result

    A mapping of asset symbol identifiers to asset details

    statuscode 200

    Assets succesfully queried.

    statuscode 500

    Internal Rotki error

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_id.

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_id.

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",
            "defi_profit_loss": "140",
            "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": "6936.05",
            "total_profit_loss": "6936.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.

  • defi_profit_loss (str) – The profit/loss from Decentralized finance events 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": {
                "amount": "125.24423",
                "usd_value": "126.5231"
            },
            "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237": {
                "amount": "456.323",
                "usd_value": "460.212"
            }
          }
    },
    "message": ""
}
Response JSON Object
  • result (object) – A mapping of accounts to the number of DAI they have locked in DSR and the corresponding USD value. If an account is not in the mapping Rotki does not see anything locked in DSR for it.

Status Codes
  • 200 OK – DSR succesfully queried.

  • 409 Conflict – User is not logged in. Or makerdao module is not activated.

  • 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.

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",
                "gain_so_far_usd_value": "0",
                "amount": "350",
                "amount_usd_value": "351.21",
                "block_number": 9128160,
                "timestamp": 1582706553,
                "tx_hash": "0x988aea85b54c5b2834b144e9f7628b524bf9faf3b87821aa520b7bcfb57ab289"
            }, {
                "movement_type": "deposit",
                "gain_so_far": "0.875232",
                "gain_so_far_usd_value": "0.885292",
                "amount": "50",
                "amount_usd_value": "50.87",
                "block_number": 9129165,
                "timestamp": 1582806553,
                "tx_hash": "0x2a1bee69b9bafe031026dbcc8f199881b568fd767482b5436dd1cd94f2642443"
            }, {
                "movement_type": "withdrawal",
                "gain_so_far": "1.12875932",
                "gain_so_far_usd_value": "1.34813",
                "amount": "350",
                "amount_usd_value": "353.12",
                "block_number": 9149160,
                "timestamp": 1592706553,
                "tx_hash": "0x618fc9542890a2f58ab20a3c12d173b3638af11fda813e61788e242b4fc9a756"
            }, {
            }],
            "gain_so_far": "1.14875932"
        },
        "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237": {
            "movements": [{
                "movement_type": "deposit",
                "gain_so_far": "0",
                "gain_so_far_usd_value": "0",
                "amount": "550",
                "amount_usd_value": "553.43",
                "block_number": 9128174,
                "timestamp": 1583706553,
                "tx_hash": "0x2a1bee69b9bafe031026dbcc8f199881b568fd767482b5436dd1cd94f2642443"
            }],
            "gain_so_far": "0.953423"
            "gain_so_far_usd_value": "0.998421"
        }
    },
    "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 in DAI from the DSR for this account.

  • gain_so_far_usd_value (string) – The total gain so far in USD from the DSR for this account. The USD value is approximate. It’s essentially the known USD values at all movements and for whatever DAI remains the current DAI price is taken into 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.

  • gain_so_far_usd_value (string) – The usd value equivalnt of the DAI gained for this account in the DSR up until the moment of the given deposit/withdrawal. The rate is the DAI/USD rate at the movement’s timestamp.

  • amount (string) – The amount of DAI deposited or withdrawn from the DSR.

  • amount_usd_value (string) – The USD euivalent value of the amount of DAI deposited or withdrawn from the DSR. The rate is the DAI/USD rate at the movement’s timestamp.

  • block_number (int) – The block number at which the deposit or withdrawal occured.

  • tx_hash (int) – The transaction hash of the DSR movement

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. Or makerdao module is not activated.

  • 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.

Getting MakerDAO vaults basic data

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

Doing a GET on the makerdao vault resource will return the basic information for each vault the user has

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/vaults HTTP/1.1
Host: localhost:5042

curl

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

wget

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

httpie

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

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/modules/makerdao/vaults')
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": [{
        "identifier": 1,
        "collateral_type": "ETH-A",
        "owner": "0xA76a9560ffFD9fC603F7d6A30c37D79665207876",
        "collateral_asset": "ETH",
        "collateral_amount": "5.232",
        "debt_value": "650",
        "collateralization_ratio": "234.21%",
        "liquidation_ratio": "150%",
        "liquidation_price": "125.1",
        "collateral_usd_value": "950.13",
        "stability_fee": "0.00%",
    }, {
        "identifier": 55,
        "collateral_type": "USDC-A",
        "owner": "0xB26a9561ffFD9fC603F7d6A30c37D79665207876",
        "collateral_asset": "USDC",
        "collateral_amount": "150",
        "debt_value": "50",
        "collateralization_ratio": "250.551%",
        "liquidation_ratio": "150%",
        "liquidation_price": "0.45",
        "collateral_usd_value": "150",
        "stability_fee": "0.75%",
    }]
    "message": ""
}
Response JSON Object
  • result (object) – A list of all vaults auto detected for the user’s accounts

Response JSON Array of Objects
  • identifier (string) – A unique integer identifier for the vault.

  • collateral_type (string) – The collateral_type of the vault. e.g. ETH-A. Various collateral types can be seen here: https://catflip.co/

  • owner (string) – The address of the owner of the vault.

  • collateral_asset (string) – The asset deposited in the vault as collateral. As of this writing supported assets are ["ETH", "BAT", "USDC", "WBTC"]

  • collateral_amount (string) – The amount of collateral currently deposited in the vault

  • debt_value (string) – The amount of DAI owed to the vault. So generated DAI plus the stability fee interest.

  • collateralization_ratio (string) – A string denoting the percentage of collateralization of the vault.

  • liquidation_ratio (string) – This is the current minimum collateralization ratio. Less than this and the vault is going to get liquidated.

  • liquidation_price (string) – The USD price that the asset deposited in the vault as collateral at which the vault is going to get liquidated.

  • collateral_usd_value (string) – The current value in USD of all the collateral in the vault according to the MakerDAO price feed.

  • stability_fee (string) – The current annual interest rate you have to pay for borrowing collateral from this vault type.

Status Codes
  • 200 OK – Vaults succesfuly queried

  • 409 Conflict – User is not logged in. Or makerdao module is not activated.

  • 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.

Getting MakerDAO vault details

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

Note

This endpoint is only available for premium users

Doing a GET on the makerdao vault details resource will return additional details for each vault and also the list of vault events such as deposits, withdrawals, liquidations, debt generation and repayment.

To get the total amount of USD lost from the vault (including liquidations) the user should simply add total_liquidated_usd and total_interest_owed.

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/vaultdetails HTTP/1.1
Host: localhost:5042

curl

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

wget

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

httpie

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

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/modules/makerdao/vaultdetails')
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": [{
        "identifier": 1,
        "creation_ts": 1589067898,
        "total_interest_owed": "0.02341",
        "total_liquidated_amount": "0",
        "total_liquidated_usd": "0",
        "events": [{
            "event_type": "deposit",
            "amount": "5.551",
            "amount_usd_value": "120.32",
            "timestamp": 1589067899,
            "tx_hash": "0x678f31d49dd70d76c0ce441343c0060dc600f4c8dbb4cee2b08c6b451b6097cd"
        }, {
            "event_type": "generate",
            "amount": "325",
            "amount_usd_value": "12003.32",
            "timestamp": 1589067900,
            "tx_hash": "0x678f31d49dd70d76c0ce441343c0060dc600f4c8dbb4cee2b08c6b451b6097cd"
        }]
    }, {
        "identifier": 56,
        "creation_ts": 1589067897,
        "total_interest_owed": "-751.32",
        "total_liquidated_amount": "1050.21",
        "total_liquidated_usd": "2501.234",
        "events": [{
            "event_type": "deposit",
            "amount": "1050.21",
            "amount_usd_value": "10500.21",
            "timestamp": 1589067899,
            "tx_hash": "0x678f31d49dd70d76c0ce441343c0060dc600f4c8dbb4cee2b08c6b451b6097cd"
        }, {
            "event_type": "generate",
            "amount": "721.32",
            "amount_usd_value": "7213.2",
            "timestamp": 1589067900,
            "tx_hash": "0x678f31d49dd70d76c0ce441343c0060dc600f4c8dbb4cee2b08c6b451b6097cd"
        }, {
            "event_type": "liquidation",
            "amount": "500",
            "amount_usd_value": "5000",
            "timestamp": 1589068000,
            "tx_hash": "0x678f31d49dd70d76c0ce441343c0060dc600f4c8dbb4cee2b08c6b451b6097cd"
        }, {
            "event_type": "liquidation",
            "amount": "550.21",
            "amount_usd_value": "5502.1",
            "timestamp": 1589068001,
            "tx_hash": "0x678f31d49dd70d76c0ce441343c0060dc600f4c8dbb4cee2b08c6b451b6097cd"
        }]
    }]
    "message": ""
}
Response JSON Object
  • result (object) – A list of all vault details detected.

  • events (object) – A list of all events that occured for this vault

Response JSON Array of Objects
  • creation_ts (int) – The timestamp of the vault’s creation.

  • total_interest_owed (string) – Total amount of DAI lost to the vault as interest rate. This can be negative, if the vault has been liquidated. In that case the negative number is the DAI that is out in the wild and does not need to be returned after liquidation.

  • total_liquidated_amount (string) – The total amount of the collateral asset that has been lost to liquidation. Will be 0 if no liquidations happened.

  • total_liquidated_usd (string) – The total usd value of collateral that got liquidated. This is essentially all liquidation events amounts multiplied by the USD price of collateral at the time.

  • event_type (string) – The type of the event. Valid types are: ["deposit", "withdraw", "generate", "payback", "liquidation"]

  • amount (string) – The amount associated with the event. So collateral deposited/withdrawn, debt generated/paid back, amount of collateral lost in liquidation.

  • amount_usd_value (string) – The usd value of the amount associated with the event at the time the event occured.

  • timestamp (int) – The unix timestamp of the event

  • tx_hash (string) – The transaction hash associated with the event.

Status Codes
  • 200 OK – Vault details succesfuly queried

  • 409 Conflict – User is not logged in. Or makerdao module is not activated.

  • 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. Can either be a hexadecimal address or an ENS name.

  • 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": "johndoe.eth",
        "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": "johndoe.eth",

        "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": "johndoe.eth",

        "label": "my hardware wallet"

        }]

}'

httpie

echo '{

    "accounts": [{

        "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",

        "label": "my new metamask",

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

        }, {

        "address": "johndoe.eth",

        "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": "johndoe.eth",\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 edit. Can either be a hexadecimal address or an ENS name.

  • 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. Each account Can either be a hexadecimal address or an ENS name.

  • 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.

Getting manually tracked balances

GET /api/(version)/balances/manual/

Doing a GET on the manually tracked balances endpoint will return all the manually tracked balance accounts from the database.

Example Request:

http

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

curl

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

wget

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

httpie

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

python-requests

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

Example Response:

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

{
    "result": {
    "balances": [{
            "asset": "XMR",
            "label": "My monero wallet",
            "amount": "50.315",
            "usd_value": "2370.13839",
            "tags": ["public"],
            "location": "blockchain"
        }, {
            "asset": "BTC",
            "label": "My XPUB BTC wallet",
            "amount": "1.425",
            "usd_value": "9087.22",
            "location": "blockchain"
        }, {
            "asset": "ZEC",
            "label" "My favorite wallet",
            "amount": "76.2"
            "usd_value": "6067.77",
            "tags": ["private", "inheritance"],
            "location": "blockchain"
        }]
    "message": ""
}
Response JSON Object
  • result (object) – An object containing all the manually tracked balances as defined here with additionally a current usd equivalent value per account.

Status Codes

Adding manually tracked balances

PUT /api/(version)/balances/manual/

Doing a PUT on the the manually tracked balances endpoint you can add a balance for an asset that Rotki can’t automatically detect, along with a label identifying it for you and any number of tags.

Example Request:

http

PUT /api/1/balances/manual/ HTTP/1.1
Host: localhost:5042

{
    "balances": [{
            "asset": "XMR",
            "label": "My monero wallet",
            "amount": "50.315",
            "tags": ["public"],
            "location": "blockchain"
        }, {
            "asset": "BTC",
            "label": "My XPUB BTC wallet",
            "amount": "1.425",
            "location": "blockchain"
        }]
}

curl

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

    "balances": [{

            "asset": "XMR",

            "label": "My monero wallet",

            "amount": "50.315",

            "tags": ["public"],

            "location": "blockchain"

        }, {

            "asset": "BTC",

            "label": "My XPUB BTC wallet",

            "amount": "1.425",

            "location": "blockchain"

        }]

}'

wget

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

    "balances": [{

            "asset": "XMR",

            "label": "My monero wallet",

            "amount": "50.315",

            "tags": ["public"],

            "location": "blockchain"

        }, {

            "asset": "BTC",

            "label": "My XPUB BTC wallet",

            "amount": "1.425",

            "location": "blockchain"

        }]

}'

httpie

echo '{

    "balances": [{

            "asset": "XMR",

            "label": "My monero wallet",

            "amount": "50.315",

            "tags": ["public"],

            "location": "blockchain"

        }, {

            "asset": "BTC",

            "label": "My XPUB BTC wallet",

            "amount": "1.425",

            "location": "blockchain"

        }]

}' | http PUT http://localhost:5042/api/1/balances/manual/

python-requests

requests.put('http://localhost:5042/api/1/balances/manual/', data='{\r\n\n    "balances": [{\r\n\n            "asset": "XMR",\r\n\n            "label": "My monero wallet",\r\n\n            "amount": "50.315",\r\n\n            "tags": ["public"],\r\n\n            "location": "blockchain"\r\n\n        }, {\r\n\n            "asset": "BTC",\r\n\n            "label": "My XPUB BTC wallet",\r\n\n            "amount": "1.425",\r\n\n            "location": "blockchain"\r\n\n        }]\r\n\n}')
Request JSON Object
  • balances (list[object]) – A list of manually tracked balances to add to Rotki

Request JSON Array of Objects
  • asset (string) – The asset that is being tracked

  • label (string) – A label to describe where is this balance stored. Must be unique between all manually tracked balance labels.

  • amount (string) – The amount of asset that is stored.

  • tags (list[optional]) – An optional list of tags to attach to the this manually tracked balance.

  • location (string) – The location where the balance is saved. Can be one of: [“external”, “kraken”, “poloniex”, “bittrex”, “binance”, “bitmex”, “coinbase”, “banks”, “blockchain”, “coinbasepro”, “gemini”]

Example Response:

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

{
    "result": {
    "balances": [{
            "asset": "XMR",
            "label": "My monero wallet",
            "amount": "50.315",
            "usd_value": "2370.13839",
            "tags": ["public"],
            "location": "blockchain"
        }, {
            "asset": "BTC",
            "label": "My XPUB BTC wallet",
            "amount": "1.425",
            "usd_value": "9087.22",
            "location": "blockchain"
        }, {
            "asset": "ZEC",
            "label" "My favorite wallet",
            "amount": "76.2"
            "usd_value": "6067.77",
            "tags": ["private", "inheritance"]
            "location": "blockchain"
        }]
    "message": ""
}
Response JSON Object
  • result (object) – An object containing all the manually tracked balances as defined here with additionally a current usd equivalent value per account.

Status Codes
  • 200 OK – Balances succesfully added

  • 400 Bad Request – Provided JSON or data is in some way malformed. The balances to add contained invalid assets or were an empty list. One of the balance labels already exist.

  • 409 Conflict – User is not logged in. 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 Cryptocompare. Check message for details.

Editing manually tracked balances

PATCH /api/(version)/balances/manual

Doing a PATCH on the the manual balances endpoint allows you to edit a number of manually tracked balances by label.

Example Request:

http

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

{
    "balances": [{
            "asset": "XMR",
            "label": "My monero wallet",
            "amount": "4.5",
            "location": "blockchain"
            },{
            "asset": "ETH",
            "label" "My favorite wallet",
            "amount": "10",
            "tags": [],
            "location": "kraken"
        }]
}

curl

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

    "balances": [{

            "asset": "XMR",

            "label": "My monero wallet",

            "amount": "4.5",

            "location": "blockchain"

            },{

            "asset": "ETH",

            "label" "My favorite wallet",

            "amount": "10",

            "tags": [],

            "location": "kraken"

        }]

}'

wget

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

    "balances": [{

            "asset": "XMR",

            "label": "My monero wallet",

            "amount": "4.5",

            "location": "blockchain"

            },{

            "asset": "ETH",

            "label" "My favorite wallet",

            "amount": "10",

            "tags": [],

            "location": "kraken"

        }]

}'

httpie

echo '{

    "balances": [{

            "asset": "XMR",

            "label": "My monero wallet",

            "amount": "4.5",

            "location": "blockchain"

            },{

            "asset": "ETH",

            "label" "My favorite wallet",

            "amount": "10",

            "tags": [],

            "location": "kraken"

        }]

}' | http PATCH http://localhost:5042/api/1/balances/manual/

python-requests

requests.patch('http://localhost:5042/api/1/balances/manual/', data='{\r\n\n    "balances": [{\r\n\n            "asset": "XMR",\r\n\n            "label": "My monero wallet",\r\n\n            "amount": "4.5",\r\n\n            "location": "blockchain"\r\n\n            },{\r\n\n            "asset": "ETH",\r\n\n            "label" "My favorite wallet",\r\n\n            "amount": "10",\r\n\n            "tags": [],\r\n\n            "location": "kraken"\r\n\n        }]\r\n\n}')
Request JSON Object
  • accounts (list[object]) – A list of manual balances to edit. As defined here.

Example Response:

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

{
    "result": {
    "balances": [{
            "asset": "XMR",
            "label": "My monero wallet",
            "amount": "4.5",
            "usd_value": "210.548",
            "tags": ["public"],
            "location": "blockchain"
        }, {
            "asset": "BTC",
            "label": "My XPUB BTC wallet",
            "amount": "1.425",
            "usd_value": "9087.22",
            "location": "blockchain"
        }, {
            "asset": "ZEC",
            "label" "My favorite wallet",
            "amount": "10"
            "usd_value": "1330.85"
            "location": "kraken"
        }]
    "message": ""
}
Response JSON Object
  • result (object) – An object containing all the manually tracked balances as defined here with additionally a current usd equivalent value per account.

Status Codes
  • 200 OK – Balances succesfully edited

  • 400 Bad Request – Provided JSON or data is in some way malformed. The balances to add contained invalid assets or were an empty list.

  • 409 Conflict – User is not logged in. 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 Cryptocompare. Check message for details.

Deleting manually tracked balances

DELETE /api/(version)/balances/manual/
Doing a DELETE on the the manual balances endpoint with a list of labels to of manually tracked balances will remove these balances from the database for the current user.

If one of the given labels to remove is invalid the entire request will fail.

Example Request:

http

DELETE /api/1/balances/manual HTTP/1.1
Host: localhost:5042

{"labels": ["My monero wallet", "My favorite wallet"]}

curl

curl -i -X DELETE http://localhost:5042/api/1/balances/manual --data-raw '{"labels": ["My monero wallet", "My favorite wallet"]}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/balances/manual --body-data='{"labels": ["My monero wallet", "My favorite wallet"]}'

httpie

echo '{"labels": ["My monero wallet", "My favorite wallet"]}' | http DELETE http://localhost:5042/api/1/balances/manual

python-requests

requests.delete('http://localhost:5042/api/1/balances/manual', data='{"labels": ["My monero wallet", "My favorite wallet"]}')
Request JSON Object
  • balances (list[string]) – A list of labels of manually tracked balances to delete

Example Response:

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

{
    "result": {
    "balances": [{
            "asset": "XMR",
            "label": "My monero wallet",
            "amount": "4.5",
            "usd_value": "210.548",
            "tags": ["public"]
            "location": "blockchain"
        }, {
            "asset": "BTC",
            "label": "My XPUB BTC wallet",
            "amount": "1.425",
            "usd_value": "9087.22",
            "location": "blockchain"
        }, {
            "asset": "ZEC",
            "label" "My favorite wallet",
            "amount": "10"
            "usd_value": "1330.85"
            "location": "blockchain"
        }]
    "message": ""
}
Response JSON Object
  • result (object) – An object containing all the manually tracked balances as defined here with additionally a current usd equivalent value per account.

Status Codes
  • 200 OK – Balances succesfully delete

  • 400 Bad Request – Provided JSON or data is in some way malformed. One of the labels to remove did not exist.

  • 409 Conflict – User is not logged in. Check message for details.

  • 500 Internal Server Error – Internal Rotki error

  • 502 Bad Gateway – Error occured with some external service query such as Cryptocompare. Check message for details.

Getting watchers

GET /api/(version)/watchers

Note

This endpoint is only available for premium users

Doing a GET on the watchers endpoint, will return the currently installed watchers from the rotki server.

Example Request:

http

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

curl

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

wget

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

httpie

http http://localhost:5042/api/1/watchers

python-requests

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

Example Response:

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

{
    "result": [{
      "identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=",
      "type": "makervault_collateralization_ratio",
      "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}
      }, {
       "identifier": "7a4m7vRrLLOipwNmzhAVdo6FaGgr0XKGYLyjHqWa2KQ=",
       "type": "makervault_collateralization_ratio",
       "args": {"ratio": "185.55", "op": "lt","vault_id": "456"}
      }],
    "message": ""
}
Response JSON Object
  • result (object) – An list containing all the watcher results.

Request JSON Array of Objects
  • identifier (string) – The identifier with which to identify this vault. It’s unique per user and vault args + watcher combination. The client needs to keep this identifier. If the entry is edited, the identifier changes.

  • type (string) – The type of the watcher. Valid types are: “makervault_collateralization_ratio”.

  • args (object) – An object containing the args for the vault. Depending on the vault type different args are possible. Check here to see the different options.

Status Codes
  • 200 OK – Watchers 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 – Could not connect to or got unexpected response format from Rotki server

For makervault ratio the possible arguments are:
  • vault_id: The id of the vault to watcher

  • ratio: The target ratio to watch for

  • op: The comparison operator:
    • lt: less than the given ratio

    • le: less than or equal to the given ratio

    • gt: greater than the the given ratio

    • ge: greater than or equal to the given ratio

Adding new watcher

PUT /api/(version)/watchers/

Note

This endpoint is only available for premium users

Doing a PUT on the the watchers endpoint you can install new watchers for watching to the server.

Example Request:

http

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

{
    "watchers": [{
      "type": "makervault_collateralization_ratio",
      "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}
      }, {
       "type": "makervault_collateralization_ratio",
       "args": {"ratio": "185.55", "op": "lt","vault_id": "456"}
      }],
}

curl

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

    "watchers": [{

      "type": "makervault_collateralization_ratio",

      "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}

      }, {

       "type": "makervault_collateralization_ratio",

       "args": {"ratio": "185.55", "op": "lt","vault_id": "456"}

      }],

}'

wget

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

    "watchers": [{

      "type": "makervault_collateralization_ratio",

      "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}

      }, {

       "type": "makervault_collateralization_ratio",

       "args": {"ratio": "185.55", "op": "lt","vault_id": "456"}

      }],

}'

httpie

echo '{

    "watchers": [{

      "type": "makervault_collateralization_ratio",

      "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}

      }, {

       "type": "makervault_collateralization_ratio",

       "args": {"ratio": "185.55", "op": "lt","vault_id": "456"}

      }],

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

python-requests

requests.put('http://localhost:5042/api/1/watchers/', data='{\r\n\n    "watchers": [{\r\n\n      "type": "makervault_collateralization_ratio",\r\n\n      "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}\r\n\n      }, {\r\n\n       "type": "makervault_collateralization_ratio",\r\n\n       "args": {"ratio": "185.55", "op": "lt","vault_id": "456"}\r\n\n      }],\r\n\n}')
Request JSON Object
  • watchers (list[object]) – A list of watchers to add as defined in the above section but without an identifier. The identifier is created server-side and returned in the response.

Example Response:

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

{
    "result": [{
      "identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=",
      "type": "makervault_collateralization_ratio",
      "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}
      }, {
       "identifier": "7a4m7vRrLLOipwNmzhAVdo6FaGgr0XKGYLyjHqWa2KQ=",
       "type": "makervault_collateralization_ratio",
       "args": {"ratio": "185.55", "op": "lt","vault_id": "456"}
      }],
    "message": ""
}
Response JSON Object
  • result (object) – An object containing all the watchers, including the ones that were added. The watchers follow the schema defined above.

Status Codes
  • 200 OK – Watchers succesfully added

  • 400 Bad Request – Provided JSON or data is in some way malformed. Or the same watcher already exists for this user in the DB.

  • 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 – Could not connect to or got unexpected response format from Rotki server

Editing watchers

PATCH /api/(version)/watchers

Note

This endpoint is only available for premium users

Doing a PATCH on the the watchers endpoint allows you to edit a number of watchers by identifier. If one of the identifier is not found, the whole method fails.

Example Request:

http

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

{
    "watchers": [{
      "identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=",
      "type": "makervault_collateralization_ratio",
      "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}
      }, {
       "identifier: "7a4m7vRrLLOipwNmzhAVdo6FaGgr0XKGYLyjHqWa2KQ=",
       "type": "makervault_collateralization_ratio",
       "args": {"ratio": "185.55", "op": "lt","vault_id": "456"}
      }]
}

curl

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

    "watchers": [{

      "identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=",

      "type": "makervault_collateralization_ratio",

      "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}

      }, {

       "identifier: "7a4m7vRrLLOipwNmzhAVdo6FaGgr0XKGYLyjHqWa2KQ=",

       "type": "makervault_collateralization_ratio",

       "args": {"ratio": "185.55", "op": "lt","vault_id": "456"}

      }]

}'

wget

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

    "watchers": [{

      "identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=",

      "type": "makervault_collateralization_ratio",

      "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}

      }, {

       "identifier: "7a4m7vRrLLOipwNmzhAVdo6FaGgr0XKGYLyjHqWa2KQ=",

       "type": "makervault_collateralization_ratio",

       "args": {"ratio": "185.55", "op": "lt","vault_id": "456"}

      }]

}'

httpie

echo '{

    "watchers": [{

      "identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=",

      "type": "makervault_collateralization_ratio",

      "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}

      }, {

       "identifier: "7a4m7vRrLLOipwNmzhAVdo6FaGgr0XKGYLyjHqWa2KQ=",

       "type": "makervault_collateralization_ratio",

       "args": {"ratio": "185.55", "op": "lt","vault_id": "456"}

      }]

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

python-requests

requests.patch('http://localhost:5042/api/1/watchers/', data='{\r\n\n    "watchers": [{\r\n\n      "identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=",\r\n\n      "type": "makervault_collateralization_ratio",\r\n\n      "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}\r\n\n      }, {\r\n\n       "identifier: "7a4m7vRrLLOipwNmzhAVdo6FaGgr0XKGYLyjHqWa2KQ=",\r\n\n       "type": "makervault_collateralization_ratio",\r\n\n       "args": {"ratio": "185.55", "op": "lt","vault_id": "456"}\r\n\n      }]\r\n\n}')
Request JSON Object
  • watchers (list[object]) – A list of watcher to edit. As defined here.

Example Response:

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

{
    "result": [{
      "identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=",
      "type": "makervault_collateralization_ratio",
      "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}
      }, {
       "identifier": "7a4m7vRrLLOipwNmzhAVdo6FaGgr0XKGYLyjHqWa2KQ=",
       "type": "makervault_collateralization_ratio",
       "args": {"ratio": "185.55", "op": "lt","vault_id": "456"}
      }],
    "message": ""
}
Response JSON Object
  • result (object) – An object containing all the watchers as defined here

Status Codes
  • 200 OK – Watchers succesfully edited

  • 400 Bad Request – Provided JSON or data is in some way malformed. Or a given identifier does not exist in the DB.

  • 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 – Could not connect to or got unexpected response format from Rotki server

Deleting watchers

DELETE /api/(version)/watchers/

Note

This endpoint is only available for premium users

Doing a DELETE on the the watchers endpoint with a list of identifiers will delete either all or none of them.

Example Request:

http

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

{"watchers": ["6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ", "92Jm7vRrLLOipwNXzhAVdo6XaGAr0XKGYLyjHqWa2KA"]}

curl

curl -i -X DELETE http://localhost:5042/api/1/watchers --data-raw '{"watchers": ["6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ", "92Jm7vRrLLOipwNXzhAVdo6XaGAr0XKGYLyjHqWa2KA"]}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/watchers --body-data='{"watchers": ["6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ", "92Jm7vRrLLOipwNXzhAVdo6XaGAr0XKGYLyjHqWa2KA"]}'

httpie

echo '{"watchers": ["6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ", "92Jm7vRrLLOipwNXzhAVdo6XaGAr0XKGYLyjHqWa2KA"]}' | http DELETE http://localhost:5042/api/1/watchers

python-requests

requests.delete('http://localhost:5042/api/1/watchers', data='{"watchers": ["6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ", "92Jm7vRrLLOipwNXzhAVdo6XaGAr0XKGYLyjHqWa2KA"]}')
Request JSON Object
  • watchers (list[string]) – A list of identifier of watchers to delete

Example Response:

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

{
    "result": [{
      "identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=",
      "type": "makervault_collateralization_ratio",
      "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}
     }],
    "message": ""
}
Response JSON Object
  • result (object) – An object containing all the watchers after deletion. The watchers follow the schema defined above.

Status Codes
  • 200 OK – Watchers succesfully delete

  • 400 Bad Request – Provided JSON or data is in some way malformed. One of the identifiers to remove did not exist.

  • 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 – Could not connect to or got unexpected response format from Rotki server

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

Sending a Ping

GET /api/(version)/ping

Doing a GET on the ping endpoint will return true. It serves as a very fast way to check the connection to the API and that everything necessary for other calls has initialized.

Example Request:

http

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

curl

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

wget

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

httpie

http http://localhost:5042/api/1/ping

python-requests

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

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

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