rotki REST 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. The message is almost always going to be empty but may at some cases also contain some informational message.

{
    "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. Please remember that if you send the "async_query": true parameter as the body of a GET request you also have to set the content type header to Content-Type: application/json;charset=UTF-8.

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 -X GET 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
Content-Type: application/json;charset=UTF-8

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

curl

curl -i -X PUT http://localhost:5042/api/1/users -H "Accept: application/json, text/javascript" -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"initial_settings": {"submit_usage_analytics": false}, "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" --header="Content-Type: application/json;charset=UTF-8" --body-data='{"initial_settings": {"submit_usage_analytics": false}, "name": "john", "password": "supersecurepassword", "premium_api_key": "dasdsda", "premium_api_secret": "adsadasd"}'

httpie

echo '{
  "initial_settings": {
    "submit_usage_analytics": false
  },
  "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" Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/users', headers={'Accept': 'application/json, text/javascript', 'Content-Type': 'application/json;charset=UTF-8'}, json={'initial_settings': {'submit_usage_analytics': False}, 'name': 'john', 'password': 'supersecurepassword', 'premium_api_key': 'dasdsda', 'premium_api_secret': 'adsadasd'})
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.

  • initial_settings (object[optional]) – Optionally provide DB settings to set when creating the new user. If not provided, default settings are used.

Example Response:

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

{
    "result": {
        "exchanges": [
             {"location": "kraken", "name": "kraken1", "kraken_account_type": "starter"},
             {"location": "poloniex", "name": "poloniex1"},
             {"location": "binance", "name": "binance1"}
         ],
        "settings": {
            "have_premium": true,
            "version": "6",
            "last_write_ts": 1571552172,
            "premium_should_sync": true,
            "include_crypto2crypto": true,
            "last_data_upload_ts": 1571552172,
            "ui_floating_precision": 2,
            "taxfree_after_period": 31536000,
            "balance_save_frequency": 24,
            "include_gas_costs": true,
            "eth_rpc_endpoint": "http://localhost:8545",
            "ksm_rpc_endpoint": "http://localhost:9933",
            "main_currency": "USD",
            "date_display_format": "%d/%m/%Y %H:%M:%S %Z",
            "last_balance_save": 1571552172,
            "submit_usage_analytics": true,
            "active_modules": ["makerdao_dsr", "makerdao_vaults", "aave"],
            "current_price_oracles": ["cryptocompare", "coingecko"],
            "historical_price_oracles": ["cryptocompare", "coingecko"],
            "taxable_ledger_actions": ["income", "airdrop"]
        }
    },
    "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
Content-Type: application/json;charset=UTF-8

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

curl

curl -i -X PATCH http://localhost:5042/api/1/users/john -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"action": "login", "password": "supersecurepassword", "sync_approval": "unknown"}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/users/john --header="Content-Type: application/json;charset=UTF-8" --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 Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/users/john', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'action': 'login', 'password': 'supersecurepassword', 'sync_approval': 'unknown'})
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": [
             {"location": "kraken", "name": "kraken1", "kraken_account_type": "starter"},
             {"location": "poloniex", "name": "poloniex1"},
             {"location": "binance", "name": "binance1"}
         ],
        "settings": {
            "have_premium": true,
            "version": "6",
            "last_write_ts": 1571552172,
            "premium_should_sync": true,
            "include_crypto2crypto": true,
            "last_data_upload_ts": 1571552172,
            "ui_floating_precision": 2,
            "taxfree_after_period": 31536000,
            "balance_save_frequency": 24,
            "include_gas_costs": true,
            "eth_rpc_endpoint": "http://localhost:8545",
            "ksm_rpc_endpoint": "http://localhost:9933",
            "main_currency": "USD",
            "date_display_format": "%d/%m/%Y %H:%M:%S %Z",
            "last_balance_save": 1571552172,
            "submit_usage_analytics": true,
            "active_modules": ["makerdao_dsr", "makerdao_vaults", "aave"],
            "current_price_oracles": ["cryptocompare", "coingecko"],
            "historical_price_oracles": ["cryptocompare", "coingecko"],
            "taxable_ledger_actions": ["income", "airdrop"]
        }
    },
    "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". In this case the result will contain an object with a payload for the message under the result key and the message under the message key. The payload has the following keys: local_size, remote_size, local_last_modified, remote_last_modified.

  • 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
Content-Type: application/json;charset=UTF-8

{
    "action": "logout"
}

curl

curl -i -X PATCH http://localhost:5042/api/1/users/john -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"action": "logout"}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/users/john --header="Content-Type: application/json;charset=UTF-8" --body-data='{"action": "logout"}'

httpie

echo '{
  "action": "logout"
}' | http PATCH http://localhost:5042/api/1/users/john Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/users/john', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'action': 'logout'})
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
Content-Type: application/json;charset=UTF-8

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

curl

curl -i -X PATCH http://localhost:5042/api/1/users/john -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"premium_api_key": "dadsfasdsd", "premium_api_secret": "fdfdsgsdmf"}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/users/john --header="Content-Type: application/json;charset=UTF-8" --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 Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/users/john', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'premium_api_key': 'dadsfasdsd', 'premium_api_secret': 'fdfdsgsdmf'})
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)/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/premium HTTP/1.1
Host: localhost:5042

curl

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

wget

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

httpie

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

python-requests

requests.delete('http://localhost:5042/api/1/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
PUT /api/(version)/premium/sync

By doing a PUT at this endpoint you can backup or restore the database for the logged-in user using premium sync.

Note

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

Example Request:

http

DELETE /api/1/premium/sync HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{
    "action": "download"
}

curl

curl -i -X DELETE http://localhost:5042/api/1/premium/sync -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"action": "download"}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/premium/sync --header="Content-Type: application/json;charset=UTF-8" --body-data='{"action": "download"}'

httpie

echo '{
  "action": "download"
}' | http DELETE http://localhost:5042/api/1/premium/sync Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/premium/sync', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'action': 'download'})
Request JSON Object
  • action (string) – The action to perform. Can only be one of "upload" or "download".

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

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
Content-Type: application/json;charset=UTF-8

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

curl

curl -i -X PATCH http://localhost:5042/api/1/users/john/password -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"current_password": "supersecret", "new_password": "evenmoresecret"}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/users/john/password --header="Content-Type: application/json;charset=UTF-8" --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 Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/users/john/password', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'current_password': 'supersecret', 'new_password': 'evenmoresecret'})

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 -X GET 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 -X GET 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,
        "last_data_upload_ts": 1571552172,
        "ui_floating_precision": 2,
        "taxfree_after_period": 31536000,
        "balance_save_frequency": 24,
        "include_gas_costs": true,
        "eth_rpc_endpoint": "http://localhost:8545",
        "ksm_rpc_endpoint": "http://localhost:9933",
        "main_currency": "USD",
        "date_display_format": "%d/%m/%Y %H:%M:%S %Z",
        "last_balance_save": 1571552172,
        "submit_usage_analytics": true,
        "active_modules": ["makerdao_dsr", "makerdao_vaults", "aave"],
        "current_price_oracles": ["coingecko"],
        "historical_price_oracles": ["cryptocompare", "coingecko"],
        "taxable_ledger_actions": ["income", "airdrop"],
        "ssf_0graph_multiplier": 2
    },
    "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.

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

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

  • ksm_rpc_endpoint (string) – A URL denoting the rpc endpoint for the Kusama node to use when contacting the Kusama blockchain. If it can not be reached or if it is invalid any default public node (e.g. Parity) is used instead.

  • dot_rpc_endpoint (string) – A URL denoting the rpc endpoint for the Polkadot node to use when contacting the Polkadot blockchain. If it can not be reached or if it is invalid any default public node (e.g. Parity) is used instead.

  • main_currency (string) – The asset 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.

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

  • current_price_oracles (list) – A list of strings denoting the price oracles rotki should query in specific order for requesting current prices.

  • historical_price_oracles (list) – A list of strings denoting the price oracles rotki should query in specific order for requesting historical prices.

  • taxable_ledger_actions (list) – A list of strings denoting the ledger action types that will be taken into account in the profit/loss calculation during accounting. All others will only be taken into account in the cost basis and will not be taxed.

  • ssf_0graph_multiplier (int) – A multiplier to the snapshot saving frequency for 0 amount graphs. Originally 0 by default. If set it denotes the multiplier of the snapshot saving frequency at which to insert 0 save balances for a graph between two saved values.

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

{
    "settings": {
        "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 '{"settings": {"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='{"settings": {"include_gas_costs": false, "ui_floating_precision": 4}}'

httpie

echo '{
  "settings": {
    "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={'settings': {'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.

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

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

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

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

  • ksm_rpc_endpoint (string[optional]) – A URL denoting the rpc endpoint for the Kusama node to use when contacting the Kusama blockchain. If it can not be reached or if it is invalid any default public node (e.g. Parity) is used instead.

  • dot_rpc_endpoint (string[optional]) – A URL denoting the rpc endpoint for the Polkadot node to use when contacting the Polkadot blockchain. If it can not be reached or if it is invalid any default public node (e.g. Parity) 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.

  • current_price_oracles (list) – A list of strings denoting the price oracles rotki should query in specific order for requesting current prices.

  • historical_price_oracles (list) – A list of strings denoting the price oracles rotki should query in specific order for requesting historical prices.

  • taxable_ledger_actions (list) – A list of strings denoting the ledger action types that will be taken into account in the profit/loss calculation during accounting. All others will only be taken into account in the cost basis and will not be taxed.

Response JSON Object
  • ssf_0graph_multiplier (int) – A multiplier to the snapshot saving frequency for 0 amount graphs. Originally 0 by default. If set it denotes the multiplier of the snapshot saving frequency at which to insert 0 save balances for a graph between two saved values.

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,
        "last_data_upload_ts": 1571552172,
        "ui_floating_precision": 4,
        "taxfree_after_period": 31536000,
        "balance_save_frequency": 24,
        "include_gas_costs": false,
        "eth_rpc_endpoint": "http://localhost:8545",
        "ksm_rpc_endpoint": "http://localhost:9933",
        "main_currency": "USD",
        "date_display_format": "%d/%m/%Y %H:%M:%S %Z",
        "last_balance_save": 1571552172,
        "submit_usage_analytics": true,
        "active_modules": ["makerdao_dsr", "makerdao_vaults", "aave"],
        "current_price_oracles": ["cryptocompare"],
        "historical_price_oracles": ["coingecko", "cryptocompare"],
        "taxable_ledger_actions": ["income", "airdrop"],
        "ssf_0graph_multiplier": 2
    },
    "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 and all completed tasks is returned.

Example Request:

http

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

curl

curl -i -X GET 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": {
        "pending": [4, 23],
        "completed": [2]
    },
    "message": ""
}
Response JSON Object
  • result (list) – A mapping of “pending” to a list of pending task ids, and of “completed” to 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 -X GET 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": { "standalone": {
                "1Ec9S8KSw4UXXhqkoG3ZD31yjtModULKGg": {
                        "amount": "10",
                        "usd_value": "70500.15"
                    }}
            }},
            "totals": {"BTC": {"amount": "10", "usd_value": "70500.15"}},
            "status_code": 200
        }
    },
    "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. Inside the response can also be an optional status_code entry which would have been the status code of the original endpoint query had it not been made async.

Status Codes

Query the current price of assets

POST /api/(version)/assets/prices/current

Querying this endpoint with a list of assets and a target asset will return an object with the the price of the assets in the target asset currency. Providing an empty list or no target asset is an error.

Note

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

Example Request:

http

POST /api/1/assets/prices/current HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{
    "assets": ["BTC", "ETH", "_ceth_0x514910771AF9Ca656af840dff83E8264EcF986CA", "USD", "EUR"],
    "target_asset": "USD",
    "ignore_cache": true
}

curl

curl -i -X POST http://localhost:5042/api/1/assets/prices/current -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"assets": ["BTC", "ETH", "_ceth_0x514910771AF9Ca656af840dff83E8264EcF986CA", "USD", "EUR"], "ignore_cache": true, "target_asset": "USD"}'

wget

wget -S -O- http://localhost:5042/api/1/assets/prices/current --header="Content-Type: application/json;charset=UTF-8" --post-data='{"assets": ["BTC", "ETH", "_ceth_0x514910771AF9Ca656af840dff83E8264EcF986CA", "USD", "EUR"], "ignore_cache": true, "target_asset": "USD"}'

httpie

echo '{
  "assets": [
    "BTC",
    "ETH",
    "_ceth_0x514910771AF9Ca656af840dff83E8264EcF986CA",
    "USD",
    "EUR"
  ],
  "ignore_cache": true,
  "target_asset": "USD"
}' | http POST http://localhost:5042/api/1/assets/prices/current Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/assets/prices/current', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'assets': ['BTC', 'ETH', '_ceth_0x514910771AF9Ca656af840dff83E8264EcF986CA', 'USD', 'EUR'], 'ignore_cache': True, 'target_asset': 'USD'})
Request JSON Object
  • assets (list) – A list of assets to query their current price.

  • target_asset (string) – The target asset against which to return the price of each asset in the list.

  • async_query (bool) – A boolean denoting whether the query should be made asynchronously or not. Missing defaults to false.

  • ignore_cache (bool) – A boolean denoting whether to ignore the current price query cache. Missing defaults to false.

Example Response:

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

{
    "result": {
        "assets": {
            "BTC": "34758.11",
            "ETH": "1302.62",
            "EUR": "1.209",
            "GBP": "1.362",
            "_ceth_0x514910771AF9Ca656af840dff83E8264EcF986CA": "20.29",
            "USD": "1"
        },
        "target_asset": "USD"
    },
    "message": ""
}
Response JSON Object
  • result (object) – A JSON object that contains the price of the assets in the target asset currency.

  • assets (object) – A map between an asset and its price.

  • target_asset (string) – The target asset against which to return the price of each asset in the list.

Status Codes
  • 200 OK – The USD prices have been sucesfully returned

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

  • 500 Internal Server Error – Internal rotki error

  • 502 Bad Gateway – An external service used in the query such as cryptocompare/coingecko could not be reached or returned unexpected response.

Get current price and custom price for assets

GET /api/(version)/assets/prices/current

Get current prices and whether they have been manually input or not for all assets. At the moment this only works for nfts.

Example Request:

http

GET /api/1/assets/prices/current HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{}

curl

curl -i -X GET http://localhost:5042/api/1/assets/prices/current -H "Content-Type: application/json;charset=UTF-8"

wget

wget -S -O- http://localhost:5042/api/1/assets/prices/current --header="Content-Type: application/json;charset=UTF-8"

httpie

http http://localhost:5042/api/1/assets/prices/current Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/assets/prices/current', headers={'Content-Type': 'application/json;charset=UTF-8'})

Example Response:

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

{
    "result": [
        {
            "asset": "nft_uniqueid1",
            "manually_input": true,
            "price_asset": "ETH",
            "price_in_asset": "1",
            "usd_price": "2505.13"
        }, {
            "asset": "nft_uniqueid2",
            "manually_input": false,
            "price_asset": "USD",
            "price_in_asset": "155.13",
            "usd_price": "155.13"
        }]
    "message": ""
}
Response JSON Object
  • result (object) – A list of results of assets along with their uds prices

Status Codes

Add manual current price for an asset

PUT /api/(version)/assets/prices/current

Giving a unique asset identifier and a price via this endpoint stores the current price for an asset. If given, this overrides all other current prices. At the moment this will only work for non fungible assets.

Example Request:

http

PUT /api/1/assets/prices/current HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{
    "from_asset": "nft_unique_id",
    "to_asset": "EUR",
    "price": "150.55"
}

curl

curl -i -X PUT http://localhost:5042/api/1/assets/prices/current -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_asset": "nft_unique_id", "price": "150.55", "to_asset": "EUR"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/assets/prices/current --header="Content-Type: application/json;charset=UTF-8" --body-data='{"from_asset": "nft_unique_id", "price": "150.55", "to_asset": "EUR"}'

httpie

echo '{
  "from_asset": "nft_unique_id",
  "price": "150.55",
  "to_asset": "EUR"
}' | http PUT http://localhost:5042/api/1/assets/prices/current Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/assets/prices/current', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_asset': 'nft_unique_id', 'price': '150.55', 'to_asset': 'EUR'})
Request JSON Object
  • from_asset (string) – The asset for which the price is given.

  • to_asset (string) – The asset against which the price is given.

  • price (string) – Custom price for the asset.

Example Response:

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

{
    "result": true
    "message": ""
}
Response JSON Object
  • result (bool) – boolean for success

Status Codes

Delete an asset that has manual price set

DELETE /api/(version)/assets/prices/current

Deletes an asset that has as manual price set. IF the asset is not found or a manual price is not set a 409 is returned. At the moment this only works for nfts.

Example Request:

http

DELETE /api/1/assets/prices/current HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{"asset": "uniquenftid1"}

curl

curl -i -X DELETE http://localhost:5042/api/1/assets/prices/current -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"asset": "uniquenftid1"}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/assets/prices/current --header="Content-Type: application/json;charset=UTF-8" --body-data='{"asset": "uniquenftid1"}'

httpie

echo '{
  "asset": "uniquenftid1"
}' | http DELETE http://localhost:5042/api/1/assets/prices/current Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/assets/prices/current', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'asset': 'uniquenftid1'})

Example Response:

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

{
    "result": true
    "message": ""
}
Response JSON Object
  • result (bool) – boolean for success

Status Codes
  • 200 OK – Succesfull deletion

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

  • 409 Conflict – Asset not found or no manual price exists or nft module not activated.

  • 500 Internal Server Error – Internal rotki error

  • 502 Bad Gateway – An external service used in the query such as cryptocompare/coingecko could not be reached or returned unexpected response.

Query the current exchange rate for select assets

GET /api/(version)/exchange_rates

Querying this endpoint with a list of strings representing some assets will return a dictionary of their current exchange rates compared to USD.

Note

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

Note

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

Example Request:

http

GET /api/1/exchange_rates HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{"async_query": true, "currencies": ["EUR", "CNY", "GBP", "BTC"]}

curl

curl -i -X GET http://localhost:5042/api/1/exchange_rates -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": true, "currencies": ["EUR", "CNY", "GBP", "BTC"]}'

wget

wget -S -O- http://localhost:5042/api/1/exchange_rates --header="Content-Type: application/json;charset=UTF-8" --body-data='{"async_query": true, "currencies": ["EUR", "CNY", "GBP", "BTC"]}'

httpie

echo '{
  "async_query": true,
  "currencies": [
    "EUR",
    "CNY",
    "GBP",
    "BTC"
  ]
}' | http http://localhost:5042/api/1/exchange_rates Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/exchange_rates', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': True, 'currencies': ['EUR', 'CNY', 'GBP', 'BTC']})
Query Parameters
  • currencies (strings-list) – A comma separated list of currencies to query. e.g.: /api/1/fiat_exchange_rates?currencies=EUR,CNY,GBP

Request JSON Object
  • currencies (list) – A list of assets to query

Example Response:

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

{
    "result": {"EUR": "0.8973438622", "CNY": "7.0837221823", "GBP": "0.7756191673", "BTC": "19420.23"},
    "message": ""
}
Response JSON Object
  • result (object) – A JSON object with each element being an asset symbol and each value its USD exchange rate. If a particular asset could not have its price queried, it will return a zero price.

Status Codes

Query the historical price of assets

POST /api/(version)/assets/prices/historical

Querying this endpoint with a list of lists of asset and timestamp, and a target asset will return an object with the price of the assets at the given timestamp in the target asset currency. Providing an empty list or no target asset is an error.

Note

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

Example Request:

http

POST /api/1/assets/prices/historical HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

 {
    "assets_timestamp": [["BTC", 1579543935], ["BTC", 1611166335], ["GBP", 1579543935], ["EUR", 1548007935]],
    "target_asset": "USD"
 }

curl

curl -i -X POST http://localhost:5042/api/1/assets/prices/historical -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"assets_timestamp": [["BTC", 1579543935], ["BTC", 1611166335], ["GBP", 1579543935], ["EUR", 1548007935]], "target_asset": "USD"}'

wget

wget -S -O- http://localhost:5042/api/1/assets/prices/historical --header="Content-Type: application/json;charset=UTF-8" --post-data='{"assets_timestamp": [["BTC", 1579543935], ["BTC", 1611166335], ["GBP", 1579543935], ["EUR", 1548007935]], "target_asset": "USD"}'

httpie

echo '{
  "assets_timestamp": [
    [
      "BTC",
      1579543935
    ],
    [
      "BTC",
      1611166335
    ],
    [
      "GBP",
      1579543935
    ],
    [
      "EUR",
      1548007935
    ]
  ],
  "target_asset": "USD"
}' | http POST http://localhost:5042/api/1/assets/prices/historical Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/assets/prices/historical', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'assets_timestamp': [['BTC', 1579543935], ['BTC', 1611166335], ['GBP', 1579543935], ['EUR', 1548007935]], 'target_asset': 'USD'})
Request JSON Object
  • assets_timestamp (list) – A list of lists of asset and timestamp

  • target_asset (string) – The target asset against which to return the price of each asset in the list

Example Response:

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

{
    "result": {
        "assets": {
            "BTC": {
                "1579543935": "24361.55",
                "1611166335": "34966.64"
            },
            "EUR": {
                "1548007935": "1.1402"
            },
            "GBP": {
                "1579543935": "1.2999120493"
            }
        },
        "target_asset": "USD"
    },
    "message": ""
}
Response JSON Object
  • result (object) – A JSON object that contains the price of each asset for the given timestamp in the target asset currency.

  • assets (object) – A map between an asset and a map that contains the asset price at the specific timestamp.

  • target_asset (string) – The target asset against which to return the price of each asset in the list.

Status Codes
  • 200 OK – The historical USD prices have been sucesfully returned

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

  • 500 Internal Server Error – Internal rotki error

  • 502 Bad Gateway – An external service used in the query such as cryptocompare/coingecko could not be reached or returned unexpected response.

PUT /api/(version)/assets/prices/historical

Manually adds the price of an asset against another asset at a certain timestamp to the database.

Example Request:

http

PUT /api/1/assets/prices/historical HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

 {
      "from_asset": "_ceth_0xD71eCFF9342A5Ced620049e616c5035F1dB98620",
      "to_asset": "USD",
      "timestamp": 1611166335,
      "price": "1.20"
 }

curl

curl -i -X PUT http://localhost:5042/api/1/assets/prices/historical -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_asset": "_ceth_0xD71eCFF9342A5Ced620049e616c5035F1dB98620", "price": "1.20", "timestamp": 1611166335, "to_asset": "USD"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/assets/prices/historical --header="Content-Type: application/json;charset=UTF-8" --body-data='{"from_asset": "_ceth_0xD71eCFF9342A5Ced620049e616c5035F1dB98620", "price": "1.20", "timestamp": 1611166335, "to_asset": "USD"}'

httpie

echo '{
  "from_asset": "_ceth_0xD71eCFF9342A5Ced620049e616c5035F1dB98620",
  "price": "1.20",
  "timestamp": 1611166335,
  "to_asset": "USD"
}' | http PUT http://localhost:5042/api/1/assets/prices/historical Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/assets/prices/historical', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_asset': '_ceth_0xD71eCFF9342A5Ced620049e616c5035F1dB98620', 'price': '1.20', 'timestamp': 1611166335, 'to_asset': 'USD'})
Request JSON Object
  • from_asset (string) – The asset for which the price is given.

  • to_asset (string) – The asset against which the price is given.

  • timestamp (int) – The unix timestamp for which to save the price

  • price (string) – Price at the timestamp given.

Example Response:

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

{
    "result": true,
    "message": ""
}
Response JSON Object
  • result (object) – true if the manual price was correctly stored in the database, false otherwise.

Status Codes
PATCH /api/(version)/assets/prices/historical

Edits price for a manually added price if it already exists in the database. Returns false if no entry was updated.

Example Request:

http

PUT /api/1/assets/prices/historical HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

 {
      "from_asset": "_ceth_0xD71eCFF9342A5Ced620049e616c5035F1dB98620",
      "to_asset": "USD",
      "timestamp": 1611166335,
      "price": "1.20"
 }

curl

curl -i -X PUT http://localhost:5042/api/1/assets/prices/historical -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_asset": "_ceth_0xD71eCFF9342A5Ced620049e616c5035F1dB98620", "price": "1.20", "timestamp": 1611166335, "to_asset": "USD"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/assets/prices/historical --header="Content-Type: application/json;charset=UTF-8" --body-data='{"from_asset": "_ceth_0xD71eCFF9342A5Ced620049e616c5035F1dB98620", "price": "1.20", "timestamp": 1611166335, "to_asset": "USD"}'

httpie

echo '{
  "from_asset": "_ceth_0xD71eCFF9342A5Ced620049e616c5035F1dB98620",
  "price": "1.20",
  "timestamp": 1611166335,
  "to_asset": "USD"
}' | http PUT http://localhost:5042/api/1/assets/prices/historical Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/assets/prices/historical', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_asset': '_ceth_0xD71eCFF9342A5Ced620049e616c5035F1dB98620', 'price': '1.20', 'timestamp': 1611166335, 'to_asset': 'USD'})
Request JSON Object
  • from_asset (string) – The asset for which the price is given.

  • to_asset (string) – The asset against which the price is given.

  • timestamp (int) – The unix timestamp for which the price was saved

  • price (string) – New price at the timestamp given.

Example Response:

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

{
    "result": true,
    "message": ""
}
Response JSON Object
  • result (object) – true if any entry was updated, false otherwise.

Status Codes
GET /api/(version)/assets/prices/historical

Queries prices of an asset against another asset at a certain timestamp to the database. If none of the fields are provided returns all the prices manually added.

Example Request:

http

GET /api/1/assets/prices/historical HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

 {
    "from_asset": "_ceth_0xD71eCFF9342A5Ced620049e616c5035F1dB98620"
 }

curl

curl -i -X GET http://localhost:5042/api/1/assets/prices/historical -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_asset": "_ceth_0xD71eCFF9342A5Ced620049e616c5035F1dB98620"}'

wget

wget -S -O- http://localhost:5042/api/1/assets/prices/historical --header="Content-Type: application/json;charset=UTF-8" --body-data='{"from_asset": "_ceth_0xD71eCFF9342A5Ced620049e616c5035F1dB98620"}'

httpie

echo '{
  "from_asset": "_ceth_0xD71eCFF9342A5Ced620049e616c5035F1dB98620"
}' | http http://localhost:5042/api/1/assets/prices/historical Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/assets/prices/historical', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_asset': '_ceth_0xD71eCFF9342A5Ced620049e616c5035F1dB98620'})
Request JSON Object
  • from_asset (string) – Optional. The from_asset for which the price is retrieved.

  • to_asset (string) – Optional. The to_asset for which the price is retrieved.

Example Response:

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

{
    "result": [
      {
        "from_asset": "_ceth_0xD533a949740bb3306d119CC777fa900bA034cd52",
        "to_asset": "USD",
        "timestamp": 1611166335,
        "price": "1.20"
      },
      {
        "from_asset": "_ceth_0xD533a949740bb3306d119CC777fa900bA034cd52",
        "to_asset": "USD",
        "timestamp": 1611166340,
        "price": "1.40"
      }
    ],
    "message": ""
}
Response JSON Object
  • result (object) – List with information for each historical price.

Status Codes
DELETE /api/(version)/assets/prices/historical

Deletes price of an asset against another asset at a certain timestamp from the database.

Example Request:

http

DELETE /api/1/assets/prices/historical HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

 {
  "from_asset": "_ceth_0xD71eCFF9342A5Ced620049e616c5035F1dB98620",
  "to_asset": "USD",
  "timestamp": 1611166335
 }

curl

curl -i -X DELETE http://localhost:5042/api/1/assets/prices/historical -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_asset": "_ceth_0xD71eCFF9342A5Ced620049e616c5035F1dB98620", "timestamp": 1611166335, "to_asset": "USD"}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/assets/prices/historical --header="Content-Type: application/json;charset=UTF-8" --body-data='{"from_asset": "_ceth_0xD71eCFF9342A5Ced620049e616c5035F1dB98620", "timestamp": 1611166335, "to_asset": "USD"}'

httpie

echo '{
  "from_asset": "_ceth_0xD71eCFF9342A5Ced620049e616c5035F1dB98620",
  "timestamp": 1611166335,
  "to_asset": "USD"
}' | http DELETE http://localhost:5042/api/1/assets/prices/historical Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/assets/prices/historical', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_asset': '_ceth_0xD71eCFF9342A5Ced620049e616c5035F1dB98620', 'timestamp': 1611166335, 'to_asset': 'USD'})
Request JSON Object
  • from_asset (string) – The asset for which the price is given.

  • to_asset (string) – The asset against which the price is given.

  • timestamp (int) – The unix timestamp for which to save the price

Example Response:

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

{
  "result": true,
  "message": ""
}
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 and with which names.

Example Request:

http

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

curl

curl -i -X GET 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": [
         {"location": "kraken", "name": "kraken1", "kraken_account_type": "starter"},
         {"location": "poloniex", "name": "poloniex1"},
         {"location": "binance", "name": "binance1"}
     ],
    "message": ""
}
Response JSON Object
  • result (list) – A list of exchange location/name pairs 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, location, api key and secret will setup the exchange for the current user. Also for some exchanges additional optional info can be provided.

Example Request:

http

PUT /api/1/exchanges HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{"name": "my kraken key", "location": "kraken", "api_key": "ddddd", "api_secret": "ffffff", "passphrase": "secret", "binance_markets": ["ETHUSDC", "BTCUSDC"], "ftx_subaccount": "Dragon"}

curl

curl -i -X PUT http://localhost:5042/api/1/exchanges -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"api_key": "ddddd", "api_secret": "ffffff", "binance_markets": ["ETHUSDC", "BTCUSDC"], "ftx_subaccount": "Dragon", "location": "kraken", "name": "my kraken key", "passphrase": "secret"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/exchanges --header="Content-Type: application/json;charset=UTF-8" --body-data='{"api_key": "ddddd", "api_secret": "ffffff", "binance_markets": ["ETHUSDC", "BTCUSDC"], "ftx_subaccount": "Dragon", "location": "kraken", "name": "my kraken key", "passphrase": "secret"}'

httpie

echo '{
  "api_key": "ddddd",
  "api_secret": "ffffff",
  "binance_markets": [
    "ETHUSDC",
    "BTCUSDC"
  ],
  "ftx_subaccount": "Dragon",
  "location": "kraken",
  "name": "my kraken key",
  "passphrase": "secret"
}' | http PUT http://localhost:5042/api/1/exchanges Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/exchanges', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'api_key': 'ddddd', 'api_secret': 'ffffff', 'binance_markets': ['ETHUSDC', 'BTCUSDC'], 'ftx_subaccount': 'Dragon', 'location': 'kraken', 'name': 'my kraken key', 'passphrase': 'secret'})
Request JSON Object
  • name (string) – A name to give to this exchange’s key

  • location (string) – The location 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.

  • kraken_account_type (string) – An optional setting for kraken. The type of the user’s kraken account. Valid values are “starter”, “intermediate” and “pro”.

  • binance_markets (list) – An optional setting for binance and binanceus. A list of string for markets that should be queried.

  • ftx_subaccount (string) – An optional setting for FTX. This sets the subaccount that will be queried from FTX.

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
Content-Type: application/json;charset=UTF-8

{"name": "my kraken key", "location": "kraken"}

curl

curl -i -X DELETE http://localhost:5042/api/1/exchanges -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"location": "kraken", "name": "my kraken key"}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/exchanges --header="Content-Type: application/json;charset=UTF-8" --body-data='{"location": "kraken", "name": "my kraken key"}'

httpie

echo '{
  "location": "kraken",
  "name": "my kraken key"
}' | http DELETE http://localhost:5042/api/1/exchanges Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/exchanges', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'location': 'kraken', 'name': 'my kraken key'})
Request JSON Object
  • name (string) – The name of the exchange whose key to delete

  • location (string) – The location 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

Edit an exchange entry

PATCH /api/(version)/exchanges

Doing a PATCH on this endpoint with an exchange’s name and location and the various attributes will result in editing it.

Example Request:

http

PATCH /api/1/exchanges HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{"name": "my kraken key", "location": "kraken", "new_name": "my_kraken", "api_key": "my_new_api_key", "api_secret": "my_new_api_secret", "passphrase": "my_new_passphrase", "kraken_account_type": "intermediate"}

curl

curl -i -X PATCH http://localhost:5042/api/1/exchanges -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"api_key": "my_new_api_key", "api_secret": "my_new_api_secret", "kraken_account_type": "intermediate", "location": "kraken", "name": "my kraken key", "new_name": "my_kraken", "passphrase": "my_new_passphrase"}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/exchanges --header="Content-Type: application/json;charset=UTF-8" --body-data='{"api_key": "my_new_api_key", "api_secret": "my_new_api_secret", "kraken_account_type": "intermediate", "location": "kraken", "name": "my kraken key", "new_name": "my_kraken", "passphrase": "my_new_passphrase"}'

httpie

echo '{
  "api_key": "my_new_api_key",
  "api_secret": "my_new_api_secret",
  "kraken_account_type": "intermediate",
  "location": "kraken",
  "name": "my kraken key",
  "new_name": "my_kraken",
  "passphrase": "my_new_passphrase"
}' | http PATCH http://localhost:5042/api/1/exchanges Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/exchanges', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'api_key': 'my_new_api_key', 'api_secret': 'my_new_api_secret', 'kraken_account_type': 'intermediate', 'location': 'kraken', 'name': 'my kraken key', 'new_name': 'my_kraken', 'passphrase': 'my_new_passphrase'})
Request JSON Object
  • name (string) – The name of the exchange key to edit

  • location (string) – The location of the exchange to edit

  • new_name (string) – Optional. If given this will be the new name for the exchange credentials.

  • api_key (string) – Optional. If given this will be the new api key for the exchange credentials.

  • api_secret (string) – Optional. If given this will be the new api secret for the exchange credentials.

  • passphrase (string) – Optional. If given this will be the new passphrase. Only for exchanges, like coinbase pro, which need a passphrase.

  • kraken_account_type (string) – Optional. An optional setting for kraken. The type of the user’s kraken account. Valid values are “starter”, “intermediate” and “pro”.

Example Response:

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

{
    "result": true
    "message": ""
}
Response JSON Object
  • result (bool) – A boolean indicating success if all went well. If there is an error then the usual result: null and message having a value format is followed.

Status Codes

Querying the balances of exchanges

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

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 -X GET 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 -X GET 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

Purging locally saved data for exchanges

DELETE /api/(version)/exchanges/data/(location)

Doing a DELETE on the appropriate exchanges trades endpoint will delete the cached trades, deposits and withdrawals for that exchange. If no exchange is given then all exchanges will be affected. Next time exchange history is queried, everything will be queried again, and may take some time.

Example Request:

http

DELETE /api/1/exchanges/delete/binance HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{}

curl

curl -i -X DELETE http://localhost:5042/api/1/exchanges/delete/binance -H "Content-Type: application/json;charset=UTF-8"

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/exchanges/delete/binance --header="Content-Type: application/json;charset=UTF-8"

httpie

http DELETE http://localhost:5042/api/1/exchanges/delete/binance Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/exchanges/delete/binance', headers={'Content-Type': 'application/json;charset=UTF-8'})

Example Response:

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

{ "result": true, "message": "" }
Status Codes

Purging locally saved ethereum transactions

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

Doing a DELETE on the transactions endpoint for ETH will purge all locally saved transaction data. Next time transactions are queried all of them will be queried again for all addresses and may take some time.

Example Request:

http

DELETE /api/1/blockchains/ETH/transactions HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{}

curl

curl -i -X DELETE http://localhost:5042/api/1/blockchains/ETH/transactions -H "Content-Type: application/json;charset=UTF-8"

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/blockchains/ETH/transactions --header="Content-Type: application/json;charset=UTF-8"

httpie

http DELETE http://localhost:5042/api/1/blockchains/ETH/transactions Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/blockchains/ETH/transactions', headers={'Content-Type': 'application/json;charset=UTF-8'})

Example Response:

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

{ "result": true, "message": "" }
Status Codes

Purging locally saved data for ethereum modules

DELETE /api/(version)/blockchains/ETH/modules/(name)/data

Doing a DELETE on the data of a specific ETH module will purge all locally saved data for the module. Can also purge all module data by doing a DELETE on /api/(version)/blockchains/ETH/modules/data in which case all module data will be purged.

Example Request:

http

DELETE /api/1/blockchains/ETH/modules/uniswap/data HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{}

curl

curl -i -X DELETE http://localhost:5042/api/1/blockchains/ETH/modules/uniswap/data -H "Content-Type: application/json;charset=UTF-8"

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/blockchains/ETH/modules/uniswap/data --header="Content-Type: application/json;charset=UTF-8"

httpie

http DELETE http://localhost:5042/api/1/blockchains/ETH/modules/uniswap/data Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/blockchains/ETH/modules/uniswap/data', headers={'Content-Type': 'application/json;charset=UTF-8'})
Request JSON Object
  • name (string) – The name of the module whose data to delete. Can be one of the supported ethereum modules. The name can be omitted by doing a DELETE on /api/(version)/blockchains/ETH/modules/data in which case all module data will be purged.

Example Response:

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

{ "result": true, "message": "" }
Status Codes

Request creation of oracle price cache

POST /api/(version)/oracles/(name)/cache

Note

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

Doing a POST on this endpoint with the appropriate arguments will request the creation of a price cache for the oracle. If it already exists it will be appended to or recreated depending on the given arguments.

Example Request:

http

POST /api/1/oracles/cryptocompare/cache HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{"from_asset": "ETH", "to_asset": "EUR", "purge_old": false, "async_query": true}

curl

curl -i -X POST http://localhost:5042/api/1/oracles/cryptocompare/cache -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": true, "from_asset": "ETH", "purge_old": false, "to_asset": "EUR"}'

wget

wget -S -O- http://localhost:5042/api/1/oracles/cryptocompare/cache --header="Content-Type: application/json;charset=UTF-8" --post-data='{"async_query": true, "from_asset": "ETH", "purge_old": false, "to_asset": "EUR"}'

httpie

echo '{
  "async_query": true,
  "from_asset": "ETH",
  "purge_old": false,
  "to_asset": "EUR"
}' | http POST http://localhost:5042/api/1/oracles/cryptocompare/cache Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/oracles/cryptocompare/cache', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': True, 'from_asset': 'ETH', 'purge_old': False, 'to_asset': 'EUR'})
Request JSON Object
  • name (string) – The name of the oracle for which to create the cache. Valid values are "cryptocompare" and "coingecko".

  • from_asset (string) – The from asset of the pair for which to generate the cache

  • to_asset (string) – The to asset of the pair for which to generate the cache

  • purge_old (bool) – If true, and an old cache exists it will be completely removed and the whole cache recreated. If false, only the parts of the time range for which no cache exists will be queried. By default this is false.

Example Response:

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

{ "result": true, "message": "" }
Status Codes

Delete an oracle price cache

DELETE /api/(version)/oracles/(name)/cache

Doing a delete on this endpoint with the appropriate arguments will request delete a specific pair’s price cache for an oracle.

Example Request:

http

DELETE /api/1/oracles/cryptocompare/cache HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{"from_asset": "ETH", "to_asset": "EUR"}

curl

curl -i -X DELETE http://localhost:5042/api/1/oracles/cryptocompare/cache -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_asset": "ETH", "to_asset": "EUR"}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/oracles/cryptocompare/cache --header="Content-Type: application/json;charset=UTF-8" --body-data='{"from_asset": "ETH", "to_asset": "EUR"}'

httpie

echo '{
  "from_asset": "ETH",
  "to_asset": "EUR"
}' | http DELETE http://localhost:5042/api/1/oracles/cryptocompare/cache Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/oracles/cryptocompare/cache', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_asset': 'ETH', 'to_asset': 'EUR'})
Request JSON Object
  • name (string) – The name of the oracle for which to create the cache. Valid values are "cryptocompare" and "coingecko".

  • from_asset (string) – The from asset of the pair for which to generate the cache

  • to_asset (string) – The to asset of the pair for which to generate the cache

Example Response:

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

{ "result": true, "message": "" }
Status Codes

Get oracle price cache data

GET /api/(version)/oracles/(name)/cache

Doing a GET on this endpoint will return information on all cached prices and pairs for the given oracle.

Note

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

Example Request:

http

GET /api/1/oracles/cryptocompare/cache HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{"async_query": true}

curl

curl -i -X GET http://localhost:5042/api/1/oracles/cryptocompare/cache -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": true}'

wget

wget -S -O- http://localhost:5042/api/1/oracles/cryptocompare/cache --header="Content-Type: application/json;charset=UTF-8" --body-data='{"async_query": true}'

httpie

echo '{
  "async_query": true
}' | http http://localhost:5042/api/1/oracles/cryptocompare/cache Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/oracles/cryptocompare/cache', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': True})
Request JSON Object
  • name (string) – The name of the oracle for which to create the cache. Valid values are "cryptocompare" and "coingecko".

Example Response:

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

{
    "result": [{
        "from_asset": "ETH",
        "to_asset": "EUR",
        "from_timestamp": "1417447629",
        "to_timestamp": "1611848905",
    }, {
        "from_asset": "BTC",
        "to_asset": "USD",
        "from_timestamp": "1437457629",
        "to_timestamp": "1601348905",
    }],
    "message": ""
}
Response JSON Object
  • result (list) – A list of cache results. Each entry contains the from/to asset of the cache pair and the range of the cache.

  • from_asset (string) – The identifier of the from asset.

  • to_asset (string) – The identifier of the to asset.

  • from_timestamp (int) – The timestamp at which the price cache for the pair starts

  • to_timestamp (int) – The timestamp at which the price cache for the pair ends

Status Codes

Get supported oracles

GET /api/(version)/oracles/

Doing a GET on this endpoint will return information on all supported oracles.

Example Request:

http

GET /api/1/oracles/ HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{}

curl

curl -i -X GET http://localhost:5042/api/1/oracles/ -H "Content-Type: application/json;charset=UTF-8"

wget

wget -S -O- http://localhost:5042/api/1/oracles/ --header="Content-Type: application/json;charset=UTF-8"

httpie

http http://localhost:5042/api/1/oracles/ Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/oracles/', headers={'Content-Type': 'application/json;charset=UTF-8'})

Example Response:

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

{
    "result": {
        "history": [{
            "id": "cryptocompare",
            "name": "Cryptocompare"
        }, {
            "id": "coingecko",
            "name": "Coingecko"
        }],
        "current": [{
            "id": "cryptocompare",
            "name": "Cryptocompare"
        }, {
            "id": "coingecko",
            "name": "Coingecko"
        }],

    "message": ""
}
Response JSON Object
  • result (object) – A mapping of all supported current and historical oracles

Status Codes

Query supported ethereum modules

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

Doing a GET on this endpoint will return all supported ethereum modules

Example Request:

http

DELETE /api/1/blockchains/ETH/modules HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{}

curl

curl -i -X DELETE http://localhost:5042/api/1/blockchains/ETH/modules -H "Content-Type: application/json;charset=UTF-8"

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/blockchains/ETH/modules --header="Content-Type: application/json;charset=UTF-8"

httpie

http DELETE http://localhost:5042/api/1/blockchains/ETH/modules Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/blockchains/ETH/modules', headers={'Content-Type': 'application/json;charset=UTF-8'})

Example Response:

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

{ "result": [{
        "id": "uniswap",
        "name": "Uniswap"
    }], [{
        "id": "yearn_vaults",
        "name": "Yearn Vaults"
    }], [{
        "id": "makerdao_dsr",
        "name": "MakerDAO DSR"
    }]
    "message": "" }
Response JSON Object
  • result (object) – A list of all supported module each with its id and human readable name

Status Codes

Querying ethereum transactions

GET /api/(version)/blockchains/ETH/transactions/(address)

Note

This endpoint also accepts parameters as query arguments.

Note

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

Doing a GET on the transactions endpoint for ETH will query all ethereum transactions for all the tracked user addresses. Caller can also specify an address to further filter the query as a from address. Also they can limit the queried transactions by timestamps. If the user is not premium and has more than 500 transaction then the returned transaction will be limited to that number. Any filtering will also be limited to those first 500 transaction. Transactions are returned most recent first.

Example Request:

http

GET /api/1/blockchains/ETH/transactions/0xdAC17F958D2ee523a2206206994597C13D831ec7/ HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

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

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/ETH/transactions/0xdAC17F958D2ee523a2206206994597C13D831ec7/ -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_timestamp": 1514764800, "only_cache": false, "to_timestamp": 1572080165}'

wget

wget -S -O- http://localhost:5042/api/1/blockchains/ETH/transactions/0xdAC17F958D2ee523a2206206994597C13D831ec7/ --header="Content-Type: application/json;charset=UTF-8" --body-data='{"from_timestamp": 1514764800, "only_cache": false, "to_timestamp": 1572080165}'

httpie

echo '{
  "from_timestamp": 1514764800,
  "only_cache": false,
  "to_timestamp": 1572080165
}' | http http://localhost:5042/api/1/blockchains/ETH/transactions/0xdAC17F958D2ee523a2206206994597C13D831ec7/ Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/transactions/0xdAC17F958D2ee523a2206206994597C13D831ec7/', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_timestamp': 1514764800, 'only_cache': False, 'to_timestamp': 1572080165})
Request JSON Object
  • limit (int) – This signifies the limit of records to return as per the sql spec.

  • offset (int) – This signifies the offset from which to start the return of records per the sql spec.

  • order_by_attribute (string) – This is the attribute of the transaction by which to order the results.

  • ascending (bool) – Should the order be aschending? This is the default. If set to false, it will be on descending order.

  • from_timestamp (int) – The timestamp after which to return transactions. If not given zero is considered as the start.

  • to_timestamp (int) – The timestamp until which to return transactions. If not given all transactions from from_timestamp until now are returned.

  • only_cache (bool) – If true then only the ethereum transactions in the DB are queried.

Example Response:

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

{ "result":
      "entries": [{
          "entry": {
              "tx_hash": "0x18807cd818b2b50a2284bda2dfc39c9f60607ccfa25b1a01143e934280675eb8",
              "timestamp": 1598006527,
              "block_number": 10703085,
              "from_address": "0x3CAdbeB58CB5162439908edA08df0A305b016dA8",
              "to_address": "0xF9986D445ceD31882377b5D6a5F58EaEa72288c3",
              "value": "0",
              "gas": "61676",
              "gas_price": "206000000000",
              "gas_used": "37154",
              "input_data": "0xa9059cbb0000000000000000000000001934aa5cdb0677aaa12850d763bf8b60e7a3dbd4000000000000000000000000000000000000000000000179b9b29a80ae20ca00",
              "nonce": 2720
         },
         "ignored_in_accounting": false
      }, {
          "entry": {
              "tx_hash": "0x19807cd818b2b50a2284bda2dfc39c9f60607ccfa25b1a01143e934280635eb7",
              "timestamp": 1588006528,
              "block_number": 10700085,
              "from_address": "0x1CAdbe158CB5162439901edA08df0A305b016dA1",
              "to_address": "0xA9916D445ce1318A2377b3D6a5F58EaEa72288a1",
              "value": "56000300000000000000000",
              "gas": "610676",
              "gas_price": "106000000000",
              "gas_used": "270154",
              "input_data": "0x",
              "nonce": 55
          },
          "ignored_in_accounting": true
      }],
      "entries_found": 95,
      "entries_limit": 500,
      "entries_total": 1000
  "message": ""
}
Request JSON Object
  • result (object) – A list of transaction entries to return for the given filter.

  • entries_found (int) – The number of entries found for the current filter. Ignores pagination.

  • entries_limit (int) – The limit of entries if free version. -1 for premium.

  • entries_total (int) – The number of total entries ignoring all filters.

Status Codes
  • 200 OK – Transactions succesfull queried

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

  • 409 Conflict – User is not logged in or some other error. Check error message for details.

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

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 -X GET 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
Content-Type: application/json;charset=UTF-8

{
      "name": "not public",
      "description": "Accounts that are not publicly 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" -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"background_color": "f8f8f8", "description": "Accounts that are not publicly associated with me", "foreground_color": "f1f1f1", "name": "not public"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/tags/ --header="Accept: application/json, text/javascript" --header="Content-Type: application/json;charset=UTF-8" --body-data='{"background_color": "f8f8f8", "description": "Accounts that are not publicly associated with me", "foreground_color": "f1f1f1", "name": "not public"}'

httpie

echo '{
  "background_color": "f8f8f8",
  "description": "Accounts that are not publicly associated with me",
  "foreground_color": "f1f1f1",
  "name": "not public"
}' | http PUT http://localhost:5042/api/1/tags/ Accept:"application/json, text/javascript" Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/tags/', headers={'Accept': 'application/json, text/javascript', 'Content-Type': 'application/json;charset=UTF-8'}, json={'background_color': 'f8f8f8', 'description': 'Accounts that are not publicly associated with me', 'foreground_color': 'f1f1f1', 'name': 'not public'})
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
Content-Type: application/json;charset=UTF-8

{
      "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" -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"background_color": "f9f9f9", "description": "Accounts that are private", "foreground_color": "f2f2f2", "name": "not public"}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/tags/ --header="Accept: application/json, text/javascript" --header="Content-Type: application/json;charset=UTF-8" --body-data='{"background_color": "f9f9f9", "description": "Accounts that are private", "foreground_color": "f2f2f2", "name": "not public"}'

httpie

echo '{
  "background_color": "f9f9f9",
  "description": "Accounts that are private",
  "foreground_color": "f2f2f2",
  "name": "not public"
}' | http PATCH http://localhost:5042/api/1/tags/ Accept:"application/json, text/javascript" Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/tags/', headers={'Accept': 'application/json, text/javascript', 'Content-Type': 'application/json;charset=UTF-8'}, json={'background_color': 'f9f9f9', 'description': 'Accounts that are private', 'foreground_color': 'f2f2f2', 'name': 'not public'})
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
Content-Type: application/json;charset=UTF-8

{
      "name": "not public"
}

curl

curl -i -X DELETE http://localhost:5042/api/1/tags/ -H "Accept: application/json, text/javascript" -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"name": "not public"}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/tags/ --header="Accept: application/json, text/javascript" --header="Content-Type: application/json;charset=UTF-8" --body-data='{"name": "not public"}'

httpie

echo '{
  "name": "not public"
}' | http DELETE http://localhost:5042/api/1/tags/ Accept:"application/json, text/javascript" Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/tags/', headers={'Accept': 'application/json, text/javascript', 'Content-Type': 'application/json;charset=UTF-8'}, json={'name': 'not public'})
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, ETH, KSM, DOT and AVAX.

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 -X GET 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": {
                "standalone": {
                    "3Kb9QPcTUJKspzjQFBppfXRcWew6hyDAPb": {
                        "amount": "0.5", "usd_value": "3770.075"
                    }, "33hjmoU9XjEz8aLxf44FNGB8TdrLkAVBBo": {
                        "amount": "0.5", "usd_value": "3770.075"
                }},
                "xpubs": [{
                        "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk",
                        "derivation_path": "m/0/0",
                        "addresses": {
                            "1LZypJUwJJRdfdndwvDmtAjrVYaHko136r": {
                                "amount": "0.5", "usd_value": "3770.075"
                            },
                            "1AMrsvqsJzDq25QnaJzX5BzEvdqQ8T6MkT": {
                                "amount": "0.5", "usd_value": "3770.075"
                            }
                    }}, {
                        "xpub": "zpub6quTRdxqWmerHdiWVKZdLMp9FY641F1F171gfT2RS4D1FyHnutwFSMiab58Nbsdu4fXBaFwpy5xyGnKZ8d6xn2j4r4yNmQ3Yp3yDDxQUo3q",
                        "derivation_path": "m",
                        "addresses": {
                            "bc1qc3qcxs025ka9l6qn0q5cyvmnpwrqw2z49qwrx5": {
                                "amount": "0.5", "usd_value": "3770.075"
                            },
                            "bc1qr4r8vryfzexvhjrx5fh5uj0s2ead8awpqspqra": {
                                "amount": "0.5", "usd_value": "3770.075"
                            }
                    }}]
             },
             "ETH": { "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B": {
                 "assets": {
                     "ETH": {"amount": "10", "usd_value": "1650.53"},
                     "_ceth_0x6B175474E89094C44Da98b954EedeAC495271d0F": {"amount": "15", "usd_value": "15.21"}
                 },
                 "liabilities": {
                     "_ceth_0x6B175474E89094C44Da98b954EedeAC495271d0F": {"amount": "20", "usd_value": "20.35"}
                 }
            }}
        },
        "totals": {
            "assets": {
                "BTC": {"amount": "1", "usd_value": "7540.15"},
                "ETH": {"amount": "10", "usd_value": "1650.53"},
                "_ceth_0x6B175474E89094C44Da98b954EedeAC495271d0F": {"amount": "15", "usd_value": "15.21"}
            },
            "liabilities": {
                "_ceth_0x6B175474E89094C44Da98b954EedeAC495271d0F": {"amount": "20", "usd_value": "20.35"}
            }
        }
    },
    "message": ""
}
resjson object per_account

The blockchain balances per account per asset. Each element of this object has a blockchain 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. Ethereum accounts have a mapping of tokens owned by each account. ETH accounts may have an optional liabilities key. This would be the same as assets. BTC accounts are separated in standalone accounts and in accounts that have been derived from an xpub. The xpub ones are listed in a list under the "xpubs" key. Each entry has the xpub, the derivation path and the list of addresses and their balances.

resjson object total

The blockchain balances in total per asset. Has 2 keys. One for assets and one for liabilities. The liabilities key may be missing if no liabilities exist.

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/debt across all locations for the user. That is exchanges, blockchains and all manually tracked balances. And it will return an overview of all queried balances. This also includes any debt/liabilities.

Example Request:

http

GET /api/1/balances/ HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{"async_query": true}

curl

curl -i -X GET http://localhost:5042/api/1/balances/ -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": true}'

wget

wget -S -O- http://localhost:5042/api/1/balances/ --header="Content-Type: application/json;charset=UTF-8" --body-data='{"async_query": true}'

httpie

echo '{
  "async_query": true
}' | http http://localhost:5042/api/1/balances/ Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/balances/', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'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 ).

  • ignore_error (bool) – Boolean denoting whether to still save a snapshot of balances even if there is an error. Off by default. So if for example Binance exchange errors out and this is true then a snapshot will be taken. Otherwise it won’t.

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": {
        "assets": {
            "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"
             }
         },
         "liabilities": {
             "_ceth_0x6B175474E89094C44Da98b954EedeAC495271d0F": {
                 "amount": "100",
                 "usd_value": "102.5",
                 "percentage_of_net_value": "1%"
             }
         },
         "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) – The result object has two main subkeys. Assets and liabilities. Both assets and liabilities value is another object with the following keys. "amount" is the amount owned in total for that asset or owed in total as a liablity. "percentage_of_net_value" is the percentage the user’s net worth that this asset or liability represents. And finally "usd_value" is the total $ value this asset/liability 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 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

  • 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

  • cryptocompare: The cryptocompare identifier for the asset. can be missing if not known. If missing the symbol is attempted to be queried.

  • coingecko: The coingecko identifier for the asset. can be missing if not known.

  • protocol: An optional string for ethereum tokens denoting the protocol they belong to. For example uniswap, for uniswap LP tokens.

  • underlying_tokens: Optional. If the token is an LP token or a token set or something similar which represents a pool of multiple other tokens, then this is a list of the underlying token addresses and a percentage that each token contributes to the pool.

    Example Request:

    http

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

    curl

    curl -i -X GET 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": {
            "_ceth_0xB6eD7644C69416d67B522e20bC294A9a9B405B31": {
                "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"
            },
            "_ceth_0xcC4eF9EEAF656aC1a2Ab886743E98e97E090ed38": {
                "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"
            },
            "_ceth_0xD850942eF8811f2A866692A623011bDE52a462C1": {
                "ethereum_address": "0xD850942eF8811f2A866692A623011bDE52a462C1",
                "ethereum_token_decimals": 18,
                "name": "Vechain Token",
                "started": 1503360000,
                "swapped_for": "VET",
                "symbol": "VEN",
                "type": "ethereum token",
                "coingecko": "vechain"
            },
        },
        "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 -X GET 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

Getting custom ethereum tokens

GET /api/(version)/assets/ethereum

Doing a GET on the ethereum assets endpoint will return a list of all custom ethereum tokens. You can also optionally specify an ethereum address to get its token details. If you query by address only a single object is returned. If you query without, a list of objects.

Example Request:

http

GET /api/1/assets/ethereum HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{"address": "0x1169C72f36A843cD3a3713a76019FAB9503B2807"}

curl

curl -i -X GET http://localhost:5042/api/1/assets/ethereum -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0x1169C72f36A843cD3a3713a76019FAB9503B2807"}'

wget

wget -S -O- http://localhost:5042/api/1/assets/ethereum --header="Content-Type: application/json;charset=UTF-8" --body-data='{"address": "0x1169C72f36A843cD3a3713a76019FAB9503B2807"}'

httpie

echo '{
  "address": "0x1169C72f36A843cD3a3713a76019FAB9503B2807"
}' | http http://localhost:5042/api/1/assets/ethereum Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/assets/ethereum', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'address': '0x1169C72f36A843cD3a3713a76019FAB9503B2807'})
Request JSON Object
  • address (string) – An optional address to query for ethereum token info. If given only token info of this address are returned. As an object. not a list. If not given, a list of all known tokens is returned.

Example Response:

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

{
    "result": [{
        "identifier": "_ceth_0x1169C72f36A843cD3a3713a76019FAB9503B2807",
        "address": "0x1169C72f36A843cD3a3713a76019FAB9503B2807",
        "decimals": 18,
        "name": "foo",
        "symbol": "FTK",
        "started": 1614636432,
        "swapped_for": "SCT",
        "coingecko": "foo-coin",
        "cryptocompare": "FOO",
        "protocol": "uniswap",
        "underlying_tokens": [
            {"address": "0x4a363BDcF9C139c0B77d929C8c8c5f971a38490c", "weight": "15.45"},
            {"address": "0xf627B24754583896AbB6376b1e231A3B26d86c99", "weight": "35.65"},
            {"address": "0x2B18982803EF09529406e738f344A0c1A54fA1EB", "weight": "39"}
        ]
    }, {
        "address": "0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e",
        "decimals": 4
    }],
    "message": ""
}
Response JSON Object
  • result (list) – A list of ethereum tokens

Response JSON Array of Objects
  • identifier (string) – The rotki identifier of the token. This is only returned from the GET endpoint and not input from the add/edit one.

  • address (string) – The address of the token. Can not be optional.

  • decimals (integer) – Ethereum token decimals. Can be missing if not known.

  • name (string) – Asset name. Can be missing if not known.

  • symbol (string) – Asset symbol. Can be missing if not known.

  • started (integer) – The timestamp of the token deployment. Can be missing if not known.

  • swapped_for (string) – If this token was swapped for another one then here we would have the identifier of that other token. If not this is null.

  • coingecko (string) – The coingecko identifier for the asset. can be missing if not known.

  • cryptocompare (string) – The cryptocompare identifier for the asset. can be missing if not known.

  • protocol (string) – A name for the protocol the token belongs to. For example uniswap for all uniswap LP tokens. Can be missing if not known or there is no protocol the token belongs to.

  • underlying_tokens (list) – Optional. If the token is an LP token or a token set or something similar which represents a pool of multiple other tokens, then this is a list of the underlying token addresses and a percentage that each token contributes to the pool.

Status Codes

Adding custom ethereum tokens

PUT /api/(version)/assets/ethereum

Doing a PUT on the ethereum assets endpoint will allow you to add a new ethereum token in the global rotki DB. Returns the asset identifier of the new custom token. For ethereum ones it’s _ceth_0xADDRESS

Example Request:

http

PUT /api/1/assets/ethereum HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{"token": {
    "address": "0x1169C72f36A843cD3a3713a76019FAB9503B2807",
    "decimals": 18,
    "name": "foo",
    "symbol": "FTK",
    "started": 1614636432,
    "swapped_for": "SCT",
    "coingecko": "foo-coin",
    "cryptocompare": "FOO",
    "protocol": "uniswap",
    "underlying_tokens": [
        {"address": "0x4a363BDcF9C139c0B77d929C8c8c5f971a38490c", "weight": "15.45"},
            {"address": "0xf627B24754583896AbB6376b1e231A3B26d86c99", "weight": "35.65"},
            {"address": "0x2B18982803EF09529406e738f344A0c1A54fA1EB", "weight": "39"}
   ]
 }}

curl

curl -i -X PUT http://localhost:5042/api/1/assets/ethereum -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"token": {"address": "0x1169C72f36A843cD3a3713a76019FAB9503B2807", "coingecko": "foo-coin", "cryptocompare": "FOO", "decimals": 18, "name": "foo", "protocol": "uniswap", "started": 1614636432, "swapped_for": "SCT", "symbol": "FTK", "underlying_tokens": [{"address": "0x4a363BDcF9C139c0B77d929C8c8c5f971a38490c", "weight": "15.45"}, {"address": "0xf627B24754583896AbB6376b1e231A3B26d86c99", "weight": "35.65"}, {"address": "0x2B18982803EF09529406e738f344A0c1A54fA1EB", "weight": "39"}]}}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/assets/ethereum --header="Content-Type: application/json;charset=UTF-8" --body-data='{"token": {"address": "0x1169C72f36A843cD3a3713a76019FAB9503B2807", "coingecko": "foo-coin", "cryptocompare": "FOO", "decimals": 18, "name": "foo", "protocol": "uniswap", "started": 1614636432, "swapped_for": "SCT", "symbol": "FTK", "underlying_tokens": [{"address": "0x4a363BDcF9C139c0B77d929C8c8c5f971a38490c", "weight": "15.45"}, {"address": "0xf627B24754583896AbB6376b1e231A3B26d86c99", "weight": "35.65"}, {"address": "0x2B18982803EF09529406e738f344A0c1A54fA1EB", "weight": "39"}]}}'

httpie

echo '{
  "token": {
    "address": "0x1169C72f36A843cD3a3713a76019FAB9503B2807",
    "coingecko": "foo-coin",
    "cryptocompare": "FOO",
    "decimals": 18,
    "name": "foo",
    "protocol": "uniswap",
    "started": 1614636432,
    "swapped_for": "SCT",
    "symbol": "FTK",
    "underlying_tokens": [
      {
        "address": "0x4a363BDcF9C139c0B77d929C8c8c5f971a38490c",
        "weight": "15.45"
      },
      {
        "address": "0xf627B24754583896AbB6376b1e231A3B26d86c99",
        "weight": "35.65"
      },
      {
        "address": "0x2B18982803EF09529406e738f344A0c1A54fA1EB",
        "weight": "39"
      }
    ]
  }
}' | http PUT http://localhost:5042/api/1/assets/ethereum Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/assets/ethereum', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'token': {'address': '0x1169C72f36A843cD3a3713a76019FAB9503B2807', 'coingecko': 'foo-coin', 'cryptocompare': 'FOO', 'decimals': 18, 'name': 'foo', 'protocol': 'uniswap', 'started': 1614636432, 'swapped_for': 'SCT', 'symbol': 'FTK', 'underlying_tokens': [{'address': '0x4a363BDcF9C139c0B77d929C8c8c5f971a38490c', 'weight': '15.45'}, {'address': '0xf627B24754583896AbB6376b1e231A3B26d86c99', 'weight': '35.65'}, {'address': '0x2B18982803EF09529406e738f344A0c1A54fA1EB', 'weight': '39'}]}})
Request JSON Object
  • token (object) – A token to add. For details on the possible fields see here.

Example Response:

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

{
    "result": {"identifier": "_ceth_0x1169C72f36A843cD3a3713a76019FAB9503B2807"},
    "message": ""
}
Response JSON Object
  • identifier (string) – The identifier of the newly added token.

Status Codes

Editing custom ethereum tokens

PATCH /api/(version)/assets/ethereum

Doing a PATCH on the ethereum assets endpoint will allow you to edit an existing ethereum token in the global rotki DB. Returns the asset identifier of the edited token for success.

Example Request:

http

PATCH /api/1/assets/ethereum HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{
    "token": {
        "address": "0x1169C72f36A843cD3a3713a76019FAB9503B2807",
        "decimals": 5,
        "name": "foo",
        "symbol": "FTK",
        "started": 1614636432,
        "swapped_for": "SCP",
        "coingecko": "foo-coin",
        "cryptocompare": "FOO",
        "protocol": "aave"
   }
}

curl

curl -i -X PATCH http://localhost:5042/api/1/assets/ethereum -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"token": {"address": "0x1169C72f36A843cD3a3713a76019FAB9503B2807", "coingecko": "foo-coin", "cryptocompare": "FOO", "decimals": 5, "name": "foo", "protocol": "aave", "started": 1614636432, "swapped_for": "SCP", "symbol": "FTK"}}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/assets/ethereum --header="Content-Type: application/json;charset=UTF-8" --body-data='{"token": {"address": "0x1169C72f36A843cD3a3713a76019FAB9503B2807", "coingecko": "foo-coin", "cryptocompare": "FOO", "decimals": 5, "name": "foo", "protocol": "aave", "started": 1614636432, "swapped_for": "SCP", "symbol": "FTK"}}'

httpie

echo '{
  "token": {
    "address": "0x1169C72f36A843cD3a3713a76019FAB9503B2807",
    "coingecko": "foo-coin",
    "cryptocompare": "FOO",
    "decimals": 5,
    "name": "foo",
    "protocol": "aave",
    "started": 1614636432,
    "swapped_for": "SCP",
    "symbol": "FTK"
  }
}' | http PATCH http://localhost:5042/api/1/assets/ethereum Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/assets/ethereum', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'token': {'address': '0x1169C72f36A843cD3a3713a76019FAB9503B2807', 'coingecko': 'foo-coin', 'cryptocompare': 'FOO', 'decimals': 5, 'name': 'foo', 'protocol': 'aave', 'started': 1614636432, 'swapped_for': 'SCP', 'symbol': 'FTK'}})
Request JSON Object
  • token (object) – Token to edit. Token is edited by address. The old token is completely replaced by all new entries passed by this endpoint. For details on the possible fields see here.

Example Response:

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

{
    "result": {"identifier": "_ceth_0x1169C72f36A843cD3a3713a76019FAB9503B2807"},
    "message": ""
}
Response JSON Object
  • identifier (string) – The identifier of the edited token.

Status Codes

Deleting custom ethereum tokens

DELETE /api/(version)/assets/ethereum

Doing a DELETE on the ethereum assets endpoint will allow you to delete an existing ethereum token from the global rotki DB by address.

Example Request:

http

DELETE /api/1/assets/ethereum HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{"address": "0x1169C72f36A843cD3a3713a76019FAB9503B2807"}

curl

curl -i -X DELETE http://localhost:5042/api/1/assets/ethereum -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0x1169C72f36A843cD3a3713a76019FAB9503B2807"}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/assets/ethereum --header="Content-Type: application/json;charset=UTF-8" --body-data='{"address": "0x1169C72f36A843cD3a3713a76019FAB9503B2807"}'

httpie

echo '{
  "address": "0x1169C72f36A843cD3a3713a76019FAB9503B2807"
}' | http DELETE http://localhost:5042/api/1/assets/ethereum Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/assets/ethereum', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'address': '0x1169C72f36A843cD3a3713a76019FAB9503B2807'})
Request JSON Object
  • address (string) – Address of the token to delete.

Example Response:

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

{
    "result": {"identifier": "GNO"},
    "message": ""
}
Response JSON Object
  • identifier (string) – The rotki identifier of the token that was deleted.

Status Codes

Get asset types

GET /api/(version)/assets/types

Doing a GET on the assets types endpoint will return a list of all valid asset type

Example Request:

http

GET /api/1/assets/types HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

curl

curl -i -X GET http://localhost:5042/api/1/assets/types -H "Content-Type: application/json;charset=UTF-8"

wget

wget -S -O- http://localhost:5042/api/1/assets/types --header="Content-Type: application/json;charset=UTF-8"

httpie

http http://localhost:5042/api/1/assets/types Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/assets/types', headers={'Content-Type': 'application/json;charset=UTF-8'})

Example Response:

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

{
    "result": ["fiat", "own chain", "ethereum token", "omni token", "neo token", "counterparty token", "bitshares token", "ardor token", "nxt token", "ubiq token", "nubits token", "burst token", "waves token", "qtum token", "stellar token", "tron token", "ontology token", "vechain token", "binance token", "eos token", "fusion token", "luniverse token", "other"],
    "message": ""
}
Response JSON Object
  • result (list) – A list of all the valid asset type values to input when adding a new asset

Status Codes

Adding custom asset

PUT /api/(version)/assets/all

Doing a PUT on the all assets endpoint will allow you to add a new asset in the global rotki DB. Returns the identifier of the newly added asset.

Example Request:

http

PUT /api/1/assets/all HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{
    "name": "foo",
    "symbol": "FOO",
    "started": 1614636432,
    "forked": "SCT",
    "swapped_for": "SCK",
    "coingecko": "foo-coin",
    "cryptocompare": "FOO"
 }

curl

curl -i -X PUT http://localhost:5042/api/1/assets/all -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"coingecko": "foo-coin", "cryptocompare": "FOO", "forked": "SCT", "name": "foo", "started": 1614636432, "swapped_for": "SCK", "symbol": "FOO"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/assets/all --header="Content-Type: application/json;charset=UTF-8" --body-data='{"coingecko": "foo-coin", "cryptocompare": "FOO", "forked": "SCT", "name": "foo", "started": 1614636432, "swapped_for": "SCK", "symbol": "FOO"}'

httpie

echo '{
  "coingecko": "foo-coin",
  "cryptocompare": "FOO",
  "forked": "SCT",
  "name": "foo",
  "started": 1614636432,
  "swapped_for": "SCK",
  "symbol": "FOO"
}' | http PUT http://localhost:5042/api/1/assets/all Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/assets/all', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'coingecko': 'foo-coin', 'cryptocompare': 'FOO', 'forked': 'SCT', 'name': 'foo', 'started': 1614636432, 'swapped_for': 'SCK', 'symbol': 'FOO'})
Request JSON Object
  • name (string) – The name of the asset. Required.

  • symbol (string) – The symol of the asset. Required.

  • started (integer) – The time the asset started existing. Optional

  • forked (string) – The identifier of an asset from which this asset got forked. For example ETC would have ETH as forked. Optional.

  • swapped_for (string) – The identifier of an asset for which this asset got swapped for. For example GNT got swapped for GLM. Optional.

Response JSON Array of Objects
  • coingecko (string) – The coingecko identifier for the asset. can be missing if not known.

  • cryptocompare (string) – The cryptocompare identifier for the asset. can be missing if not known.

Example Response:

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

{
    "result": {"identifier": "4979582b-ee8c-4d45-b461-15c4220de666"},
    "message": ""
}
Response JSON Object
  • identifier (string) – The identifier of the newly added token.

Status Codes

Editing custom assets

PATCH /api/(version)/assets/all

Doing a PATCH on the custom assets endpoint will allow you to edit an existing asset in the global rotki DB.

Example Request:

http

PUT /api/1/assets/ethereum HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{
    "identifier": "4979582b-ee8c-4d45-b461-15c4220de666",
    "name": "foo",
    "symbol": "FOO",
    "started": 1614636432,
    "forked": "SCT",
    "swapped_for": "SCK",
    "coingecko": "foo-coin",
    "cryptocompare": "FOO"
}

curl

curl -i -X PUT http://localhost:5042/api/1/assets/ethereum -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"coingecko": "foo-coin", "cryptocompare": "FOO", "forked": "SCT", "identifier": "4979582b-ee8c-4d45-b461-15c4220de666", "name": "foo", "started": 1614636432, "swapped_for": "SCK", "symbol": "FOO"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/assets/ethereum --header="Content-Type: application/json;charset=UTF-8" --body-data='{"coingecko": "foo-coin", "cryptocompare": "FOO", "forked": "SCT", "identifier": "4979582b-ee8c-4d45-b461-15c4220de666", "name": "foo", "started": 1614636432, "swapped_for": "SCK", "symbol": "FOO"}'

httpie

echo '{
  "coingecko": "foo-coin",
  "cryptocompare": "FOO",
  "forked": "SCT",
  "identifier": "4979582b-ee8c-4d45-b461-15c4220de666",
  "name": "foo",
  "started": 1614636432,
  "swapped_for": "SCK",
  "symbol": "FOO"
}' | http PUT http://localhost:5042/api/1/assets/ethereum Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/assets/ethereum', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'coingecko': 'foo-coin', 'cryptocompare': 'FOO', 'forked': 'SCT', 'identifier': '4979582b-ee8c-4d45-b461-15c4220de666', 'name': 'foo', 'started': 1614636432, 'swapped_for': 'SCK', 'symbol': 'FOO'})
Request JSON Object
  • asset (object) – Asset to edit. For details on the possible fields see here. The only extra field has to be the identifier of the asset to edit.

Example Response:

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

{
    "result": true,
    "message": ""
}
Status Codes

Deleting custom assets

DELETE /api/(version)/assets/all

Doing a DELETE on the custom assets endpoint will allow you to delete an existing asset from the global rotki DB.

Example Request:

http

DELETE /api/1/assets/all HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{"identifier": "4979582b-ee8c-4d45-b461-15c4220de666"}

curl

curl -i -X DELETE http://localhost:5042/api/1/assets/all -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"identifier": "4979582b-ee8c-4d45-b461-15c4220de666"}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/assets/all --header="Content-Type: application/json;charset=UTF-8" --body-data='{"identifier": "4979582b-ee8c-4d45-b461-15c4220de666"}'

httpie

echo '{
  "identifier": "4979582b-ee8c-4d45-b461-15c4220de666"
}' | http DELETE http://localhost:5042/api/1/assets/all Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/assets/all', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'identifier': '4979582b-ee8c-4d45-b461-15c4220de666'})
Request JSON Object
  • identifier (string) – Address of the asset to delete.

Example Response:

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

{
    "result": true,
    "message": ""
}
Status Codes
  • 200 OK – Asset succesfully deleted.

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

  • 409 Conflict – Some conflict at deleting. For example identifier does not exist in the DB. Or deleting the asset would break a constraint since it’s used by other assets.

  • 500 Internal Server Error – Internal rotki error

Checking for pending asset updates

GET /api/(version)/assets/updates

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 this endpoint will prompt a query on the remote github server and return how many updates (if any) exists for the local asset database.

Example Request:

http

GET /api/1/assets/updates HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{"async_query": true}

curl

curl -i -X GET http://localhost:5042/api/1/assets/updates -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": true}'

wget

wget -S -O- http://localhost:5042/api/1/assets/updates --header="Content-Type: application/json;charset=UTF-8" --body-data='{"async_query": true}'

httpie

echo '{
  "async_query": true
}' | http http://localhost:5042/api/1/assets/updates Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/assets/updates', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': True})

Example Response:

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

{
    "result": {
        "local": 1,
        "remote": 4,
        "new_changes": 121
    "message": ""
}
Response JSON Object
  • local (int) – The version of the local assets database

  • remote (int) – The latest assets update version on the remote

  • new_changes (int) – The number of changes (additions, edits and deletions) that would be applied to reach the remote version.

Status Codes

Performing an asset update

POST /api/(version)/assets/updates

Note

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

Doing a POST on this endpoint will attempt an update of the assets database.

Example Request:

http

POST /api/1/assets/updates HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{
    "async_query": true,
    "up_to_version": 5,
    "conflicts": {
        "_ceth_0xD178b20c6007572bD1FD01D205cC20D32B4A6015": "local",
        "_ceth_0xD178b20c6007572bD1FD01D205cC20D32B4A6015": "remote",
        "Fas-23-da20": "local"
    }
}

curl

curl -i -X POST http://localhost:5042/api/1/assets/updates -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": true, "conflicts": {"Fas-23-da20": "local", "_ceth_0xD178b20c6007572bD1FD01D205cC20D32B4A6015": "remote"}, "up_to_version": 5}'

wget

wget -S -O- http://localhost:5042/api/1/assets/updates --header="Content-Type: application/json;charset=UTF-8" --post-data='{"async_query": true, "conflicts": {"Fas-23-da20": "local", "_ceth_0xD178b20c6007572bD1FD01D205cC20D32B4A6015": "remote"}, "up_to_version": 5}'

httpie

echo '{
  "async_query": true,
  "conflicts": {
    "Fas-23-da20": "local",
    "_ceth_0xD178b20c6007572bD1FD01D205cC20D32B4A6015": "remote"
  },
  "up_to_version": 5
}' | http POST http://localhost:5042/api/1/assets/updates Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/assets/updates', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': True, 'conflicts': {'Fas-23-da20': 'local', '_ceth_0xD178b20c6007572bD1FD01D205cC20D32B4A6015': 'remote'}, 'up_to_version': 5})
Request JSON Object
  • async_query (bool) – Optional. If given and true then the query becomes an asynchronous query.

  • up_to_version (int) – Optional. If given then the asset updates up to and including this version will be pulled and applied

  • conflicts (object) – Optional. Should only be given if at the previous run there were conflicts returned. This is a mapping of asset identifiers to either "local" or "remote" specifying which of the two to keep in a conflict.

Example Response:

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

{
    "result": true
    "message": ""
}

Example Response:

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

{
  "result": [{
      "identifier":  "assetid1",
      "local": {
          "coingecko": "2give",
          "name": "2GIVE",
          "started": 1460937600,
          "symbol": "2GIVE",
          "type": "own chain"
      },
      "remote": {
          "coingecko": "TWOgive",
          "name": "TWOGIVE",
          "started": 1460937600,
          "symbol": "2GIVEORNOTTOGIVE",
          "type": "own chain"
     }}, {
     "identifier": "asset_id2",
     "local": {
             "coingecko": "aave",
             "ethereum_address": "0x7Fc66500c84A76Ad7e9c93437bFc5Ac33E2DDaE9",
             "ethereum_token_decimals": 18,
             "name": "Aave Token",
             "started": 1600970788,
             "symbol": "AAVE",
             "type": "ethereum token"
     },
     "remote": {
             "coingecko": "aaveNGORZ",
             "ethereum_address": "0x1Fc66500c84A76Ad7e9c93437bFc5Ac33E2DDaE9",
             "ethereum_token_decimals": 15,
             "name": "Aave Token FOR REALZ",
             "started": 1600970789,
             "symbol": "AAVE_YO!",
             "type": "binance token"
     }
  }],
  "message": ""
}
Response JSON Object
  • result (object) – Either true if all went fine or a a list of conflicts, containing the identifier of the asset in question and the local and remote versions.

Status Codes
  • 200 OK – Update was succesfully applied (if any).

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

  • 409 Conflict – Conflicts were found during update. The conflicts should also be returned. No user is currently logged in.

  • 500 Internal Server Error – Internal rotki error

  • 502 Bad Gateway – Error while trying to reach the remote for asset updates.

Replacing an asset

PUT /api/(version)/assets/replace

It’s possible to replace an asset with another asset in both the global and the user DB. If the source asset identifier exists in the global DB it’s removed in favor of the target asset. If not, the global DB is not touched. In both cases the user DB is touched and all appearances of the source asset identifier are replaced with target asset. If the asset you are replacing is used as swapped_for, forked_for or underlying asset by another asset you will first have to manually delete it from there.

Example Request:

http

PUT /api/1/assets/replace HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{"source_identifier": "4979582b-ee8c-4d45-b461-15c4220de666", "target_asset": "BTC"}

curl

curl -i -X PUT http://localhost:5042/api/1/assets/replace -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"source_identifier": "4979582b-ee8c-4d45-b461-15c4220de666", "target_asset": "BTC"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/assets/replace --header="Content-Type: application/json;charset=UTF-8" --body-data='{"source_identifier": "4979582b-ee8c-4d45-b461-15c4220de666", "target_asset": "BTC"}'

httpie

echo '{
  "source_identifier": "4979582b-ee8c-4d45-b461-15c4220de666",
  "target_asset": "BTC"
}' | http PUT http://localhost:5042/api/1/assets/replace Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/assets/replace', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'source_identifier': '4979582b-ee8c-4d45-b461-15c4220de666', 'target_asset': 'BTC'})
Request JSON Object
  • source_identifier (string) – The identifier of the asset that will get replaced/removed. This asset does not need to exist in the global DB. If it does it will be removed.

  • target_asset (string) – The identifier of the asset that will replace the source asset. This must be an existing asset.

Example Response:

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

{
    "result": true,
    "message": ""
}
Status Codes

Querying asset icons

GET /api/(version)/assets/(identifier)/icon

Doing a GET on the asset icon endpoint will return the icon of the given asset. If we have no icon for an asset a 404 is returned.

Example Request:

http

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

curl

curl -i -X GET http://localhost:5042/api/1/assets/_ceth_0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e/icon

wget

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

httpie

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

python-requests

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

Example Response:

HTTP/1.1 200 OK
Content-Type: image/png
Result

The data of the image

Status Codes
  • 200 OK – Icon succesfully queried

  • 304 Not Modified – Icon data has not changed. Should be cached on the client. This is returned if the given If-Match or If-None-Match header match the etag of the previous response.

  • 400 Bad Request – Provided JSON is in some way malformed. Either unknown asset or invalid size.

  • 404 Not Found – We have no icon for that asset

  • 500 Internal Server Error – Internal rotki error

Uploading custom asset icons

PUT /api/(version)/assets/(identifier)/icon
POST /api/(version)/assets/(identifier)/icon

Doing either a PUT or a POST on the asset icon endpoint with appropriate arguments will upload a custom icon for an asset. That icon will take precedence over what rotki already knows for the asset if anything.

Example Request:

http

PUT /api/1/assets/ACUSTOMICON/icon/large HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{"file": "/path/to/file"}

curl

curl -i -X PUT http://localhost:5042/api/1/assets/ACUSTOMICON/icon/large -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"file": "/path/to/file"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/assets/ACUSTOMICON/icon/large --header="Content-Type: application/json;charset=UTF-8" --body-data='{"file": "/path/to/file"}'

httpie

echo '{
  "file": "/path/to/file"
}' | http PUT http://localhost:5042/api/1/assets/ACUSTOMICON/icon/large Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/assets/ACUSTOMICON/icon/large', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'file': '/path/to/file'})
Request JSON Object
  • file (string) – The path to the image file to upload for PUT. The file itself for POST.

Example Response:

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

{"result": {"identifier": "_ceth_0x6810e776880C02933D47DB1b9fc05908e5386b96"}, "message": ""}
Response JSON Object
  • identifier (strin) – The identifier of the asset for which the icon was uploaded.

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 -X GET 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 identifier)

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
Content-Type: application/json;charset=UTF-8

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

curl

curl -i -X GET http://localhost:5042/api/1/statistics/balance/BTC -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_timestamp": 1514764800, "to_timestamp": 1572080165}'

wget

wget -S -O- http://localhost:5042/api/1/statistics/balance/BTC --header="Content-Type: application/json;charset=UTF-8" --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 Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/statistics/balance/BTC', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'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
Content-Type: application/json;charset=UTF-8

{"distribution_by": "location"}

curl

curl -i -X GET http://localhost:5042/api/1/statistics/value_distribution/ -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"distribution_by": "location"}'

wget

wget -S -O- http://localhost:5042/api/1/statistics/value_distribution/ --header="Content-Type: application/json;charset=UTF-8" --body-data='{"distribution_by": "location"}'

httpie

echo '{
  "distribution_by": "location"
}' | http http://localhost:5042/api/1/statistics/value_distribution/ Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/statistics/value_distribution/', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'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
Content-Type: application/json;charset=UTF-8

{"distribution_by": "asset"}

curl

curl -i -X GET http://localhost:5042/api/1/statistics/value_distribution/ -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"distribution_by": "asset"}'

wget

wget -S -O- http://localhost:5042/api/1/statistics/value_distribution/ --header="Content-Type: application/json;charset=UTF-8" --body-data='{"distribution_by": "asset"}'

httpie

echo '{
  "distribution_by": "asset"
}' | http http://localhost:5042/api/1/statistics/value_distribution/ Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/statistics/value_distribution/', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'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 -X GET 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 can also be queried asynchronously by using "async_query": true

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. If the user is not premium and has more than 250 trades then the returned trades will be limited to that number. Any filtering will also be limited to those first 250 trades. Trades are returned most recent first.

Example Request:

http

GET /api/1/trades HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

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

curl

curl -i -X GET http://localhost:5042/api/1/trades -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_timestamp": 1451606400, "location": "external", "only_cache": false, "to_timestamp": 1571663098}'

wget

wget -S -O- http://localhost:5042/api/1/trades --header="Content-Type: application/json;charset=UTF-8" --body-data='{"from_timestamp": 1451606400, "location": "external", "only_cache": false, "to_timestamp": 1571663098}'

httpie

echo '{
  "from_timestamp": 1451606400,
  "location": "external",
  "only_cache": false,
  "to_timestamp": 1571663098
}' | http http://localhost:5042/api/1/trades Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/trades', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_timestamp': 1451606400, 'location': 'external', 'only_cache': False, 'to_timestamp': 1571663098})
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.

  • only_cache (bool) – Optional.If this is true then the equivalent exchange/location is not queried, but only what is already in the DB is returned.

Example Response:

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

{
    "result": {
        "entries": [{
            "entry": {
                "trade_id": "dsadfasdsad",
                "timestamp": 1491606401,
                "location": "external",
                "base_asset": "BTC",
                "quote_asset": "EUR",
                "trade_type": "buy",
                "amount": "0.5541",
                "rate": "8422.1",
                "fee": "0.55",
                "fee_currency": "USD",
                "link": "Optional unique trade identifier",
                "notes": "Optional notes"
            },
            "ignored_in_accounting": false
        }],
        "entries_found": 95,
        "entries_limit": 250,
    "message": ""
}
Response JSON Object
  • entries (object) – An array of trade objects and their metadata. Each entry is composed of the main trade entry under the "entry" key and other metadata like "ignored_in_accounting" for each trade.

  • entries_found (int) – The amount of trades found for the user. That disregards the filter and shows all trades found.

  • entries_limit (int) – The trades limit for the account tier of the user. If unlimited then -1 is returned.

Response JSON Array of Objects
  • trade_id (string) – The uniquely identifying identifier for this trade. The trade id depends on the data of the trade. If the trade is edited so will the trade id.

  • timestamp (int) – The timestamp at which the trade occured

  • location (string) – A valid location at which the trade happened

  • base_asset (string) – The base_asset of the trade.

  • quote_asset (string) – The quote_asset of the trade.

  • 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) – Optional. The fee that was paid, if anything, for this trade

  • fee_currency (string) – Optional. The currency in which fee is denominated in.

  • link (string) – Optional unique trade identifier or link to the trade.

  • notes (string) – Optional notes about the trade.

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
Content-Type: application/json;charset=UTF-8

{
    "timestamp": 1491606401,
    "location": "external",
    "base_asset": "BTC",
    "quote_asset": "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 -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"amount": "0.5541", "base_asset": "BTC", "fee": "0.55", "fee_currency": "USD", "link": "Optional unique trade identifier", "location": "external", "notes": "Optional notes", "quote_asset": "EUR", "rate": "8422.1", "timestamp": 1491606401, "trade_type": "buy"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/trades --header="Content-Type: application/json;charset=UTF-8" --body-data='{"amount": "0.5541", "base_asset": "BTC", "fee": "0.55", "fee_currency": "USD", "link": "Optional unique trade identifier", "location": "external", "notes": "Optional notes", "quote_asset": "EUR", "rate": "8422.1", "timestamp": 1491606401, "trade_type": "buy"}'

httpie

echo '{
  "amount": "0.5541",
  "base_asset": "BTC",
  "fee": "0.55",
  "fee_currency": "USD",
  "link": "Optional unique trade identifier",
  "location": "external",
  "notes": "Optional notes",
  "quote_asset": "EUR",
  "rate": "8422.1",
  "timestamp": 1491606401,
  "trade_type": "buy"
}' | http PUT http://localhost:5042/api/1/trades Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/trades', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'amount': '0.5541', 'base_asset': 'BTC', 'fee': '0.55', 'fee_currency': 'USD', 'link': 'Optional unique trade identifier', 'location': 'external', 'notes': 'Optional notes', 'quote_asset': 'EUR', 'rate': '8422.1', 'timestamp': 1491606401, 'trade_type': 'buy'})
Request JSON Object
  • timestamp (int) – The timestamp at which the trade occured

  • location (string) – A valid location at which the trade happened

  • 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) – Optional. The fee that was paid, if anything, for this trade

  • fee_currency (string) – Optional. The currency in which fee is denominated in

  • link (string) – Optional unique trade identifier or link to the trade.

  • notes (string) – Optional notes about the trade.

Response JSON Array of Objects
  • base_asset (string) – The base_asset of the trade.

  • quote_asset (string) – The quote_asset of the trade.

Example Response:

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

{
    "result": [{
            "trade_id": "dsadfasdsad",
            "timestamp": 1491606401,
            "location": "external",
            "base_asset": "BTC",
            "quote_asset": "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 trade entries 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. The edited trade’s trade id is returned and will be different.

Example Request:

http

PATCH /api/1/trades HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{
    "trade_id" : "dsadfasdsad",
    "timestamp": 1491606401,
    "location": "external",
    "base_asset": "BTC",
    "quote_asset": "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 -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"amount": "1.5541", "base_asset": "BTC", "fee": "0.55", "fee_currency": "USD", "link": "Optional unique trade identifier", "location": "external", "notes": "Optional notes", "quote_asset": "EUR", "rate": "8422.1", "timestamp": 1491606401, "trade_id": "dsadfasdsad", "trade_type": "buy"}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/trades --header="Content-Type: application/json;charset=UTF-8" --body-data='{"amount": "1.5541", "base_asset": "BTC", "fee": "0.55", "fee_currency": "USD", "link": "Optional unique trade identifier", "location": "external", "notes": "Optional notes", "quote_asset": "EUR", "rate": "8422.1", "timestamp": 1491606401, "trade_id": "dsadfasdsad", "trade_type": "buy"}'

httpie

echo '{
  "amount": "1.5541",
  "base_asset": "BTC",
  "fee": "0.55",
  "fee_currency": "USD",
  "link": "Optional unique trade identifier",
  "location": "external",
  "notes": "Optional notes",
  "quote_asset": "EUR",
  "rate": "8422.1",
  "timestamp": 1491606401,
  "trade_id": "dsadfasdsad",
  "trade_type": "buy"
}' | http PATCH http://localhost:5042/api/1/trades Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/trades', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'amount': '1.5541', 'base_asset': 'BTC', 'fee': '0.55', 'fee_currency': 'USD', 'link': 'Optional unique trade identifier', 'location': 'external', 'notes': 'Optional notes', 'quote_asset': 'EUR', 'rate': '8422.1', 'timestamp': 1491606401, 'trade_id': 'dsadfasdsad', 'trade_type': 'buy'})
Request JSON Object
  • trade_id (string) – The trade_id of the trade to edit. Note: the returned trade id will be different.

  • timestamp (int) – The new timestamp

  • location (string) – The new location

  • base_asset (string) – The new base_asset

  • quote_asset (string) – The new quote_asset

  • trade_type (string) – The new trade type

  • rate (string) – The new trade rate

  • fee (string) – The new fee. Can be set to null.

  • fee_currency (string) – The new fee currency. Can be set to null.

  • link (string) – The new link attribute. Can be set to null.

  • notes (string) – The new notes attribute. Can be set to null.

Example Response:

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

{
    "result": {
        "trade_id": "sdfhdjskfha",
        "timestamp": 1491606401,
        "location": "external",
        "base_asset": "BTC",
        "quote_asset": "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. The trade id will be different if the trade was succesfully edited.

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
Content-Type: application/json;charset=UTF-8

{ "trade_id" : "dsadfasdsad"}

curl

curl -i -X DELETE http://localhost:5042/api/1/trades -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"trade_id": "dsadfasdsad"}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/trades --header="Content-Type: application/json;charset=UTF-8" --body-data='{"trade_id": "dsadfasdsad"}'

httpie

echo '{
  "trade_id": "dsadfasdsad"
}' | http DELETE http://localhost:5042/api/1/trades Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/trades', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'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 asset movements

GET /api/(version)/asset_movements

Note

This endpoint also accepts parameters as query arguments.

Doing a GET on this endpoint will return all asset movements (deposits/withdrawals) from all possible exchanges for the current user. It can be further filtered by a time range of a location. For non premium users there is a limit on the amount of movements returned.

Example Request:

http

GET /api/1/asset_movements HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{"from_timestamp": 1451606400, "to_timestamp": 1571663098, "location": "kraken", "only_cache": false}

curl

curl -i -X GET http://localhost:5042/api/1/asset_movements -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_timestamp": 1451606400, "location": "kraken", "only_cache": false, "to_timestamp": 1571663098}'

wget

wget -S -O- http://localhost:5042/api/1/asset_movements --header="Content-Type: application/json;charset=UTF-8" --body-data='{"from_timestamp": 1451606400, "location": "kraken", "only_cache": false, "to_timestamp": 1571663098}'

httpie

echo '{
  "from_timestamp": 1451606400,
  "location": "kraken",
  "only_cache": false,
  "to_timestamp": 1571663098
}' | http http://localhost:5042/api/1/asset_movements Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/asset_movements', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_timestamp': 1451606400, 'location': 'kraken', 'only_cache': False, 'to_timestamp': 1571663098})
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. Valid locations are for now only exchanges for deposits/widthrawals.

Parameters
  • only_cache (bool) – Optional. If this is true then the equivalent exchange/location is not queried, but only what is already in the DB is returned.

Example Response:

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

{
    "result": {
        "entries": [{
            "entry": {
                "identifier": "foo"
                "location": "kraken",
                "category": "deposit",
                "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",
                "transaction_id": "3a4b9b2404f6e6fb556c3e1d46a9752f5e70a93ac1718605c992b80aacd8bd1d",
                "timestamp": 1451706400
                "asset": "ETH",
                "amount": "500.55",
                "fee_asset": "ETH",
                "fee": "0.1",
                "link": "optional exchange unique id"
            },
            "ignored_in_accounting": false
        }],
        "entries_found": 80,
        "entries_limit": 100,
    "message": ""
}
Response JSON Object
  • entries (object) – An array of deposit/withdrawal objects and their metadata. Each entry is composed of the main movement entry under the "entry" key and other metadata like "ignored_in_accounting" for each asset movement.

  • entries_found (int) – The amount of deposit/withdrawals found for the user. That disregards the filter and shows all asset movements found.

  • entries_limit (int) – The movements query limit for the account tier of the user. If unlimited then -1 is returned.

Response JSON Array of Objects
  • identifier (string) – The uniquely identifying identifier for this asset movement

  • location (string) – A valid location at which the deposit/withdrawal occured

  • category (string) – Either "deposit" or "withdrawal"

  • address (string) – The source address if this is a deposit or the destination address if this is a withdrawal.

  • transaction_id (string) – The transaction id

  • timestamp (integer) – The timestamp at which the deposit/withdrawal occured

  • asset (string) – The asset deposited or withdrawn

  • amount (string) – The amount of asset deposited or withdrawn

  • fee_asset (string) – The asset in which fee is denominated in

  • fee (string) – The fee that was paid, if anything, for this deposit/withdrawal

  • link (string) – Optional unique exchange identifier for the deposit/withdrawal

Status Codes

Dealing with ledger actions

GET /api/(version)/ledgeractions

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 this endpoint will return all ledger actions of the current user. That means income, loss, expense and other actions. They can be further filtered by time range and/or location. If the user is not premium and has more than 50 actions then the returned results will be limited to that number. Any filtering will also be limited to those first 50 actions. Actions are returned most recent first.

Example Request:

http

GET /api/1/ledgeractions HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

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

curl

curl -i -X GET http://localhost:5042/api/1/ledgeractions -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_timestamp": 1451606400, "location": "blockchain", "to_timestamp": 1571663098}'

wget

wget -S -O- http://localhost:5042/api/1/ledgeractions --header="Content-Type: application/json;charset=UTF-8" --body-data='{"from_timestamp": 1451606400, "location": "blockchain", "to_timestamp": 1571663098}'

httpie

echo '{
  "from_timestamp": 1451606400,
  "location": "blockchain",
  "to_timestamp": 1571663098
}' | http http://localhost:5042/api/1/ledgeractions Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/ledgeractions', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_timestamp': 1451606400, 'location': 'blockchain', 'to_timestamp': 1571663098})
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 actions 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 actions by location. A valid location name has to be provided. If missing location filtering does not happen.

  • only_cache (bool) – Optional. If this is true then the equivalent exchange/location is not queried, but only what is already in the DB is returned.

Example Response:

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

{
    "result": {
        "entries": [{
            "entry": {
                "identifier": 344,
                "timestamp": 1491606401,
                "action_type": "loss",
                "location": "blockchain",
                "amount": "1550",
                "asset": "_ceth_0x6B175474E89094C44Da98b954EedeAC495271d0F",
                "rate": "0.85",
                "rate_asset": "EUR",
                "link": "https://etherscan.io/tx/0xea5594ad7a1e552f64e427b501676cbba66fd91bac372481ff6c6f1162b8a109"
                "notes": "The DAI I lost in the pickle finance hack"
            },
            "ignored_in_accounting": false
        }],
        "entries_found": 1,
        "entries_limit": 50,
    "message": ""
}
Response JSON Object
  • entries (object) – An array of action objects and their metadata. Each entry is composed of the ledger action entry under the "entry" key and other metadata like "ignored_in_accounting" for each action.

  • entries_found (int) – The amount of actions found for the user. That disregards the filter and shows all actions found.

  • entries_limit (int) – The actions limit for the account tier of the user. If unlimited then -1 is returned.

Response JSON Array of Objects
  • identifier (int) – The uniquely identifying identifier for this action.

  • timestamp (int) – The timestamp at which the action occured

  • action_type (string) – The type of action. Valid types are: income, loss, donation received, expense and dividends income.

  • location (string) – A valid location at which the action happened.

  • amount (string) – The amount of asset for the action

  • asset (string) – The asset for the action

  • rate (string) – Optional. If given then this is the rate in rate_asset for the asset of the action.

  • rate_asset (string) – Optional. If given then this is the asset for which rate is given.

  • link (string) – Optional unique identifier or link to the action. Can be an empty string

  • notes (string) – Optional notes about the action. Can be an empty string

Status Codes
PUT /api/(version)/ledgeractions

Doing a PUT on this endpoint adds a new ledgeraction to rotki’s currently logged in user. The identifier of the new created action is returned.

Example Request:

http

PUT /api/1/ledgeraction HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{
    "action": {
        "timestamp": 1491606401,
        "action_type": "income",
        "location": "external",
        "amount": "1",
        "asset": "ETH",
        "rate": "650",
        "rate_asset": "EUR",
        "link": "Optional unique identifier",
        "notes": "Eth I received for being pretty"
}}

curl

curl -i -X PUT http://localhost:5042/api/1/ledgeraction -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"action": {"action_type": "income", "amount": "1", "asset": "ETH", "link": "Optional unique identifier", "location": "external", "notes": "Eth I received for being pretty", "rate": "650", "rate_asset": "EUR", "timestamp": 1491606401}}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/ledgeraction --header="Content-Type: application/json;charset=UTF-8" --body-data='{"action": {"action_type": "income", "amount": "1", "asset": "ETH", "link": "Optional unique identifier", "location": "external", "notes": "Eth I received for being pretty", "rate": "650", "rate_asset": "EUR", "timestamp": 1491606401}}'

httpie

echo '{
  "action": {
    "action_type": "income",
    "amount": "1",
    "asset": "ETH",
    "link": "Optional unique identifier",
    "location": "external",
    "notes": "Eth I received for being pretty",
    "rate": "650",
    "rate_asset": "EUR",
    "timestamp": 1491606401
  }
}' | http PUT http://localhost:5042/api/1/ledgeraction Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/ledgeraction', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'action': {'action_type': 'income', 'amount': '1', 'asset': 'ETH', 'link': 'Optional unique identifier', 'location': 'external', 'notes': 'Eth I received for being pretty', 'rate': '650', 'rate_asset': 'EUR', 'timestamp': 1491606401}})

The request object is the same as above, a LedgerAction entry.

Example Response:

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

{
    "result": {"identifier": 1},
    "message": ""
}
Response JSON Object
  • result (object) – The identifier ofthe newly created ledger action

Status Codes
PATCH /api/(version)/ledgeractions

Doing a PATCH on this endpoint edits an existing ledger action in rotki’s currently logged in user using the given identifier.

Example Request:

http

PATCH /api/1/ledgeractions HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{
    "identifier": 55,
    "timestamp": 1491606401,
    "action_type": "income",
    "location": "external",
    "amount": "2",
    "asset": "ETH",
    "rate": "650",
    "rate_asset": "EUR",
    "link": "Optional unique identifier",
    "notes": "Eth I received for being pretty"
}

curl

curl -i -X PATCH http://localhost:5042/api/1/ledgeractions -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"action_type": "income", "amount": "2", "asset": "ETH", "identifier": 55, "link": "Optional unique identifier", "location": "external", "notes": "Eth I received for being pretty", "rate": "650", "rate_asset": "EUR", "timestamp": 1491606401}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/ledgeractions --header="Content-Type: application/json;charset=UTF-8" --body-data='{"action_type": "income", "amount": "2", "asset": "ETH", "identifier": 55, "link": "Optional unique identifier", "location": "external", "notes": "Eth I received for being pretty", "rate": "650", "rate_asset": "EUR", "timestamp": 1491606401}'

httpie

echo '{
  "action_type": "income",
  "amount": "2",
  "asset": "ETH",
  "identifier": 55,
  "link": "Optional unique identifier",
  "location": "external",
  "notes": "Eth I received for being pretty",
  "rate": "650",
  "rate_asset": "EUR",
  "timestamp": 1491606401
}' | http PATCH http://localhost:5042/api/1/ledgeractions Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/ledgeractions', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'action_type': 'income', 'amount': '2', 'asset': 'ETH', 'identifier': 55, 'link': 'Optional unique identifier', 'location': 'external', 'notes': 'Eth I received for being pretty', 'rate': '650', 'rate_asset': 'EUR', 'timestamp': 1491606401})

The request object is the same as above, a LedgerAction entry, with the addition of the identifier which signifies which ledger action entry will be edited.

Example Response:

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

{
    "result": {
        "entries": [{
            "entry": {
                "identifier": 55,
                "timestamp": 1491606401,
                "action_type": "income"
                "location": "external",
                "amount": "2",
                "asset": "ETH",
                "rate": "650",
                "rate_asset": "EUR",
                "link": "Optional unique identifier",
                "notes": "Eth I received for being pretty"
            },
            "ignored_in_accounting": false
        }],
        "entries_found": 1,
        "entries_limit": 50,
    "message": ""
}
Response JSON Object
  • entries (object) – An array of action objects after editing. Same schema as the get method.

  • entries_found (int) – The amount of actions found for the user. That disregards the filter and shows all actions found.

  • entries_limit (int) – The actions limit for the account tier of the user. If unlimited then -1 is returned.

Status Codes
DELETE /api/(version)/ledgeractions

Doing a DELETE on this endpoint deletes an existing ledger action in rotki’s currently logged in user using the identifier.

Example Request:

http

DELETE /api/1/ledgeractions HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{"identifier" : 55}

curl

curl -i -X DELETE http://localhost:5042/api/1/ledgeractions -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"identifier": 55}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/ledgeractions --header="Content-Type: application/json;charset=UTF-8" --body-data='{"identifier": 55}'

httpie

echo '{
  "identifier": 55
}' | http DELETE http://localhost:5042/api/1/ledgeractions Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/ledgeractions', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'identifier': 55})
Request JSON Object
  • identifier (integer) – The identifier of the action to delete.

Example Response:

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

{
    "result": {
        "entries": [{
            "entry": {
                "identifier": 35,
                "timestamp": 1491606401,
                "action_type": "income"
                "location": "external",
                "amount": "2",
                "asset": "ETH",
                "rate": "650",
                "rate_asset": "EUR",
                "link": "Optional unique identifier",
                "notes": "Eth I received for being pretty"
            },
            "ignored_in_accounting": false
        }],
        "entries_found": 1,
        "entries_limit": 50,
    "message": ""
}
Response JSON Object
  • entries (object) – An array of action objects after deletion. Same schema as the get method.

  • entries_found (int) – The amount of actions found for the user. That disregards the filter and shows all actions found.

  • entries_limit (int) – The actions limit for the account tier of the user. If unlimited then -1 is returned.

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 -X GET 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
Content-Type: application/json;charset=UTF-8

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

curl

curl -i -X GET http://localhost:5042/api/1/history/ -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": true, "from_timestamp": 1514764800, "to_timestamp": 1572080165}'

wget

wget -S -O- http://localhost:5042/api/1/history/ --header="Content-Type: application/json;charset=UTF-8" --body-data='{"async_query": true, "from_timestamp": 1514764800, "to_timestamp": 1572080165}'

httpie

echo '{
  "async_query": true,
  "from_timestamp": 1514764800,
  "to_timestamp": 1572080165
}' | http http://localhost:5042/api/1/history/ Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/history/', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': True, 'from_timestamp': 1514764800, 'to_timestamp': 1572080165})
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",
            "ledger_actions_profit_loss": "1500",
            "margin_positions_profit_loss": "500",
            "settlement_losses": "200",
            "ethereum_transaction_gas_costs": "2.5",
            "asset_movement_fees": "3.45",
            "general_trade_profit_loss": "5002",
            "taxable_trade_profit_loss": "5002",
            "total_taxable_profit_loss": "6936.05",
            "total_profit_loss": "6936.05"
        },
        "events_processed": 1000,
        "events_limit": 1000,
        "first_processed_timestamp": 1428994442,
        "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,
            "cost_basis": null,
            "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,
            "cost_basis": {
                "is_complete": true,
                "matched_acquisitions": [{
                    "time": 15653231,
                    "description": "trade",
                    "location": "kraken",
                    "used_amount": "0.1",
                    "amount": "1",
                    "rate": "500",
                    "fee_rate": "0.1",
                }, {
                    "time": 15654231,
                    "description": "trade",
                    "location": "bittrex",
                    "used_amount": "0.1",
                    "amount": "1",
                    "rate": "550",
                    "fee_rate": "0",
                }]
            },
            "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.

  • ledger_actions_profit_loss (str) – The profit/loss from all the manually input ledger actions. Income, loss, expense and more.

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

  • events_processed (int) – The total number of events processed. This also includes events in the past which are not exported due to the requested PnL range.

  • events_limit (int) – The limit of the events for the user’s tier. -1 stands for unlimited. If the limit is hit then the event processing stops and only all events and PnL calculation up to the limit is returned.

  • first_processed_timestamp (int) – The timestamp of the very first event processed. This can be before the query period since we always query from the beginning of history to have a full cost basis.

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.

  • cost_basis (object) – An object describing the cost basis of the event if it’s a spend event. Contains a boolean attribute "is_complete" to denoting if we have complete cost basis information for the spent asset or not. If not then this means that rotki does not know enough to properly calculate cost basis. The other attribute is "matched_acquisitions" a list of matched acquisition events from which the cost basis is calculated. Each event has "time", "description", "location" attributes which are self-explanatory. Then it also has the "amount" which is the amount that was acquired in that event and the "used_amount" which is how much of that is used in this spend action. Then there is the "rate" key which shows the rate in the profit currency with which 1 unit of the asset was acquired at the event. And finally the "fee_rate" denoting how much of the profit currency was paid for each unit of the asset bought.

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
Content-Type: application/json;charset=UTF-8

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

curl

curl -i -X GET http://localhost:5042/api/1/history/export -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"directory_path": "/home/username/path/to/csvdir"}'

wget

wget -S -O- http://localhost:5042/api/1/history/export --header="Content-Type: application/json;charset=UTF-8" --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 Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/history/export', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'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 history progress status

GET /api/(version)/history/status

Doing a GET on the history’s query current status will return information about the progress of the current historical query process.

Example Request:

http

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

curl

curl -i -X GET http://localhost:5042/api/1/history/status

wget

wget -S -O- http://localhost:5042/api/1/history/status

httpie

http http://localhost:5042/api/1/history/status

python-requests

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

Example Response:

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

{
    "result": {
        "processing_state": "Querying kraken exchange history",
        "total_progress": "50%"
    }
    "message": ""
}
Response JSON Object
  • processing_state (str) – The name of the task that is currently being executed for the history query and profit/loss report.

  • total_progress (str) – A percentage showing the total progress of the profit/loss report.

Status Codes

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 -X GET 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,
        "last_data_upload_ts": 0
    }
    "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.

Status Codes

Getting blockchain account data

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

Note

Supported blockchains: "BTC", "ETH", "KSM", "DOT", "AVAX"

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 -X GET 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"]
     }, {
        "address": "G7UkJAutjbQyZGRiP8z5bBSBPBJ66JbTKAkFDq3cANwENyX",
        "label": "my Kusama account",
        "tags": null
     }],
     "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. For BTC blockchain query and if the entry is an xpub then this attribute is misssing.

  • xpub (string) – The extended public key. This attribute only exists for BTC blockchain query and if the entry is an xpub

  • 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

Example Request:

http

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

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/BTC/

wget

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

httpie

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

python-requests

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

Example Response:

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

{
    "result" : {
        "standalone": [{
            "address": "bc1qc3qcxs025ka9l6qn0q5cyvmnpwrqw2z49qwrx5",
            "label": null,
            "tags": ["private"],
            }, {
            "address": "bc1qr4r8vryfzexvhjrx5fh5uj0s2ead8awpqspqra",
            "label": "some label",
            "tags": null,
        }],
        "xpubs": [{
            "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk",
            "derivation_path": "m/0/0",
            "label": "ledger xpub",
            "tags": ["super secret", "awesome"],
            "addresses": [{
                "address": "1LZypJUwJJRdfdndwvDmtAjrVYaHko136r",
                "label": "derived address",
                "tags": ["super secret", "awesome", "derived"]
                }, {
                "address": "1AMrsvqsJzDq25QnaJzX5BzEvdqQ8T6MkT",
                "label": null,
                "tags": null
                }]
            }, {
            "xpub": "zpub6quTRdxqWmerHdiWVKZdLMp9FY641F1F171gfT2RS4D1FyHnutwFSMiab58Nbsdu4fXBaFwpy5xyGnKZ8d6xn2j4r4yNmQ3Yp3yDDxQUo3q",
            "derivation_path": null,
            "label": "some label",
            "tags": null,
            "addresses": null,
        }]
    },
     "message": "",
}
Response JSON Object
  • result (list) – An object with the account data details. Has two attributes. "standalone" for standalone addresses. That follows the same response format as above. And "xpub" for bitcoin xpubs. Below we will see the format of the xpub response.

Response JSON Array of Objects
  • xpub (string) – The extended public key string

  • derivation_path (string) – [Optional] If existing this is the derivation path from which to start deriving accounts from the xpub.

  • label (string) – [Optional] The label to describe the xpub. Can also be null.

  • tags (list) – [Optional] A list of tags associated with the account. Can also be null.

  • addresses (list) – [Optional] A list of address objects derived by the account. Can also be null. The attributes of each object are as seen in the previous response.

Status Codes

Getting all DeFi balances

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

Doing a GET on the DeFi balances endpoint will return a mapping of all accounts to their respective balances in DeFi protocols.

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

curl

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

wget

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

httpie

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

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/defi')
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": [{
            "protocol": {"name": "Curve"},
            "balance_type": "Asset",
            "base_balance": {
                "token_address": "0xdF5e0e81Dff6FAF3A7e52BA697820c5e32D806A8",
                "token_name": "Y Pool",
                "token_symbol": "yDAI+yUSDC+yUSDT+yTUSD",
                "balance": {
                    "amount": "1000",
                    "usd_value": "1009.12"
                }
            },
            "underlying_balances": [{
                "token_address": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
                "token_name": "Dai Stablecoin",
                "token_symbol": "DAI",
                "balance": {
                    "amount": "200",
                    "usd_value": "201.12"
                }
            }, {
                "token_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
                "token_name": "USD//C",
                "token_symbol": "USDC",
                "balance": {
                    "amount": "300",
                    "usd_value": "302.14"
                }
            }, {
                "token_address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
                "token_name": "Tether USD",
                "token_symbol": "USDT",
                "balance": {
                    "amount": "280",
                    "usd_value": "281.98"
                }
            }, {
                "token_address": "0x0000000000085d4780B73119b644AE5ecd22b376",
                "token_name": "TrueUSD",
                "token_symbol": "TUSD",
                "balance": {
                    "amount": "220",
                    "usd_value": "221.201"
                }
            }]
        }, {
            "protocol": {"name": "Compound"},
            "balance_type": "Asset",
            "base_balance": {
                "token_address": "0x6C8c6b02E7b2BE14d4fA6022Dfd6d75921D90E4E",
                "token_name": "Compound Basic Attention Token",
                "token_symbol": "cBAT",
                "balance": {
                    "amount": "8000",
                    "usd_value": "36.22"
                }
            },
            "underlying_balances": [{
                "token_address": "0x0D8775F648430679A709E98d2b0Cb6250d2887EF",
                "token_name": "Basic Attention Token",
                "token_symbol": "BAT",
                "balance": {
                    "amount": "150",
                    "usd_value": "36.21"
                }
            }]
        }, {
            "protocol": {"name": "Compound"},
            "balance_type": "Asset",
            "base_balance": {
                "token_address": "0xc00e94Cb662C3520282E6f5717214004A7f26888",
                "token_name": "Compound",
                "token_symbol": "COMP",
                "balance": {
                    "amount": "0.01",
                    "usd_value": "1.9"
                }
            },
            "underlying_balances": []
        }],
        "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B": [{
            "protocol": {"name": "Aave"},
            "balance_type": "Asset",
            "base_balance": {
                "token_address": "0xfC1E690f61EFd961294b3e1Ce3313fBD8aa4f85d",
                "token_name": "Aave Interest bearing DAI",
                "token_symbol": "aDAI",
                "balance": {
                    "amount": "2000",
                    "usd_value": "2001.95"
                }
            },
            "underlying_balances": [{
                "token_address": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
                "token_name": "Dai Stablecoin",
                "token_symbol": "DAI",
                "balance": {
                    "amount": "2000",
                    "usd_value": "2001.95"
                }
            }]
        }],
    },
    "message": ""
}
Response JSON Object
  • result (object) – A mapping from account to list of DeFi balances.

Response JSON Array of Objects
  • protocol (object) – The name of the protocol. Since these names come from Zerion check here for supported names.

  • balance_type (string) – One of "Asset" or "Debt" denoting that one if deposited asset in DeFi and the other a debt or liability.

  • base_balance (string) – A single DefiBalance entry. It’s comprised of a token address, name, symbol and a balance. This is the actually deposited asset in the protocol. Can also be a synthetic in case of synthetic protocols or lending pools.

  • underlying_balances (string) – A list of underlying DefiBalances supporting the base balance. Can also be an empty list. The format of each balance is thesame as that of base_balance. For lending this is going to be the normal token. For example for aDAI this is DAI. For cBAT this is BAT etc. For pools this list contains all tokens that are contained in the pool.

Status Codes
  • 200 OK – Balances succesfully queried.

  • 409 Conflict – User is not logged in or if using own chain the chain is not synced.

  • 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 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 -X GET 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 -X GET 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": {
                    "amount": "0",
                    "usd_value": "0"
                },
                "value": {
                    "amount": "350",
                    "usd_value": "351.21"
                },
                "block_number": 9128160,
                "timestamp": 1582706553,
                "tx_hash": "0x988aea85b54c5b2834b144e9f7628b524bf9faf3b87821aa520b7bcfb57ab289"
            }, {
                "movement_type": "deposit",
                "gain_so_far": {
                    "amount": "0.875232",
                    "usd_value": "0.885292"
                },
                "value": {
                    "amount": "50",
                    "usd_value": "50.87"
                },
                "block_number": 9129165,
                "timestamp": 1582806553,
                "tx_hash": "0x2a1bee69b9bafe031026dbcc8f199881b568fd767482b5436dd1cd94f2642443"
            }, {
                "movement_type": "withdrawal",
                "gain_so_far": {
                    "amount": "1.12875932",
                    "usd_value": "1.34813"
                },
                "value": {
                    "amount": "350",
                    "usd_value": "353.12"
                },
                "block_number": 9149160,
                "timestamp": 1592706553,
                "tx_hash": "0x618fc9542890a2f58ab20a3c12d173b3638af11fda813e61788e242b4fc9a756"
            }, {
            }],
            "gain_so_far": {
                "amount": "1.14875932",
                "usd_value": "1.2323"
            }
        },
        "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237": {
            "movements": [{
                "movement_type": "deposit",
                "gain_so_far": {
                    "amount": "0",
                    "usd_value": "0"
                },
                "value": {
                    "amount": "550",
                    "usd_value": "553.43"
                },
                "block_number": 9128174,
                "timestamp": 1583706553,
                "tx_hash": "0x2a1bee69b9bafe031026dbcc8f199881b568fd767482b5436dd1cd94f2642443"
            }],
            "gain_so_far": {
                "amount": "0.953423",
                "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. The amount is the DAI amount and the USD value is the added usd value of all the usd values of each movement again plus the usd value of the remaining taking into account current usd price

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 along with the usd value equivalent 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.

  • value (string) – The amount of DAI deposited or withdrawn from the DSR along with the USD equivalent 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 -X GET 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",
            "usd_value": "950.13"
        },
        "debt": {
            "amount": "650",
            "usd_value": "653.42"
        },
        "collateralization_ratio": "234.21%",
        "liquidation_ratio": "150%",
        "liquidation_price": "125.1",
        "stability_fee": "0.00%",
    }, {
        "identifier": 55,
        "collateral_type": "USDC-A",
        "owner": "0xB26a9561ffFD9fC603F7d6A30c37D79665207876",
        "collateral_asset": "_ceth_0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "collateral": {
            "amount": "150",
            "usd_value": "150"
        },
        "debt": {
            "amount": "50",
            "usd_value": "53.2"
        },
        "collateralization_ratio": "250.551%",
        "liquidation_ratio": "150%",
        "liquidation_price": "0.45",
        "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 identifier of the asset deposited in the vault as collateral.

  • collateral (string) – The amount of collateral currently deposited in the vault along with the current value in USD of all the collateral in the vault according to the MakerDAO price feed.

  • debt (string) – The amount of DAI owed to the vault. So generated DAI plus the stability fee interest. Along with its current usd value.

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

  • 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 -X GET 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,
        "collateral_asset": "ETH",
        "creation_ts": 1589067898,
        "total_interest_owed": "0.02341",
        "total_liquidated": {
            "amount": "0",
            "usd_value": "0"
        },
        "events": [{
            "event_type": "deposit",
            "value": {
                "amount": "5.551",
                "usd_value": "120.32"
            },
            "timestamp": 1589067899,
            "tx_hash": "0x678f31d49dd70d76c0ce441343c0060dc600f4c8dbb4cee2b08c6b451b6097cd"
        }, {
            "event_type": "generate",
            "value": {
                "amount": "325",
                "usd_value": "12003.32"
            },
            "timestamp": 1589067900,
            "tx_hash": "0x678f31d49dd70d76c0ce441343c0060dc600f4c8dbb4cee2b08c6b451b6097cd"
        }]
    }, {
        "identifier": 56,
        "collateral_asset": "_ceth_0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "creation_ts": 1589067897,
        "total_interest_owed": "-751.32",
        "total_liquidated": {
            "amount": "1050.21",
            "usd_value": "2501.234"
        },
        "events": [{
            "event_type": "deposit",
            "value": {
                "amount": "1050.21",
                "usd_value": "10500.21"
            },
            "timestamp": 1589067899,
            "tx_hash": "0x678f31d49dd70d76c0ce441343c0060dc600f4c8dbb4cee2b08c6b451b6097cd"
        }, {
            "event_type": "generate",
            "value": {
                "amount": "721.32",
                "usd_value": "7213.2"
            },
            "timestamp": 1589067900,
            "tx_hash": "0x678f31d49dd70d76c0ce441343c0060dc600f4c8dbb4cee2b08c6b451b6097cd"
        }, {
            "event_type": "liquidation",
            "value": {
                "amount": "500",
                "usd_value": "5000"
            },
            "timestamp": 1589068000,
            "tx_hash": "0x678f31d49dd70d76c0ce441343c0060dc600f4c8dbb4cee2b08c6b451b6097cd"
        }, {
            "event_type": "liquidation",
            "value": {
                "amount": "550.21",
                "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
  • collateral_asset (string) – The identifier of the asset deposited in the vault as collateral.

  • 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. Even if the vault has been paid out this still shows how much interest was paid to the vault. So it’s past and future interest owed.

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

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

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

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

Getting Aave balances

GET /api/(version)/blockchains/ETH/modules/aave/balances

Doing a GET on the aave balances resource will return the balances that the user has locked in Aave for lending and borrowing along with their current APYs.

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

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/ETH/modules/aave/balances

wget

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

httpie

http http://localhost:5042/api/1/blockchains/ETH/modules/aave/balances

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/modules/aave/balances')
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": {
            "lending": {
                "_ceth_0x6B175474E89094C44Da98b954EedeAC495271d0F": {
                    "balance": {
                        "amount": "350.0",
                        "usd_value": "351.21"
                    },
                    "apy": "3.51%"
                },
                "_ceth_0xdd974D5C2e2928deA5F71b9825b8b646686BD200": {
                    "balance": {
                        "amount": "220.21",
                        "usd_value": "363.3465"
                    },
                    "apy": "0.53%"
                },
            },
            "borrowing": {
                "_ceth_0x80fB784B7eD66730e8b1DBd9820aFD29931aab03": {
                    "balance": {
                        "amount": "590.21",
                        "usd_value": "146.076975"
                    },
                    "variable_apr": "7.46%"
                    "stable_apr": "9.03%"
                }
            }
        },
        "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237": {
            "lending": {},
            "borrowing": {
                "_ceth_0x0D8775F648430679A709E98d2b0Cb6250d2887EF": {
                    "balance": {
                        "amount": "560",
                        "usd_value": "156.8"
                    },
                    "variable_apr": "7.46%"
                    "stable_apr": "9.03%"
                }
            }
        }
    },
    "message": ""
}
Response JSON Object
  • result (object) – A mapping of all accounts that currently have Aave balance to the balances and APY data for each account for lending and borrowing. Each key is an asset and its values are the current balance and the APY in %

Status Codes
  • 200 OK – Aave balances succesfully queried.

  • 409 Conflict – User is not logged in. Or aave 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 Aave historical data

GET /api/(version)/blockchains/ETH/modules/aave/history

Note

This endpoint is only available for premium users

Doing a GET on the makerdao dsrhistory resource will return the history of deposits,withdrawals and interest payments of each account in Aave’s lending.

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

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/ETH/modules/aave/history

wget

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

httpie

http http://localhost:5042/api/1/blockchains/ETH/modules/aave/history

python-requests

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

  • reset_db_data (bool) – Boolean denoting whether all aave event data saved in the DB are going to be deleted and rewritten after this query. False by default.

Example Response:

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

{
    "result": {
        "0xA0B6B7fEa3a3ce3b9e6512c0c5A157a385e81056": {
            "events": [{
                "event_type": "deposit",
                "asset": "_ceth_0x6B175474E89094C44Da98b954EedeAC495271d0F",
                "atoken": "_ceth_0xfC1E690f61EFd961294b3e1Ce3313fBD8aa4f85d",
                "value": {
                    "amount": "350.0",
                    "usd_value": "351.21"
                },
                "block_number": 9128160,
                "timestamp": 1582706553,
                "tx_hash": "0x988aea85b54c5b2834b144e9f7628b524bf9faf3b87821aa520b7bcfb57ab289",
                "log_index": 1
            }, {
                "event_type": "interest",
                "asset": "_ceth_0xfC1E690f61EFd961294b3e1Ce3313fBD8aa4f85d",
                "value": {
                    "amount": "0.5323",
                    "usd_value": "0.5482"
                },
                "block_number": 9129165,
                "timestamp": 1582806553,
                "tx_hash": "0x2a1bee69b9bafe031026dbcc8f199881b568fd767482b5436dd1cd94f2642443",
                "log_index": 1
            }, {
                "event_type": "withdrawal",
                "asset": "_ceth_0x6B175474E89094C44Da98b954EedeAC495271d0F",
                "atoken": "_ceth_0xfC1E690f61EFd961294b3e1Ce3313fBD8aa4f85d",
                "value": {
                    "amount": "150",
                    "usd_value": "150.87"
                },
                "block_number": 9149160,
                "timestamp": 1592706553,
                "tx_hash": "0x618fc9542890a2f58ab20a3c12d173b3638af11fda813e61788e242b4fc9a756",
                "log_index": 1
            }, {
                "event_type": "deposit",
                "asset": "_ceth_0xE41d2489571d322189246DaFA5ebDe1F4699F498",
                "atoken": "_ceth_0x6Fb0855c404E09c47C3fBCA25f08d4E41f9F062f",
                "value": {
                    "amount": "150",
                    "usd_value": "60.995"
                },
                "block_number": 9149160,
                "timestamp": 1592706553,
                "tx_hash": "0x618fc9542890a2f58ab20a3c12d173b3638af11fda813e61788e242b4fc9a755",
                "log_index": 1
            }],
            "total_earned": {
                "_ceth_0x6B175474E89094C44Da98b954EedeAC495271d0F": {
                    "amount": "0.9482",
                    "usd_value": "1.001"
                },
                "_ceth_0xE41d2489571d322189246DaFA5ebDe1F4699F498": {
                    "amount": "0.523",
                    "usd_value": "0.0253"
                }
            },
            "total_lost": {
                "_ceth_0xFC4B8ED459e00e5400be803A9BB3954234FD50e3": {
                    "amount": "0.3212",
                    "usd_value": "3560.32"
                }
            }
        },
        "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237": {
            "events": [{
                "event_type": "deposit",
                "asset": "_ceth_0x0D8775F648430679A709E98d2b0Cb6250d2887EF",
                "value": {
                    "amount": "500",
                    "usd_value": "124.1"
                },
                "block_number": 9149160,
                "timestamp": 1592706553,
                "tx_hash": "0x618fc9542890a2f58ab20a3c12d173b3638af11fda813e61788e242b4fc9a755",
                "log_index": 1
            }],
            "total_earned_interest": {
                "_ceth_0x0D8775F648430679A709E98d2b0Cb6250d2887EF": {
                    "amount": "0.9482",
                    "usd_value": "0.2312"
                }
            },
            "total_lost": {},
            "total_earned_liquidations": {},
        }
    },
    "message": ""
}
Response JSON Object
  • result (object) – A mapping of accounts to the Aave history report of each account. If an account is not in the mapping rotki does not see anything ever deposited in Aave for it.

  • events (object) – A list of AaveEvents. Check the fields below for the potential values.

  • total_earned_interest (object) – A mapping of asset identifier to total earned (amount + usd_value mapping) for each asset’s interest earnings. The total earned is essentially the sum of all interest payments plus the difference between balanceOf and principalBalanceOf for each asset.

  • total_lost (object) – A mapping of asset identifier to total lost (amount + usd_value mapping) for each asset. The total losst for each asset is essentially the accrued interest from borrowing and the collateral lost from liquidations.

  • total_earned_liquidations (object) – A mapping of asset identifier to total earned (amount + usd_value mapping) for each repaid assets during liquidations.

Response JSON Array of Objects
  • event_type (string) – The type of Aave event. Can be "deposit", "withdrawal", "interest", "borrow", "repay" and "liquidation".

  • timestamp (int) – The unix timestamp at which the event occured.

  • block_number (int) – The block number at which the event occured. If the graph is queried this is unfortunately always 0, so UI should not show it.

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

  • log_index (int) – The log_index of the event. For the graph this is indeed a unique number in combination with the transaction hash, but it’s unfortunately not the log index.

  • asset (string) – This attribute appears in all event types except for "liquidation". It shows the asset that this event is about. This can only be an underlying asset of an aToken.

  • atoken (string) – This attribute appears in "deposit" and "withdrawals". It shows the aToken involved in the event.

  • value (object) – This attribute appears in all event types except for "liquidation". The value (amount and usd_value mapping) of the asset for the event. The rate is the asset/USD rate at the events’s timestamp.

  • borrow_rate_mode (string) – This attribute appears only in "borrow" events. Signifies the type of borrow. Can be either "stable" or "variable".

  • borrow_rate (string) – This attribute appears only in "borrow" events. Shows the rate at which the asset was borrowed. It’s a floating point number. For example "0.155434" would means 15.5434% interest rate for this borrowing.

  • accrued_borrow_interest (string) – This attribute appears only in "borrow" events. Its a floating point number showing the acrrued interest for borrowing the asset so far

  • fee (object) – This attribute appears only in "repay" events. The value (amount and usd_value mapping) of the fee for the repayment. The rate is the asset/USD rate at the events’s timestamp.

  • collateral_asset (string) – This attribute appears only in "liquidation" events. It shows the collateral asset that the user loses due to liquidation.

  • collateral_balance (string) – This attribute appears only in "liquidation" events. It shows the value (amount and usd_value mapping) of the collateral asset that the user loses due to liquidation. The rate is the asset/USD rate at the events’s timestamp.

  • principal_asset (string) – This attribute appears only in "liquidation" events. It shows the principal debt asset that is repaid due to the liquidation due to liquidation.

  • principal_balance (string) – This attribute appears only in "liquidation" events. It shows the value (amount and usd_value mapping) of the principal asset whose debt is repaid due to liquidation. The rate is the asset/USD rate at the events’s timestamp.

Status Codes
  • 200 OK – Aave history succesfully queried.

  • 409 Conflict – No user is currently logged in or currently logged in user does not have a premium subscription. Or aave 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 AdEx balances

GET /api/(version)/blockchains/ETH/modules/adex/balances

Doing a GET on the adex balances resource will return the ADX staked in the pools of the platform.

Note

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

Example Request:

http

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

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/ETH/modules/adex/balances

wget

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

httpie

http http://localhost:5042/api/1/blockchains/ETH/modules/adex/balances

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/modules/adex/balances')
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": {
      "0xE74ad5437C6CFB0cCD6bADda1F6b57b6E542E75e": [
          {
              "adx_balance": {
                  "amount": "1050",
                  "usd_value": "950"
              },
              "contract_address": "0x4846C6837ec670Bbd1f5b485471c8f64ECB9c534",
              "dai_unclaimed_balance": {
                  "amount": "0.221231768887185282",
                  "usd_value": "0.221895464193846837846"
              },
              "pool_id": "0x1ce0c96393fa219d9776f33146e983a3e4a7d95821faca1b180ea0011d93a121",
              "pool_name": "Tom"
          }
      ]
  },
  "message": "",
}
Response JSON Object
  • result (object) – A mapping between accounts and their balances in the AdEx pools (represented by a list where each item is a pool).

  • address (string) – The staking contract address.

  • pool_id (string) – The identifier of the pool.

  • pool_id – The name of the pool.

  • adx_balance (object) – The sum of the staked ADX plus the unclaimed ADX amount the user has in the pool, and its USD value.

  • dai_unclaimed_balance (object) – The unclaimed DAI amount the user has in the pool and its USD value.

Status Codes
  • 200 OK – AdEx balances succesfully queried.

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

  • 500 Internal Server Error – Internal rotki error.

  • 502 Bad Gateway – An external service used in the query such as etherscan or the graph node could not be reached or returned unexpected response.

Getting AdEx historical data

GET /api/(version)/blockchains/ETH/modules/adex/history

Doing a GET on the adex events history resource will return the history of staking events (e.g. withdraw, deposit) and the staking details of the pools.

Note

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

Example Request:

http

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

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/ETH/modules/adex/history

wget

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

httpie

http http://localhost:5042/api/1/blockchains/ETH/modules/adex/history

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/modules/adex/history')
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": {
      "0xE74ad5437C6CFB0cCD6bADda1F6b57b6E542E75e": {
          "events": [
              {
                  "bond_id": "0x540cab9883923c01e657d5da4ca5674b6e4626b4a148224635495502d674c7c5",
                  "event_type": "deposit",
                  "identity_address": "0x2a6c38D16BFdc7b4a20f1F982c058F07BDCe9204",
                  "pool_id": "0x1ce0c96393fa219d9776f33146e983a3e4a7d95821faca1b180ea0011d93a121",
                  "pool_name": "Tom",
                  "timestamp": 1604366004,
                  "tx_hash": "0x9989f47c6c0a761f98f910ac24e2438d858be96c12124a13be4bb4b3150c55ea",
                  "value": {
                      "amount": "1000",
                      "usd_value": "950"
                  }
              },
              {
                  "event_type": "claim",
                  "identity_address": "0x2a6c38D16BFdc7b4a20f1F982c058F07BDCe9204",
                  "pool_id": "0x1ce0c96393fa219d9776f33146e983a3e4a7d95821faca1b180ea0011d93a121",
                  "pool_name": "Tom",
                  "timestamp": 1607453764,
                  "tx_hash": "0xa9ee91af823c0173fc5ada908ff9fe3f4d7c84a2c9da795f0889b3f4ace75b13",
                  "value": {
                      "amount": "50",
                      "usd_value": "45.23"
                  },
                  "token": "_ceth_0xADE00C28244d5CE17D72E40330B1c318cD12B7c3",
              },
              {
                  "bond_id": "0x540cab9883923c01e657d5da4ca5674b6e4626b4a148224635495502d674c7c5",
                  "event_type": "withdraw",
                  "identity_address": "0x2a6c38D16BFdc7b4a20f1F982c058F07BDCe9204",
                  "pool_id": "0x1ce0c96393fa219d9776f33146e983a3e4a7d95821faca1b180ea0011d93a121",
                  "pool_name": "Tom",
                  "timestamp": 1607453764,
                  "tx_hash": "0xa9ee91af823c0173fc5ada908ff9fe3f4d7c84a2c9da795f0889b3f4ace75b13",
                  "value": {
                      "amount": "1000",
                      "usd_value": "950"
                  }
              },
              {
                  "bond_id": "0x16bb43690fe3764b15a2eb8d5e94e1ac13d6ef38e6c6f9d9f9c745eaff92d427",
                  "event_type": "deposit",
                  "identity_address": "0x2a6c38D16BFdc7b4a20f1F982c058F07BDCe9204",
                  "pool_id": "0x1ce0c96393fa219d9776f33146e983a3e4a7d95821faca1b180ea0011d93a121",
                  "pool_name": "Tom",
                  "timestamp": 1607453764,
                  "tx_hash": "0xa9ee91af823c0173fc5ada908ff9fe3f4d7c84a2c9da795f0889b3f4ace75b13",
                  "value": {
                      "amount": "1050",
                      "usd_value": "1015"
                  }
              },
              {
                  "event_type": "claim",
                  "identity_address": "0x2a6c38D16BFdc7b4a20f1F982c058F07BDCe9204",
                  "pool_id": "0x1ce0c96393fa219d9776f33146e983a3e4a7d95821faca1b180ea0011d93a121",
                  "pool_name": "Tom",
                  "timestamp": 1607915796,
                  "tx_hash": "0x892e2dacbd0fcb787d7104b4f384e24fc4573294b75b9bfd91ca969119d8ed80",
                  "value": {
                      "amount": "43",
                      "usd_value": "39.233"
                  },
                  "token": "_ceth_0xADE00C28244d5CE17D72E40330B1c318cD12B7c3",
              },
              {
                  "bond_id": "0x16bb43690fe3764b15a2eb8d5e94e1ac13d6ef38e6c6f9d9f9c745eaff92d427",
                  "event_type": "withdraw",
                  "identity_address": "0x2a6c38D16BFdc7b4a20f1F982c058F07BDCe9204",
                  "pool_id": "0x1ce0c96393fa219d9776f33146e983a3e4a7d95821faca1b180ea0011d93a121",
                  "pool_name": "Tom",
                  "timestamp": 1607915796,
                  "tx_hash": "0x892e2dacbd0fcb787d7104b4f384e24fc4573294b75b9bfd91ca969119d8ed80",
                  "value": {
                      "amount": "1050",
                      "usd_value": "1015"
                  }
              },
              {
                  "bond_id": "0x30bd07a0cc0c9b94e2d10487c1053fc6a5043c41fb28dcfa3ff80a68013eb501",
                  "event_type": "deposit",
                  "identity_address": "0x2a6c38D16BFdc7b4a20f1F982c058F07BDCe9204",
                  "pool_id": "0x1ce0c96393fa219d9776f33146e983a3e4a7d95821faca1b180ea0011d93a121",
                  "pool_name": "Tom",
                  "timestamp": 1607915796,
                  "tx_hash": "0x892e2dacbd0fcb787d7104b4f384e24fc4573294b75b9bfd91ca969119d8ed80",
                  "value": {
                      "amount": "1093",
                      "usd_value": "1075"
                  }
              }
          ],
          "staking_details": [
              {
                  "contract_address": "0x4846C6837ec670Bbd1f5b485471c8f64ECB9c534",
                  "pool_id": "0x1ce0c96393fa219d9776f33146e983a3e4a7d95821faca1b180ea0011d93a121",
                  "pool_name": "Tom",
                  "apr": "52.43%",
                  "adx_balance": {
                      "amount": "1093",
                      "usd_value": "1075"
                  },
                  "adx_unclaimed_balance": {
                      "amount": "19.75",
                      "usd_value": "5.24"
                  },
                  "dai_unclaimed_balance": {
                      "amount": "0.221231768887185282",
                      "usd_value": "0.221895464193846837846"
                  },
                  "adx_profit_loss": {
                      "amount": "93",
                      "usd_value": "81"
                  },
                  "dai_profit_loss": {
                      "amount": "0.22",
                      "usd_value": "0.21"
                  },
                  "total_staked_amount": "28809204.154057988204380985"
              }
          ]
      }
  },
  "message": "",
}
Response JSON Object
  • result (object) – A mapping between accounts and their events history on the AdEx pools and the staking details of the pools.

  • events (list[object]) –

    A list of all the staking events generated by the address interacting with the pools.

    • tx_hash: The transaction hash of the event.

    • timestamp: The Unix timestamp in UTC when the event happened (in seconds).

    • identity_address: The contract address associated with the user address in the platform.

    • event_type: The type of event. Can be: "deposit" (bond), "withdraw" (unbond), "withdraw request" (unbond request) and "claim" (channel withdraw).

    • value: the deposited, withdrawn or claimed ADX amount and its USD value.

    • bond_id (except claim events): The identifier of the bond, shared among deposit, withdraw and withdraw requested events that involve the same bond.

    • pool_id: The identifier of the pool.

    • pool_name: The name of the pool.

    • token (only claim events): The identifier of the tokens claimed.

  • staking_details (list[object]) –

    A list of the staking details of the staking pools the address is currently staking in.

    • contract_address: The ADX staking contract address.

    • pool_id: The identifier of the pool.

    • pool_name: The name of the pool.

    • total_staked_amount: The total amount of ADX staked in the pool.

    • adx_balance: The sum of the staked ADX plus the unclaimed ADX amount the user has in the pool, and its USD value.

    • adx_unclaimed_balance: The unclaimed ADX amount the user has in the pool and its USD value.

    • dai_unclaimed_balance: The unclaimed DAI amount the user has in the pool and its USD value.

    • apr: The current staking APR in the pool.

    • adx_profit_loss: The ADX profit/loss amount and its USD value (includes unclaimed ADX).

    • dai_profit_loss: The DAI profit/loss amount and its USD value (includes unclaimed DAI).

Status Codes
  • 200 OK – AdEx events history succesfully queried.

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

  • 500 Internal Server Error – Internal rotki error.

  • 502 Bad Gateway – An external service used in the query such as etherscan or the graph node could not be reached or returned unexpected response.

Getting Balancer balances

GET /api/(version)/blockchains/ETH/modules/balancer/balances

Doing a GET on the balancer balances resource will return the balances locked in Balancer Liquidity Pools (LPs or pools).

Note

This endpoint is only available for premium users

Note

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

Example Request:

http

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

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/ETH/modules/balancer/balances

wget

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

httpie

http http://localhost:5042/api/1/blockchains/ETH/modules/balancer/balances

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/modules/balancer/balances')
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": {
    "0x49a2DcC237a65Cc1F412ed47E0594602f6141936": [
      {
        "address": "0x1efF8aF5D577060BA4ac8A29A13525bb0Ee2A3D5",
        "tokens": [
          {
            "token": "_ceth_0xFC4B8ED459e00e5400be803A9BB3954234FD50e3",
            "total_amount": "2326.81686488",
            "user_balance": {
              "amount": "331.3943886097855861540937492",
              "usd_value": "497.0915829146783792311406238"
            },
            "usd_price": "1.5",
            "weight": "50"
          },
          {
            "token": "_ceth_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
            "total_amount": "74878.381384930530866965",
            "user_balance": {
              "amount": "10664.47290875603144268225218",
              "usd_value": "15996.70936313404716402337827"
            },
            "usd_price": "1.5",
            "weight": "50"
          }
        ],
        "total_amount": "1760.714302455317821908",
        "user_balance": {
          "amount": "250.767840213663437898",
          "usd_value": "16493.80094604872554325451889"
        }
      },
      {
        "address": "0x280267901C175565C64ACBD9A3c8F60705A72639",
        "tokens": [
          {
            "token": "_ceth_0x2ba592F78dB6436527729929AAf6c908497cB200",
            "total_amount": "3728.283461100135483274",
            "user_balance": {
              "amount": "3115.861971106915456546519315",
              "usd_value": "4673.792956660373184819778972"
            },
            "usd_price": "1.5",
            "weight": "75.0"
          },
          {
            "token": "_ceth_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
            "total_amount": "98.530639172406329742",
            "user_balance": {
              "amount": "82.34563567641578625390887189",
              "usd_value": "123.5184535146236793808633078"
            },
            "usd_price": "1.5",
            "weight": "25.0"
          }
        ],
        "total_amount": "5717.338833050074822996",
        "user_balance": {
          "amount": "4778.187826034253307037",
          "usd_value": "4797.311410174996864200642280"
        }
      },
    ],
  },
  "message": "",
}
Response JSON Object
  • result (object) – A mapping between accounts and their Balancer balances (represented by a list where each item is a LP).

  • address (string) – The LP contract address.

  • tokens (list[object]) –

    A list with the LP underlying tokens data.

    • token: the token identifier (as string). When its an object it means the token is unknown to rotki.

    • total_amount: the total amount of this token the LP has.

    • usd_price: the token USD price.

    • user_balance: the token amount of the user and its estimated USD value.

    • weight: the weight (%) that represents the token in the LP.

  • total_amount (string) – The total amount of liquidity tokens the LP has.

  • user_balance (object) – The liquidity token amount of the user balance and its estimated USD value.

Status Codes
  • 200 OK – Balancer balances succesfully queried.

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

  • 500 Internal Server Error – Internal rotki error.

  • 502 Bad Gateway – An external service used in the query such as the graph node could not be reached or returned unexpected response.

Getting Balancer events

GET /api/(version)/blockchains/ETH/modules/balancer/history/events

Doing a GET on the Balancer events history resource will return the history of all Balancer events (i.e. add and remove liquidity in the pools).

Note

This endpoint is only available for premium users

Note

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

Example Request:

http

GET /api/1/blockchains/ETH/modules/balancer/history/events HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/ETH/modules/balancer/history/events

wget

wget -S -O- http://localhost:5042/api/1/blockchains/ETH/modules/balancer/history/events

httpie

http http://localhost:5042/api/1/blockchains/ETH/modules/balancer/history/events

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/modules/balancer/history/events')
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

{
    "message": "",
    "result": {
        "0x7716a99194d758c8537F056825b75Dd0C8FDD89f": [
            {
              "pool_address": "0x59A19D8c652FA0284f44113D0ff9aBa70bd46fB4",
              "pool_tokens": [
                { "token": "_ceth_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "weight": "20" },
                { "token": "_ceth_0xba100000625a3754423978a60c9317c58a424e3D", "weight": "80" }
              ],
              "events": [
                {
                  "tx_hash": "0xb9dff9df4e3838c75d354d62c4596d94e5eb8904e07cee07a3b7ffa611c05544",
                  "log_index": 331,
                  "timestamp": 1597144247,
                  "event_type": "mint",
                  "lp_balance": {
                    "amount": "0.042569019597126949",
                    "usd_value": "19.779488662371895"
                  },
                  "amounts": {
                    "_ceth_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2": "0.05",
                    "_ceth_0xba100000625a3754423978a60c9317c58a424e3D": "0"
                  }
                },
                {
                  "tx_hash": "0xfa1dfeb83480e51a15137a93cb0eba9ac92c1b6b0ee0bd8551a422c1ed83695b",
                  "log_index": 92,
                  "timestamp": 1597243001,
                  "event_type": "burn",
                  "lp_balance": {
                    "amount": "0.042569019597126949",
                    "usd_value": "19.01364749076136579119809947"
                  },
                  "amounts": {
                    "_ceth_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2": "0.010687148200906598",
                    "_ceth_0xba100000625a3754423978a60c9317c58a424e3D": "0.744372160905819159"
                  }
                }
              ],
              "profit_loss_amounts": {
                "_ceth_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2": "-0.039312851799093402",
                "_ceth_0xba100000625a3754423978a60c9317c58a424e3D": "0.744372160905819159"
              },
              "usd_profit_loss": "-0.76584117161052920880190053"
            }
        ]
    }
}
Response JSON Object
  • result (object) – A mapping between accounts and their Balancer events history (grouped per liquidity pool).

  • address (string) – The address of the user who interacted with the pool.

  • events (list[object]) –

    A list of all the events generated by the address interacting with the pool.

    • tx_hash: The transaction hash of the event.

    • log_index: The index of the event in the transaction.

    • timestamp: The Unix timestamp in UTC when the event happened (in seconds).

    • event_type: The type of interaction, i.e. “mint” (add liquidity) and “burn” (remove liquidity).

    • amounts: A mapping between each pool token identifier and the amount added or removed on the event.

    • lp_balance: The amount of liquidity token (i.e. BPT) involved in the event and its estimated USD amount. This amount is set to zero if the endpoint is not able to get the USD value of the event token at a particular timestamp.

  • pool_address (string) – The contract address of the pool.

  • profit_loss_amounts (list[object]) – A mapping between each pool token identifier and the profit/loss amount.

  • pool_tokens (list[object]) –

    A list with the LP underlying tokens data.

    • token: the token identifier (as string). When its an object it means the token is unknown to rotki.

    • weight: the weight (%) that represents the token in the LP.

  • usd_profit_loss (string) – The total profit/loss in USD.

Status Codes
  • 200 OK – Balancer events succesfully queried.

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

  • 500 Internal Server Error – Internal rotki error.

  • 502 Bad Gateway – An external service used in the query such as the graph node could not be reached or returned unexpected response.

Getting Balancer trades

GET /api/(version)/blockchains/ETH/modules/balancer/history/trades

Doing a GET on the Balancer trades history resource will return the history of all Balancer trades.

Note

This endpoint is only available for premium users

Note

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

Example Request:

http

GET /api/1/blockchains/ETH/modules/balancer/history/trades HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/ETH/modules/balancer/history/trades

wget

wget -S -O- http://localhost:5042/api/1/blockchains/ETH/modules/balancer/history/trades

httpie

http http://localhost:5042/api/1/blockchains/ETH/modules/balancer/history/trades

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/modules/balancer/history/trades')
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": {
      "0x029f388aC4D5C8BfF490550ce0853221030E822b": [
          {
              "address": "0x029f388aC4D5C8BfF490550ce0853221030E822b",
              "amount": "0.075627332013165531",
              "base_asset": "_ceth_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
              "fee": "0",
              "fee_currency": "_ceth_0x4a220E6096B25EADb88358cb44068A3248254675",
              "location": "balancer",
              "quote_asset": "_ceth_0x4a220E6096B25EADb88358cb44068A3248254675",
              "rate": "0.02194014031410883771422129499",
              "swaps": [
                  {
                      "amount0_in": "3.446984883890308608",
                      "amount0_out": "0",
                      "amount1_in": "0",
                      "amount1_out": "0.075627332013165531",
                      "from_address": "0x0000000000007F150Bd6f54c40A34d7C3d5e9f56",
                      "log_index": 37,
                      "to_address": "0x6545773483142Fd781023EC74ee008d93aD5466B",
                      "token0": "_ceth_0x4a220E6096B25EADb88358cb44068A3248254675",
                      "token1": "_ceth_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
                      "tx_hash": "0x9a5c2c73762ef2e8af326e7b286488a4b238b9855d3fd749370bb3074aabf6e5"
                  }
              ],
              "timestamp": 1606924530,
              "trade_id": "0x9a5c2c73762ef2e8af326e7b286488a4b238b9855d3fd749370bb3074aabf6e5-0",
              "trade_type": "buy",
              "tx_hash": "0x9a5c2c73762ef2e8af326e7b286488a4b238b9855d3fd749370bb3074aabf6e5"
          },
          {
              "address": "0x029f388aC4D5C8BfF490550ce0853221030E822b",
              "amount": "3.214606868598057153",
              "base_asset": "_ceth_0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2",
              "fee": "0",
              "fee_currency": "_ceth_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
              "location": "balancer",
              "quote_asset": "_ceth_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
              "rate": "1.068431955314709719236410104",
              "swaps": [
                  {
                      "amount0_in": "3.008714642619599872",
                      "amount0_out": "0",
                      "amount1_in": "0",
                      "amount1_out": "3.214606868598057153",
                      "from_address": "0x0000000000007F150Bd6f54c40A34d7C3d5e9f56",
                      "log_index": 334,
                      "to_address": "0x987D7Cc04652710b74Fff380403f5c02f82e290a",
                      "token0": "_ceth_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
                      "token1": "_ceth_0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2",
                      "tx_hash": "0xe8f02a2c1105a0dd093d6bff6983bbc6ac662424e116fe4d53ea4f2fd4d36497"
                  }
              ],
              "timestamp": 1606921757,
              "trade_id": "0xe8f02a2c1105a0dd093d6bff6983bbc6ac662424e116fe4d53ea4f2fd4d36497-0",
              "trade_type": "buy",
              "tx_hash": "0xe8f02a2c1105a0dd093d6bff6983bbc6ac662424e116fe4d53ea4f2fd4d36497"
          }
      ]
  },
  "message": "",
}
Response JSON Object
  • result (object) – A mapping between accounts and their Balancer trades history

  • address (string) – The address of the user who initiated the trade

  • base_asset (object) – Either an identifier if it’s a known token or the address/symbol/name object for the base asset of the trade. That which is bought.

  • quote_asset (object) – Either an identifier if it’s a known token or the address/symbol/name object for the quote asset of the trade. That which is sold to buy the base asset.

  • amount (string) – In case of a trade_type buy (and for Balancer all are buys) this is the amount of "base_asset" that is bought.

  • rate (string) – How much of each quote asset was given for the base asset amount. Essentially "amount" / "rate" will give you what you paid in "quote_asset".

  • location (string) – Always balancer.

  • fee (string) – Always 0 for now.

  • fee_currency (string) – Always quote_asset.

  • timestamp (int) – The timestamp of the trade

  • trade_id (string) – A combination of transaction hash plus a unique id (for custom trades that are virtually made by us)

  • trade_type (string) – Always buy

  • tx_hash (string) – The transaction hash

  • swaps (list[object]) –

    A list of all the swaps that the trade is made of. Each swap is an object with the following attributes:

    • token0: Either an identifier if it’s a known token or the address/symbol/name object for token0 of the swap.

    • token1: Either an identifier if it’s a known token or the address/symbol/name object for token1 of the swap.

    • amount0_in: The amount (can be zero) of token0 that the user is putting in the swap.

    • amount1_in: The amount (can be zero) of token1 that the user is putting in the swap.

    • amount0_out: The amount (can be zero) of token0 that the user is getting out of the swap.

    • amount1_out: The amount (can be zero) of token1 that the user is getting out of the swap.

    • from_address: The address that is putting tokens in the swap. Can be many different parties in a multi swap.

    • to_address: The address that is getting tokens out of the swap. Can be many different parties in a multi swap.

    • address: Always the same address of the user, associated with the trade the swaps belong to.

    • location: Always balancer.

    • tx_hash: The transaction hash of the swap (always the same for swaps of the same transaction/trade).

    • log_index: The index of the swap in the transaction/trade.

Status Codes
  • 200 OK – Balancer trades succesfully queried.

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

  • 500 Internal Server Error – Internal rotki error.

  • 502 Bad Gateway – An external service used in the query such as the graph node could not be reached or returned unexpected response.

Getting Compound balances

GET /api/(version)/blockchains/ETH/modules/compound/balances

Doing a GET on the compound balances resource will return the balances that the user has locked in Compound for lending and borrowing along with their current APYs. The APYs are return in a string percentage with 2 decimals of precision. If for some reason APY can’t be queried null is returned.

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

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/ETH/modules/compound/balances

wget

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

httpie

http http://localhost:5042/api/1/blockchains/ETH/modules/compound/balances

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/modules/compound/balances')
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": {
            "rewards": {
                "_ceth_0xc00e94Cb662C3520282E6f5717214004A7f26888": {
                    "balance" :{
                        "amount": "3.5",
                        "usd_value": "892.5",
                    }
                }
            },
            "lending": {
                "_ceth_0x6B175474E89094C44Da98b954EedeAC495271d0F": {
                    "balance": {
                        "amount": "350.0",
                        "usd_value": "351.21"
                    },
                    "apy": "3.51%"
                },
                "_ceth_0xFC4B8ED459e00e5400be803A9BB3954234FD50e3": {
                    "balance": {
                        "amount": "1",
                        "usd_value": "9500"
                    },
                    "apy": null,
                },
            },
            "borrowing": {
                "ETH": {
                    "balance": {
                        "amount": "10",
                        "usd_value": "3450"
                    },
                    "apy": "7.46%"
                }
            }
        },
        "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237": {
            "lending": {},
            "borrowing": {
                "_ceth_0x0D8775F648430679A709E98d2b0Cb6250d2887EF": {
                    "balance": {
                        "amount": "560",
                        "usd_value": "156.8"
                    },
                    "apy": "7.46%"
                }
            }
        }
    },
    "message": ""
}
Response JSON Object
  • result (object) – A mapping of all accounts that currently have compound balance to the balances and APY data for each account for lending and borrowing. Each key is an asset identifier and its values are the current balance and the APY in %

Status Codes
  • 200 OK – Compound balances succesfully queried.

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

  • 500 Internal Server Error – Internal rotki error.

  • 502 Bad Gateway – An external service used in the query such as etherscan or the graph node could not be reached or returned unexpected response.

Getting compound historical data

GET /api/(version)/blockchains/ETH/modules/compound/history

Note

This endpoint is only available for premium users

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 compound balances history resource will return all compound events for all addresses who are tracked for compound.

Example Request:

http

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

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/ETH/modules/compound/history

wget

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

httpie

http http://localhost:5042/api/1/blockchains/ETH/modules/compound/history

python-requests

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

  • reset_db_data (bool) – Boolean denoting whether all compound event data saved in the DB are going to be deleted and rewritten after this query. False by default.

  • from_timestamp (int) – Timestamp from which to query compound historical data. If not given 0 is implied.

  • to_timestamp (int) – Timestamp until which to query compound historical data. If not given current timestamp is implied.

Example Response:

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

{
    "result": {
        "events": [{
            "event_type": "mint",
            "address": "0xA0B6B7fEa3a3ce3b9e6512c0c5A157a385e81056",
            "block_number": 1,
            "timestamp": 2,
            "asset": "_ceth_0x6B175474E89094C44Da98b954EedeAC495271d0F",
            "value": {
                "amount": "10.5",
                "usd_value": "10.86"
            },
            "to_asset": "_ceth_0x5d3a536E4D6DbD6114cc1Ead35777bAB948E3643",
            "to_value": {
                "amount": "165.21",
                "usd_value": "10.86"
            },
            "tx_hash": "0x988aea85b54c5b2834b144e9f7628b524bf9faf3b87821aa520b7bcfb57ab289",
            "log_index": 1
        }, {
            "event_type": "redeem",
            "address": "0xA0B6B7fEa3a3ce3b9e6512c0c5A157a385e81056",
            "block_number": 1,
            "timestamp": 2,
            "asset": "_ceth_0x5d3a536E4D6DbD6114cc1Ead35777bAB948E3643",
            "value": {
                "amount": "165.21",
                "usd_value": "12.25"
            },
            "to_asset": "_ceth_0x6B175474E89094C44Da98b954EedeAC495271d0F",
            "to_value": {
                "amount": "12.01",
                "usd_value": "12.25"
            },
            "realized_pnl": {
                "amount": "1",
                "usd_value": "1.15"
            },
            "tx_hash": "0x188aea85b54c5b2834b144e9f7628b524bf9faf3b87821aa520b7bcfb57ab289",
            "log_index": 1
        }, {
            "event_type": "borrow",
            "address": "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237",
            "block_number": 1,
            "timestamp": 2,
            "asset": "_ceth_0xE41d2489571d322189246DaFA5ebDe1F4699F498",
            "value": {
                "amount": "10",
                "usd_value": "4.5"
            },
            "tx_hash": "0x188aea85b54c5b2834b144e9f7628b524bf9faf3b87821aa520b7bcfb57ab289",
            "log_index": 1
        }, {
            "event_type": "repay",
            "address": "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237",
            "block_number": 1,
            "timestamp": 2,
            "asset": "_ceth_0xE41d2489571d322189246DaFA5ebDe1F4699F498",
            "value": {
                "amount": "10.5",
                "usd_value": "4.8"
            },
            "realized_pnl": {
                "amount": "0.5",
                "usd_value": "0.8"
            },
            "tx_hash": "0x188aea85b54c5b2834b144e9f7628b524bf9faf3b87821aa520b7bcfb57ab289",
            "log_index": 1
        }, {
            "event_type": "liquidation",
            "address": "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237",
            "block_number": 1,
            "timestamp": 2,
            "asset": "ETH",
            "value": {
                "amount": "0.00005",
                "usd_value": "0.09"
            },
            "to_asset": "_ceth_0xE41d2489571d322189246DaFA5ebDe1F4699F498",
            "to_value": {
                "amount": "10",
                "usd_value": "4.5"
            }
            "realized_pnl": null,
            "tx_hash": "0x188aea85b54c5b2834b144e9f7628b524bf9faf3b87821aa520b7bcfb57ab289",
            "log_index": 1
        }, {
            "event_type": "comp",
            "address": "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237",
            "block_number": 1,
            "timestamp": 2,
            "asset": "_ceth_0xc00e94Cb662C3520282E6f5717214004A7f26888",
            "value": {
                "amount": "1.01",
                "usd_value": "195"
            },
            "realized_pnl": {
                "amount": "1.01",
                "usd_value": "195"
            },
            "tx_hash": "0x188aea85b54c5b2834b144e9f7628b524bf9faf3b87821aa520b7bcfb57ab289",
            "log_index": 1
        }],
        "interest_profit": {
            "0xA0B6B7fEa3a3ce3b9e6512c0c5A157a385e81056": {
                "_ceth_0xc00e94Cb662C3520282E6f5717214004A7f26888": {
                        "amount": "3.5",
                        "usd_value": "892.5",
                    },
                 "_ceth_0x6B175474E89094C44Da98b954EedeAC495271d0F": {
                        "amount": "250",
                        "usd_value": "261.1",
                }
            },
            "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237": {
                "_ceth_0xE41d2489571d322189246DaFA5ebDe1F4699F498": {
                    "amount": "0.55",
                    "usd_value": "86.1"
                }
            }
         },
         "debt_loss": {
            "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237": {
                 "ETH": {
                        "amount": "0.1",
                        "usd_value": "30.5",
                }
            }
         },
         "liquidation_profit": {
            "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237": {
                 "ETH": {
                        "amount": "0.00005",
                        "usd_value": "0.023",
                }
            }
         },
         "rewards": {
            "0xA0B6B7fEa3a3ce3b9e6512c0c5A157a385e81056": {
                "_ceth_0xc00e94Cb662C3520282E6f5717214004A7f26888": {
                        "amount": "3.5",
                        "usd_value": "892.5",
                    },
            }
         }
    },
    "message": ""
}
Response JSON Object
  • events (object) – A list of mint/redeem/borrow/repay/liquidation/comp events for Compound

  • interest_profit (object) – A mapping of addresses to mappings of totals assets earned from lending over a given period

  • debt_loss (object) – A mapping of addresses to mappings of totals assets lost to repayment fees and liquidation over a given period.

  • liquidation_profit (object) – A mapping of addresses to mappings of totals assets gained thanks to liquidation repayments over a given period.

  • rewards (object) – A mapping of addresses to mappings of totals assets (only COMP atm) gained as a reward for using Compound over a given period.

Response JSON Array of Objects
  • event_type (string) – The type of the compound event. Can be: - "mint": if depositing a token which mints a cToken equivalent. - "redeem": if redeeming a cToken for the underlying normal equivalent - "borrow": if you are borrowing an asset from compound - "repay": if you are repaying an asset borrowed from compound - "liquidation": if your borrowing position got liquidated - "comp": if this is a comp earning reward

  • address (string) – The address of the account involved in the event

  • timestamp (int) – The unix timestamp at which the event occured.

  • block_number (int) – The block number at which the event occured.

  • asset (string) – The asset involved in the event. - For "mint" events this is the underlying asset. - For "redeem" events this is the cToken. - For "borrow" and "repay" events this is the borrowed asset - For "liquidation" events this is the part of the debt that was repaid by the liquidator. - For "comp" events this the COMP token.

  • value (object) – The value of the asset for the event. The rate is the asset/USD rate at the events’s timestamp.

  • to_asset (string) – [Optional] The target asset involved in the event. - For "mint" events this is the cToken. - For "redeem" events this is the underlying asset. - For "borrow" and "repay" this is missing. - For "liquidation" events this is asset lost to the liquidator.

  • to_value (object) – [Optional] The value of the to_asset for the event. The rate is the asset/USD rate at the events’s timestamp.

  • realized_pnl (object) – [Optional]. Realized profit/loss at this event if any. - For "redeem" events this can be the realized profit from compound interest at this event. Amount is for the normal token. - For "repay" events this can be the realized loss from compound debt up to this point. Amount is for the borrowed asset. - For "comp" events this is the gain in COMP.

  • tx_hash (int) – The transaction hash of the event.

  • log_index (int) – The log index of the event.

Status Codes
  • 200 OK – Compound history succesfully queried.

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

  • 500 Internal Server Error – Internal rotki error.

  • 502 Bad Gateway – An external service used in the query such as etherscan or the graph node could not be reached or returned unexpected response.

Getting Liquity balances

GET /api/(version)/blockchains/ETH/modules/liquity/balances

Doing a GET on the liquity balances resource will return the balances that the user has in troves.

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 will provide different information if called with a premium account or not. With premium accounts information about staking is provided.

Example Request:

http

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

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/ETH/modules/liquity/balances

wget

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

httpie

http http://localhost:5042/api/1/blockchains/ETH/modules/liquity/balances

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/modules/liquity/balances')
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": {
      "0x063c26fF1592688B73d8e2A18BA4C23654e2792E": {
          "collateral": {
              "asset": "ETH"
              "amount": "5.3100000000000005",
              "usd_value": "16161.675300000001521815"
          },
          "debt": {
              "asset": "_ceth_0x5f98805A4E8be255a32880FDeC7F6728C6568bA0"
              "amount": "6029.001719188487",
              "usd_value": "6089.29173638037187"
          },
          "collateralization_ratio": "268.0655281381374051287323733",
          "liquidation_price": "1261.435199626818912670885158",
          "active": true,
          "trove_id": 148
      }
    },
    "message": ""
}
Response JSON Object
  • result (object) – A mapping of all accounts that currently have Liquity positions to trove information.

Status Codes
  • 200 OK – Liquity balances succesfully queried.

  • 409 Conflict – User is not logged in or Liquity 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 Liquity staked amount

GET /api/(version)/blockchains/ETH/modules/liquity/staking

Doing a GET on the liquity balances resource will return the balances that the user has staked.

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 requires a premium account.

Example Request:

http

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

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/ETH/modules/liquity/staking

wget

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

httpie

http http://localhost:5042/api/1/blockchains/ETH/modules/liquity/staking

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/modules/liquity/staking')
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": {
      "0x063c26fF1592688B73d8e2A18BA4C23654e2792E": {
          "asset": "_ceth_0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D"
          "amount": "177.02",
          "usd_value": "265.530"
      }
    },
    "message": ""
}
Response JSON Object
  • result (object) – A mapping of the amount and value of LQTY staked in the protocol.

Status Codes
  • 200 OK – Liquity staking information succesfully queried.

  • 409 Conflict – User is not logged in or Liquity 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 Liquity historical trove data

GET /api/(version)/blockchains/ETH/modules/liquity/events/trove

Note

This endpoint is only available for premium users

Doing a GET on the liquity events resource will return the history of deposits, withdrawals, liquidations and trove events of each account in Liquity.

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

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/ETH/modules/liquity/events/

wget

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

httpie

http http://localhost:5042/api/1/blockchains/ETH/modules/liquity/events/

python-requests

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

  • reset_db_data (bool) – Boolean denoting whether all liquity event data saved in the DB are going to be deleted and rewritten after this query. False by default.

Example Response:

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

{
    "result": {
          "0x063c26fF1592688B73d8e2A18BA4C23654e2792E": [
                  {
                      "kind": "trove",
                      "tx": "0xc8ad6f6ec244a93e1d66e60d1eab2ff2cb9de1f3a1f45c7bb4e9d2f720254137",
                      "address": "0x063c26fF1592688B73d8e2A18BA4C23654e2792E",
                      "timestamp": 1627818194,
                      "debt_after": {
                          "amount": "6029.001719188487125",
                          "usd_value": "6149.58175357225686750",
                          "asset": "_ceth_0x5f98805A4E8be255a32880FDeC7F6728C6568bA0"
                      },
                      "debt_delta": {
                          "amount": "6029.001719188487125",
                          "usd_value": "6149.58175357225686750",
                          "asset": "_ceth_0x5f98805A4E8be255a32880FDeC7F6728C6568bA0"
                      },
                      "collateral_after": {
                          "amount": "3.5",
                          "usd_value": "10500.0",
                          "asset": "ETH"
                      },
                      "collateral_delta": {
                          "amount": "3.5",
                          "usd_value": "10500.0",
                          "asset": "ETH"
                      },
                      "trove_operation": "Open Trove",
                      "sequence_number": "51647"
                  },
                  {
                      "kind": "trove",
                      "tx": "0x8c875e36737918807af1616cc89a084971a569f33006acba308897a80554983a",
                      "address": "0x063c26fF1592688B73d8e2A18BA4C23654e2792E",
                      "timestamp": 1627818617,
                      "debt_after": {
                          "amount": "6029.001719188487125",
                          "usd_value": "6143.552751853068380375",
                          "asset": "_ceth_0x5f98805A4E8be255a32880FDeC7F6728C6568bA0"
                      },
                      "debt_delta": {
                          "amount": "0",
                          "usd_value": "0.000",
                          "asset": "_ceth_0x5f98805A4E8be255a32880FDeC7F6728C6568bA0"
                      },
                      "collateral_after": {
                          "amount": "5.31",
                          "usd_value": "15930.00",
                          "asset": "ETH"
                      },
                      "collateral_delta": {
                          "amount": "1.81",
                          "usd_value": "5430.00",
                          "asset": "ETH"
                      },
                      "trove_operation": "Adjust Trove",
                      "sequence_number": "51747"
                  }
              ]
              "stake": [
                  {
                      "kind": "stake",
                      "tx": "0xe527749c76a3af56d86c97a8f8f8ce07e191721e9e16a0f62a228f8a8ef6d295",
                      "address": "0x063c26fF1592688B73d8e2A18BA4C23654e2792E",
                      "timestamp": 1627827057,
                      "stake_after": {
                          "amount": "177.02",
                          "usd_value": "654.974",
                          "asset": "_ceth_0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D"
                      },
                      "stake_change": {
                          "amount": "177.02",
                          "usd_value": "654.974",
                          "asset": "_ceth_0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D"
                      },
                      "issuance_gain": {
                          "amount": "0",
                          "usd_value": "0.00",
                          "asset": "_ceth_0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D"
                      },
                      "redemption_gain": {
                          "amount": "0",
                          "usd_value": "0.00",
                          "asset": "_ceth_0x5f98805A4E8be255a32880FDeC7F6728C6568bA0"
                      },
                      "stake_operation": "Stake Created",
                      "sequence_number": "51676"
                  }
              ]
          }
      }
    },
    "message": ""
}
Response JSON Object
  • result (object) – A mapping of accounts to the Liquity history report of each account. If an account is not in the mapping rotki does not see anything ever deposited in Liquity for it.

  • kind (string) – “trove” if it’s an action in troves and “stake” if it’s a change in the staking position

  • timestamp (int) – The unix timestamp at which the event occured.

  • tx (string) – The transaction hash of the event.

  • debt_after (object) – Debt in the Trove after the operation

  • collateral_after (object) – Amount, asset and usd value of collateral at the Trove

  • debt_delta (object) – Amount, asset and usd value of debt that the operation changed.

  • collateral_delta (object) – Amount, asset and usd value of collateral that the operation changed.

  • trove_operation (string) – The operation that happened in the change. Can be Open Trove, Close Trove, Adjust Trove, Accrue Rewards, Liquidation In Normal Mode, Liquidation In Recovery Mode, Redeem Collateral

Status Codes
  • 200 OK – Liquity history succesfully queried.

  • 409 Conflict – No user is currently logged in or currently logged in user does not have a premium subscription. Or Liquity 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 Liquity historical staking data

GET /api/(version)/blockchains/ETH/modules/liquity/events/staking

Note

This endpoint is only available for premium users

Doing a GET on the liquity events resource will return the history for staking events.

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

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/ETH/modules/liquity/events/

wget

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

httpie

http http://localhost:5042/api/1/blockchains/ETH/modules/liquity/events/

python-requests

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

  • reset_db_data (bool) – Boolean denoting whether all liquity event data saved in the DB are going to be deleted and rewritten after this query. False by default.

Example Response:

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

{
    "result": {
          "0x063c26fF1592688B73d8e2A18BA4C23654e2792E": [
              {
                  "kind": "stake",
                  "tx": "0xe527749c76a3af56d86c97a8f8f8ce07e191721e9e16a0f62a228f8a8ef6d295",
                  "address": "0x063c26fF1592688B73d8e2A18BA4C23654e2792E",
                  "timestamp": 1627827057,
                  "stake_after": {
                      "amount": "177.02",
                      "usd_value": "654.974",
                      "asset": "_ceth_0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D"
                  },
                  "stake_change": {
                      "amount": "177.02",
                      "usd_value": "654.974",
                      "asset": "_ceth_0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D"
                  },
                  "issuance_gain": {
                      "amount": "0",
                      "usd_value": "0.00",
                      "asset": "_ceth_0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D"
                  },
                  "redemption_gain": {
                      "amount": "0",
                      "usd_value": "0.00",
                      "asset": "_ceth_0x5f98805A4E8be255a32880FDeC7F6728C6568bA0"
                  },
                  "stake_operation": "Stake Created",
                  "sequence_number": "51676"
              }
          ]
    },
    "message": ""
}
Response JSON Object
  • result (object) – A mapping of accounts to the Liquity history report of each account. If an account is not in the mapping rotki does not see anything ever deposited in Liquity for it.

  • kind (string) – “trove” if it’s an action in troves and “stake” if it’s a change in the staking position

  • timestamp (int) – The unix timestamp at which the event occured.

  • tx (string) – The transaction hash of the event.

  • stake_after (string) – Amount, asset and usd value changed in the operation over the staked position. Amount is represented in LQTY

  • stake_change (string) – Amount, asset and usd value that the operation changed

  • stake_operation (string) – Can be Stake Created, Stake Increased, Stake Decreased, Stake Removed, Gains Withdrawn

Status Codes
  • 200 OK – Liquity history succesfully queried.

  • 409 Conflict – No user is currently logged in or currently logged in user does not have a premium subscription. Or Liquity 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 Uniswap balances

GET /api/(version)/blockchains/ETH/modules/uniswap/balances

Doing a GET on the uniswap balances resource will return the balances locked in Uniswap Liquidity Pools (LPs or pools).

Note

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

Example Request:

http

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

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/ETH/modules/uniswap/balances

wget

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

httpie

http http://localhost:5042/api/1/blockchains/ETH/modules/uniswap/balances

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/modules/uniswap/balances')
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": {
    "0xcf2B8EeC2A9cE682822b252a1e9B78EedebEFB02": [
      {
        "address": "0x318BE2AA088FFb991e3F6E61AFb276744e36F4Ae",
        "assets": [
          {
            "asset": {
              "ethereum_address": "0x364A7381A5b378CeD7AB33d1CDf6ff1bf162Bfd6",
              "name": "DeFi-X Token",
              "symbol": "TGX"
            },
            "total_amount": "9588317.030426553444567747",
            "usd_price": "0.3015901111469715543448531276626107",
            "user_balance": {
              "amount": "4424094.631122964837017895643",
              "usd_value": "1334263.191525095084350185834"
            }
          },
          {
            "asset": "_ceth_0xdAC17F958D2ee523a2206206994597C13D831ec7",
            "total_amount": "2897321.681999",
            "usd_price": "1.001",
            "user_balance": {
              "amount": "1336837.868136041506994516873",
              "usd_value": "1338174.706004177548501511390"
            }
          }
        ],
        "total_supply": "5.255427314262137581",
        "user_balance": {
          "amount": "2.424878911648769806",
          "usd_value": "2672437.897529272632851697224"
        }
      }
    ],
  },
  "message": "",
}
Response JSON Object
  • result (object) – A mapping between accounts and their Uniswap balances (represented by a list where each item is a LP).

  • address (string) – The LP contract address.

  • assets (list[object]) – A list with the LP underlying tokens data. Per item, when "asset" is an object, it means the token is unknown to rotki. "total_amount" is the total amount of this token the pool has. "total_amount" is only available to premium users. For free users null is returned. "usd_price" is the token USD price. "user_balance" contains the user token balance and its estimated USD value.

  • total_supply (optional[string]) – The total amount of liquidity tokens the LP has. Only available for premium users via the graph query. For free users null is returned.

  • user_balance (object) – The liquidity token user balance and its USD value.

Status Codes
  • 200 OK – Uniswap balances succesfully queried.

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

  • 500 Internal Server Error – Internal rotki error.

  • 502 Bad Gateway – An external service used in the query such as etherscan or the graph node could not be reached or returned unexpected response.

Getting Uniswap events

GET /api/(version)/blockchains/ETH/modules/uniswap/history/events

Doing a GET on the uniswap events history resource will return the history of all uniswap events (i.e. add and remove liquidity in the pools).

Note

This endpoint is only available for premium users

Note

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

Example Request:

http

GET /api/1/blockchains/ETH/modules/uniswap/history/events HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/ETH/modules/uniswap/history/events

wget

wget -S -O- http://localhost:5042/api/1/blockchains/ETH/modules/uniswap/history/events

httpie

http http://localhost:5042/api/1/blockchains/ETH/modules/uniswap/history/events

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/modules/uniswap/history/events')
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

{
    "message": "",
    "result": {
        "0x6C0F75eb3D69B9Ea2fB88dbC37fc086a12bBC93F": [
            {
                "address": "0x6C0F75eb3D69B9Ea2fB88dbC37fc086a12bBC93F",
                "events": [
                    {
                        "amount0": "953.198109979915172437",
                        "amount1": "720.804729278838558402",
                        "event_type": "mint",
                        "log_index": 232,
                        "lp_amount": "190.200269390899700166",
                        "timestamp": 1597412453,
                        "tx_hash": "0x95c31c24811aa89890f586455230a21b5e6805571291c41f2429c0b27ffa6494",
                        "usd_price": "1498.982998827867862380542829830168"
                    },
                    {
                        "amount0": "689.108242482979840535",
                        "amount1": "632.127650995837381138",
                        "event_type": "burn",
                        "log_index": 100,
                        "lp_amount": "190.200269390899700166",
                        "timestamp": 1597906014,
                        "tx_hash": "0xf5c8fb7369d00f306c615d664021de2b0498e74edc538f7767c66f477adaeec5",
                        "usd_price": "1336.795325171526015938992923665357"
                    }
                ],
                "pool_address": "0x2C7a51A357d5739C5C74Bf3C96816849d2c9F726",
                "profit_loss0": "264.089867496935331902",
                "profit_loss1": "88.677078283001177264",
                "token0": "_ceth_0x0e2298E3B3390e3b945a5456fBf59eCc3f55DA16",
                "token1": "_ceth_0xdF5e0e81Dff6FAF3A7e52BA697820c5e32D806A8",
                "usd_profit_loss": "162.1876736563418464415499063"
            }
        ]
    }
}
Response JSON Object
  • result (object) – A mapping between accounts and their Uniswap events history (grouped per liquidity pool)

  • address (string) – The address of the user who interacted with the pool

  • events (list[object]) –

    A list of all the events generated by the address interacting with the pool

    • event_type: The type of interaction, i.e. “mint” (add liquidity) and “burn” (remove liquidity).

    • amount0: The amount of token0 involved in the event.

    • amount1: The amount of token1 involved in the event.

    • lp_amount: The amount of liquidity token (i.e. UNI-V2) involved in the event.

    • usd_price: The USD amount involved in the event.

    • log_index: The index of the event in the transaction.

    • tx_hash: The transaction hash of the event.

    • timestamp: The Unix timestamp in UTC when the event happened (in seconds).

  • pool_address (string) – The contract address of the pool.

  • profit_loss0 (string) – The token0 profit/loss.

  • profit_loss1 (string) – The token1 profit/loss.

  • token0 (object) – The pool’s pair left token identifier

  • token1 (object) – The pool’s pair right token identifier.

  • usd_profit_loss (string) – The total profit/loss in USD.

Status Codes
  • 200 OK – Uniswap events succesfully queried.

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

  • 500 Internal Server Error – Internal rotki error.

  • 502 Bad Gateway – An external service used in the query such as etherscan or the graph node could not be reached or returned unexpected response.

Getting Uniswap trades

GET /api/(version)/blockchains/ETH/modules/uniswap/history/trades

Doing a GET on the uniswap trades history resource will return the history of all uniswap trades.

Note

This endpoint is only available for premium users

Note

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

Example Request:

http

GET /api/1/blockchains/ETH/modules/uniswap/history/trades HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/ETH/modules/uniswap/history/trades

wget

wget -S -O- http://localhost:5042/api/1/blockchains/ETH/modules/uniswap/history/trades

httpie

http http://localhost:5042/api/1/blockchains/ETH/modules/uniswap/history/trades

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/modules/uniswap/history/trades')
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": {
    "0x21d05071cA08593e13cd3aFD0b4869537e015C92": [{
        "address": "0x21d05071cA08593e13cd3aFD0b4869537e015C92",
        "amount": "1411.453463704718081611",
        "base_asset": "_ceth_0x6B175474E89094C44Da98b954EedeAC495271d0F",
        "fee": "0",
        "fee_currency": "_ceth_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "location": "uniswap",
        "quote_asset": "_ceth_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "rate": "371.4351220275573898976315789",
        "swaps": [{
            "amount0_in": "0",
            "amount0_out": "1411.453463704718081611",
            "amount1_in": "3.8",
            "amount1_out": "0",
            "from_address": "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D",
            "log_index": 90,
            "to_address": "0x21d05071cA08593e13cd3aFD0b4869537e015C92",
            "token0": "_ceth_0x6B175474E89094C44Da98b954EedeAC495271d0F",
            "token1": "_ceth_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
            "tx_hash": "0xf6272151d26f391886232263a384d1d9fb84c54e33119d014bc0b556dc27e900"}],
        "timestamp": 1603056982,
        "trade_id": "0xf6272151d26f391886232263a384d1d9fb84c54e33119d014bc0b556dc27e900-0",
        "trade_type": "buy",
        "tx_hash": "0xf6272151d26f391886232263a384d1d9fb84c54e33119d014bc0b556dc27e900"}, {
        "address": "0x21d05071cA08593e13cd3aFD0b4869537e015C92",
        "amount": "904.171423330858608178",
        "base_asset": "_ceth_0x6B175474E89094C44Da98b954EedeAC495271d0F",
        "fee": "0",
        "fee_currency": "ALEPH",
        "location": "uniswap",
        "quote_asset": "_ceth_0x27702a26126e0B3702af63Ee09aC4d1A084EF628",
        "rate": "0.1604821621994156262081817395",
        "swaps": [{
            "amount0_in": "5634.092979176915803392",
            "amount0_out": "0",
            "amount1_in": "0",
            "amount1_out": "2.411679959413889526",
            "from_address": "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D",
            "log_index": 98,
            "to_address": "0xA478c2975Ab1Ea89e8196811F51A7B7Ade33eB11",
            "token0": "_ceth_0x27702a26126e0B3702af63Ee09aC4d1A084EF628",
            "token1": "_ceth_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
            "tx_hash": "0x296c750be451687a6e95de55a85c1b86182e44138902599fb277990447d5ded6"}, {
            "amount0_in": "0",
            "amount0_out": "904.171423330858608178",
            "amount1_in": "2.411679959413889526",
            "amount1_out": "0",
            "from_address": "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D",
            "log_index": 101,
            "to_address": "0x21d05071cA08593e13cd3aFD0b4869537e015C92",
            "token0": "_ceth_0x6B175474E89094C44Da98b954EedeAC495271d0F",
            "token1": "_ceth_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
            "tx_hash": "0x296c750be451687a6e95de55a85c1b86182e44138902599fb277990447d5ded6"}],
        "timestamp": 1602796833,
        "trade_id": "0x296c750be451687a6e95de55a85c1b86182e44138902599fb277990447d5ded6-0",
        "trade_type": "buy",
        "tx_hash": "0x296c750be451687a6e95de55a85c1b86182e44138902599fb277990447d5ded6"}
    ],
  },
  "message": "",
}
Response JSON Object
  • result (object) – A mapping between accounts and their Uniswap trades history

  • address (string) – The address of the user who initiated the trade

  • base_asset (object) – Either an identifier if it’s a known token or the address/symbol/name object for the base asset of the trade. That which is bought.

  • quote_asset (object) – Either an identifier if it’s a known token or the address/symbol/name object for the quote asset of the trade. That which is sold to buy the base asset.

  • amount (string) – In case of a trade_type buy (and for uniswap all are buys) this is the amount of "base_asset" that is bought.

  • rate (string) – How much of each quote asset was given for the base asset amount. Essentially &q