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

Note

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

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",
      "sync_database": true,
      "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", "sync_database": true}'

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", "sync_database": true}'

httpie

echo '{
  "initial_settings": {
    "submit_usage_analytics": false
  },
  "name": "john",
  "password": "supersecurepassword",
  "premium_api_key": "dasdsda",
  "premium_api_secret": "adsadasd",
  "sync_database": true
}' | 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', 'sync_database': True})
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.

  • sync_database (bool[optional]) – If set to true rotki will try to download a remote database for premium users if there is any.

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

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,
            "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"],
            "ssf_graph_multiplier": 2,
            "non_sync_exchanges": [{"location": "binance", "name": "binance1"}]
        }
    },
    "message": ""
}
Response JSON Object:

  • result (object) – For successful 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 successful

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

  • 409 Conflict – Another user is already logged in. User already exists. 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

POST /api/(version)/users/(username)

By doing a POST at this endpoint, you can login to the user with username.

Note

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

Example Request:

http

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

{
    "password": "supersecurepassword",
    "sync_approval": "unknown",
    "resume_from_backup": false
}

curl

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

wget

wget -S -O- http://localhost:5042/api/1/users/john --header="Content-Type: application/json;charset=UTF-8" --post-data='{"password": "supersecurepassword", "resume_from_backup": false, "sync_approval": "unknown"}'

httpie

echo '{
  "password": "supersecurepassword",
  "resume_from_backup": false,
  "sync_approval": "unknown"
}' | http POST http://localhost:5042/api/1/users/john Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/users/john', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'password': 'supersecurepassword', 'resume_from_backup': False, 'sync_approval': 'unknown'})
Request JSON Object:

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

  • resume_from_backup (bool) – An optional boolean denoting if the user approved a resume from backup. This is used to handle the case where the encrypted user database is in a semi upgraded state during user login. If not given, the value defaults to false so if a semi upgraded database exists during login, the consumer of the api will receive a response with a status ‘300 Multiple Choices’, an explanatory message and an empty result. If the value is true then the latest backup will be used and the login will proceed as usual.

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,
            "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"],
            "ssf_graph_multiplier": 2,
            "non_sync_exchanges": [{"location": "binance", "name": "binance1"}]
        }
    },
    "message": ""
}
Response JSON Object:

  • result (object) – For successful 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 successfully

  • 300 Multiple Choices –

    This would be the response status in the following two cases:

    • There is an unfinished upgrade to the encrypted user database, and the login was sent with resume_from_backup set to false. The consumer of the api can resend with resume_from_backup set to true, so that the user will login using the latest backup of the encrypted database. In this case the response will contain an empty result key and an explanatory message on the message key.

    • 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 – User does not exist. Another user is already logged in. 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 – Generic internal rotki error

  • 542 – Internal rotki error relating to the database. Check message for more details.

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 "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":{
         "eth": {"api_key":"key1"},
         "arbitrum_one": {"api_key":"key3"}
      },
      "cryptocompare": {"api_key":"boooookey"},
      "opensea": {"api_key":"goooookey"},
      "monerium": {"username":"Ben", "password":"secure"}
   },
   "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"}. For etherscan services all are grouped under the etherscan key. If there are no etherscan services this key won’t be present. The monerium service has a different structure than the rest. Has username and password keys.

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.

Some credentials like monerium can’t be input if the user is not premium.

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", "beaconchain", "loopring", "opensea", blockscout, monerium.

  • api_key (string[optional]) – Each entry in the list should have an api_key entry except for monerium.

  • username (string[optional]) – The monerium entry should have a username key. For monerium the user should have premium.

  • password (string[optional]) – The monerium entry should have a password key. For monerium the user should have premium.

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.

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.

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,
        "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"],
        "ssf_graph_multiplier": 2,
        "non_sync_exchanges": [{"location": "binance", "name": "binance1"}],
        "cost_basis_method": "fifo",
        "oracle_penalty_threshold_count": 5,
        "oracle_penalty_duration": 1800,
        "address_name_priority": ["private_addressbook", "blockchain_account",
                                  "global_addressbook", "ethereum_tokens",
                                  "hardcoded_mappings", "ens_names"],
    },
    "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.

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

  • ssf_graph_multiplier (int) – A multiplier to the snapshot saving frequency for zero 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.

  • cost_basis_method (string) – Defines which method to use during the cost basis calculation. Currently supported: fifo, lifo.

  • address_name_priority (string) – Defines the priority to search for address names. From first to last location in this array, the first name found will be displayed.

  • infer_zero_timed_balances (bool) – A boolean denoting whether to infer zero timed balances for assets that have no balance at a specific time. This is useful for showing zero balance periods in graphs.

  • query_retry_limit (int) – The number of times to retry a query to external services before giving up. Default is 5.

  • connect_timeout (int) – The number of seconds to wait before giving up on establishing a connection to an external service. Default is 30.

  • read_timeout (int) – The number of seconds to wait for the first byte after a connection to an external service has been established. Default is 30.

  • oracle_penalty_threshold_count (int) – The number of failures after which an oracle is penalized. Default is 5.

  • oracle_penalty_duration (int) – The duration in seconds for which an oracle is penalized. Default is 1800.

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.

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

  • beacon_rpc_endpoint (string[optional]) – A URL denoting the rpc endpoint for the ethereum consensus layer beacon node to use when contacting the consensus layer. If it can not be reached or if it is invalid beaconcha.in is used.

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

  • non_syncing_exchanges (list) – A list of objects with the keys name and location of the exchange. These exchanges will be ignored when querying the trades. Example: [{"name": "my_exchange", "location": "binance"}].

Response JSON Object:

  • ssf_graph_multiplier (int) – A multiplier to the snapshot saving frequency for zero 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.

  • infer_zero_timed_balances (bool) – A boolean denoting whether to infer zero timed balances for assets that have no balance at a specific time. This is useful for showing zero balance periods in graphs.

  • query_retry_limit (int) – The number of times to retry a query to external services before giving up. Default is 5.

  • connect_timeout (int) – The number of seconds to wait before giving up on establishing a connection to an external service. Default is 30.

  • read_timeout (int) – The number of seconds to wait for the first byte after a connection to an external service has been established. Default is 30.

  • oracle_penalty_threshold_count (int) – The number of failures after which an oracle is penalized. Default is 5.

  • oracle_penalty_duration (int) – The duration in seconds for which an oracle is penalized. Default is 1800.

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,
        "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"],
        "ssf_graph_multiplier": 2,
        "non_sync_exchanges": [{"location": "binance", "name": "binance1"}]
    },
    "message": ""
}
Response JSON Object:

  • result (object) – Same as when doing GET on the settings

Status Codes:

Getting backend arguments

GET /api/(version)/settings/configuration

By doing a GET, you can retrieve the parameters used to initialize the backend.

Example Request:

http

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

curl

curl -i -X GET http://localhost:5042/api/1/settings/configuration -H "Content-Type: application/json"

wget

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

httpie

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

python-requests

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

Example Response:

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

{
     "result": {
             "max_size_in_mb_all_logs": {
                     "value": 300,
                     "is_default": true
             },
             "max_logfiles_num": {
                     "value": 3,
                     "is_default": true
             },
             "sqlite_instructions": {
                     "value": 5000,
                     "is_default": true
             }
     },
     "message": ""
 }
Response JSON Object:

  • max_size_in_mb_all_logs (object) – Maximum size in megabytes that will be used for all rotki logs.

  • max_num_log_files (object) – Maximum number of logfiles to keep.

  • sqlite_instructions (object) – Instructions per sqlite context switch. 0 means disabled.

  • value (int) – Value used for the configuration.

  • is_default (bool) – true if the setting was not modified and false if it was.

Status Codes:

Adding information for web3 nodes

GET /api/(version)/blockchains/(blockchain)/nodes

By querying this endpoint the information for the nodes in the database will be returned

Example Request:

http

GET /api/1/blockchains/eth/nodes HTTP/1.1
Host: localhost:5042

curl

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

wget

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

httpie

http http://localhost:5042/api/1/blockchains/eth/nodes

python-requests

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

Example Response:

The following is an example response of querying Ethereum nodes information.

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

{
  "result": [
      {
          "identifier": 1,
          "name": "etherscan",
          "endpoint": "",
          "owned": false,
          "weight": "40.00",
          "active": true,
          "blockchain": "eth"
      },
      {
          "identifier": 2,
          "name": "mycrypto",
          "endpoint": "https://api.mycryptoapi.com/eth",
          "owned": false,
          "weight": "20.00",
          "active": true,
          "blockchain": "eth"
      },
      {
          "identifier": 3,
          "name": "blockscout",
          "endpoint": "https://mainnet-nethermind.blockscout.com/",
          "owned": false,
          "weight": "20.00",
          "active": true,
          "blockchain": "eth"
      },
      {
          "identifier": 4,
          "name": "avado pool",
          "endpoint": "https://mainnet.eth.cloud.ava.do/",
          "owned": false,
          "weight": "20.00",
          "active": true,
          "blockchain": "eth"
      }
  ],
  "message": ""
}
Response JSON Object:

  • result (list) – A list with information about the web3 nodes.

  • name (string) – Name and primary key of the node.

  • endpoint (string) – rpc endpoint of the node. Will be used to query it.

  • weight (string) – Weight of the node in the range of 0 to 100 with 2 decimals.

  • owned (string) – True if the user owns the node or false if is a public node.

  • active (string) – True if the node should be used or false if it shouldn’t.

Status Codes:
PUT /api/(version)/blockchains/(blockchain)/nodes

By doing a PUT on this endpoint you will be able to add a new node to the list of nodes.

Example Request:

http

PUT /api/1/blockchains/eth/nodes HTTP/1.1
Host: localhost:5042
Content-Type: application/json

{
  "name": "my_node",
  "endpoint": "http://localhost:8385",
  "owned": true,
  "weight": "40.30",
  "active": true
}

curl

curl -i -X PUT http://localhost:5042/api/1/blockchains/eth/nodes -H "Content-Type: application/json" --data-raw '{"active": true, "endpoint": "http://localhost:8385", "name": "my_node", "owned": true, "weight": "40.30"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/blockchains/eth/nodes --header="Content-Type: application/json" --body-data='{"active": true, "endpoint": "http://localhost:8385", "name": "my_node", "owned": true, "weight": "40.30"}'

httpie

echo '{
  "active": true,
  "endpoint": "http://localhost:8385",
  "name": "my_node",
  "owned": true,
  "weight": "40.30"
}' | http PUT http://localhost:5042/api/1/blockchains/eth/nodes Content-Type:application/json

python-requests

requests.put('http://localhost:5042/api/1/blockchains/eth/nodes', headers={'Content-Type': 'application/json'}, json={'active': True, 'endpoint': 'http://localhost:8385', 'name': 'my_node', 'owned': True, 'weight': '40.30'})
Response JSON Object:

  • name (string) – Name and primary key of the node. This field has to be unique. This field cannot be empty or use the key etherscan.

  • endpoint (string) – rpc endpoint of the node. Will be used to query it.

  • owned (string) – True if the user owns the node or false if is a public node.

  • weight (string) – Weight of the node in the range of 0 to 100 with 2 decimals.

  • active (string) – True if the node should be used or false if it shouldn’t.

Status Codes:
PATCH /api/(version)/blockchains/(blockchain)/nodes

By doing a PATCH on this endpoint you will be able to edit an already existing node entry with the information provided.

Example Request:

http

PATCH /api/1/blockchains/eth/nodes HTTP/1.1
Host: localhost:5042
Content-Type: application/json

{
  "identifier": 8,
  "name": "my_node",
  "endpoint": "http://localhost:8386",
  "owned": true,
  "weight": 80,
  "active": false
}

curl

curl -i -X PATCH http://localhost:5042/api/1/blockchains/eth/nodes -H "Content-Type: application/json" --data-raw '{"active": false, "endpoint": "http://localhost:8386", "identifier": 8, "name": "my_node", "owned": true, "weight": 80}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/blockchains/eth/nodes --header="Content-Type: application/json" --body-data='{"active": false, "endpoint": "http://localhost:8386", "identifier": 8, "name": "my_node", "owned": true, "weight": 80}'

httpie

echo '{
  "active": false,
  "endpoint": "http://localhost:8386",
  "identifier": 8,
  "name": "my_node",
  "owned": true,
  "weight": 80
}' | http PATCH http://localhost:5042/api/1/blockchains/eth/nodes Content-Type:application/json

python-requests

requests.patch('http://localhost:5042/api/1/blockchains/eth/nodes', headers={'Content-Type': 'application/json'}, json={'active': False, 'endpoint': 'http://localhost:8386', 'identifier': 8, 'name': 'my_node', 'owned': True, 'weight': 80})
Response JSON Object:

  • identifier (int) – Id of the node that will be edited.

  • name (string) – Name of the node that will be edited.

  • endpoint (string) – rpc endpoint of the node. Will be used to query it.

  • owned (string) – True if the user owns the node or false if is a public node.

  • weight (string) – Weight of the node in the range of 0 to 100 with 2 decimals.

  • active (string) – True if the node should be used or false if it shouldn’t.

Status Codes:
DELETE /api/(version)/blockchains/(blockchain)/nodes

By doing a DELETE on this endpoint you will be able to delete an already existing node.

Example Request:

http

PUT /api/1/blockchains/eth/nodes HTTP/1.1
Host: localhost:5042
Content-Type: application/json

{
  "identifier": 8
}

curl

curl -i -X PUT http://localhost:5042/api/1/blockchains/eth/nodes -H "Content-Type: application/json" --data-raw '{"identifier": 8}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/blockchains/eth/nodes --header="Content-Type: application/json" --body-data='{"identifier": 8}'

httpie

echo '{
  "identifier": 8
}' | http PUT http://localhost:5042/api/1/blockchains/eth/nodes Content-Type:application/json

python-requests

requests.put('http://localhost:5042/api/1/blockchains/eth/nodes', headers={'Content-Type': 'application/json'}, json={'identifier': 8})
Response JSON Object:

  • identifier (int) – Id of the node that will be deleted.

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:

Cancel ongoing async tasks

DELETE /api/(version)/tasks/(task_id)

By calling this endpoint with a particular task identifier you can cancel the ongoing task with that identifier. Keep in mind that this may leave stuff half-finished since the canceled task may be stopped in the middle.

Example Request:

http

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

curl

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

wget

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

httpie

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

python-requests

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

Example Response:

The following is an example response of a succesfully canceled task

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

{
    "result": true, "message": ""
}
Response JSON Object:

  • result (bool) – True if the task was canceled and false otherwise.

Status Codes:

Query the latest price of assets

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

Querying this endpoint with a list of assets and a target asset will return a mapping of assets to their prices in the target asset and an integer representing the oracle the price was gotten from. 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/latest HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{
    "assets": ["BTC", "ETH", "eip155:1/erc20:0x514910771AF9Ca656af840dff83E8264EcF986CA", "USD", "EUR"],
    "target_asset": "USD",
    "ignore_cache": true
}

curl

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

wget

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

httpie

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

python-requests

requests.post('http://localhost:5042/api/1/assets/prices/latest', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'assets': ['BTC', 'ETH', 'eip155:1/erc20:0x514910771AF9Ca656af840dff83E8264EcF986CA', 'USD', 'EUR'], 'ignore_cache': True, 'target_asset': 'USD'})
Request JSON Object:

  • assets (list) – A list of assets to query their latest 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 latest price query cache. Missing defaults to false.

Example Response:

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

{
    "result": {
        "assets": {
            "BTC": ["34758.11", 1],
            "ETH": ["1302.62", 2],
            "EUR": ["1.209", 8],
            "GBP": ["1.362", 8],
            "eip155:1/erc20:0x514910771AF9Ca656af840dff83E8264EcF986CA": ["20.29", 1],
            "USD": ["1", 8]
        },
        "target_asset": "USD",
        "oracles": {
          "coingecko": 1,
          "cryptocompare": 2,
          "uniswapv2": 3,
          "uniswapv3": 4,
          "manualcurrent": 5,
          "blockchain": 6,
          "fiat": 7
        }
    },
    "message": ""
}
Response JSON Object:

  • result (object) – A JSON object that contains the price of the assets in the target asset currency and the oracle used to query it.

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

  • oracles (object) – A mapping of oracles to their integer id used.

Status Codes:

  • 200 OK – The USD prices have been successfully 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 NFT assets

POST /api/(version)/nfts/prices

Get current prices and whether they have been manually input or not for NFT assets.

Example Request:

http

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

  {"lps_handling": "all_nfts"}

:reqjson string[optional] lps_handling: A flag to specify how to handle LP NFTs. Possible values are `'all_nfts'` (default), `'only_lps'` and `'exclude_lps'`. You can use 'only_lps' if you want to only include LPs NFTs in the result or you can use 'exclude_lps' if you want NFTs not marked as LP positions.

curl

curl -i -X POST http://nohost/api/1/nfts/prices --data-raw '{"lps_handling": "all_nfts"}



:reqjson string[optional] lps_handling: A flag to specify how to handle LP NFTs. Possible values are `'all_nfts'` (default), `'only_lps'` and `'exclude_lps'`. You can use 'only_lps' if you want to only include LPs NFTs in the result or you can use 'exclude_lps' if you want NFTs not marked as LP positions.'

wget

wget -S -O- http://nohost/api/1/nfts/prices --post-data='{"lps_handling": "all_nfts"}



:reqjson string[optional] lps_handling: A flag to specify how to handle LP NFTs. Possible values are `'all_nfts'` (default), `'only_lps'` and `'exclude_lps'`. You can use 'only_lps' if you want to only include LPs NFTs in the result or you can use 'exclude_lps' if you want NFTs not marked as LP positions.'

httpie

echo '{"lps_handling": "all_nfts"}



:reqjson string[optional] lps_handling: A flag to specify how to handle LP NFTs. Possible values are `'"'"'all_nfts'"'"'` (default), `'"'"'only_lps'"'"'` and `'"'"'exclude_lps'"'"'`. You can use '"'"'only_lps'"'"' if you want to only include LPs NFTs in the result or you can use '"'"'exclude_lps'"'"' if you want NFTs not marked as LP positions.' | http POST http://nohost/api/1/nfts/prices

python-requests

requests.post('http://nohost/api/1/nfts/prices', data='{"lps_handling": "all_nfts"}\r\n\n\r\n\n:reqjson string[optional] lps_handling: A flag to specify how to handle LP NFTs. Possible values are `\'all_nfts\'` (default), `\'only_lps\'` and `\'exclude_lps\'`. You can use \'only_lps\' if you want to only include LPs NFTs in the result or you can use \'exclude_lps\' if you want NFTs not marked as LP positions.')

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:

Get all manually input latest prices

POST /api/(version)/assets/prices/latest/all

Retrieve all the manually input latest prices stored in the database, including prices for nfts.

Example Request:

http

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

{"to_asset": "EUR"}

curl

curl -i -X POST http://localhost:5042/api/1/assets/prices/latest/all -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"to_asset": "EUR"}'

wget

wget -S -O- http://localhost:5042/api/1/assets/prices/latest/all --header="Content-Type: application/json;charset=UTF-8" --post-data='{"to_asset": "EUR"}'

httpie

echo '{
  "to_asset": "EUR"
}' | http POST http://localhost:5042/api/1/assets/prices/latest/all Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/assets/prices/latest/all', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'to_asset': 'EUR'})
Request JSON Object:

  • from_asset (string) – Optional. Asset identifier to use as filter in the from side of the prices.

  • to_asset (string) – Optional. Asset identifier to use as filter in the to side of the prices.

Example Response:

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

{
    "result": [
      {
        "from_asset": "ETH",
        "to_asset": "EUR",
        "price": "5"
      },
      {
        "from_asset": "USD",
        "to_asset": "EUR",
        "price": "25"
      },
      {
        "from_asset": "_nft_custom",
        "to_asset": "ETH",
        "price_in_asset": "1"
      }
    ],
    "message": ""
}
Response JSON Object:

  • result (object) – A list of results with the prices along their from_asset and to_asset.

Status Codes:

Add manual current price for an asset

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

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

python-requests

requests.put('http://localhost:5042/api/1/assets/prices/latest', 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/latest

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

python-requests

requests.delete('http://localhost:5042/api/1/assets/prices/latest', 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 – Successful 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. If an asset’s price could not be queried then zero will be returned as the price.

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 successfully 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. If a manual price for the specified asset pair and timestamp already exists, it is replaced with the new price provided.

Example Request:

http

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

 {
      "from_asset": "eip155:1/erc20: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": "eip155:1/erc20: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": "eip155:1/erc20:0xD71eCFF9342A5Ced620049e616c5035F1dB98620", "price": "1.20", "timestamp": 1611166335, "to_asset": "USD"}'

httpie

echo '{
  "from_asset": "eip155:1/erc20: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': 'eip155:1/erc20: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": "eip155:1/erc20: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": "eip155:1/erc20: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": "eip155:1/erc20:0xD71eCFF9342A5Ced620049e616c5035F1dB98620", "price": "1.20", "timestamp": 1611166335, "to_asset": "USD"}'

httpie

echo '{
  "from_asset": "eip155:1/erc20: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': 'eip155:1/erc20: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": "eip155:1/erc20: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": "eip155:1/erc20: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": "eip155:1/erc20:0xD71eCFF9342A5Ced620049e616c5035F1dB98620"}'

httpie

echo '{
  "from_asset": "eip155:1/erc20: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': 'eip155:1/erc20: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": "eip155:1/erc20:0xD533a949740bb3306d119CC777fa900bA034cd52",
        "to_asset": "USD",
        "timestamp": 1611166335,
        "price": "1.20"
      },
      {
        "from_asset": "eip155:1/erc20: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": "eip155:1/erc20: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": "eip155:1/erc20: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": "eip155:1/erc20:0xD71eCFF9342A5Ced620049e616c5035F1dB98620", "timestamp": 1611166335, "to_asset": "USD"}'

httpie

echo '{
  "from_asset": "eip155:1/erc20: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': 'eip155:1/erc20: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"]}

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"], "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"], "location": "kraken", "name": "my kraken key", "passphrase": "secret"}'

httpie

echo '{
  "api_key": "ddddd",
  "api_secret": "ffffff",
  "binance_markets": [
    "ETHUSDC",
    "BTCUSDC"
  ],
  "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'], '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.

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:
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 successful 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 successful 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 evm transactions

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

Doing a DELETE on the evm transactions endpoint will purge all locally saved transaction data. Optionally can specify the evm chain to only purge transactions of that chain. 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/evm/transactions HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{"evm_chain": "optimism"}

curl

curl -i -X DELETE http://localhost:5042/api/1/blockchains/evm/transactions -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"evm_chain": "optimism"}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/blockchains/evm/transactions --header="Content-Type: application/json;charset=UTF-8" --body-data='{"evm_chain": "optimism"}'

httpie

echo '{
  "evm_chain": "optimism"
}' | http DELETE http://localhost:5042/api/1/blockchains/evm/transactions Content-Type:"application/json;charset=UTF-8"

python-requests

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

  • evm_chain (string) – Optional. The name of the evm chain for which to purge transaction. "ethereum", "optimism" etc. If not given all transactions for all chains are purged.

Example Response:

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

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

Decode transactions that haven’t been decoded yet

POST /api/(version)/blockchains/evm/transactions/decode

Doing a POST on the transactions decoding endpoint will start the decoding process for all the transactions that haven’t been decoded yet for the given chain and addresses combination. Transactions already decoded won’t be re-decoded.

Note

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

Example Request:

http

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

{
    "async_query": false,
    "evm_chains": ["ethereum", "optimism"]
}

curl

curl -i -X POST http://localhost:5042/api/1/blockchains/evm/transactions/decode -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": false, "evm_chains": ["ethereum", "optimism"]}'

wget

wget -S -O- http://localhost:5042/api/1/blockchains/evm/transactions/decode --header="Content-Type: application/json;charset=UTF-8" --post-data='{"async_query": false, "evm_chains": ["ethereum", "optimism"]}'

httpie

echo '{
  "async_query": false,
  "evm_chains": [
    "ethereum",
    "optimism"
  ]
}' | http POST http://localhost:5042/api/1/blockchains/evm/transactions/decode Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/blockchains/evm/transactions/decode', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': False, 'evm_chains': ['ethereum', 'optimism']})
Request JSON Object:

  • evm_chains (list) – A list specifying the evm chains for which to decode tx_hashes. The possible values are limited to the chains with evm transactions. If the list is not provided all transactions from all the chains will be decoded.

Example Response:

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

{ "result": {"decoded_tx_number": {"ethereum": 4, "optimism": 1}}, "message": "" }
Response JSON Object:

  • decoded_tx_number (object) – A mapping of how many transactions were decoded per requested chain. If a chain was not requested no key will exist in the mapping.

Status Codes:
GET /api/(version)/blockchains/evm/transactions/decode

Doing a GET on the transactions decoding endpoint will return a breakdown of the number of transactions that are not decoded.

Note

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

Example Request:

http

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

{"async_query": false}

curl

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

wget

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

httpie

echo '{
  "async_query": false
}' | http http://localhost:5042/api/1/blockchains/evm/transactions/decode Content-Type:"application/json;charset=UTF-8"

python-requests

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

Example Response:

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

{ "result": {"ethereum": 2, "optimism": 1, "base": 1}, "message": "" }
Response JSON Object:

  • result (object) – A mapping of the EVM chain name to the number of transactions missing the decoding.

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:

Getting all supported chains

GET /api/(version)/blockchains/supported

Doing a GET on the supported chains will return all supported chains along with their type. If it is an EVM chain it will also contain the name of the EVM chain.

Example Request

http

GET /api/(version)/blockchains/supported HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8

{}

Example Response

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

{
    "result": [
        {
            "id": "eth",
            "name": "ethereum",
            "type": "evm",
            "native_token": "ETH",
            "image": "ethereum.svg",
            "evm_chain_name": "ethereum"
        },
        {
            "id": "eth2",
            "name": "Ethereum Staking",
            "type": "eth2",
            "native_token": "ETH2",
            "image": "ethereum.svg"
        },
        {
            "id": "btc",
            "name": "bitcoin",
            "type": "bitcoin",
            "native_token": "BTC",
            "image": "bitcoin.svg"
        },
        {
            "id": "bch",
            "name": "bitcoin cash",
            "type": "bitcoin",
            "native_token": "BCH",
            "image": "bitcoin-cash.svg"
        },
        {
            "id": "ksm",
            "name": "kusama",
            "type": "substrate",
            "native_token": "KSM",
            "image": "kusama.svg"
        },
        {
            "id": "avax",
            "name": "avalanche",
            "type": "evm",
            "native_token": "AVAX",
            "image": "avalanche.svg",
            "evm_chain_name": "avalanche"
        },
        {
            "id": "dot",
            "name": "polkadot",
            "type": "substrate",
            "native_token": "DOT",
            "image": "polkadot.svg"
        },
        {
            "id": "optimism",
            "name": "optimism",
            "type": "evm",
            "native_token": "ETH",
            "image": "optimism.svg",
            "evm_chain_name": "optimism"
        },
        {
            "id": "polygon_pos",
            "name": "Polygon PoS",
            "type": "evm",
            "native_token": "eip155:137/erc20:0x0000000000000000000000000000000000001010",
            "image": "polygon_pos.svg",
            "evm_chain_name": "polygon_pos"
        },
        {
            "id": "arbitrum_one",
            "name": "Arbitrum One",
            "type": "evm",
            "native_token": "ETH",
            "image": "arbitrum_one.svg",
            "evm_chain_name": "arbitrum_one"
        },
        {
            "id": "base",
            "name": "base",
            "type": "evm",
            "native_token": "ETH",
            "image": "base.svg",
            "evm_chain_name": "base"
        },
        {
            "id": "gnosis",
            "name": "gnosis",
            "type": "evm",
            "native_token": "XDAI",
            "image": "gnosis.svg",
            "evm_chain_name": "gnosis"
        }
    ],
    "message": ""
}
Response JSON Object:

  • result (object) – Contains all supported chains’ ID, name, type, EVM chain name (if applicable).

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 evm transactions

POST /api/(version)/blockchains/evm/transactions/

Note

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

Doing a POST on the evm transactions endpoint will query all evm transactions for all the tracked user addresses. Caller can also specify a chain and/or an address to further filter the query. Also they can limit the queried transactions by timestamps and can filter transactions by related event’s properties (asset, counterparties and whether to exclude transactions with ignored assets). If the user is not premium and has more than the transaction limit then the returned transaction will be limited to that number. Any filtering will also be limited. Transactions are returned most recent first.

Example Request:

http

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

{
    "accounts": [{
        "address": "0x3CAdbeB58CB5162439908edA08df0A305b016dA8",
        "evm_chain": "optimism"
    }, {
        "address": "0xF2Eb18a344b2a9dC769b1914ad035Cbb614Fd238"
    }],
    "from_timestamp": 1514764800,
    "to_timestamp": 1572080165,
    "only_cache": false
}

curl

curl -i -X POST http://localhost:5042/api/1/blockchains/evm/transactions -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"accounts": [{"address": "0x3CAdbeB58CB5162439908edA08df0A305b016dA8", "evm_chain": "optimism"}, {"address": "0xF2Eb18a344b2a9dC769b1914ad035Cbb614Fd238"}], "from_timestamp": 1514764800, "only_cache": false, "to_timestamp": 1572080165}'

wget

wget -S -O- http://localhost:5042/api/1/blockchains/evm/transactions --header="Content-Type: application/json;charset=UTF-8" --post-data='{"accounts": [{"address": "0x3CAdbeB58CB5162439908edA08df0A305b016dA8", "evm_chain": "optimism"}, {"address": "0xF2Eb18a344b2a9dC769b1914ad035Cbb614Fd238"}], "from_timestamp": 1514764800, "only_cache": false, "to_timestamp": 1572080165}'

httpie

echo '{
  "accounts": [
    {
      "address": "0x3CAdbeB58CB5162439908edA08df0A305b016dA8",
      "evm_chain": "optimism"
    },
    {
      "address": "0xF2Eb18a344b2a9dC769b1914ad035Cbb614Fd238"
    }
  ],
  "from_timestamp": 1514764800,
  "only_cache": false,
  "to_timestamp": 1572080165
}' | http POST http://localhost:5042/api/1/blockchains/evm/transactions Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/blockchains/evm/transactions', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'accounts': [{'address': '0x3CAdbeB58CB5162439908edA08df0A305b016dA8', 'evm_chain': 'optimism'}, {'address': '0xF2Eb18a344b2a9dC769b1914ad035Cbb614Fd238'}], '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_attributes (list[string]) – This is the list of attributes of the transaction by which to order the results.

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

  • accounts (list[string]) – List of accounts to filter by. Each account contains an "address" key which is required and is an evm address. It can also contains an "evm_chain" field which is the specific chain for which to limit the address.

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

  • evm_chain (string) – Optional. The name of the evm chain by which to filter all transactions. "ethereum", "optimism" etc.

  • asset (string) – Optional. Serialized asset to filter by.

  • exclude_ignored_assets (bool) – Optional. Whether to exclude transactions with ignored assets. Default true.

Example Response:

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

{
  "result": {
    "entries": [{
      "entry": {
        "tx_hash": "0x18807cd818b2b50a2284bda2dfc39c9f60607ccfa25b1a01143e934280675eb8",
        "evm_chain":"ethereum",
        "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": "0x867119d6c66cab26561ccc5775c9cd215389efb2e3832e54baed2a0a34498c4b",
          "evm_chain": "optimism",
          "timestamp": 1661993636,
          "block_number": 15449856,
          "from_address": "0xF2Eb18a344b2a9dC769b1914ad035Cbb614Fd238",
          "to_address": "0x4f9Fbb3f1E99B56e0Fe2892e623Ed36A76Fc605d",
          "value": "0",
          "gas": "118197",
          "gas_price": "17961480822",
          "gas_used": "111201",
          "input_data": "0xa694fc3a0000000000000000000000000000000000000000000000162069b9d8ad5c348a",
          "nonce": 88
        },
        "ignored_in_accounting" true,

      }, {
      "entry": {
        "tx_hash": "0x19807cd818b2b50a2284bda2dfc39c9f60607ccfa25b1a01143e934280635eb7",
        "evm_chain": "ethereum",
        "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": false,
      }],
    "entries_found": 95,
    "entries_limit": 500,
    "entries_total": 1000

},
  "message": ""
}
Response JSON Object:

  • result (object) – A list of transaction entries to return for the given filter.

  • entry (object) – A single transaction entry

  • ignored_in_accounting (bool) – A boolean indicating whether this transaction should be ignored in accounting or not

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

Request transactions event decoding

PUT /api/(version)/blockchains/evm/transactions

Note

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

Doing a PUT on the evm transactions endpoint will request a decoding of the given transactions and generation of decoded events. That basically entails querying the transaction receipts for each transaction hash and then decoding all events. If events are already queried and ignore_cache is true they will be deleted and re-queried.

Example Request:

http

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

{
    "async_query": true,
    "data": [{
        "evm_chain": "ethereum",
        "tx_hashes": ["0xe33041d0ae336cd4c588a313b7f8649db07b79c5107424352b9e52a6ea7a9742", "0xed6e64021f960bb40f11f1c00ec1d5ca910471e75a080e42b347ba5af7e73516"]
    }, {
        "evm_chain": "optimism",
        "tx_hashes": ["0x13344150ae236c54c588c313b7f8600d007b79c5107424352b9e52a6ea712741"]
    }],
    "ignore_cache": false
}

curl

curl -i -X PUT http://localhost:5042/api/1/blockchains/evm/transactions -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": true, "data": [{"evm_chain": "ethereum", "tx_hashes": ["0xe33041d0ae336cd4c588a313b7f8649db07b79c5107424352b9e52a6ea7a9742", "0xed6e64021f960bb40f11f1c00ec1d5ca910471e75a080e42b347ba5af7e73516"]}, {"evm_chain": "optimism", "tx_hashes": ["0x13344150ae236c54c588c313b7f8600d007b79c5107424352b9e52a6ea712741"]}], "ignore_cache": false}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/blockchains/evm/transactions --header="Content-Type: application/json;charset=UTF-8" --body-data='{"async_query": true, "data": [{"evm_chain": "ethereum", "tx_hashes": ["0xe33041d0ae336cd4c588a313b7f8649db07b79c5107424352b9e52a6ea7a9742", "0xed6e64021f960bb40f11f1c00ec1d5ca910471e75a080e42b347ba5af7e73516"]}, {"evm_chain": "optimism", "tx_hashes": ["0x13344150ae236c54c588c313b7f8600d007b79c5107424352b9e52a6ea712741"]}], "ignore_cache": false}'

httpie

echo '{
  "async_query": true,
  "data": [
    {
      "evm_chain": "ethereum",
      "tx_hashes": [
        "0xe33041d0ae336cd4c588a313b7f8649db07b79c5107424352b9e52a6ea7a9742",
        "0xed6e64021f960bb40f11f1c00ec1d5ca910471e75a080e42b347ba5af7e73516"
      ]
    },
    {
      "evm_chain": "optimism",
      "tx_hashes": [
        "0x13344150ae236c54c588c313b7f8600d007b79c5107424352b9e52a6ea712741"
      ]
    }
  ],
  "ignore_cache": false
}' | http PUT http://localhost:5042/api/1/blockchains/evm/transactions Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/blockchains/evm/transactions', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': True, 'data': [{'evm_chain': 'ethereum', 'tx_hashes': ['0xe33041d0ae336cd4c588a313b7f8649db07b79c5107424352b9e52a6ea7a9742', '0xed6e64021f960bb40f11f1c00ec1d5ca910471e75a080e42b347ba5af7e73516']}, {'evm_chain': 'optimism', 'tx_hashes': ['0x13344150ae236c54c588c313b7f8600d007b79c5107424352b9e52a6ea712741']}], 'ignore_cache': False})
Request JSON Object:

  • data[optional] (list) – A list of data to decode. Each data entry consists of an "evm_chain" key specifying the evm chain for which to decode tx_hashes and a "tx_hashes" key which is an optional list of transaction hashes to request decoding for in that chain. If the list of transaction hashes is not passed then all transactions for that chain are decoded. Passing an empty list is not allowed.

  • 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. This is always false by default. If true is given then the decoded events will be deleted and re-queried.

Example Response:

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

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

Querying tags

GET /api/(version)/tags

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

Example Request:

http

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

curl

curl -i -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 publicly 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 newly 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, ETH2, 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"},
                     "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F": {"amount": "15", "usd_value": "15.21"}
                 },
                 "liabilities": {
                     "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F": {"amount": "20", "usd_value": "20.35"}
                 }
            }},
             "eth2": { "0x9675faa8d15665e30d31dc10a332828fa15e2c7490f7d1894d9092901b139801ce476810f8e1e0c7658a9abdb9c4412e": {
                 "assets": {
                     "ETH2": {"amount": "33.12", "usd_value": "45243.21"},
                 },
                 "0x97bc980f17f42a994827899e0720cee288b538646292ce7c866a5a5c9d1002cd1fb7a80195445be2670b64cf4d1c215e": {
                 "assets": {
                     "ETH2": {"amount": "32.45", "usd_value": "40241.55"},
                 },
            }},
        },
        "totals": {
            "assets": {
                "BTC": {"amount": "1", "usd_value": "7540.15"},
                "ETH": {"amount": "10", "usd_value": "1650.53"},
                "ETH2": {"amount": "65.57", "usd_value": "85484.76"},
                "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F": {"amount": "15", "usd_value": "15.21"}
            },
            "liabilities": {
                "eip155:1/erc20: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 successfully queried.

statuscode 400:

Provided JSON is in some way malformed

statuscode 401:

User is not logged in.

statuscode 409:

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 serves as a hacky way of notifying the backend that the user has logged in the dashboard and background task scheduling or other heavy tasks can commence.

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": {
             "eip155:1/erc20: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

POST /api/(version)/assets/all

Doing a POST on the all assets endpoint will return a list of all supported assets and their details.

Note

When filtering using evm_chain, asset_type if provided must be evm_token.

Example Request:

http

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

{
  "asset_type": "own chain",
  "limit": 15,
  "offset": 0
}

curl

curl -i -X POST http://localhost:5042/api/1/assets/all -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"asset_type": "own chain", "limit": 15, "offset": 0}'

wget

wget -S -O- http://localhost:5042/api/1/assets/all --header="Content-Type: application/json;charset=UTF-8" --post-data='{"asset_type": "own chain", "limit": 15, "offset": 0}'

httpie

echo '{
  "asset_type": "own chain",
  "limit": 15,
  "offset": 0
}' | http POST http://localhost:5042/api/1/assets/all Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/assets/all', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'asset_type': 'own chain', 'limit': 15, 'offset': 0})
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_attributes (list[string]) – This is the list of attributes of the asset by which to order the results. By default we sort using name.

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

  • name (string) – The name of asset to be used to filter the result data. Optional.

  • symbol (string) – An asset symbol to be used to filter the result data. Optional.

  • asset_type (string) – The category of an asset to be used to filter the result data. Optional.

  • evm_chain (string) – The name for the evm chain to be used to filter the result data. Possible values are ethereum, optimism, gnosis, celo, etc. Optional.

  • address (string) – The address of the evm asset to be used to filter the result data. Optional.

  • show_user_owned_assets_only (bool) – A flag to specify if only user owned assets should be returned. Defaults to "false". Optional.

  • show_whitelisted_assets_only (bool) – If set to true then only whitelisted spam tokens are queried.

  • ignored_assets_handling (string) – A flag to specify how to handle ignored assets. Possible values are ‘none’, ‘exclude’ and ‘show_only’. You can write ‘none’ in order to not handle them in any special way (meaning to show them too). This is the default. You can write ‘exclude’ if you want to exclude them from the result. And you can write ‘show_only’ if you want to only see the ignored assets in the result.

  • identifiers (list[string]) – A list of asset identifiers to filter by. Optional.

Example Response:

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

{
    "result": [
        {
            "identifier": "eip155:1/erc20:0xB6eD7644C69416d67B522e20bC294A9a9B405B31",
            "evm_address": "0xB6eD7644C69416d67B522e20bC294A9a9B405B31",
            "evm_chain":"ethereum",
            "token_kind":"erc20",
            "decimals": 8,
            "name": "0xBitcoin",
            "started": 1517875200,
            "symbol": "0xBTC",
            "asset_type": "evm token"
            "cryptocompare":"0xbtc",
            "coingecko":"0xbtc",
            "protocol":"None"
        },
        {
            "identifier": "DCR",
            "name": "Decred",
            "started": 1450137600,
            "symbol": "DCR",
            "asset_type": "own chain"
        },
        {
            "identifier": "eip155:1/erc20:0xcC4eF9EEAF656aC1a2Ab886743E98e97E090ed38",
            "evm_address": "0xcC4eF9EEAF656aC1a2Ab886743E98e97E090ed38",
            "evm_chain":"ethereum",
            "token_kind":"erc20",
            "decimals": 18,
            "name": "DigitalDevelopersFund",
            "started": 1498504259,
            "symbol": "DDF",
            "asset_type": "evm token"
            "cryptocompare":"DDF",
            "coingecko":"ddf",
            "protocol":"None"
        },
        {
            "identifier": "ETC",
            "forked": "ETH",
            "name": "Ethereum classic",
            "started": 1469020840,
            "symbol": "ETC",
            "asset_type": "own chain"
        },
        {
            "identifier": "KRW",
            "name": "Korean won",
            "symbol": "KRW",
            "asset_type": "fiat"
        },
        {
            "identifier": "eip155:1/erc20:0xD850942eF8811f2A866692A623011bDE52a462C1",
            "evm_address": "0xD850942eF8811f2A866692A623011bDE52a462C1",
            "evm_chain":"ethereum",
            "token_kind":"erc20",
            "decimals": 18,
            "name": "Vechain Token",
            "started": 1503360000,
            "swapped_for": "VET",
            "symbol": "VEN",
            "asset_type": "evm token",
            "coingecko": "vechain"
            "cryptocompare":"VET",
            "coingecko":"vet",
            "protocol":"None"
        }
    ],
    "message": ""
}
Response JSON Object:

  • result (list) – A list of assets that match the query with their respective asset details.

  • asset_type (string) – The type of asset. Valid values are ethereum token, own chain, omni token and more. For all valid values check here.

  • started (integer) – An optional unix timestamp denoting when we know the asset started to have a price.

  • name (string) – The long name of the asset. Does not need to be the same as the unique identifier.

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

  • swapped_for (string) – 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 (string) – The symbol used for this asset. This is not guaranteed to be unique.

  • evm_address (string) – If the type is evm_token then this will be the hexadecimal address of the token’s contract.

  • evm_chain (string) – If the type is evm_token then this will be the name of the evm chain. “ethereum”, “optimism” etc.

  • token_kind (string) – If the type is evm_token then this will be the token type, for example erc20.

  • decimals (integer) – If the type is evm_token then this will be the number of decimals the token has.

  • cryptocompare (string) – The cryptocompare identifier for the asset. can be missing if not known. If missing a query by symbol is attempted.

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

  • protocol (string) – An optional string for evm tokens denoting the protocol they belong to. For example uniswap, for uniswap LP tokens.

  • underlying_tokens (object) – 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(value in the range of 0 to 100) that each token contributes to the pool.

  • notes (string) – If the type is custom_asset this is a string field with notes added by the user.

  • custom_asset_type (string) – If the type is custom_asset this field contains the custom type set by the user for the asset.

Status Codes:

Get asset identifiers mappings

POST /api/(version)/assets/mappings

Doing a POST on the assets mappings endpoint with a list of of identifiers will return a mapping of those identifiers to their respective name and symbols.

Example Request:

http

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

{
  "identifiers": [
      "eip155:1/erc20:0xB6eD7644C69416d67B522e20bC294A9a9B405B31",
      "DCR",
      "eip155:1/erc20:0xcC4eF9EEAF656aC1a2Ab886743E98e97E090ed38",
      "_nft_0x57f1887a8bf19b14fc0df6fd9b2acc9af147ea85_26612040215479394739615825115912800930061094786769410446114278812336794170041"
  ]
}

curl

curl -i -X POST http://localhost:5042/api/1/assets/mappings -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"identifiers": ["eip155:1/erc20:0xB6eD7644C69416d67B522e20bC294A9a9B405B31", "DCR", "eip155:1/erc20:0xcC4eF9EEAF656aC1a2Ab886743E98e97E090ed38", "_nft_0x57f1887a8bf19b14fc0df6fd9b2acc9af147ea85_26612040215479394739615825115912800930061094786769410446114278812336794170041"]}'

wget

wget -S -O- http://localhost:5042/api/1/assets/mappings --header="Content-Type: application/json;charset=UTF-8" --post-data='{"identifiers": ["eip155:1/erc20:0xB6eD7644C69416d67B522e20bC294A9a9B405B31", "DCR", "eip155:1/erc20:0xcC4eF9EEAF656aC1a2Ab886743E98e97E090ed38", "_nft_0x57f1887a8bf19b14fc0df6fd9b2acc9af147ea85_26612040215479394739615825115912800930061094786769410446114278812336794170041"]}'

httpie

echo '{
  "identifiers": [
    "eip155:1/erc20:0xB6eD7644C69416d67B522e20bC294A9a9B405B31",
    "DCR",
    "eip155:1/erc20:0xcC4eF9EEAF656aC1a2Ab886743E98e97E090ed38",
    "_nft_0x57f1887a8bf19b14fc0df6fd9b2acc9af147ea85_26612040215479394739615825115912800930061094786769410446114278812336794170041"
  ]
}' | http POST http://localhost:5042/api/1/assets/mappings Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/assets/mappings', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'identifiers': ['eip155:1/erc20:0xB6eD7644C69416d67B522e20bC294A9a9B405B31', 'DCR', 'eip155:1/erc20:0xcC4eF9EEAF656aC1a2Ab886743E98e97E090ed38', '_nft_0x57f1887a8bf19b14fc0df6fd9b2acc9af147ea85_26612040215479394739615825115912800930061094786769410446114278812336794170041']})

Example Response:

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

{
  "result": {
    "assets": {
      "eip155:1/erc20:0xB6eD7644C69416d67B522e20bC294A9a9B405B31": {
        "name": "0xBitcoin",
        "symbol": "0xBTC",
        "asset_type": "evm token",
        "collection_id": "0"
      },
      "DCR": {
        "name": "Decred",
        "symbol": "DCR",
        "asset_type": "own chain"
      },
      "eip155:1/erc20:0xcC4eF9EEAF656aC1a2Ab886743E98e97E090ed38": {
        "name": "DigitalDevelopersFund",
        "symbol": "DDF",
        "chain_id": 1,
        "is_custom_asset": false,
        "asset_type": "evm token"
      },
      "_nft_0x57f1887a8bf19b14fc0df6fd9b2acc9af147ea85_26612040215479394739615825115912800930061094786769410446114278812336794170041": {
        "name": "Mooncat 151",
        "asset_type": "nft",
        "collection_name": "Mooncats",
        "image_url": "https://myimg.com"
      }
    },
    "asset_collections": {
      "0": {
        "name": "0xBitcoin",
        "symbol": "0xBTC"
      }
    }
  },
  "message": ""
}
Response JSON Object:

  • assets (object) – A mapping of identifiers to (1) their name, symbol & chain(if available) if they are assets. And to (2) their name, collection name and image url if they are nfts.

  • asset_collections (object) – A mapping of asset collections ids to their properties.

  • name (string) – Name of the asset/nft.

  • symbol (string) – Symbol of the asset. Will only exist for non-nft assets.

  • chain_id (int) – This value might not be included in all the results. Chain id of the chain where the asset is located if the asset is an EVM token.

  • custom_asset_type (string) – This value might not be included in all the results. It represents the custom asset type for a custom asset.

  • collection_name (string) – Only included for NFTs. May be null if nft has no collection. If it does then this is its name.

  • image_url (string) – Only included for NFTs. May be null if nft has no image. If it does this is a url to the image.

Status Codes:

Search for assets

POST /api/(version)/assets/search

Doing a POST on the assets search endpoint will return a list of objects containing an asset’s name, symbol and identifier in ascending order of the assets’ names by default. The result returned is based on the search keyword and column specified to search.

Example Request:

http

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

{
  "value": "bitcoin",
  "search_column": "name",
  "limit": 50,
  "order_by_attributes": ["symbol"],
  "ascending": [false]
}

curl

curl -i -X POST http://localhost:5042/api/1/assets/search -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"ascending": [false], "limit": 50, "order_by_attributes": ["symbol"], "search_column": "name", "value": "bitcoin"}'

wget

wget -S -O- http://localhost:5042/api/1/assets/search --header="Content-Type: application/json;charset=UTF-8" --post-data='{"ascending": [false], "limit": 50, "order_by_attributes": ["symbol"], "search_column": "name", "value": "bitcoin"}'

httpie

echo '{
  "ascending": [
    false
  ],
  "limit": 50,
  "order_by_attributes": [
    "symbol"
  ],
  "search_column": "name",
  "value": "bitcoin"
}' | http POST http://localhost:5042/api/1/assets/search Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/assets/search', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'ascending': [False], 'limit': 50, 'order_by_attributes': ['symbol'], 'search_column': 'name', 'value': 'bitcoin'})
Request JSON Object:

  • limit (int) – This signifies the limit of records to return as per the sql spec.

  • order_by_attributes (list[string]) – This is the list of attributes of the asset by which to order the results. By default we sort using name.

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

  • value (string) – A string to be used search the assets. Required.

  • search_column (string) – A column on the assets table to perform the search on. One of "name" or "symbol". Required.

  • return_exact_matches (bool) – A flag that specifies whether the result returned should match the search keyword. Defaults to "false".

  • chain_id (int[optional]) – Chain id of the chain where the asset is located if the asset is an EVM token.

Example Response:

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

{
    "result": [
        {
            "identifier": "eip155:1/erc20:0xB6eD7644C69416d67B522e20bC294A9a9B405B31",
            "name": "0xBitcoin",
            "symbol": "0xBTC"
            "chain_id": 1,
            "is_custom_asset": false
        },
        {
            "identifier": "BTC",
            "name": "bitcoin",
            "symbol": "BTC",
            "is_custom_asset": false
        }
    ],
    "message": ""
}
Response JSON Object:

  • result (object) – A list of objects that contain the asset details which match the search keyword.

  • identifier (string) – Identifier of the asset.

  • name (string) – Name of the asset.

  • symbol (string) – Symbol of the asset.

  • chain_id (int) – This value might not be included in all the results. Chain id of the chain where the asset is located if the asset is an EVM token.

  • custom_asset_type (string) – This value might not be included in all the results. It represents the custom asset type for a custom asset.

  • asset_type (string) – This value represents the asset type. Can be custom asset, nft, etc.

  • collection_name (string) – This value might not be included in all the results. It represents the nft collection name.

Status Codes:

Search for assets(Levenshtein)

POST /api/(version)/assets/search/levenshtein

Doing a POST on the assets search endpoint will return a list of objects containing an asset’s name, symbol and identifier based on the search keyword provided. This approach using Levenshtein distance for the search functionality and returns them by the closest match first.

Example Request:

http

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

{
  "value": "bitcoin",
  "limit": 50
}

curl

curl -i -X POST http://localhost:5042/api/1/assets/search/levenshtein -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"limit": 50, "value": "bitcoin"}'

wget

wget -S -O- http://localhost:5042/api/1/assets/search/levenshtein --header="Content-Type: application/json;charset=UTF-8" --post-data='{"limit": 50, "value": "bitcoin"}'

httpie

echo '{
  "limit": 50,
  "value": "bitcoin"
}' | http POST http://localhost:5042/api/1/assets/search/levenshtein Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/assets/search/levenshtein', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'limit': 50, 'value': 'bitcoin'})
Request JSON Object:

  • limit (int) – This signifies the limit of records to return as per the sql spec.

  • value (string) – A string to be used to search the assets. Required.

  • chain_id (int[optional]) – Chain id of a supported EVM chain used to filter the result

  • owner_addresses (list[string][optional]) – A list of evm addresses. If provided, only nfts owned by these addresses will be returned.

  • name (string[optional]) – Optional nfts name to filter by.

  • collection_name (string[optional]) – Optional nfts collection_name to filter by.

  • ignored_assets_handling (string[optional]) – A flag to specify how to handle ignored assets. Possible values are ‘none’, ‘exclude’ and ‘show_only’. You can write ‘none’ in order to not handle them in any special way (meaning to show them too). This is the default. You can write ‘exclude’ if you want to exclude them from the result. And you can write ‘show_only’ if you want to only see the ignored assets in the result.

Example Response:

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

{
    "result": [
        {
            "identifier": "eip155:1/erc20:0xB6eD7644C69416d67B522e20bC294A9a9B405B31",
            "name": "0xBitcoin",
            "symbol": "0xBTC"
            "chain_id": 1,
            "is_custom_asset": false
        }
    ],
    "message": ""
}
Response JSON Object:

  • result (object) – A list of objects that contain the asset details which match the search keyword ordered by distance to search keyword.

  • identifier (string) – Identifier of the asset.

  • name (string) – Name of the asset.

  • symbol (string) – Symbol of the asset.

  • chain_id (int) – This value might not be included in all the results. Chain id of the chain where the asset is located if the asset is an EVM token.

  • custom_asset_type (string) – This value might not be included in all the results. It represents the custom asset type for a custom asset.

  • asset_type (string) – This value represents the asset type. Can be custom asset, nft, etc.

Status Codes:

Querying owned assets

GET /api/(version)/assets/

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

Example Request:

http

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

curl

curl -i -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:

Detecting owned tokens

POST /api/(version)/blockchains/(blockchain)/tokens/detect

Doing POST on the detect tokens endpoint will detect tokens owned by the provided addresses on the specified blockchain. If no addresses provided, tokens for all user’s addresses will be detected.

Note

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

Example Request:

http

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

{"addresses": ["0xC88eA7a5df3A7BA59C72393C5b2dc2CE260ff04D", "0xE07Af3FBEAf8584dc885f5bAA7c72419BDDf002D"]}

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/eth/tokens/detect --data-raw '{"addresses": ["0xC88eA7a5df3A7BA59C72393C5b2dc2CE260ff04D", "0xE07Af3FBEAf8584dc885f5bAA7c72419BDDf002D"]}'

wget

wget -S -O- http://localhost:5042/api/1/blockchains/eth/tokens/detect --body-data='{"addresses": ["0xC88eA7a5df3A7BA59C72393C5b2dc2CE260ff04D", "0xE07Af3FBEAf8584dc885f5bAA7c72419BDDf002D"]}'

httpie

echo '{"addresses": ["0xC88eA7a5df3A7BA59C72393C5b2dc2CE260ff04D", "0xE07Af3FBEAf8584dc885f5bAA7c72419BDDf002D"]}' | http http://localhost:5042/api/1/blockchains/eth/tokens/detect

python-requests

requests.get('http://localhost:5042/api/1/blockchains/eth/tokens/detect', data='{"addresses": ["0xC88eA7a5df3A7BA59C72393C5b2dc2CE260ff04D", "0xE07Af3FBEAf8584dc885f5bAA7c72419BDDf002D"]}')
Request JSON Object:

  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

  • only_cache (bool) – Boolean denoting whether to use only cache or re-detect tokens.

  • addresses (list) – A list of addresses to detect tokens for.

Example Response:

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

{
    "result": {
        "0x31F05553be0EBBf7774241603Cc7b28771F989B3": {
            "tokens": [
                "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F", "eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
            ],
            "last_update_timestamp": 1658764910,
        },
    },
    "message": ""
}
Response JSON Object:

  • result (object) – a dictionary containing mappings of an account to owned tokens and last tokens update timestamp. Tokens and last_update_timestamp can be None (if no info about account’s tokens yet).

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

PATCH /api/1/assets/all 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 PATCH http://localhost:5042/api/1/assets/all -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=PATCH http://localhost:5042/api/1/assets/all --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 PATCH http://localhost:5042/api/1/assets/all Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/assets/all', 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 successfully 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": {
        "eip155:1/erc20:0xD178b20c6007572bD1FD01D205cC20D32B4A6015": "local",
        "eip155:1/erc20: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", "eip155:1/erc20: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", "eip155:1/erc20:0xD178b20c6007572bD1FD01D205cC20D32B4A6015": "remote"}, "up_to_version": 5}'

httpie

echo '{
  "async_query": true,
  "conflicts": {
    "Fas-23-da20": "local",
    "eip155:1/erc20: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', 'eip155:1/erc20: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",
             "decimals": 18,
             "name": "Aave Token",
             "started": 1600970788,
             "symbol": "AAVE",
             "type": "ethereum token"
     },
     "remote": {
             "coingecko": "aaveNGORZ",
             "ethereum_address": "0x1Fc66500c84A76Ad7e9c93437bFc5Ac33E2DDaE9",
             "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:

Reset state of assets

DELETE /api/(version)/assets/updates

Doing a DELETE on this endpoint will attempt to reset the state of the assets in the globaldb. Can be called in two modes, soft where the API will try to reset the state of packaged assets without modifying assets added by the user and hard mode where the assets added by the user will be deleted and the database will get the information from the packaged globaldb.

Example Request:

http

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

{
    "ignore_warnings": true,
    "reset": "hard"
}

curl

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

wget

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

httpie

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

python-requests

requests.delete('http://localhost:5042/api/1/assets/updates', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'ignore_warnings': True, 'reset': 'hard'})
Request JSON Object:

  • ignore_warnings (bool) – Optional. Defaults to false. If set to true the database will be reset even if there are events that depend on assets that will be deleted.

  • reset (str) – The mode selected to perform the reset. Can be either soft or hard.

Example Response:

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

{
    "result": true,
    "message": ""
}
Response JSON Object:

  • result (object) – true if the reset was completed successfully

Status Codes:

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/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/icon?asset=eip155%3A1%2Ferc20%3A3A0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET 'http://localhost:5042/api/1/assets/icon?asset=eip155%3A1%2Ferc20%3A3A0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e'

wget

wget -S -O- 'http://localhost:5042/api/1/assets/icon?asset=eip155%3A1%2Ferc20%3A3A0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e'

httpie

http 'http://localhost:5042/api/1/assets/icon?asset=eip155%3A1%2Ferc20%3A3A0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e'

python-requests

requests.get('http://localhost:5042/api/1/assets/icon?asset=eip155%3A1%2Ferc20%3A3A0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e')
Reqquery string asset:

Identifier of the asset to be queried.

Example Response:

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

The data of the image

Status Codes:

  • 200 OK – Icon successfully queried

  • 202 Accepted – Icon is not in the system and has been requested from coingecko but has not yet been 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/icon/modify
POST /api/(version)/assets/icon/modify

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/icon/modify HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{"file": "/path/to/file", "asset": "eip155:1/erc20:0x6810e776880C02933D47DB1b9fc05908e5386b96"}

curl

curl -i -X PUT http://localhost:5042/api/1/assets/icon/modify -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"asset": "eip155:1/erc20:0x6810e776880C02933D47DB1b9fc05908e5386b96", "file": "/path/to/file"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/assets/icon/modify --header="Content-Type: application/json;charset=UTF-8" --body-data='{"asset": "eip155:1/erc20:0x6810e776880C02933D47DB1b9fc05908e5386b96", "file": "/path/to/file"}'

httpie

echo '{
  "asset": "eip155:1/erc20:0x6810e776880C02933D47DB1b9fc05908e5386b96",
  "file": "/path/to/file"
}' | http PUT http://localhost:5042/api/1/assets/icon/modify Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/assets/icon/modify', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'asset': 'eip155:1/erc20:0x6810e776880C02933D47DB1b9fc05908e5386b96', 'file': '/path/to/file'})
Request JSON Object:

  • file (string) – The path to the image file to upload for PUT. The file itself for POST.

  • asset (string) – Identifier of the asset to be updated.

Example Response:

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

{"result": {"identifier": "eip155:1/erc20:0x6810e776880C02933D47DB1b9fc05908e5386b96"}, "message": ""}
Response JSON Object:

  • identifier (strin) – The identifier of the asset for which the icon was uploaded.

Status Codes:

Refreshing asset icons

PATCH /api/(version)/assets/icon/modify

Doing a PATCH on the asset icon endpoint will refresh the icon of the given asset. First, the cache of the icon of the given asset is deleted and then re-queried from CoinGecko and saved to the filesystem.

Example Request:

http

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

{"asset": "eip155:1/erc20:0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e"}

curl

curl -i -X PATCH http://localhost:5042/api/1/assets/icon/modify -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"asset": "eip155:1/erc20:0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e"}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/assets/icon/modify --header="Content-Type: application/json;charset=UTF-8" --body-data='{"asset": "eip155:1/erc20:0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e"}'

httpie

echo '{
  "asset": "eip155:1/erc20:0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e"
}' | http PATCH http://localhost:5042/api/1/assets/icon/modify Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/assets/icon/modify', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'asset': 'eip155:1/erc20:0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e'})
Request JSON Object:

  • asset (string) – Identifier of the asset to be refreshed.

Example Response:

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

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

Statistics for netvalue over time

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

Doing a GET on the statistics netvalue over time endpoint will return all the saved historical data points with user’s history. For non-premium users this returns up to 2 weeks of data in the past.

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:
Statuscode 401:

No user is currently logged in.

Statistics for asset or collection balance over time

POST /api/(version)/statistics/balance

Note

This endpoint is only available for premium users

Doing a POST on the statistics asset/collection 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. Depending on the given argument this will either query a single asset or a collection of assets.

Example Request:

http

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

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

curl

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

wget

wget -S -O- http://localhost:5042/api/1/statistics/balance --header="Content-Type: application/json;charset=UTF-8" --post-data='{"asset": "BTC", "from_timestamp": 1514764800, "to_timestamp": 1572080165}'

httpie

echo '{
  "asset": "BTC",
  "from_timestamp": 1514764800,
  "to_timestamp": 1572080165
}' | http POST http://localhost:5042/api/1/statistics/balance Content-Type:"application/json;charset=UTF-8"

python-requests

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

  • asset (string) – Identifier of the asset. This is mutually exclusive with the collection id. If this is given then only a single asset’s balances will be queried. If not given a collection_id MUST be given.

  • collection_id (integer) – Collection id to query. This is mutually exclusive with the asset. If this is given then combined balances of all assets of the collection are returned. If not given an asset MUST be given.

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:

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

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:

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:

  • limit (int) – Optional. 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_attributes (list[string]) – Optional. This is the list of attributes of the trade table by which to order the results. If none is given ‘time’ is assumed. Valid values are: [‘time’, ‘location’, ‘type’, ‘amount’, ‘rate’, ‘fee’].

  • ascending (list[bool]) – Optional. False by default. Defines the order by which results are returned depending on the chosen order by attribute.

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

  • base_asset (string) – Optionally filter trades by base_asset. A valid asset identifier has to be provided. If missing trades are not filtered by base asset.

  • quote_asset (string) – Optionally filter trades by quote_asset. A valid asset identifier has to be provided. If missing trades are not filtered by quote asset.

  • trade_type (string) – Optionally filter trades by type. A valid trade type (buy, sell) has to be provided. If missing trades are not filtered by type.

  • include_ignored_trades (bool) – Determines whether ignored trades should be included in the result returned. Defaults to "true".

  • exclude_ignored_assets (bool) – Determines whether the trades with ignored assets should be included in the result returned. Defaults to "true".

  • 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_total": 155,
        "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 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.

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 occurred

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

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

{ "trades_ids" : ["dsadfasdsad"]}

curl

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

wget

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

httpie

echo '{
  "trades_ids": [
    "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={'trades_ids': ['dsadfasdsad']})
Request JSON Object:

  • trades_ids (string) – The list of identifiers for trades to delete.

Example Response:

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

{
    "result": true,
    "message": ""
}
Response JSON Object:

  • result (bool) – Returns true if all identifiers were found and deleted, otherwise returns false.

  • message (string) – Returns "" if result is True else returns the error message.

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:

  • limit (int) – Optional. 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_attributes (list[string]) – Optional. This is the list of attributes of the asset movements table by which to order the results. If none is given ‘time’ is assumed. Valid values are: [‘time’, ‘location’, ‘category’, ‘amount’, ‘fee’].

  • ascending (list[bool]) – Optional. False by default. Defines the order by which results are returned depending on the chosen order by attribute.

  • 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 asset movements by location. A valid location name has to be provided. Valid locations are for now only exchanges for deposits/withdrawals.

  • asset (string) – Optionally filter asset movements by asset. A valid asset identifier has to be provided. If missing, movements are not filtered by asset.

  • action (string) – Optionally filter asset movements by action type. A valid action type (deposit, withdrawals) has to be provided. If missing movements are not filtered by type.

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

  • exclude_ignored_assets (bool) – Optional. If this is true then the asset movements of ignored assets are not returned, defaults to "true".

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_total": 120,
        "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 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.

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 occurred

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

  • 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 History Events

POST /api/(version)/history/events

Doing a POST on this endpoint with the given filter parameters will return all history events matching the filter. All arguments are optional. If nothing is given all events will be returned.

Example Request:

http

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

{
    "from_timestamp": 1500,
    "to_timestamp": 999999
}

curl

curl -i -X POST http://localhost:5042/api/1/history/events -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_timestamp": 1500, "to_timestamp": 999999}'

wget

wget -S -O- http://localhost:5042/api/1/history/events --header="Content-Type: application/json;charset=UTF-8" --post-data='{"from_timestamp": 1500, "to_timestamp": 999999}'

httpie

echo '{
  "from_timestamp": 1500,
  "to_timestamp": 999999
}' | http POST http://localhost:5042/api/1/history/events Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/history/events', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_timestamp': 1500, 'to_timestamp': 999999})
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.

  • otherargs (object) – Check the documentation of the remaining arguments here.

  • customized_events_only (bool) – Optional. If enabled the search is performed only for manually customized events. Default false.

Example Response:

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

{
    "result": {
        "events": [{
            "entry": {
                "identifier": 1,
                "entry_type": "evm event",
                "asset": "ETH",
                "balance": {"amount": "0.00863351371344", "usd_value": "0"},
                "counterparty": "gas",
                "event_identifier": "10x8d822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f",
                "event_subtype": "fee",
                "event_type": "spend",
                "location": "ethereum",
                "location_label": "0x6e15887E2CEC81434C16D587709f64603b39b545",
                "notes": "Burned 0.00863351371344 ETH for gas",
                "sequence_index": 0,
                "timestamp": 1642802807,
                "event_accounting_rule_status": "not processed",
                "tx_hash": "0x8d822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f",
                "address": null,
                "product": null
            },
            "customized": false,
            "hidden": true,
            "ignored_in_accounting": false,
            "has_details": false,
            "grouped_events_num": 1
          }, {
            "entry": {
                "identifier": 2,
                "entry_type": "evm event",
                "asset": "ETH",
                "balance": {"amount": "0.00163351371344", "usd_value": "0"},
                "counterparty": "gas",
                "event_identifier": "10x1c822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f",
                "event_subtype": "fee",
                "event_type": "spend",
                "location": "ethereum",
                "location_label": "0xce15887E2CEC81434C16D587709f64603b39b545",
                "notes": "Burned 0.00863351371344 ETH for gas",
                "sequence_index": 0,
                "timestamp": 1642802807,
                "event_accounting_rule_status": "not processed",
                "tx_hash": "0x1c822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f",
                "address": null,
                "product": null
            },
            "customized": false,
            "ignored_in_accounting": false,
            "has_details": false,
            "grouped_events_num": 3
        }, {
            "entry": {
                "identifier": 3,
                "entry_type": "eth_withdrawal_event",
                "asset": "ETH",
                "balance": {"amount": "0.00163351371344", "usd_value": "0"},
                "event_identifier": "EW_1454_20453",
                "event_subtype": "remove_asset",
                "event_type": "staking",
                "location": "ethereum",
                "location_label": "0xce15887E2CEC81434C16D587709f64603b39b545",
                "notes": "Withdrew 0.00163351371344 ETH from validator 1454",
                "sequence_index": 0,
                "timestamp": 1652802807,
                "event_accounting_rule_status": "not processed",
                "validator_index": 1454,
                "is_exit": false
            },
            "customized": false,
            "hidden": true,
            "ignored_in_accounting": false,
            "has_details": false,
            "grouped_events_num": 1
        }, {
            "entry": {
                "identifier": 4,
                "entry_type": "eth_block_event",
                "asset": "ETH",
                "balance": {"amount": "0.00163351371344", "usd_value": "0"},
                "event_identifier": "evm_1_block_15534342",
                "event_subtype": "block_production",
                "event_type": "staking",
                "location": "ethereum",
                "location_label": "0xce15887E2CEC81434C16D587709f64603b39b545",
                "notes": "Validator 1454 produced block 15534342 with 0.00163351371344 going to 0xce15887E2CEC81434C16D587709f64603b39b545 as the block reward",
                "sequence_index": 0,
                "timestamp": 1652802807,
                "event_accounting_rule_status": "not processed",
                "validator_index": 1454,
                "block_number": 15534342
            },
            "customized": false,
            "ignored_in_accounting": false,
            "has_details": false,
            "grouped_events_num": 2
        },  {
            "entry": {
                "identifier": 5,
                "entry_type": "eth deposit event",
                "asset": "ETH",
                "balance": {"amount": "32", "usd_value": "0"},
                "counterparty": "eth2",
                "event_identifier": "10x2c822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f",
                "event_subtype": "deposit asset",
                "event_type": "staking",
                "location": "ethereum",
                "location_label": "0xA215887E2CEC81434C16D587709f64603b39b545",
                "notes": "Deposit 32 ETH to validator 4242",
                "sequence_index": 15,
                "timestamp": 1642802807,
                "event_accounting_rule_status": "not processed",
                "tx_hash": "0x2c822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f",
                "address": "0x00000000219ab540356cBB839Cbe05303d7705Fa",
                "product": "staking",
                "validator_index": 4242
            },
            "customized": false,
            "ignored_in_accounting": false,
            "has_details": false,
            "grouped_events_num": 3
        }],
       "entries_found": 95,
       "entries_limit": 500,
       "entries_total": 1000
    },
    "message": ""
}
Response JSON Object:

  • decoded_events (list) – A list of history events. Each event is an object comprised of the event entry and a boolean denoting if the event has been customized by the user or not. Each entry may also have a has_details flag if true. If has_details is true, then it is possible to call /history/events/details endpoint to retrieve some extra information about the event. Also each entry may have a customized flag set to true. If it does, it means the event has been customized/added by the user. Each entry may also have a hidden flag if set to true. If it does then that means it should be hidden in the UI due to consolidation of events. Finally if group_by_event_ids exist and is true, each entry contains grouped_events_num which is an integer with the amount of events under the common event identifier. The consumer has to query this endpoint again with group_by_event_ids set to false and with the event_identifiers filter set to the identifier of the events having more than 1 event. Finally ignored_in_accounting is set to true when the user has marked this event as ignored. Following are all possible entries depending on entry type.

  • identifier (string) – Common key. This is the identifier of a single event.

  • entry_type (string) – Common key. This identifies the category of the event and determines the schema. Possible values are: "history event", "evm event", "eth withdrawal event", "eth block event", "eth deposit event".

  • event_identifier (string) – Common key. An event identifier grouping multiple events under a common group. This is how we group transaction events under a transaction, staking related events under block production etc.

  • sequence_index (int) – Common key. This is an index that tries to provide the order of history entries for a single event_identifier.

  • timestamp (int) – Common key. The timestamp of the entry

  • event_accounting_rule_status (string) – Common key. It explains the status of accounting rules for the event. Possible values are: has rule: Meaning the event has a rule. processed: meaning the event will be processed because it is affected by another event. not processed meaning it doesn’t have any rule and won’t be processed by accounting.

  • location (string) – Common key. The location of the entry. Such as “ethereum”, “optimism”, etc.

  • asset (string) – Common key. The asset involved in the event.

  • balance (object) – Common key. The balance of the asset involved in the event.

  • event_type (string) – Common key. The type of the event. Valid values are retrieved from the backend.

  • event_subtype (string) – Common key. The subtype of the event. Valid values are retrieved from the backend.

  • location_label (string) – Common key. The location_label of the event. This means different things depending on event category. For evm events it’s the initiating address. For withdrawal events the recipient address. For block production events the fee recipient.

  • notes (string) – Common key. String description of the event.

  • tx_hash (string) – Evm event & eth deposit key. The transaction hash of the event as a hex string.

  • counterparty (string) – Evm event & eth deposit key. The counterparty of the event. This is most of the times a protocol such as uniswap, but can also be an exchange name such as kraken. Possible values are requested by the backend.

  • product (string) – Evm event & eth deposit key. This is the product type with which the event interacts. Such as pool, staking contract etc. Possible values are requested by the backend.

  • address (string) – Evm event & eth deposit key. This is the address of the contract the event interacts with if there is one.

  • validator_index (int) – Eth staking (withdrawal + block production + eth deposit) key. The index of the validator related to the event.

  • is_exit (bool) – Eth withdrawal event key. A boolean denoting if the withdrawal is a full exit or not.

  • block_number (int) – Eth block event key. An integer representing the number of the block for which the event is made.

  • 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:
PUT /api/(version)/history/events

Doing a PUT on this endpoint can add a new event to rotki. For each entry type, the specified arguments are different. The unique identifier for the entry is returned as success.

Example Request:

PUT /api/(version)/history/events

http

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

{
   "entry_type": "history event",
   "event_identifier": "RE_xxxxxxxxxx",
   "location": "ethereum",
   "timestamp": 1569924574,
   "balance": {"amount": "1.542", "usd_value": "1.675"},
   "sequence_index": 162,
   "event_type": "informational",
   "event_subtype": "approve",
   "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359",
   "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12",
   "notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE"
}

curl

curl -i -X PUT http://localhost:5042/api/1/history/events -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "balance": {"amount": "1.542", "usd_value": "1.675"}, "entry_type": "history event", "event_identifier": "RE_xxxxxxxxxx", "event_subtype": "approve", "event_type": "informational", "location": "ethereum", "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE", "sequence_index": 162, "timestamp": 1569924574}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/history/events --header="Content-Type: application/json;charset=UTF-8" --body-data='{"asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "balance": {"amount": "1.542", "usd_value": "1.675"}, "entry_type": "history event", "event_identifier": "RE_xxxxxxxxxx", "event_subtype": "approve", "event_type": "informational", "location": "ethereum", "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE", "sequence_index": 162, "timestamp": 1569924574}'

httpie

echo '{
  "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359",
  "balance": {
    "amount": "1.542",
    "usd_value": "1.675"
  },
  "entry_type": "history event",
  "event_identifier": "RE_xxxxxxxxxx",
  "event_subtype": "approve",
  "event_type": "informational",
  "location": "ethereum",
  "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12",
  "notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE",
  "sequence_index": 162,
  "timestamp": 1569924574
}' | http PUT http://localhost:5042/api/1/history/events Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/history/events', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'asset': 'eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359', 'balance': {'amount': '1.542', 'usd_value': '1.675'}, 'entry_type': 'history event', 'event_identifier': 'RE_xxxxxxxxxx', 'event_subtype': 'approve', 'event_type': 'informational', 'location': 'ethereum', 'location_label': '0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12', 'notes': 'Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE', 'sequence_index': 162, 'timestamp': 1569924574})
Request JSON Object:

  • sequence_index (int) – This is an index that tries to provide the order of history entries for a single event_identifier.

  • location (string) – The location of the entry. Such as “ethereum”, “optimism”, etc.

  • asset (string) – The asset identifier for this entry

  • event_identifier (string) – The event identifier to be used for the event.

  • event_type (string) – The main event type of the entry. Possible event types can be seen in the HistoryEventType enum.

  • event_subtype (string) – The subtype for the entry. Possible event types can be seen in the HistoryEventSubType enum.

  • location_label (string[optional]) – location_label is a string field that allows to provide more information about the location. For example when we use this structure in blockchains can be used to specify the source address.

  • notes (string[optional]) – This is a description of the event entry in plain text explaining what is being done. This is supposed to be shown to the user.

Example Request:

PUT /api/(version)/history/events

http

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

{
   "entry_type": "evm event",
   "tx_hash": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e",
   "event_identifier": "10x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e",
   "sequence_index": 162,
   "timestamp": 1569924574,
   "location": "ethereum",
   "event_type": "informational",
   "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359",
   "balance": {"amount": "1.542", "usd_value": "1.675"},
   "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12",
   "notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE",
   "event_subtype": "approve",
   "counterparty": "0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE",
   "extra_data": {}
}

curl

curl -i -X PUT http://localhost:5042/api/1/history/events -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "balance": {"amount": "1.542", "usd_value": "1.675"}, "counterparty": "0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE", "entry_type": "evm event", "event_identifier": "10x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "event_subtype": "approve", "event_type": "informational", "extra_data": {}, "location": "ethereum", "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE", "sequence_index": 162, "timestamp": 1569924574, "tx_hash": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/history/events --header="Content-Type: application/json;charset=UTF-8" --body-data='{"asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "balance": {"amount": "1.542", "usd_value": "1.675"}, "counterparty": "0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE", "entry_type": "evm event", "event_identifier": "10x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "event_subtype": "approve", "event_type": "informational", "extra_data": {}, "location": "ethereum", "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE", "sequence_index": 162, "timestamp": 1569924574, "tx_hash": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e"}'

httpie

echo '{
  "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359",
  "balance": {
    "amount": "1.542",
    "usd_value": "1.675"
  },
  "counterparty": "0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE",
  "entry_type": "evm event",
  "event_identifier": "10x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e",
  "event_subtype": "approve",
  "event_type": "informational",
  "extra_data": {},
  "location": "ethereum",
  "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12",
  "notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE",
  "sequence_index": 162,
  "timestamp": 1569924574,
  "tx_hash": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e"
}' | http PUT http://localhost:5042/api/1/history/events Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/history/events', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'asset': 'eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359', 'balance': {'amount': '1.542', 'usd_value': '1.675'}, 'counterparty': '0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE', 'entry_type': 'evm event', 'event_identifier': '10x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e', 'event_subtype': 'approve', 'event_type': 'informational', 'extra_data': {}, 'location': 'ethereum', 'location_label': '0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12', 'notes': 'Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE', 'sequence_index': 162, 'timestamp': 1569924574, 'tx_hash': '0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e'})
Request JSON Object:

  • tx_hash (string) – This is the transaction hash of the evm event

  • event_identifier (string[optional]) – The event identifier to be used for the event.

  • sequence_index (int) – This is an index that tries to provide the order of history entries for a single event_identifier.

  • location (string) – The location of the entry. Such as “ethereum”, “optimism”, etc.

  • asset (string) – The asset identifier for this entry

  • event_type (string) –

    The main event type of the entry. Possible event types can be seen in the HistoryEventType enum.

  • event_subtype (string) –

    The subtype for the entry. Possible event types can be seen in the HistoryEventSubType enum.

  • location_label (string[optional]) – location_label is a string field that allows to provide more information about the location. For example when we use this structure in blockchains can be used to specify the source address.

  • notes (string[optional]) – This is a description of the event entry in plain text explaining what is being done. This is supposed to be shown to the user.

  • counterparty (string[optional]) – An identifier for a potential counterparty of the event entry. For a send it’s the target. For a receive it’s the sender. For bridged transfer it’s the bridge’s network identifier. For a protocol interaction it’s the protocol.

  • address (string[optional]) – Any relevant address that this event interacted with.

  • extra_data (object[optional]) – An object containing any other data to be stored.

Example Request:

PUT /api/(version)/history/events

http

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

{
   "entry_type": "eth block event",
   "event_identifier": "BLOCK_11",
   "timestamp": 1569924574,
   "balance": {"amount": "1.542", "usd_value": "1.675"},
   "block_number": 11,
   "validator_index": 1,
   "fee_recipient": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12",
   "is_mev_reward": true
}

curl

curl -i -X PUT http://localhost:5042/api/1/history/events -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"balance": {"amount": "1.542", "usd_value": "1.675"}, "block_number": 11, "entry_type": "eth block event", "event_identifier": "BLOCK_11", "fee_recipient": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "is_mev_reward": true, "timestamp": 1569924574, "validator_index": 1}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/history/events --header="Content-Type: application/json;charset=UTF-8" --body-data='{"balance": {"amount": "1.542", "usd_value": "1.675"}, "block_number": 11, "entry_type": "eth block event", "event_identifier": "BLOCK_11", "fee_recipient": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "is_mev_reward": true, "timestamp": 1569924574, "validator_index": 1}'

httpie

echo '{
  "balance": {
    "amount": "1.542",
    "usd_value": "1.675"
  },
  "block_number": 11,
  "entry_type": "eth block event",
  "event_identifier": "BLOCK_11",
  "fee_recipient": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12",
  "is_mev_reward": true,
  "timestamp": 1569924574,
  "validator_index": 1
}' | http PUT http://localhost:5042/api/1/history/events Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/history/events', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'balance': {'amount': '1.542', 'usd_value': '1.675'}, 'block_number': 11, 'entry_type': 'eth block event', 'event_identifier': 'BLOCK_11', 'fee_recipient': '0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12', 'is_mev_reward': True, 'timestamp': 1569924574, 'validator_index': 1})
Request JSON Object:

  • event_identifier (string[optional]) – The event identifier to be used for the event.

  • block_number (int) – This is the number of the block where the event took place.

  • validator_index (int) – This is the index of the validator.

  • fee_recipient (string) – an evm address field to specify the fee recipient in an “eth block event”.

  • is_mev_reward (bool) – true if the “eth block event” is an mev reward event.

Example Request:

PUT /api/(version)/history/events

http

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

{
   "entry_type": "eth deposit event",
   "timestamp": 1569924574,
   "balance": {"amount": "1.542", "usd_value": "1.675"},
   "tx_hash": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e",
   "event_identifier": "RE_xxxxxxxxxx",
   "validator_index": 1,
   "sequence_index": 162,
   "depositor": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12",
   "extra_data": {}
}

curl

curl -i -X PUT http://localhost:5042/api/1/history/events -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"balance": {"amount": "1.542", "usd_value": "1.675"}, "depositor": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "entry_type": "eth deposit event", "event_identifier": "RE_xxxxxxxxxx", "extra_data": {}, "sequence_index": 162, "timestamp": 1569924574, "tx_hash": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "validator_index": 1}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/history/events --header="Content-Type: application/json;charset=UTF-8" --body-data='{"balance": {"amount": "1.542", "usd_value": "1.675"}, "depositor": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "entry_type": "eth deposit event", "event_identifier": "RE_xxxxxxxxxx", "extra_data": {}, "sequence_index": 162, "timestamp": 1569924574, "tx_hash": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "validator_index": 1}'

httpie

echo '{
  "balance": {
    "amount": "1.542",
    "usd_value": "1.675"
  },
  "depositor": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12",
  "entry_type": "eth deposit event",
  "event_identifier": "RE_xxxxxxxxxx",
  "extra_data": {},
  "sequence_index": 162,
  "timestamp": 1569924574,
  "tx_hash": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e",
  "validator_index": 1
}' | http PUT http://localhost:5042/api/1/history/events Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/history/events', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'balance': {'amount': '1.542', 'usd_value': '1.675'}, 'depositor': '0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12', 'entry_type': 'eth deposit event', 'event_identifier': 'RE_xxxxxxxxxx', 'extra_data': {}, 'sequence_index': 162, 'timestamp': 1569924574, 'tx_hash': '0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e', 'validator_index': 1})
Request JSON Object:

  • tx_hash (string) – This is the transaction hash of the evm event

  • sequence_index (int) – This is an index that tries to provide the order of history entries for a single event_identifier.

  • validator_index (int) – This is the index of the validator.

  • event_identifier (string[optional]) – The event identifier to be used for the event.

  • depositor (string) – an evm address field to specify the depositor in an “eth deposit event”.

  • extra_data (object[optional]) – An object containing any other data to be stored.

Example Request:

PUT /api/(version)/history/events

http

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

{
   "entry_type": "eth withdrawal event",
   "timestamp": 1569924574,
   "balance": {"amount": "1.542", "usd_value": "1.675"},
   "is_exit": true,
   "validator_index": 1,
   "withdrawal_address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12",
   "event_identifier": "EW_XX_XXXXX"
}

curl

curl -i -X PUT http://localhost:5042/api/1/history/events -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"balance": {"amount": "1.542", "usd_value": "1.675"}, "entry_type": "eth withdrawal event", "event_identifier": "EW_XX_XXXXX", "is_exit": true, "timestamp": 1569924574, "validator_index": 1, "withdrawal_address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/history/events --header="Content-Type: application/json;charset=UTF-8" --body-data='{"balance": {"amount": "1.542", "usd_value": "1.675"}, "entry_type": "eth withdrawal event", "event_identifier": "EW_XX_XXXXX", "is_exit": true, "timestamp": 1569924574, "validator_index": 1, "withdrawal_address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12"}'

httpie

echo '{
  "balance": {
    "amount": "1.542",
    "usd_value": "1.675"
  },
  "entry_type": "eth withdrawal event",
  "event_identifier": "EW_XX_XXXXX",
  "is_exit": true,
  "timestamp": 1569924574,
  "validator_index": 1,
  "withdrawal_address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12"
}' | http PUT http://localhost:5042/api/1/history/events Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/history/events', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'balance': {'amount': '1.542', 'usd_value': '1.675'}, 'entry_type': 'eth withdrawal event', 'event_identifier': 'EW_XX_XXXXX', 'is_exit': True, 'timestamp': 1569924574, 'validator_index': 1, 'withdrawal_address': '0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12'})
Request JSON Object:

  • event_identifier (string[optional]) – The event identifier to be used for the event.

  • validator_index (int) – This is the index of the validator.

  • withdrawal_address (string) – an evm address field to specify the withdrawer in an “eth withdrawal event”.

  • is_exit (bool) – true if the “eth withdrawal event” is an exit event.

Request JSON Object:

  • entry_type (string) – The type of the event that will be processed. Different validation is used based on the value for this field. Possible values are: "history event", "evm event", "eth withdrawal event", "eth block event", "eth deposit event".

  • timestamp (int) – The timestamp of the entry in milliseconds.

  • balance (object) – The amount/usd value of the event. If not known usd_value can also be “0”.

Example Response:

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

{
    "result": {"identifier": 243},
    "message": ""
}
Response JSON Array of Objects:

  • identifier (int) – The uniquely identifying identifier for this entry.

Status Codes:
PATCH /api/(version)/history/events

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

Example Request:

http

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

{
    "entry_type": "evm event",
    "identifier": 243,
    "event_identifier": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e",
    "sequence_index": 162,
    "timestamp": 1569924574,
    "location": "blockchain",
    "event_type": "informational",
    "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359",
    "balance": {"amount": "1.542", "usd_value": "1.675"},
    "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12",
    "notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE",
    "event_subtype": "approve",
    "counterparty": "0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE"
}

curl

curl -i -X PATCH http://localhost:5042/api/1/history/events -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "balance": {"amount": "1.542", "usd_value": "1.675"}, "counterparty": "0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE", "entry_type": "evm event", "event_identifier": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "event_subtype": "approve", "event_type": "informational", "identifier": 243, "location": "blockchain", "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE", "sequence_index": 162, "timestamp": 1569924574}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/history/events --header="Content-Type: application/json;charset=UTF-8" --body-data='{"asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "balance": {"amount": "1.542", "usd_value": "1.675"}, "counterparty": "0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE", "entry_type": "evm event", "event_identifier": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "event_subtype": "approve", "event_type": "informational", "identifier": 243, "location": "blockchain", "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE", "sequence_index": 162, "timestamp": 1569924574}'

httpie

echo '{
  "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359",
  "balance": {
    "amount": "1.542",
    "usd_value": "1.675"
  },
  "counterparty": "0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE",
  "entry_type": "evm event",
  "event_identifier": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e",
  "event_subtype": "approve",
  "event_type": "informational",
  "identifier": 243,
  "location": "blockchain",
  "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12",
  "notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE",
  "sequence_index": 162,
  "timestamp": 1569924574
}' | http PATCH http://localhost:5042/api/1/history/events Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/history/events', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'asset': 'eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359', 'balance': {'amount': '1.542', 'usd_value': '1.675'}, 'counterparty': '0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE', 'entry_type': 'evm event', 'event_identifier': '0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e', 'event_subtype': 'approve', 'event_type': 'informational', 'identifier': 243, 'location': 'blockchain', 'location_label': '0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12', 'notes': 'Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE', 'sequence_index': 162, 'timestamp': 1569924574})

The request object uses all the same arguments for each entry type as the add event endpoint, with the addition of the identifier which signifies which entry will be edited.

Example Response:

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

{
    "result": true,
    "message": ""
}
Status Codes:
DELETE /api/(version)/history/events

Doing a DELETE on this endpoint deletes a set of history entry events from the DB for the currently logged in user. If any of the identifiers is not found in the DB the entire call fails. If any of the identifiers are the last for their transaction hash the call fails, unless the force_delete argument is given.

Example Request:

http

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

{"identifiers" : [55, 65, 124]}

curl

curl -i -X DELETE http://localhost:5042/api/1/history/events -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"identifiers": [55, 65, 124]}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/history/events --header="Content-Type: application/json;charset=UTF-8" --body-data='{"identifiers": [55, 65, 124]}'

httpie

echo '{
  "identifiers": [
    55,
    65,
    124
  ]
}' | http DELETE http://localhost:5042/api/1/history/events Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/history/events', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'identifiers': [55, 65, 124]})
Request JSON Object:

  • identifiers (list<integer>) – A list of the identifiers of the history entries to delete.

  • force_delete (bool) – If true, then even if an event is the last event of a transaction it will be deleted. False by default.

Example Response:

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

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

  • 200 OK – Event was successfully removed.

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

  • 409 Conflict – No user is logged in or one of the identifiers to delete did not correspond to an event in the DB or one of the identifiers was for the last event in the corresponding transaction hash and force_delete was false..

  • 500 Internal Server Error – Internal rotki error

Exporting History Events

POST /api/(version)/history/events/export

Doing a POST on this endpoint with the given filter parameters will export a csv with all history events matching the filter to a file in the provided directory. Only the ‘directory_path’ argument is required. If no filter is used all the events will be exported.

Example Request:

http

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

{
    "directory_path": "/home",
    "from_timestamp": 1500,
    "to_timestamp": 999999
}

curl

curl -i -X POST http://localhost:5042/api/1/history/events/export -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"directory_path": "/home", "from_timestamp": 1500, "to_timestamp": 999999}'

wget

wget -S -O- http://localhost:5042/api/1/history/events/export --header="Content-Type: application/json;charset=UTF-8" --post-data='{"directory_path": "/home", "from_timestamp": 1500, "to_timestamp": 999999}'

httpie

echo '{
  "directory_path": "/home",
  "from_timestamp": 1500,
  "to_timestamp": 999999
}' | http POST http://localhost:5042/api/1/history/events/export Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/history/events/export', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'directory_path': '/home', 'from_timestamp': 1500, 'to_timestamp': 999999})
Request JSON Object:

  • directory_path (string) – The directory in which to write the exported CSV file

  • otherargs (object) – Check the documentation of the remaining arguments here.

Example Response:

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

{
    "result": true,
    "message" "",
}
Status Codes:
PUT /api/(version)/history/events/export

Doing a PUT on this endpoint with the given filter parameters will download a csv with all history events matching the filter. All arguments are optional. If no filter is used all the events will be downloaded.

Example Request:

http

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

{
    "from_timestamp": 1500,
    "to_timestamp": 999999
}

curl

curl -i -X PUT http://localhost:5042/api/1/history/events/export -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_timestamp": 1500, "to_timestamp": 999999}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/history/events/export --header="Content-Type: application/json;charset=UTF-8" --body-data='{"from_timestamp": 1500, "to_timestamp": 999999}'

httpie

echo '{
  "from_timestamp": 1500,
  "to_timestamp": 999999
}' | http PUT http://localhost:5042/api/1/history/events/export Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/history/events/export', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_timestamp': 1500, 'to_timestamp': 999999})
Request JSON Object:

  • order_by_attributes (list[string]) – This is the list of attributes of the transaction by which to order the results.

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

  • group_by_event_ids (bool) – A boolean determining if results should be grouped by common event identifiers. If true, the result will return only the first event of each group but also the number of events the group has. Default is false.

  • from_timestamp (int) – The timestamp from which to start querying. Default is 0.

  • to_timestamp (int) – The timestamp until which to query. Default is now.

  • event_identifiers (list[string]) – An optional list of event identifiers to filter for.

  • event_types (list[string]) – An optional list of event types by which to filter the decoded events.

  • event_subtypes (list[string]) – An optional list of event subtypes by which to filter the decoded events.

  • location (list) – An optional location name to filter events only for that location.

  • location_labels (list[string]) – A list of location labels to optionally filter by. Location label is a string field that allows you to provide more information about the location. When used in blockchains, it is used to specify the user’s address. For exchange events, it’s the exchange name assigned by the user.

  • entry_types (object) – An object with two keys named ‘values’ and ‘behavior’. ‘values’ is a list of entry types to optionally filter by. ‘behavior’ is optional and is a string with the value ‘include’ or ‘exclude’ which defines the filtering behavior. It defaults to ‘include’. Entry type is the event category and defines the schema. Possible values are: “history event,” “evm event,” “eth withdrawal event,” “eth block event,” “eth deposit event.”

  • asset (string) – The asset to optionally filter by.

  • tx_hashes (list[string]) – An optional list of transaction hashes to filter for. This will make it an EVM event query.

  • counterparties (list[string]) – An optional list of counterparties to filter by. List of strings. This will make it an EVM event query. We currently have a special exception for “eth2” as a counterparty. It filters for all eth staking events if given. It can’t be given along with other counterparties in a filter. Or with an entry types filter.

  • products (list[string]) – An optional list of product type to filter by. List of strings. This will make it an EVM event query.

  • addresses (list[string]) – An optional list of EVM addresses to filter by in the set of counterparty addresses. This will make it an EVM event query.

  • validator_indices (list[int]) – An optional list of validator indices to filter by. This makes it an EthStakingevent query.

Example Response:

HTTP/1.1 200 OK
Content-Type: text/csv
Status Codes:

Querying online events

POST /api/(version)/history/events/query

Doing a POST on this endpoint will query latest online events for the given event type and save them in the DB

Example Request:

http

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

{
    "async_query": true,
    "query_type": "eth_withdrawals"
}

curl

curl -i -X POST http://localhost:5042/api/1/history/events/query -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": true, "query_type": "eth_withdrawals"}'

wget

wget -S -O- http://localhost:5042/api/1/history/events/query --header="Content-Type: application/json;charset=UTF-8" --post-data='{"async_query": true, "query_type": "eth_withdrawals"}'

httpie

echo '{
  "async_query": true,
  "query_type": "eth_withdrawals"
}' | http POST http://localhost:5042/api/1/history/events/query Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/history/events/query', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': True, 'query_type': 'eth_withdrawals'})
Request JSON Object:

  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

  • query_type (string) – The name of the type of events to query for. Valid values are: "eth_withdrawals", "block_productions", "exchanges"

Example Response:

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

{
   "result": true,
   "message": ""
}
Response JSON Object:

  • result (bool) – A boolean for success or failure

  • message (str) – Error message if any errors occurred.

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. Will return the id of the generated report to query.

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": 15,
    "message": ""
}
Response JSON Object:

  • result (int) – The id of the generated report to later query

Status Codes:

Export PnL report debug data

POST /api/(version)/history/debug

Note

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

Doing a POST on the PnL report debug endpoint will trigger a query and export of the history of all actions (trades, deposits, withdrawals, loans, eth transactions) within a specific time range alongside the user settings and ignored events identifiers.

Example Request:

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

  • directory_path (path) – Optional. The directory the PnL debug data should be written to.

  • async_query (bool) – Optional boolean denoting whether this is an asynchronous query or not. Defaults to false.

Example Response:

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

{
    "result": {
      "events": [
          {
          "identifier": 12,
          "event_identifier": "0xb626d9d9e3a5b9ecbe0c2194cf96ab7561063c6d31e0e6799d56a589b8094609",
          "sequence_index": 0,
          "timestamp": 1651258550,
          "location": "blockchain",
          "asset": "ETH",
          "balance": {
              "amount": "3.55448345",
              "usd_value": "24455.415502078435"
          },
          "event_type": "receive",
          "accounting_event_type": "history base entry",

          "event_subtype": null,
          "location_label": "0x19e4057A38a730be37c4DA690b103267AAE1d75d",
          "notes": "Receive 3.55448345 ETH 0xaBEA9132b05A70803a4E85094fD0e1800777fBEF -> 0x19e4057A38a730be37c4DA690b103267AAE1d75d",
          "counterparty": "0xaBEA9132b05A70803a4E85094fD0e1800777fBEF"
          },
          {
          "identifier": 8,
          "event_identifier": "0xa9905f5eaa664a53e6513f7ba2147dcebc3e54d4062df9df1925116b6a220014",
          "sequence_index": 0,
          "timestamp": 1651259834,
          "location": "blockchain",
          "accounting_event_type": "history base entry",
          "asset": "ETH",
          "balance": {
              "amount": "0.009",
              "usd_value": "33.85395142596176076"
          },
          "event_type": "spend",
          "event_subtype": "fee",
          "location_label": "0x19e4057A38a730be37c4DA690b103267AAE1d75d",
          "notes": "Burned 0.001367993179812 ETH for gas",
          "counterparty": "gas"
          }
      ],
      "settings": {
          "have_premium": false,
          "version": 32,
          "last_write_ts": 1654528773,
          "premium_should_sync": false,
          "include_crypto2crypto": true,
          "last_data_upload_ts": 0,
          "ui_floating_precision": 2,
          "taxfree_after_period": 31536000,
          "balance_save_frequency": 24,
          "include_gas_costs": true,
          "ksm_rpc_endpoint": "http://localhost:9933",
          "dot_rpc_endpoint": "",
          "main_currency": "USD",
          "date_display_format": "%d/%m/%Y %H:%M:%S %Z",
          "last_balance_save": 0,
          "submit_usage_analytics": true,
          "active_modules": [
              "uniswap",
              "eth2",
              "aave",
              "loopring",
              "balancer",
              "yearn_vaults_v2",
              "makerdao_vaults",
              "compound",
              "liquity",
              "pickle_finance",
              "nfts",
              "sushiswap"
          ],
          "frontend_settings": "{\"defi_setup_done\":false,\"timeframe_setting\":\"REMEMBER\",\"visible_timeframes\":[\"All\",\"1Y\",\"3M\",\"1M\",\"2W\",\"1W\"],\"last_known_timeframe\":\"2W\",\"query_period\":5,\"profit_loss_report_period\":{\"year\":\"2022\",\"quarter\":\"ALL\"},\"thousand_separator\":\",\",\"decimal_separator\":\".\",\"currency_location\":\"after\",\"refresh_period\":-1,\"explorers\":{},\"items_per_page\":10,\"amount_rounding_mode\":0,\"value_rounding_mode\":1,\"dark_mode_enabled\":false,\"light_theme\":{\"primary\":\"#7e4a3b\",\"accent\":\"#e45325\",\"graph\":\"#96DFD2\"},\"dark_theme\":{\"primary\":\"#ff5722\",\"accent\":\"#ff8a50\",\"graph\":\"#E96930\"},\"graph_zero_based\":false,\"nfts_in_net_value\":true,\"dashboard_tables_visible_columns\":{\"ASSETS\":[\"percentage_of_total_net_value\"],\"LIABILITIES\":[\"percentage_of_total_net_value\"],\"NFT\":[\"percentage_of_total_net_value\"]},\"date_input_format\":\"%d/%m/%Y %H:%M:%S\",\"version_update_check_frequency\":24,\"enable_ens\":true}",
          "account_for_assets_movements": true,
          "btc_derivation_gap_limit": 20,
          "calculate_past_cost_basis": true,
          "display_date_in_localtime": true,
          "current_price_oracles": [
              "coingecko",
              "cryptocompare",
              "uniswapv2",
              "uniswapv3",
          ],
          "historical_price_oracles": ["manual", "cryptocompare", "coingecko"],
          "pnl_csv_with_formulas": true,
          "pnl_csv_have_summary": false,
          "ssf_graph_multiplier": 0,
          "last_data_migration": 3,
          "non_syncing_exchanges": []
          "evmchains_to_skip_detection": []
      },
      "ignored_events_ids": {
          "trade": ["X124-JYI", "2325"],
          "ethereum transaction": ["0xfoo", "0xboo"]
      }
      "pnl_settings": {
          "from_timestamp": 0,
          "to_timestamp": 1656608820
      }
      },
    "message": ""
}
Response JSON Object:

  • result (object) – This returns the requested Pnl debug data. "events" represent the history events created within specified timestamps. "settings" represent the user settings at the point when the pnl debug was exported. "ignored_events_ids" represent action identifiers ignored by the user.

Status Codes:

Import PnL report debug data

PUT /api/(version)/history/debug
PATCH /api/(version)/history/debug

Note

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

Doing a PUT on the PnL report debug endpoint with a path to the debug PnL json file will import the history events, settings and ignored action identifiers. Doing a PATCH on the PnL report debug endpoint with the debug PnL json file will import the history events, settings and ignored action identifiers uploaded as multipart/form-data.

Example Request:

http

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

 {
      "filepath": "/home/user/Documents/pnl_debug.json",
      "async_query": true
  }

curl

curl -i -X PUT http://localhost:5042/api/1/history/debug -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": true, "filepath": "/home/user/Documents/pnl_debug.json"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/history/debug --header="Content-Type: application/json;charset=UTF-8" --body-data='{"async_query": true, "filepath": "/home/user/Documents/pnl_debug.json"}'

httpie

echo '{
  "async_query": true,
  "filepath": "/home/user/Documents/pnl_debug.json"
}' | http PUT http://localhost:5042/api/1/history/debug Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/history/debug', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': True, 'filepath': '/home/user/Documents/pnl_debug.json'})
Request JSON Object:

  • file (str) – The path to the exported debug PnL JSON file.

  • 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": true,
    "message": ""
}
Response JSON Object:

  • result (bool) – Boolean denoting success or failure of the query.

Status Codes:

  • 200 OK – Import of debug history data successfully

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

  • 409 Conflict – No user is currently logged in. Import history data does not contain required keys. Import history data contains some invalid data types. Error importing history debug data.

  • 500 Internal Server Error – Internal rotki error.

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 success or failure of the query

Status Codes:

  • 200 OK – File were exported successfully

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

Download action history CSV

GET /api/(version)/history/download

Doing a GET on the history download endpoint will download the last previously queried history to CSV files and return it in a zip file. If history has not been queried before an error is returned.

Example Request:

http

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

curl

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

wget

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

httpie

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

python-requests

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

Get missing acquisitions and prices

GET /api/(version)/history/actionable_items

Note

This endpoint should be called after getting a PnL report data.

Doing a GET on the this endpoint will return all missing acquisitions and missing prices encountered during generation of the last PnL report.

Example Request:

http

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

curl

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

wget

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

httpie

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

python-requests

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

Example Response:

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

{
  "result": {
      "report_id": 42,
      "missing_acquisitions": [
        {
          "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359v",
          "time": 1428994442,
          "found_amount": "0",
          "missing_amount": "0.1"
        },
        {
          "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359",
          "time": 1439048640,
          "found_amount": "0",
          "missing_amount": "14.36963"
        },
        {
          "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359",
          "time": 1439994442,
          "found_amount": "0",
          "missing_amount": "0.0035000000"
        },
        {
          "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359",
          "time": 1439994442,
          "found_amount": "0",
          "missing_amount": "1.7500"
        }
      ],
    "missing_prices": [
      {
        "from_asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359",
        "to_asset": "AVAX",
        "time": 1439994442,
        "rate_limited": false,
      },
      {
        "from_asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359",
        "to_asset": "USD",
        "time": 1439995442,
        "rate_limited": true,
      }
    ]
  },
  "message": ""
}
Response JSON Object:

  • result (object) – An object with missing acquisitions and prices data.

  • report_id (int) – [Optional – missing if no report was ran]. The id of the PnL report for which the actionable items were generated.

  • missing_prices (list) – A list that contains entries of missing prices found during PnL reporting.

  • missing_acquisitions (list) – A list that contains entries of missing acquisitions found during PnL reporting.

Response JSON Array of Objects:

  • from_asset (str) – The asset whose price is missing.

  • to_asset (str) – The asset in which we want the price of from_asset.

  • time (int) – The timestamp for which the price is missing.

  • asset (str) – The asset that is involved in the event.

  • time – The timestamp this event took place in.

  • found_amount (str) – The matching amount found from an acquisition event for a spend.

  • missing_amount (str) – The corresponding acquisition amount we can’t find for a particular spend.

Resjosnarr bool rate_limited:

True if we couldn’t get the price and any of the oracles got rate limited.

Status Codes:

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:

Query saved PnL Reports

GET /api/(version)/reports/(report_id)

Doing a GET on the PnL reports endpoint with an optional report id will return information for that report or for all reports. Free users can only query up to 20 saved reports.

Example Request:

http

GET /api/1/reports/4 HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/api/1/reports/4

wget

wget -S -O- http://localhost:5042/api/1/reports/4

httpie

http http://localhost:5042/api/1/reports/4

python-requests

requests.get('http://localhost:5042/api/1/reports/4')
Request JSON Object:

  • report_id (int) – An optional id to limit the query to that specific report.

Example Response:

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

{
  "result":{
    "entries":[
      {
        "identifier":2,
        "timestamp":1637931305,
        "start_ts":15,
        "end_ts":1637928988,
        "first_processed_timestamp":null,
        "last_processed_timestamp": 1602042717,
        "settings": {
            "profit_currency": "USD",
            "taxfree_after_period": 365,
            "include_crypto2crypto": true,
            "calculate_past_cost_basis": true,
            "include_gas_costs": true,
            "account_for_assets_movements": true,
            "cost_basis_method": "lifo",
            "eth_staking_taxable_after_withdrawal_enabled": true
        },
        "overview": {
            "trade": {"free": "0", "taxable": "60.1"},
            "transaction event": {"free": "0", "taxable": "40.442"},
            "fee": {"free": "10", "taxable": "55.5"}
        }
      },
      {
        "identifier":3,
        "timestamp":1637931305,
        "start_ts":0,
        "end_ts":1637928988,
        "first_processed_timestamp":null,
        "last_processed_timestamp": 1602042717,
        "settings": {
            "profit_currency": "USD",
            "taxfree_after_period": 365,
            "include_crypto2crypto": true,
            "calculate_past_cost_basis": true,
            "include_gas_costs": true,
            "account_for_assets_movements": true,
            "cost_basis_method": "fifo",
            "eth_staking_taxable_after_withdrawal_enabled": false
        },
        "overview": {
            "trade": {"free": "0", "taxable": "60.1"},
            "fee": {"free": "10", "taxable": "55.5"}
        }
      },
      {
        "identifier":4,
        "timestamp":1647931305,
        "start_ts":0,
        "end_ts":1637928988,
        "first_processed_timestamp":null,
        "last_processed_timestamp": 1602042717,
        "settings": {
            "profit_currency": "USD",
            "taxfree_after_period": 365,
            "include_crypto2crypto": true,
            "calculate_past_cost_basis": true,
            "include_gas_costs": true,
            "account_for_assets_movements": true,
            "cost_basis_method": "fifo",
            "eth_staking_taxable_after_withdrawal_enabled": false
        },
        "overview": {
            "asset movement": {"free": "0", "taxable": "5"},
            "fee": {"free": "10", "taxable": "55.5"}
        }
      }
    ],
    "entries_found":3,
    "entries_limit":20
  },
  "message":""
}
Response JSON Object:

  • identifier (int) – The identifier of the PnL report

  • start_ts (int) – The end unix timestamp of the PnL report

  • end_ts (int) – The end unix timestamp of the PnL report

  • first_processed_timestamp (int) – The timestamp of the first even we processed in the PnL report or 0 for empty report.

  • overview (object) – The overview contains an entry for totals per event type. Each entry contains pnl breakdown (free/taxable for now).

  • last_processed_timestamp (int) – The timestamp of the last processed action. This helps us figure out when was the last action the backend processed and if it was before the start of the PnL period to warn the user WHY the PnL is empty.

  • processed_actions (int) – The number of actions processed by the PnL report. This is not the same as the events shown within the report as some of them may be before the time period of the report started. This may be smaller than “total_actions”.

  • total_actions (int) – The total number of actions to be processed by the PnL report. This is not the same as the events shown within the report as some of them they may be before or after the time period of the report.

  • entries_found (int) – The number of reports found if called without a specific report id.

  • entries_limit (int) – -1 if there is no limit (premium). Otherwise the limit of saved reports to inspect is 20.

Settings This object contains an entry per PnL report setting. :resjson str profit_currency: The identifier of the asset used as profit currency in the PnL report. :resjson integer taxfree_after_period: An optional integer for the value of taxfree_after_period setting. Can be either null or an integer. :resjson bool include_crypto2crypto: The value of the setting used in the PnL report. :resjson bool calculate_past_cost_basis: The value of the setting used in the PnL report. :resjson bool include_gas_costs: The value of the setting used in the PnL report. :resjson bool account_for_assets_movements: The value of the setting used in the PnL report. :resjson str cost_basis_method: The method for cost basis calculation. Either fifo or lifo. :resjson bool eth_staking_taxable_after_withdrawal_enabled: A boolean indicating whether the staking of ETH is taxable only after the merge and withdrawals are enabled (true) or (false) if each eth staking event is considered taxable at the point of receiving if if you can’t yet withdraw. :statuscode 200: Data were queried successfully. :statuscode 409: No user is currently logged in. :statuscode 500: Internal rotki error.

Get saved events of a PnL Report

POST /api/(version)/reports/(report_id)/data

Doing a POST on the PnL reports data endpoint with a specific report id and optional pagination and timestamp filtering will query the events of the given report.

Example Request:

http

POST /api/1/reports/4/data HTTP/1.1
Host: localhost:5042

curl

curl -i -X POST http://localhost:5042/api/1/reports/4/data

wget

wget -S -O- http://localhost:5042/api/1/reports/4/data

httpie

http POST http://localhost:5042/api/1/reports/4/data

python-requests

requests.post('http://localhost:5042/api/1/reports/4/data')
Request JSON Object:

  • report_id (int) – Optional. The id of the report to query as a view arg.

  • limit (int) – Optional. 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.

  • from_timestamp (str) – Optional. A filter for the from_timestamp of the range of events to query.

  • to_timestamp (str) – Optional. A filter for the to_timestamp of the range of events to query.

  • order_by_attributes (list[string]) – Optional. Default is [“timestamp”]. The list of the attributes to order results by.

  • ascending (list[bool]) – Optional. Default is [false]. The order in which to return results depending on the order by attribute.

  • event_type (str) – Optional. Not used yet. In the future will be a filter for the type of event to query.

Example Response:

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

{
  "result": {
      "entries": [{
          "asset": "BTC",
          "cost_basis": {
              "is_complete": true,
              "matched_acquisitions": [
                  {
                      "amount": "0.001",
                      "event": {
                          "full_amount": "1",
                          "index": 11,
                          "rate": "100.1",
                          "timestamp": 1458994442
                      },
                      "taxable": false}
               ]},
          "free_amount": "1E-11",
          "location": "bitmex",
          "notes": "bitmex withdrawal",
          "pnl_free": "-1.0010E-9",
          "pnl_taxable": "0.00",
          "price": "9367.55",
          "taxable_amount": "0",
          "timestamp": 1566572401,
          "type": "asset movement"
      }, {
          "asset": "XMR",
          "cost_basis": null,
          "free_amount": "0",
          "location": "poloniex",
          "notes": "Buy XMR(Monero) with ETH(Ethereum).Amount in",
          "pnl_free": "0",
          "pnl_taxable": "0",
          "price": "12.47924607060",
          "taxable_amount": "1.40308443",
          "timestamp": 1539713238,
          "type": "trade"
  }],
  "entries_found": 2,
  "entries_limit": 1000
 },
 "message": ""
}
Response JSON Object:

  • asset (str) – The asset that is involved in the event.

  • cost_basis (object) – Can be null. 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 an "amount" attribute denoting how much of the acquisition event this entry uses. A "taxable" attribute denoting if this acquisition concerns taxable or tax-free spend. Then there is also an event which shows the full event. It’s attributes show the full amount bought, when, at what rate and the index of the event in the PnL report.

  • free_amount (str) – The amount of the event that counts as tax free.

  • taxable_amount (str) – The amount of the event that counts as taxable.

  • location (str) – The location this event took place in.

  • notes (str) – A description of the event.

  • pnl_free (str) – The non-taxable profit/loss caused by this event.

  • pnl_taxable (str) – The taxable profit/loss caused by this event.

  • price (str) – The price in profit_currency for asset used

  • taxable_amount – The amount of the event that counts as taxable.

  • timestamp (int) – The timestamp this event took place in.

  • type (str) – The type of event. Can be any of the possible accounting event types.

  • group_id (str) – Optional. Can be missing. An id signifying events that should be grouped together in the frontend. If missing no grouping needs to happen.

Status Codes:

Purge PnL report and all its data

DELETE /api/(version)/reports/(report_id)

Doing a DELETE on the PnL reports endpoint with a specific report will remove the given report and all of its saved events from the DB.

Example Request:

http

DELETE /api/1/reports/4 HTTP/1.1
Host: localhost:5042

curl

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

wget

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

httpie

http DELETE http://localhost:5042/api/1/reports/4

python-requests

requests.delete('http://localhost:5042/api/1/reports/4')
Request JSON Object:

  • report_id (int) – The id of the report to delete as a view arg.

Example Response:

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

{
    "result": true
    "message": ""
}
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/periodic HTTP/1.1
Host: localhost:5042

curl

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

wget

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

httpie

http http://localhost:5042/api/1/periodic

python-requests

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

Example Response:

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

{
    "result": {
        "last_balance_save": 1572345881,
        "connected_nodes": {
            "eth": ["nodeX", "nodeY"],
            "optimism": ["nodeW", "nodeZ"],
            "polygon_pos": ["nodeA", "nodeB"],
        },
        "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.

  • last_data_upload_ts (int) – The last time (unix timestamp) at which a new DB was pushed to the remote as backup.

  • connected_nodes (object) – A dictionary containing the evm chain name and a list of connected nodes.

Status Codes:

Getting blockchain account data

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

Note

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

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

Example Request:

http

GET /api/1/blockchains/eth/accounts HTTP/1.1
Host: localhost:5042

curl

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

wget

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

httpie

http http://localhost:5042/api/1/blockchains/eth/accounts

python-requests

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

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

  • 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. Should never by an empty list.

Status Codes:

Example Request:

http

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

curl

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

wget

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

httpie

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

python-requests

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

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. Should never be an empty list.

  • 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 the same 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 successfully 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 successfully 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 occurred.

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

Status Codes:

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": "eip155:1/erc20: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 successfully 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": "eip155:1/erc20: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 occurred 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:

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": {
                "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F": {
                    "balance": {
                        "amount": "350.0",
                        "usd_value": "351.21"
                    },
                    "apy": "3.51%"
                },
                "eip155:1/erc20:0xdd974D5C2e2928deA5F71b9825b8b646686BD200": {
                    "balance": {
                        "amount": "220.21",
                        "usd_value": "363.3465"
                    },
                    "apy": "0.53%"
                },
            },
            "borrowing": {
                "eip155:1/erc20:0x80fB784B7eD66730e8b1DBd9820aFD29931aab03": {
                    "balance": {
                        "amount": "590.21",
                        "usd_value": "146.076975"
                    },
                    "variable_apr": "7.46%"
                    "stable_apr": "9.03%"
                }
            }
        },
        "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237": {
            "lending": {},
            "borrowing": {
                "eip155:1/erc20: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 successfully 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 stats

GET /api/(version)/blockchains/eth/modules/aave/stats

Doing a GET on the aave stats resource will return the 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/stats HTTP/1.1
Host: localhost:5042

curl

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

wget

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

httpie

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

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/modules/aave/stats')
Request JSON Object:

  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

  • from_timestamp (int) – Timestamp from which to query aave historical data. If not given 0 is implied.

  • to_timestamp (int) – Timestamp until which to query aave historical data. If not given current timestamp is implied.

Example Response:

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

{
    "result": {
        "0xA0B6B7fEa3a3ce3b9e6512c0c5A157a385e81056": {
            "total_earned": {
                "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F": {
                    "amount": "0.9482",
                    "usd_value": "1.001"
                },
                "eip155:1/erc20:0xE41d2489571d322189246DaFA5ebDe1F4699F498": {
                    "amount": "0.523",
                    "usd_value": "0.0253"
                }
            },
            "total_lost": {
                "eip155:1/erc20:0xFC4B8ED459e00e5400be803A9BB3954234FD50e3": {
                    "amount": "0.3212",
                    "usd_value": "3560.32"
                }
            },
            "total_earned_liquidations": {},
        },
        "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237": {
            "total_earned_interest": {
                "eip155:1/erc20: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.

  • 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 asset during liquidations.

Status Codes:

  • 200 OK – Aave history successfully queried.

  • 400 Bad Request – Requested module is not allowed to query statistics.

  • 401 Unauthorized – No user is currently logged in or currently logged in user does not have a premium subscription.

  • 409 Conflict – 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 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": "eip155:1/erc20:0xFC4B8ED459e00e5400be803A9BB3954234FD50e3",
            "total_amount": "2326.81686488",
            "user_balance": {
              "amount": "331.3943886097855861540937492",
              "usd_value": "497.0915829146783792311406238"
            },
            "usd_price": "1.5",
            "weight": "50"
          },
          {
            "token": "eip155:1/erc20: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": "eip155:1/erc20:0x2ba592F78dB6436527729929AAf6c908497cB200",
            "total_amount": "3728.283461100135483274",
            "user_balance": {
              "amount": "3115.861971106915456546519315",
              "usd_value": "4673.792956660373184819778972"
            },
            "usd_price": "1.5",
            "weight": "75.0"
          },
          {
            "token": "eip155:1/erc20: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:

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": "eip155:1/erc20:0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "weight": "20" },
                { "token": "eip155:1/erc20: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": {
                    "eip155:1/erc20:0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2": "0.05",
                    "eip155:1/erc20:0xba100000625a3754423978a60c9317c58a424e3D": "0"
                  }
                },
                {
                  "tx_hash": "0xfa1dfeb83480e51a15137a93cb0eba9ac92c1b6b0ee0bd8551a422c1ed83695b",
                  "log_index": 92,
                  "timestamp": 1597243001,
                  "event_type": "burn",
                  "lp_balance": {
                    "amount": "0.042569019597126949",
                    "usd_value": "19.01364749076136579119809947"
                  },
                  "amounts": {
                    "eip155:1/erc20:0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2": "0.010687148200906598",
                    "eip155:1/erc20:0xba100000625a3754423978a60c9317c58a424e3D": "0.744372160905819159"
                  }
                }
              ],
              "profit_loss_amounts": {
                "eip155:1/erc20:0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2": "-0.039312851799093402",
                "eip155:1/erc20: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:

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": {
                "eip155:1/erc20:0xc00e94Cb662C3520282E6f5717214004A7f26888": {
                    "balance" :{
                        "amount": "3.5",
                        "usd_value": "892.5",
                    }
                }
            },
            "lending": {
                "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F": {
                    "balance": {
                        "amount": "350.0",
                        "usd_value": "351.21"
                    },
                    "apy": "3.51%"
                },
                "eip155:1/erc20:0xFC4B8ED459e00e5400be803A9BB3954234FD50e3": {
                    "balance": {
                        "amount": "1",
                        "usd_value": "9500"
                    },
                    "apy": null,
                },
            },
            "borrowing": {
                "ETH": {
                    "balance": {
                        "amount": "10",
                        "usd_value": "3450"
                    },
                    "apy": "7.46%"
                }
            }
        },
        "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237": {
            "lending": {},
            "borrowing": {
                "eip155:1/erc20: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:

Getting compound statistics

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

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 stats resource will return information related profit and loss of the events present in the database.

Example Request:

http

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

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/ETH/modules/compound/stats

wget

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

httpie

http http://localhost:5042/api/1/blockchains/ETH/modules/compound/stats

python-requests

requests.get('http://localhost:5042/api/1/blockchains/ETH/modules/compound/stats')
Request JSON Object:

  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

  • 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":{
    "interest_profit":{
      "0xA0B6B7fEa3a3ce3b9e6512c0c5A157a385e81056":{
        "eip155:1/erc20:0xc00e94Cb662C3520282E6f5717214004A7f26888":{
          "amount":"3.5",
          "usd_value":"892.5"
        },
        "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F":{
          "amount":"250",
          "usd_value":"261.1"
        }
      },
      "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237":{
        "eip155:1/erc20: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":{
        "eip155:1/erc20:0xc00e94Cb662C3520282E6f5717214004A7f26888":{
          "amount":"3.5",
          "usd_value":"892.5"
        }
      }
    }
  },
  "message":""
}
Response JSON Object:

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

Status Codes:

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": "eip155:1/erc20: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:

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": {
          "balances": {
            "staked": {
              "asset": "ETH",
              "amount": "43.180853032438783295",
              "usd_value": "43.180853032438783295",
            },
            "lusd_rewards": {
              "asset": "eip155:1/erc20:0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D",
              "amount": "94477.70111867384658505",
              "usd_value": "94477.70111867384658505",
            },
            "eth_rewards": {
              "asset": "eip155:1/erc20:0x5f98805A4E8be255a32880FDeC7F6728C6568bA0",
              "amount": "10211401.723115634393264567",
              "usd_value": "10211401.723115634393264567",
            }
          },
          "proxies": {
              "0x063c26fF1592688B73d8e2A18BA4C23654e2792E": {
                "staked": {
                  "asset": "ETH",
                  "amount": "43.180853032438783295",
                  "usd_value": "43.180853032438783295",
                },
                "lusd_rewards": {
                  "asset": "eip155:1/erc20:0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D",
                  "amount": "94477.70111867384658505",
                  "usd_value": "94477.70111867384658505",
                },
                "eth_rewards": {
                  "asset": "eip155:1/erc20:0x5f98805A4E8be255a32880FDeC7F6728C6568bA0",
                  "amount": "10211401.723115634393264567",
                  "usd_value": "10211401.723115634393264567",
                }
          }
      }
    },
    "message": ""
}
Response JSON Object:

  • optional[balances] (object) – A mapping of the category to the amount & value of assets staked in the protocol.

  • optional[proxies] (object) – A mapping of proxy addresses to the amount and value of assets staked in the protocol.

Status Codes:

Getting Liquity stability pool information

GET /api/(version)/blockchains/eth/modules/liquity/pool

Doing a GET on the liquity stability pool resource will return the balances deposited in it and the rewards accrued.

Note

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

Note

This endpoint requires a premium account.

Example Request:

http

GET /api/1/blockchains/eth/modules/liquity/pool HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/eth/modules/liquity/pool

wget

wget -S -O- http://localhost:5042/api/1/blockchains/eth/modules/liquity/pool

httpie

http http://localhost:5042/api/1/blockchains/eth/modules/liquity/pool

python-requests

requests.get('http://localhost:5042/api/1/blockchains/eth/modules/liquity/pool')
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": {
          "balances": {
            "gains": {
              "asset": "ETH",
              "amount": "43.180853032438783295",
              "usd_value": "43.180853032438783295",
            },
            "rewards": {
              "asset": "eip155:1/erc20:0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D",
              "amount": "94477.70111867384658505",
              "usd_value": "94477.70111867384658505",
            },
            "deposited": {
              "asset": "eip155:1/erc20:0x5f98805A4E8be255a32880FDeC7F6728C6568bA0",
              "amount": "10211401.723115634393264567",
              "usd_value": "10211401.723115634393264567",
            }
          },
          "proxies": {
              "0x063c26fF1592688B73d8e2A18BA4C23654e2792E": {
                "gains": {
                  "asset": "ETH",
                  "amount": "43.180853032438783295",
                  "usd_value": "43.180853032438783295",
                },
                "rewards": {
                  "asset": "eip155:1/erc20:0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D",
                  "amount": "94477.70111867384658505",
                  "usd_value": "94477.70111867384658505",
                },
                "deposited": {
                  "asset": "eip155:1/erc20:0x5f98805A4E8be255a32880FDeC7F6728C6568bA0",
                  "amount": "10211401.723115634393264567",
                  "usd_value": "10211401.723115634393264567",
                }
          }
      }
    },
    "message": ""
}
Response JSON Object:

  • balances (object) – A mapping of the category to the amount & value of assets staked in the protocol.

  • proxies (object) – A mapping of proxy addresses to the amount and value of assets staked in the protocol.

  • deposited (object) – Information about the amount and usd value of the LUSD deposited.

  • gains (object) – Information about the amount and usd value of the ETH gained as reward for liquidations.

  • rewards (object) – Information about the amount and usd value of the LQTY rewards gained.

Status Codes:

Getting Liquity staking information

GET /api/(version)/blockchains/eth/modules/liquity/stats

Doing a GET on the liquity stats resource will return the statistics for staking in the stability pool and the LQTY staking service.

Note

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

Note

This endpoint requires a premium account.

Example Request:

http

GET /api/1/blockchains/eth/modules/liquity/stats HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/eth/modules/liquity/stats

wget

wget -S -O- http://localhost:5042/api/1/blockchains/eth/modules/liquity/stats

httpie

http http://localhost:5042/api/1/blockchains/eth/modules/liquity/stats

python-requests

requests.get('http://localhost:5042/api/1/blockchains/eth/modules/liquity/stats')
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": {
    "global_stats": {
      "total_usd_gains_stability_pool": "41902.74041824219",
      "total_usd_gains_staking": "190.09104568340678",
      "total_deposited_stability_pool": "1915600.7290263602",
      "total_withdrawn_stability_pool": "914454.5094041774",
      "total_deposited_stability_pool_usd_value": "0.0",
      "total_withdrawn_stability_pool_usd_value": "0.0",
      "staking_gains": [
        {
          "asset": "ETH",
          "amount": "0.19015022103888912",
          "usd_value": "23.001055387590114"
        },
        {
          "asset": "eip155:1/erc20:0x5f98805A4E8be255a32880FDeC7F6728C6568bA0",
          "amount": "168.7710091203543",
          "usd_value": "167.08999029581668"
        },
        {
          "asset": "eip155:1/erc20:0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D",
          "amount": "1445.7823568041297",
          "usd_value": "0.0"
        }
      ],
      "stability_pool_gains": [
        {
          "asset": "ETH",
          "amount": "14.0767134582469",
          "usd_value": "31051.389153894255"
        },
        {
          "asset": "eip155:1/erc20:0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D",
          "amount": "11887.091269011284",
          "usd_value": "10851.35126434794"
        }
      ]
    },
    "by_address": {
      "0xF662f831361c8Ab48d807f7753eb3d641be25d24": {
        "total_usd_gains_stability_pool": "0.0",
        "total_usd_gains_staking": "0.0",
        "total_deposited_stability_pool": "1519146.7290263602",
        "total_withdrawn_stability_pool": "914454.5094041774",
        "total_deposited_stability_pool_usd_value": "0.0",
        "total_withdrawn_stability_pool_usd_value": "0.0",
        "staking_gains": [
          {
            "asset": "ETH",
            "amount": "0.18236022449762773",
            "usd_value": "0.0"
          },
          {
            "asset": "eip155:1/erc20:0x5f98805A4E8be255a32880FDeC7F6728C6568bA0",
            "amount": "2.23017071973649",
            "usd_value": "0.0"
          },
          {
            "asset": "eip155:1/erc20:0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D",
            "amount": "1445.7823568041297",
            "usd_value": "0.0"
          }
        ],
        "stability_pool_gains": [
          {
            "asset": "ETH",
            "amount": "1.7820064710306824",
            "usd_value": "0.0"
          },
          {
            "asset": "eip155:1/erc20:0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D",
            "amount": "7646.741845927703",
            "usd_value": "0.0"
          }
        ]
      },
      "0xbB8311c7bAD518f0D8f907Cad26c5CcC85a06dC4": {
        "total_usd_gains_stability_pool": "41902.74041824219",
        "total_usd_gains_staking": "190.09104568340678",
        "total_deposited_stability_pool": "396454.0",
        "total_withdrawn_stability_pool": "0",
        "total_deposited_stability_pool_usd_value": "0.0",
        "total_withdrawn_stability_pool_usd_value": "0",
        "staking_gains": [
          {
            "asset": "ETH",
            "amount": "0.007789996541261418",
            "usd_value": "23.001055387590114"
          },
          {
            "asset": "eip155:1/erc20:0x5f98805A4E8be255a32880FDeC7F6728C6568bA0",
            "amount": "166.54083840061782",
            "usd_value": "167.08999029581668"
          }
        ],
        "stability_pool_gains": [
          {
            "asset": "ETH",
            "amount": "12.294706987216218",
            "usd_value": "31051.389153894255"
          },
          {
            "asset": "eip155:1/erc20:0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D",
            "amount": "4240.34942308358",
            "usd_value": "10851.35126434794"
          }
        ]
      }
    }
  },
  "message": ""
}
Response JSON Object:

  • result (object) – A mapping with the keys global_stats and by_address.

  • global_stats (object) – Stats aggregating the information for all the addresses tracked in the liquity module.

  • global_stats – Breakdown by tracked address of the stats.

  • total_usd_gains_stability_pool (string) – Sum of all the gains valued at the moment of the event for the stability pool.

  • total_usd_gains_staking (string) – Sum of all the gains valued at the moment of the event for liquity staking.

  • total_deposited_stability_pool (string) – Total amount of LUSD deposited in the stability pool.

  • total_withdrawn_stability_pool (string) – Total amount of LUSD withdrawn from the stability pool.

  • total_deposited_stability_pool_usd_value (string) – Sum of the USD value deposited in the stability pool at the time of the events.

  • total_withdrawn_stability_pool_usd_value (string) – Sum of the USD value withdrawn from the stability pool at the time of the events.

  • staking_gains (list[object]) – Breakdown by asset of the gains claimed by staking.

  • stability_pool_gains (list[object]) – Breakdown by asset of the gains claimed by depositing in the stability pool.

Status Codes:

Getting Uniswap balances

GET /api/(version)/blockchains/eth/modules/uniswap/v2/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/v2/balances HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/eth/modules/uniswap/v2/balances

wget

wget -S -O- http://localhost:5042/api/1/blockchains/eth/modules/uniswap/v2/balances

httpie

http http://localhost:5042/api/1/blockchains/eth/modules/uniswap/v2/balances

python-requests

requests.get('http://localhost:5042/api/1/blockchains/eth/modules/uniswap/v2/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": "eip155:1/erc20: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:

Getting Uniswap V3 balances

GET /api/(version)/blockchains/eth/modules/uniswap/v3/balances

Doing a GET on the uniswap v3 balances resource will return the balances locked in Uniswap V3 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/v3/balances HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/eth/modules/uniswap/v3/balances

wget

wget -S -O- http://localhost:5042/api/1/blockchains/eth/modules/uniswap/v3/balances

httpie

http http://localhost:5042/api/1/blockchains/eth/modules/uniswap/v3/balances

python-requests

requests.get('http://localhost:5042/api/1/blockchains/eth/modules/uniswap/v3/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",
        "nft_id": 223251,
        "price_range": ["1000", "1500"],
        "assets": [
          {
            "asset": {
              "ethereum_address": "0x364A7381A5b378CeD7AB33d1CDf6ff1bf162Bfd6",
              "name": "DeFi-X Token",
              "symbol": "TGX"
            },
            "total_amount": "410064.7008276195",
            "usd_price": "0.3015901111469715543448531276626107",
            "user_balance": {
              "amount": "4.631122964837017895643",
              "usd_value": "1334263.191525095084350185834"
            }
          },
          {
            "asset": "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7",
            "total_amount": "1251.608339987909",
            "usd_price": "1.001",
            "user_balance": {
              "amount": "1336837.868136041506994516873",
              "usd_value": "1338174.706004177548501511390"
            }
          }
        ],
        "total_supply": null,
        "user_balance": {
          "amount": "0",
          "usd_value": "2672437.897529272632851697224"
        }
      }
    ],
  },
  "message": "",
}
Response JSON Object:

  • result (object) – A mapping between accounts and their Uniswap V3 balances (represented by a list where each item is a LP).

  • address (string) – The LP contract address.

  • nft_id (int) – The LP position NFT ID.

  • price_range (string) – The range of prices the LP position is valid for.

  • 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. "usd_price" is the token USD price. "user_balance" contains the user token balance and its estimated USD value.

  • total_supply (string) – The total amount of liquidity tokens the LP has. This is null as Uniswap V3 does not store LP as tokens.

  • user_balance (object) – The liquidity token user balance and its USD value.

Status Codes:

Getting Uniswap/Sushiswap events

GET /api/(version)/blockchains/eth/modules/{module}/stats

Doing a GET on the uniswap/sushiswap stats endpoint will return information about the profit and loss on uniswap/sushiswap events for the selected range.

Note

This endpoint is only available for premium users

Note

module can only be one of uniswap or sushiswap for this endpoint.

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": [
            {
                "pool_address": "0x2C7a51A357d5739C5C74Bf3C96816849d2c9F726",
                "profit_loss0": "264.089867496935331902",
                "profit_loss1": "88.677078283001177264",
                "token0": "eip155:1/erc20:0x0e2298E3B3390e3b945a5456fBf59eCc3f55DA16",
                "token1": "eip155:1/erc20:0xdF5e0e81Dff6FAF3A7e52BA697820c5e32D806A8",
                "usd_profit_loss": "162.1876736563418464415499063"
            }
        ]
    }
}
Response JSON Object:

  • result (object) – A mapping between accounts and their Uniswap events stats per pool.

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

Getting yearn finance vaults balances

GET /api/(version)/blockchains/eth/modules/yearn/vaults/balances

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 yearn finance vaults balances resource will return all yearn vault balances.

Example Request:

http

GET /api/1/blockchains/eth/modules/yearn/vaults/balances HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/eth/modules/yearn/vaults/balances

wget

wget -S -O- http://localhost:5042/api/1/blockchains/eth/modules/yearn/vaults/balances

httpie

http http://localhost:5042/api/1/blockchains/eth/modules/yearn/vaults/balances

python-requests

requests.get('http://localhost:5042/api/1/blockchains/eth/modules/yearn/vaults/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": {
        "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237": {
            "YCRV Vault": {
                "underlying_token": "eip155:1/erc20:0xdF5e0e81Dff6FAF3A7e52BA697820c5e32D806A8",
                "vault_token": "eip155:1/erc20:0x5dbcF33D8c2E976c6b560249878e6F1491Bca25c",
                "underlying_value": {
                    "amount": "25", "usd_value": "150"
                },
                "vault_value": {
                    "amount": "19", "usd_value": "150"
                },
                "roi": "25.55%"
            },
            "YYFI Vault": {
                "underlying_token": "eip155:1/erc20:0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e",
                "vault_token": "eip155:1/erc20:0xBA2E7Fed597fd0E3e70f5130BcDbbFE06bB94fe1",
                "underlying_value": {
                    "amount": "25", "usd_value": "150"
                },
                "vault_value": {
                    "amount": "19", "usd_value": "150"
                }
            }
        },
    "0xA0B6B7fEa3a3ce3b9e6512c0c5A157a385e81056": {
        "YALINK Vault": {
                "underlying_token": "eip155:1/erc20:0xA64BD6C70Cb9051F6A9ba1F163Fdc07E0DfB5F84",
                "vault_token": "eip155:1/erc20:0x29E240CFD7946BA20895a7a02eDb25C210f9f324",
                "underlying_value": {
                    "amount": "25", "usd_value": "150"
                },
                "vault_value": {
                    "amount": "19", "usd_value": "150"
                },
                "roi": "35.15%"
        }
    }
    },
    "message": ""
}
Response JSON Object:

  • result (object) – A mapping of addresses to a mapping of vault names to vault balances

Response JSON Array of Objects:

  • underlying_token (string) – The symbol of the token that is deposited to the vault

  • vault_token (string) – The symbol of the token that is minted when you deposit underlying token to the vault

  • underlying_value (object) – The value of the underlying token for the vault.

  • vault_value (object) – The value of the vault token for the vault.

  • roi (optional[string]) – An optional string. The Return of Investment for the vault since its creation.

Status Codes:

Getting yearn finance vaults historical data

GET /api/(version)/blockchains/eth/modules/yearn/vaults/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 yearn finance vaults history resource will return all yearn vault related events for addresses that have utilized yearn finance vaults.

Example Request:

http

GET /api/1/blockchains/eth/modules/yearn/vaults/history HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/eth/modules/yearn/vaults/history

wget

wget -S -O- http://localhost:5042/api/1/blockchains/eth/modules/yearn/vaults/history

httpie

http http://localhost:5042/api/1/blockchains/eth/modules/yearn/vaults/history

python-requests

requests.get('http://localhost:5042/api/1/blockchains/eth/modules/yearn/vaults/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 yearn 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 yearn vaults historical data. If not given 0 is implied.

  • to_timestamp (int) – Timestamp until which to query yearn vaults historical data. If not given current timestamp is implied.

Example Response:

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

{
    "result": {
        "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237": {
            "YCRV Vault": {
                "events": [{
                    "event_type": "deposit",
                    "block_number": 1,
                    "timestamp": 1,
                    "from_asset": "eip155:1/erc20:0xdF5e0e81Dff6FAF3A7e52BA697820c5e32D806A8",
                    "from_value": {
                        "amount": "115000", "usd_value": "119523.23"
                    },
                    "to_asset": "eip155:1/erc20:0xdF5e0e81Dff6FAF3A7e52BA697820c5e32D806A8",
                    "to_value": {
                        "amount": "108230.234", "usd_value": "119523.23"
                    },
                    "realized_pnl": null,
                    "tx_hash": "0x188aea85b54c5b2834b144e9f7628b524bf9faf3b87821aa520b7bcfb57ab289",
                    "log_index": 1
                }, {
                    "event_type": "withdraw",
                    "block_number": 1,
                    "timestamp": 1,
                    "from_asset": "eip155:1/erc20:0xdF5e0e81Dff6FAF3A7e52BA697820c5e32D806A8",
                    "from_value": {
                        "amount": "108230.234", "usd_value": "125321.24"
                    },
                    "to_asset": "eip155:1/erc20:0xdF5e0e81Dff6FAF3A7e52BA697820c5e32D806A8",
                    "to_value": {
                        "amount": "117500.23", "usd_value": "123500.32"
                    },
                    "realized_pnl": {
                        "amount": "2500.23", "usd_value": "2750.452"
                    },
                    "tx_hash": "0x188aea85b54c5b2834b144e9f7628b524bf9faf3b87821aa520b7bcfb57ab289",
                    "log_index": 1
                }],
                "profit_loss": {
                        "amount": "2500.23", "usd_value": "2750.452"
                }
            },
            "YYFI Vault": {
                "events": [{
                    "event_type": "deposit",
                    "block_number": 1,
                    "timestamp": 1,
                    "from_asset": "eip155:1/erc20:0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e",
                    "from_value": {
                        "amount": "5", "usd_value": "155300.23"
                    },
                    "to_asset": "yYFI",
                    "to_value": {
                        "amount": "4.97423", "usd_value": "154300.44"
                    },
                    "realized_pnl": null,
                    "tx_hash": "0x188aea85b54c5b2834b144e9f7628b524bf9faf3b87821aa520b7bcfb57ab289",
                    "log_index": 1
                }],
                "profit_loss": {
                        "amount": "0.05", "usd_value": "1500"
                }
        }
    },
    "0xA0B6B7fEa3a3ce3b9e6512c0c5A157a385e81056": {
        "YSRENCURVE Vault": {
                "events": [{
                    "event_type": "deposit",
                    "block_number": 1,
                    "timestamp": 1,
                    "from_asset": "eip155:1/erc20:0x075b1bb99792c9E1041bA13afEf80C91a1e70fB3",
                    "from_value": {
                        "amount": "20", "usd_value": "205213.12"
                    },
                    "to_asset": "eip155:1/erc20:0x7Ff566E1d69DEfF32a7b244aE7276b9f90e9D0f6",
                    "to_value": {
                        "amount": "19.8523", "usd_value": "2049874.23"
                    },
                    "realized_pnl": null,
                    "tx_hash": "0x188aea85b54c5b2834b144e9f7628b524bf9faf3b87821aa520b7bcfb57ab289",
                    "log_index": 1
                }],
                "profit_loss": {
                        "amount": "0.1", "usd_value": "1984.23"
                }
        }
    }},
    "message": ""
}
Response JSON Object:

  • result (object) – A mapping of addresses to vault history results

  • profit_loss (object) – The total profit/loss for the vault

Response JSON Array of Objects:

  • event_type (string) – The type of the yearn vault event. - "deposit": when you deposit a token in the vault - "withdraw": when you withdraw a token from the vault

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

  • block_number (int) – The block number at which the event occurred.

  • from_asset (string) – The source asset involved in the event. - For "deposit" events this is the asset being deposited in the vault - For "withdraw" events this is the vault token that is being burned and converted to the original asset.

  • from_value (object) – The value of the from asset for the event. The rate should be the asset/USD rate at the event’s timestamp. But in reality due to current limitations of our implementation is the USD value at the current timestamp. We will address this soon.

  • to_asset (string) – The target asset involved in the event. - For "deposit" events this is the vault token that is minted to represent the equivalent of the deposited asset. - For "withdraw" events this is the original token that the user withdrew from the vault

  • to_value (object) – The value of the to asset for the event. The rate should be the asset/USD rate at the event’s timestamp. But in reality due to current limitations of our implementation is the USD value at the current timestamp. We will address this soon.

  • realized_pnl (object) – [Optional]. Realized profit/loss at this event if any. May happen for withdraw events. Same limitation as the usd value in from/to value applies.

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

  • log_index (int) – The log index of the event.

Status Codes:

Getting yearn finance V2 vaults balances

GET /api/(version)/blockchains/eth/modules/yearn/vaultsv2/balances

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 yearn finance vaults V2 balances resource will return all yearn vault balances.

Example Request:

http

GET /api/1/blockchains/eth/modules/yearn/vaultsv2/balances HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/eth/modules/yearn/vaultsv2/balances

wget

wget -S -O- http://localhost:5042/api/1/blockchains/eth/modules/yearn/vaultsv2/balances

httpie

http http://localhost:5042/api/1/blockchains/eth/modules/yearn/vaultsv2/balances

python-requests

requests.get('http://localhost:5042/api/1/blockchains/eth/modules/yearn/vaultsv2/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":{
      "0x915C4580dFFD112db25a6cf06c76cDd9009637b7":{
        "0x5f18C75AbDAe578b483E5F43f12a39cF75b973a9":{
            "underlying_token":"eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
            "vault_token":"eip155:1/erc20:0x5f18C75AbDAe578b483E5F43f12a39cF75b973a9",
            "underlying_value":{
              "amount":"74.292820",
              "usd_value":"105.0"
            },
            "vault_value":{
              "amount":"70",
              "usd_value":"105.0"
            },
            "roi":"-238.20%"
        },
        "0xB8C3B7A2A618C552C23B1E4701109a9E756Bab67":{
            "underlying_token":"eip155:1/erc20:0x111111111117dC0aa78b770fA6A738034120C302",
            "vault_token":"eip155:1/erc20:0xB8C3B7A2A618C552C23B1E4701109a9E756Bab67",
            "underlying_value":{
              "amount":"2627.246068139435250",
              "usd_value":"3825.0"
            },
            "vault_value":{
              "amount":"2550",
              "usd_value":"3825.0"
            },
            "roi":"9.14%"
        }
      }
  },
  "message":""
}
Response JSON Object:

  • result (object) – A mapping of addresses to a mapping of vault names to vault balances

Response JSON Array of Objects:

  • underlying_token (string) – The identifier of the token that is deposited to the vault

  • vault_token (string) – The identifier of the token that is minted when you deposit underlying token to the vault

  • underlying_value (object) – The value of the underlying token for the vault.

  • vault_value (object) – The value of the vault token for the vault.

  • roi (optional[string]) – An optional string. The Return of Investment for the vault since its creation.

Status Codes:

Getting yearn finance V2 vaults historical data

GET /api/(version)/blockchains/eth/modules/yearn/vaultsv2/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 yearn finance vaults V2 history resource will return all yearn vault related events for addresses that have utilized yearn finance vaults.

Example Request:

http

GET /api/1/blockchains/eth/modules/yearn/vaultsv2/history HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/eth/modules/yearn/vaultsv2/history

wget

wget -S -O- http://localhost:5042/api/1/blockchains/eth/modules/yearn/vaultsv2/history

httpie

http http://localhost:5042/api/1/blockchains/eth/modules/yearn/vaultsv2/history

python-requests

requests.get('http://localhost:5042/api/1/blockchains/eth/modules/yearn/vaultsv2/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 yearn 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 yearn vaults historical data. If not given 0 is implied.

  • to_timestamp (int) – Timestamp until which to query yearn vaults historical data. If not given current timestamp is implied.

Example Response:

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

{
  "result":{
      "0x915C4580dFFD112db25a6cf06c76cDd9009637b7":{
        "eip155:1/erc20:0xF29AE508698bDeF169B89834F76704C3B205aedf":{
            "events":[
              {
                  "event_type":"deposit",
                  "block_number":12588754,
                  "timestamp":1623087604,
                  "from_asset":"eip155:1/erc20:0xC011a73ee8576Fb46F5E1c5751cA3B9Fe0af2a6F",
                  "from_value":{
                    "amount":"273.682277822922514201",
                    "usd_value":"273.682277822922514201"
                  },
                  "to_asset":"eip155:1/erc20:0xF29AE508698bDeF169B89834F76704C3B205aedf",
                  "to_value":{
                    "amount":"269.581682615706959373",
                    "usd_value":"269.581682615706959373"
                  },
                  "realized_pnl":null,
                  "tx_hash":"0x01ed01b47b8c7bdab961dd017e8412d1e9d181163e72cbfbce931395004bda4b",
                  "log_index":149
              }
            ],
            "profit_loss":{
              "amount":"-273.682277822922514201",
              "usd_value":"-273.682277822922514201"
            }
        },
        "eip155:1/erc20:0x1C6a9783F812b3Af3aBbf7de64c3cD7CC7D1af44":{
            "events":[
              {
                  "event_type":"deposit",
                  "block_number":12462638,
                  "timestamp":1621397797,
                  "from_asset":"eip155:1/erc20:0x94e131324b6054c0D789b190b2dAC504e4361b53",
                  "from_value":{
                    "amount":"32064.715735449204040742",
                    "usd_value":"32064.715735449204040742"
                  },
                  "to_asset":"eip155:1/erc20:0x1C6a9783F812b3Af3aBbf7de64c3cD7CC7D1af44",
                  "to_value":{
                    "amount":"32064.715735449204040742",
                    "usd_value":"32064.715735449204040742"
                  },
                  "realized_pnl":null,
                  "tx_hash":"0x0a53f8817f44ac0f8b516b7fa7ecba2861c001f506dbc465fe289a7110fcc1ca",
                  "log_index":16
              },
              {
                  "event_type":"withdraw",
                  "block_number":12494161,
                  "timestamp":1621820621,
                  "from_asset":"eip155:1/erc20:0x1C6a9783F812b3Af3aBbf7de64c3cD7CC7D1af44",
                  "from_value":{
                    "amount":"32064.715735449204040742",
                    "usd_value":"32064.715735449204040742"
                  },
                  "to_asset":"eip155:1/erc20:0x94e131324b6054c0D789b190b2dAC504e4361b53",
                  "to_value":{
                    "amount":"32092.30659836985292638",
                    "usd_value":"32092.30659836985292638"
                  },
                  "realized_pnl":{
                    "amount":"27.590862920648885638",
                    "usd_value":"27.590862920648885638"
                  },
                  "tx_hash":"0xda0694c6b3582fe03b2eb9edb0169d23c8413157e233d0c8f678a7cc9ab4f918",
                  "log_index":134
              }
            ],
            "profit_loss":{
              "amount":"27.590862920648885638",
              "usd_value":"27.590862920648885638"
            }
          }
    }
  },
  "message":""
}
Response JSON Object:

  • result (object) – A mapping of addresses to vault history results

  • profit_loss (object) – The total profit/loss for the vault

Response JSON Array of Objects:

  • event_type (string) – The type of the yearn vault event. - "deposit": when you deposit a token in the vault - "withdraw": when you withdraw a token from the vault

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

  • block_number (int) – The block number at which the event occurred.

  • from_asset (string) – The source asset involved in the event. - For "deposit" events this is the asset being deposited in the vault - For "withdraw" events this is the vault token that is being burned and converted to the original asset.

  • from_value (object) – The value of the from asset for the event. The rate should be the asset/USD rate at the events’s timestamp. But in reality due to current limitations of our implementation is the USD value at the current timestamp. We will address this soon.

  • to_asset (string) – The target asset involved in the event. - For "deposit" events this is the vault token that is minted to represent the equivalent of the deposited asset. - For "withdraw" events this is the original token that the user withdrew from the vault

  • to_value (object) – The value of the to asset for the event. The rate should be the asset/USD rate at the events’s timestamp. But in reality due to current limitations of our implementation is the USD value at the current timestamp. We will address this soon.

  • realized_pnl (object) – [Optional]. Realized profit/loss at this event if any. May happen for withdraw events. Same limitation as the usd value in from/to value applies.

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

  • log_index (int) – The log index of the event.

Status Codes:

Getting Loopring balances

GET /api/(version)/blockchains/eth/modules/loopring/balances

Doing a GET on the loopring balances resource will return the balances in loopring L2 that the user has deposited from any of the L1 addresses that are set to track loopring.

Note

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

Example Request:

http

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

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/eth/modules/loopring/balances

wget

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

httpie

http http://localhost:5042/api/1/blockchains/eth/modules/loopring/balances

python-requests

requests.get('http://localhost:5042/api/1/blockchains/eth/modules/loopring/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": [{
              "ETH": {
                  "amount": "1050",
                  "usd_value": "950"
              },
              "eip155:1/erc20:0x6810e776880C02933D47DB1b9fc05908e5386b96": {
                  "amount": "1",
                  "usd_value": "5"
              }
      }]
  },
  "message": ""
}
Response JSON Object:

  • result (object) – A mapping between accounts and their balances

Status Codes:

Getting eth2 staking performance

PUT /api/(version)/blockchains/eth2/stake/performance

Doing a PUT on the ETH2 stake performance endpoint will return the performance for all validators (or the filtered ones) in a paginated manner.

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

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

{"from_timestamp": 1451606400, "to_timestamp": 1571663098, "validator_indices": [0, 15, 23542], "only_cache": false, "status": "all", "limit": 10, "offset": 10}

curl

curl -i -X PUT http://localhost:5042/api/1/blockchains/eth2/stake/performance -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_timestamp": 1451606400, "limit": 10, "offset": 10, "only_cache": false, "status": "all", "to_timestamp": 1571663098, "validator_indices": [0, 15, 23542]}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/blockchains/eth2/stake/performance --header="Content-Type: application/json;charset=UTF-8" --body-data='{"from_timestamp": 1451606400, "limit": 10, "offset": 10, "only_cache": false, "status": "all", "to_timestamp": 1571663098, "validator_indices": [0, 15, 23542]}'

httpie

echo '{
  "from_timestamp": 1451606400,
  "limit": 10,
  "offset": 10,
  "only_cache": false,
  "status": "all",
  "to_timestamp": 1571663098,
  "validator_indices": [
    0,
    15,
    23542
  ]
}' | http PUT http://localhost:5042/api/1/blockchains/eth2/stake/performance Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/blockchains/eth2/stake/performance', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_timestamp': 1451606400, 'limit': 10, 'offset': 10, 'only_cache': False, 'status': 'all', 'to_timestamp': 1571663098, 'validator_indices': [0, 15, 23542]})
Request JSON Object:

  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

  • only_cache (bool) – If false then we skip any cached values

  • limit (int) – Optional. 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.

  • from_timestamp (int[optional]) – The timestamp from which to query. Can be missing in which case we query from 0.

  • to_timestamp (int[optional]) – The timestamp until which to query. Can be missing in which case we query until now.

  • validator_indices (list[optional]) – The indices of the validators to filter for

  • addresses (list[optional]) – The associated addresses for which to filter the results. These will associate with a validator if the address is a depositor, a withdrawal address or a fee recipient.

  • status (string[optional]) – The status by which to filter. By default and if missing it’s "all" validators. Can also fiter by "active" or "exited".

Example Response:

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

  {
    "result": {
        "sums": {
            "apr": "0.0597652039949379861158979362586657031468575710584143257025001370766265371913491",
            "execution": "0.951964836013963505",
            "exits": "0.0014143880000005993",
            "outstanding_consensus_pnl": "0.000829238",
            "sum": "3.2351487110139639043",
            "withdrawals": "2.2809402489999998"
        },
        "validators": {
            "432840": {
                "apr": "0.0466762036714707128052091929912369373004480648295118244406922158753010413605874",
                "execution": "0.93361811418473",
                "exits": "0.0014143880000005993",
                "sum": "2.5266283731847305993",
                "withdrawals": "1.591595871"
            },
            "624729": {
                "apr": "0.0130890003234672733106887432674287658464095062289025012618079212013254958307617",
                "execution": "0.018346721829233505",
                "outstanding_consensus_pnl": "0.000829238",
                "sum": "0.708520337829233305",
                "withdrawals": "0.6893443779999998"
            }
        },
        "entries_found": 2,
        "entries_total": 402
    },
    "message": ""
}
Response JSON Object:

  • sums (object) – Sums of all the pages of the results

  • validator (object) – Mapping of validator index to performance for the current page

  • apr (string) – The APR of returns for the given timerange for the validator.

  • execution (string) – The sum of execution layer ETH PnL for the validator.

  • withdrawals (string) – The sum of consensus layer withdrawals ETH pnl for the validator

  • exits (string) – The sum of the exit ETH PnL for the validator

  • outstanding_consensus_pnl (string) – If a recent timerange is queried we also take into account not yet withdrawn ETH gathering in the consensus layer.

  • entries_found (int) – The validators found for the current filter

  • entries_total (int) – The total number of validators found

Status Codes:

Getting Eth2 Staking daily stats

POST /api/(version)/blockchains/eth2/stake/dailystats

Doing a POST on the ETH2 stake daily stats endpoint will return daily stats for your ETH2 validators filtered and paginated by the given parameters

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

POST /api/1/blockchains/eth2/stake/dailystats HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{"from_timestamp": 1451606400, "to_timestamp": 1571663098, "validator_indices": [0, 15, 23542], "addresses": ["0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12"],  "status": "all", "only_cache": false}

curl

curl -i -X POST http://localhost:5042/api/1/blockchains/eth2/stake/dailystats -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"addresses": ["0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12"], "from_timestamp": 1451606400, "only_cache": false, "status": "all", "to_timestamp": 1571663098, "validator_indices": [0, 15, 23542]}'

wget

wget -S -O- http://localhost:5042/api/1/blockchains/eth2/stake/dailystats --header="Content-Type: application/json;charset=UTF-8" --post-data='{"addresses": ["0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12"], "from_timestamp": 1451606400, "only_cache": false, "status": "all", "to_timestamp": 1571663098, "validator_indices": [0, 15, 23542]}'

httpie

echo '{
  "addresses": [
    "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12"
  ],
  "from_timestamp": 1451606400,
  "only_cache": false,
  "status": "all",
  "to_timestamp": 1571663098,
  "validator_indices": [
    0,
    15,
    23542
  ]
}' | http POST http://localhost:5042/api/1/blockchains/eth2/stake/dailystats Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/blockchains/eth2/stake/dailystats', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'addresses': ['0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12'], 'from_timestamp': 1451606400, 'only_cache': False, 'status': 'all', 'to_timestamp': 1571663098, 'validator_indices': [0, 15, 23542]})
Request JSON Object:

  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

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

  • limit (int) – Optional. 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_attributes (list[string]) – Optional. This is the list of attributes of the eth2_daily_staking_details table by which to order the results. If none is given ‘timestamp’ is assumed. Valid values are: [‘timestamp’, ‘validator_index’, ‘pnl’].

  • ascending (list[bool]) – Optional. False by default. Defines the order by which results are returned depending on the chosen order by attribute.

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

  • validator_indices (list(string)[optional]) – Optionally filter entries validator indices. If missing data for all validators are returned.

  • addresses (list(string)[optional]) – The associated addresses for which to filter the results. These will associate with a validator if the address is a depositor, a withdrawal address or a fee recipient.

  • status (string[optional]) – The status by which to filter. By default and if missing it’s "all" validators. Can also fiter by "active" or "exited".

Example Response:

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

{
  "result": {
      "entries": [{
            "validator_index": 15,
            "timestamp": 1613952000,
            "pnl": {"amount": "0.007", "usd_value": "70"},
        }, {
            "validator_index": 43567,
            "timestamp": 1613865600,
            "pnl": {"amount": "-0.0066", "usd_value": "-6.6"},
        }],
        "entries_found": 95,
        "entries_total": 1000,
        "sum_pnl": "0.0014",
   },
  "message": "",
}

:resjson entries : The list of daily stats filtered by the given filter.

Response JSON Object:

  • string (eth_depositor) – The eth1 address that made the deposit for the validator.

  • int (timestamp) – The timestamp of the start of the day in GMT for which this entry is.

  • object (pnl) – The amount of ETH gained or lost in that day along with its usd value. Average price of the day is taken.

  • sum_pnl (string) – The sum of PnL in ETH for the current filter and current page.

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

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

Status Codes:

Adding an Eth2 validator

PUT /api/(version)/blockchains/eth2/validators

Doing a PUT on the eth2 validators endpoint will input information and track an ETH2 validator.

Note

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

Example Request:

http

PUT /api/1/blockchains/eth2/validators HTTP/1.1
Host: localhost:5042

curl

curl -i -X PUT http://localhost:5042/api/1/blockchains/eth2/validators

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/blockchains/eth2/validators

httpie

http PUT http://localhost:5042/api/1/blockchains/eth2/validators

python-requests

requests.put('http://localhost:5042/api/1/blockchains/eth2/validators')
Request JSON Object:

  • int (validator_index) – An optional integer representing the validator index of the validator to track. If this is not given then the public key of the validator has to be given!

  • str (public_key) – An optional string representing the hexadecimal string of the public key of the validator to track. If this is not given the the validator index has to be given!

  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

Response JSON Object:

  • ownership_percentage – An optional string representing the amount of the validator owned by the user in the range of 0 to 100. If not provided a default value of 100 is assigned.

Example Response:

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

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

Deleting Eth2 validators

DELETE /api/(version)/blockchains/eth2/validators

Doing a DELETE on the eth2 validators endpoint will delete information and stop tracking a number of ETH2 validator/s.

Example Request:

http

DELETE /api/1/blockchains/eth2/validators HTTP/1.1
Host: localhost:5042
Content-Type: application/json

{
  "validators": [1, 23423, 3233]
}

curl

curl -i -X DELETE http://localhost:5042/api/1/blockchains/eth2/validators -H "Content-Type: application/json" --data-raw '{"validators": [1, 23423, 3233]}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/blockchains/eth2/validators --header="Content-Type: application/json" --body-data='{"validators": [1, 23423, 3233]}'

httpie

echo '{
  "validators": [
    1,
    23423,
    3233
  ]
}' | http DELETE http://localhost:5042/api/1/blockchains/eth2/validators Content-Type:application/json

python-requests

requests.delete('http://localhost:5042/api/1/blockchains/eth2/validators', headers={'Content-Type': 'application/json'}, json={'validators': [1, 23423, 3233]})
Request JSON Object:

  • validators (list[int]) – A list of indices of eth2 validators to delete

Example Response:

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

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

Editing an Eth2 validator

PATCH /api/(version)/blockchains/eth2/validators

Doing a PATCH on the eth2 validators endpoint will allow to edit the ownership percentage of a validator identified by its index.

Example Request:

http

PUT /api/1/blockchains/eth2/validators HTTP/1.1
Host: localhost:5042

curl

curl -i -X PUT http://localhost:5042/api/1/blockchains/eth2/validators

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/blockchains/eth2/validators

httpie

http PUT http://localhost:5042/api/1/blockchains/eth2/validators

python-requests

requests.put('http://localhost:5042/api/1/blockchains/eth2/validators')
Request JSON Object:

  • int (validator_index) – An integer representing the validator index of the validator to edit.

Response JSON Object:

  • ownership_percentage – A float representing the amount of the validator owned by the user in the range of 0 to 100. If not provided a default value of 100 is assigned.

Example Response:

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

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

Getting tracked Eth2 validators

GET /api/(version)/blockchains/eth2/validators

Doing a GET on the ETH2 validators endpoint will get information on the tracked ETH2 validators. If the user is not premium they will see up to a certain limit of validators. If ignore cache is false, only DB data is return. If it’s true then all validator data will be refreshed and new validators will be detected.

Note

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

Example Request:

http

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

{"ignore_cache": true, "async_query": true}

curl

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

wget

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

httpie

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

python-requests

requests.get('http://localhost:5042/api/1/blockchains/eth2/validators', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': True, 'ignore_cache': 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 DB cache and refresh all validator data.

  • validator_indices (list(string)[optional]) – Optionally filter entries validator indices. If missing data for all validators are returned.

  • addresses (list(string)[optional]) – The associated addresses for which to filter the results. These will associate with a validator if the address is a depositor, a withdrawal address or a fee recipient.

  • status (string[optional]) – The status by which to filter. By default and if missing it’s "all" validators. Can also fiter by "active" or "exited".

Example Response:

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

{
  "result":{
    "entries":[
      {
        "index":1,
        "public_key":"0xa1d1ad0714035353258038e964ae9675dc0252ee22cea896825c01458e1807bfad2f9969338798548d9858a571f7425c",
        "withdrawal_address": "0x23a3283f9f538a54d49139cd35c2fe0443cad3db",
        "status": "pending",
      },
      {
        "index":1532,
        "public_key":"0xa509dec619e5b3484bf4bc1c33baa4c2cdd5ac791876f4add6117f7eded966198ab77862ec2913bb226bdf855cc6d6ed",
        "ownership_percentage": "50",
        "activation_timestamp": 1701971000,
        "status": "active"
      },
      {
        "index":5421,
        "public_key":"0xa64722f93f37c7da8da67ee36fd2a763103897efc274e3accb4cd172382f7a170f064b81552ae77cdbe440208a1b897e",
        "ownership_percentage": "25.75",
        "withdrawal_address": "0xfa13283f9e538a84d49139cd35c2fe0443caa34f",
        "activation_timestamp": 1701972000,
        "withdrawable_timestamp": 1702572000,
        "status": "exited"
      }
    ],
    "entries_found":3,
    "entries_limit":4
  },
  "message":""
}
Response JSON Object:

  • entries (object) – The resulting entries list

  • index (integer) – The index of the validator

  • public_key (string) – The public key of the validator

  • status (string) – The status of the validator. Can be one of "pending", "active", "exiting" and "exited".

  • ownership_percentage (string[optional]) – The ownership percentage of the validator. If missing assume 100%.

  • withdrawal_address (string[optional]) – The withdrawal address for the validator if set.

  • activation_timestamp (integer[optional]) – If existing this is the timestamp the validator will (or has been) activate/d. If not then this is a pending validator not yet fully deposited or not yet processed by the consensus layer.

  • withdrawable_timestamp (integer[optional]) – If existing this is the timestamp the validator will (or has been) able to be completely withdrawn. In other words from which point on a full exit will happen next time it’s skimmed by withdrawals. If this key exists this mean we are dealing with a validator that is exiting or has exited.

Status Codes:

Getting Pickle’s DILL balances

GET /api/(version)/blockchains/eth/modules/pickle/dill

Doing a GET on the pickle’s DILL balances resource will return the balances that the user has locked with the rewards that can be claimed.

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

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/eth/modules/pickle/dill

wget

wget -S -O- http://localhost:5042/api/1/blockchains/eth/modules/pickle/dill

httpie

http http://localhost:5042/api/1/blockchains/eth/modules/pickle/dill

python-requests

requests.get('http://localhost:5042/api/1/blockchains/eth/modules/pickle/dill')
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": {
          "0x5c4D8CEE7dE74E31cE69E76276d862180545c307": {
              "locked_amount": {
                  "amount": "4431.204412216798860222",
                  "usd_value": "43735.98754857980475039114",
                  "asset": "eip155:1/erc20:0x429881672B9AE42b8EbA0E26cD9C73711b891Ca5"
              },
              "pending_rewards": {
                  "amount": "82.217560698031032969",
                  "usd_value": "811.48732408956629540403",
                  "asset": "eip155:1/erc20:0x429881672B9AE42b8EbA0E26cD9C73711b891Ca5"
              },
              "locked_until": 1755129600
          }
      },
      "message": ""
  }
Response JSON Object:

  • result (object) – A mapping of all accounts that currently have Pickle locked to keys locked_amount, pending_rewards and locked_until

Status Codes:

Querying ethereum airdrops

GET /api/(version)/blockchains/eth/airdrops

Doing a GET on the ethereum airdrops endpoint will return how much and of which token any of the tracked ethereum addresses are entitled to.

Example Request

http

GET /api/1/blockchains/eth/airdrops HTTP/1.1
Host: localhost:5042

curl

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

wget

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

httpie

http http://localhost:5042/api/1/blockchains/eth/airdrops

python-requests

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

Example Response:

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

{
   "result": {
      "0xe5B3330A43CeC5A01A80E75ebaB2d3bc17e70819": {
            "1inch": {
               "amount": "675.55",
               "asset": "eip155:1/erc20:0x111111111117dC0aa78b770fA6A738034120C302",
               "link": "https://app.uniswap.org/",
               "claimed": false
            }
      },
      "0x0B89f648eEcCc574a9B7449B5242103789CCD9D7": {
            "1inch": {
               "amount": "1823.23",
               "asset": "eip155:1/erc20:0x111111111117dC0aa78b770fA6A738034120C302",
               "link": "https://1inch.exchange/",
               "claimed": false
            },
            "uniswap": {
               "amount": "400",
               "asset": "eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984",
               "link": "https://app.uniswap.org/",
               "claimed": true,
               "icon_url": "https://raw.githubusercontent.com/rotki/data/main/airdrops/icons/uniswap.svg"
            }
      },
      "message": ""
   }
}
Request JSON Object:

  • result (object) – A mapping of addresses to protocols for which claimable airdrops exist

Status Codes:

Get addresses to query per protocol

GET /api/(version)/queried_addresses/

Doing a GET on this endpoint will return a mapping of which addresses are set for querying for each protocol. If a protocol is not returned or has no addresses then all addresses are queried

Example Request:

http

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

curl

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

wget

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

httpie

http http://localhost:5042/api/1/queried_addresses

python-requests

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

Example Response:

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

{
    "result": {
        "aave": ["0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b"],
        "makerdao_dsr": ["0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b"],
    },
    "message": ""
}
Response JSON Object:

  • result (list) – A mapping of modules/protocols for which an entry exists to the list of addresses to query.

Status Codes:

Add address to query per protocol

PUT /api/(version)/queried_addresses/

Doing a PUT on this endpoint will add a new address for querying by a protocol/module. Returns all the queried addresses per module after the addition.

Example Request:

http

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

{
    "module": "aave",
    "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b"
}

curl

curl -i -X PUT http://localhost:5042/api/1/queried_addresses -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b", "module": "aave"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/queried_addresses --header="Content-Type: application/json;charset=UTF-8" --body-data='{"address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b", "module": "aave"}'

httpie

echo '{
  "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b",
  "module": "aave"
}' | http PUT http://localhost:5042/api/1/queried_addresses Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/queried_addresses', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'address': '0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b', 'module': 'aave'})

Example Response:

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

{
    "result": {
        "aave": ["0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b"],
        "makerdao_dsr": ["0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b"],
    },
    "message": ""
}
Response JSON Object:

  • result (list) – A mapping of modules/protocols for which an entry exists to the list of addresses to query.

Status Codes:

Remove an address to query per protocol

DELETE /api/(version)/queried_addresses/

Doing a DELETE on this endpoint will remove an address for querying by a protocol/module. Returns all the queried addresses per module after the deletion.

Example Request:

http

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

{
    "module": "aave",
    "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b"
}

curl

curl -i -X DELETE http://localhost:5042/api/1/queried_addresses -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b", "module": "aave"}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/queried_addresses --header="Content-Type: application/json;charset=UTF-8" --body-data='{"address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b", "module": "aave"}'

httpie

echo '{
  "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b",
  "module": "aave"
}' | http DELETE http://localhost:5042/api/1/queried_addresses Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/queried_addresses', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'address': '0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b', 'module': 'aave'})

Example Response:

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

{
    "result": {
        "aave": ["0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B"],
        "makerdao_dsr": ["0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b"],
    },
    "message": ""
}
Response JSON Object:

  • result (list) – A mapping of modules/protocols for which an entry exists to the list of addresses to query.

Status Codes:

Adding EVM accounts to all EVM chains

PUT /api/(version)/blockchains/evm/accounts

Doing a PUT on the EVM accounts endpoint functions just like the add blockchain accounts endpoint but adds the addresses for all evm chains. It will follow the following logic. Take ethereum mainnet as the parent chain. If it’s a contract there, it will only add it to the mainnet. If it’s an EoA it will try all chains one by one and see if they have any transactions/activity and add it to the ones that do.

Note

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

Example Request:

http

PUT /api/1/blockchains/evm/accounts HTTP/1.1
Host: localhost:5042

{
    "accounts": [{
            "address": "0x9008D19f58AAbD9eD0D60971565AA8510560ab41",
            "label": "my new metamask",
            "tags": ["public", "metamask"]
        }, {
            "address": "0x9531C059098e3d194fF87FebB587aB07B30B1306"
        }, {
            "address": "0x106B62Fdd27B748CF2Da3BacAB91a2CaBaeE6dCa"
        }, {
            "address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65"
        }, {
            "address": "0x7277F7849966426d345D8F6B9AFD1d3d89183083"
        }]
}

For request details check `here <blockchain_account_addition_section_>`__

curl

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

    "accounts": [{

            "address": "0x9008D19f58AAbD9eD0D60971565AA8510560ab41",

            "label": "my new metamask",

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

        }, {

            "address": "0x9531C059098e3d194fF87FebB587aB07B30B1306"

        }, {

            "address": "0x106B62Fdd27B748CF2Da3BacAB91a2CaBaeE6dCa"

        }, {

            "address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65"

        }, {

            "address": "0x7277F7849966426d345D8F6B9AFD1d3d89183083"

        }]

}



For request details check `here <blockchain_account_addition_section_>`__'

wget

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

    "accounts": [{

            "address": "0x9008D19f58AAbD9eD0D60971565AA8510560ab41",

            "label": "my new metamask",

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

        }, {

            "address": "0x9531C059098e3d194fF87FebB587aB07B30B1306"

        }, {

            "address": "0x106B62Fdd27B748CF2Da3BacAB91a2CaBaeE6dCa"

        }, {

            "address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65"

        }, {

            "address": "0x7277F7849966426d345D8F6B9AFD1d3d89183083"

        }]

}



For request details check `here <blockchain_account_addition_section_>`__'

httpie

echo '{

    "accounts": [{

            "address": "0x9008D19f58AAbD9eD0D60971565AA8510560ab41",

            "label": "my new metamask",

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

        }, {

            "address": "0x9531C059098e3d194fF87FebB587aB07B30B1306"

        }, {

            "address": "0x106B62Fdd27B748CF2Da3BacAB91a2CaBaeE6dCa"

        }, {

            "address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65"

        }, {

            "address": "0x7277F7849966426d345D8F6B9AFD1d3d89183083"

        }]

}



For request details check `here <blockchain_account_addition_section_>`__' | http PUT http://localhost:5042/api/1/blockchains/evm/accounts

python-requests

requests.put('http://localhost:5042/api/1/blockchains/evm/accounts', data='{\r\n\n    "accounts": [{\r\n\n            "address": "0x9008D19f58AAbD9eD0D60971565AA8510560ab41",\r\n\n            "label": "my new metamask",\r\n\n            "tags": ["public", "metamask"]\r\n\n        }, {\r\n\n            "address": "0x9531C059098e3d194fF87FebB587aB07B30B1306"\r\n\n        }, {\r\n\n            "address": "0x106B62Fdd27B748CF2Da3BacAB91a2CaBaeE6dCa"\r\n\n        }, {\r\n\n            "address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65"\r\n\n        }, {\r\n\n            "address": "0x7277F7849966426d345D8F6B9AFD1d3d89183083"\r\n\n        }]\r\n\n}\r\n\n\r\n\nFor request details check `here <blockchain_account_addition_section_>`__')

Example Response:

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

{
  "result": {
      "added":{
         "0x9531C059098e3d194fF87FebB587aB07B30B1306": ["all"],
         "0x9008D19f58AAbD9eD0D60971565AA8510560ab41": ["eth"]
      },
      "failed":{
         "0xc37b40ABdB939635068d3c5f13E7faF686F03B65": [
            "polygon_pos",
            "arbitrum_one",
            "base",
            "gnosis"
         ]
      },
      "existed":{
         "0x7277F7849966426d345D8F6B9AFD1d3d89183083": ["gnosis"]
      },
      "no_activity":{
         "0x106B62Fdd27B748CF2Da3BacAB91a2CaBaeE6dCa": ["all"],
         "0x7277F7849966426d345D8F6B9AFD1d3d89183083": [
            "eth",
            "optimism",
            "avax",
            "polygon_pos",
            "arbitrum_one",
            "base"
         ]
      },
      "eth_contracts": ["0x9008D19f58AAbD9eD0D60971565AA8510560ab41"]
  },
  "message": ""
}

Note

When a result includes all the chains instead of listing them all we use the special symbol all

Response JSON Object:

  • added (object) – A mapping containing addresses and what chains they were added to.

  • existed (object) – A mapping containing addresses and in what chains they were already tracked before the api call so no action was taken on them.

  • failed (object) – A mapping containing which chains failed to get added for each address due to some error contacting remote APIs.

  • no_activity (list) – A mapping containing addresses and in which chains they had no activity so no action was taken for them.

  • no_activity – A list of the addresses that were detected as ethereum contracts.

Status Codes:

  • 200 OK – Accounts successfully added

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

  • 401 Unauthorized – User is not logged in.

  • 409 Conflict – Provided tags do not exist. Check message for details.

  • 500 Internal Server Error – Internal rotki error

  • 502 Bad Gateway – Remote error occurred when attempted to connect to an Avalanche or Polkadot node and only if it’s the first account added. Check message for details.

POST /api/(version)/blockchains/evm/accounts

Doing a POST on the EVM accounts endpoint will re-detect evm accounts on all supported chains. Rotki will go through already added addresses and for each address, if it is an EOA (not a smart contract) and has activity on some chain, will add it to that chain.

Note

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

Example Request:

http

POST /api/1/blockchains/evm/accounts HTTP/1.1
Host: localhost:5042

{}

curl

curl -i -X POST http://localhost:5042/api/1/blockchains/evm/accounts --data-raw '{}'

wget

wget -S -O- http://localhost:5042/api/1/blockchains/evm/accounts --post-data='{}'

httpie

echo '{}' | http POST http://localhost:5042/api/1/blockchains/evm/accounts

python-requests

requests.post('http://localhost:5042/api/1/blockchains/evm/accounts', data='{}')

Example Response:

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

{
  "result": true,
  "message": ""
}
Response JSON Object:

  • result (bool) – true in case of success, null otherwise.

Status Codes:

Adding blockchain accounts

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

Note

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

Supported blockchains with ENS domains: "BTC", "BCH", "ETH", "KSM", "DOT"

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

Doing a PUT on the blockchains endpoint with a specific blockchain URL and a list of account data in the json data will add these accounts to the tracked accounts for the given blockchain and the current user. A list of accounts’ addresses that were added during a request is returned. This data is returned so that if you add an ens name, you get its name’s resolved address for the further usage. If one of the given accounts to add is invalid the entire request will fail.

Example Request:

http

PUT /api/1/blockchains/eth/accounts HTTP/1.1
Host: localhost:5042

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

curl

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

    "accounts": [{

            "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",

            "label": "my new metamask",

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

        }, {

            "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b"

        }]

}'

wget

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

    "accounts": [{

            "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",

            "label": "my new metamask",

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

        }, {

            "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b"

        }]

}'

httpie

echo '{

    "accounts": [{

            "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",

            "label": "my new metamask",

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

        }, {

            "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b"

        }]

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

python-requests

requests.put('http://localhost:5042/api/1/blockchains/eth/accounts', data='{\r\n\n    "accounts": [{\r\n\n            "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",\r\n\n            "label": "my new metamask",\r\n\n            "tags": ["public", "metamask"]\r\n\n        }, {\r\n\n            "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b"\r\n\n        }]\r\n\n}')
reqjson list[object] accounts:

A list of account data to add for the given blockchain

reqjsonarr string address:

The address of the account to add. Can either be a hexadecimal address or an ENS name.

reqjsonarr string[optional] label:

An optional label to describe the new account. Cannot be empty string.

reqjsonarr list[optional] tags:

An optional list of tags to attach to the new account. Can be null. Should never be an empty list.

reqjson bool async_query:

Boolean denoting whether this is an asynchronous query or not

Example Response:

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

{
  "result": [
      "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",
      "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b"
  ],
  "message": ""
}
resjson list result:

A list containing accounts’ addresses that were added during a request.

statuscode 200:

Accounts successfully added

statuscode 400:

Provided JSON or data is in some way malformed. The accounts to add contained invalid addresses or were an empty list.

statuscode 401:

User is not logged in.

statuscode 409:

Provided tags do not exist. Check message for details.

statuscode 500:

Internal rotki error

statuscode 502:

Remote error occurred when attempted to connect to an Avalanche or Polkadot node and only if it’s the first account added. Check message for details.

Adding BTC/BCH xpubs

PUT /api/(version)/blockchains/(blockchain)/xpub

Note

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

Note

Only "BCH" and "BTC" are the supported blockchain values for Xpubs.

Doing a PUT on the xpubs endpoint will add an extended public key for bitcoin/bitcoin cash mainnet. All derived addresses that have ever had a transaction from this xpub and derivation path will be found and added for tracking in rotki.

Example Request:

http

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

{
    "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk",
    "xpub_type": "p2sh_p2wpkh",
    "derivation_path": "m/0/0",
    "label": "my electrum xpub",
    "tags": ["public", "old"]
}

curl

curl -i -X PUT http://localhost:5042/api/1/blockchains/BTC/xpub -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"derivation_path": "m/0/0", "label": "my electrum xpub", "tags": ["public", "old"], "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk", "xpub_type": "p2sh_p2wpkh"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/blockchains/BTC/xpub --header="Content-Type: application/json;charset=UTF-8" --body-data='{"derivation_path": "m/0/0", "label": "my electrum xpub", "tags": ["public", "old"], "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk", "xpub_type": "p2sh_p2wpkh"}'

httpie

echo '{
  "derivation_path": "m/0/0",
  "label": "my electrum xpub",
  "tags": [
    "public",
    "old"
  ],
  "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk",
  "xpub_type": "p2sh_p2wpkh"
}' | http PUT http://localhost:5042/api/1/blockchains/BTC/xpub Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/blockchains/BTC/xpub', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'derivation_path': 'm/0/0', 'label': 'my electrum xpub', 'tags': ['public', 'old'], 'xpub': 'xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk', 'xpub_type': 'p2sh_p2wpkh'})
Request JSON Object:

  • xpub (string) – The extended public key to add

  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

Request JSON Array of Objects:

  • derivation_path (string) – The derivation path from which to start deriving addresses relative to the xpub.

  • xpub_type (string[optional]) – An optional type to denote the type of the given xpub. If omitted the prefix xpub/ypub/zpub is used to determine the type. The valid xpub types are: "p2pkh", "p2sh_p2wpkh", "wpkh" and "p2tr".

  • label (string[optional]) – An optional label to describe the new extended public key

  • tags (list[optional]) – An optional list of tags to attach to the xpub. Can be null. Should never be an empty list.

Example Response:

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

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

  • 200 OK – Xpub successfully added

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

  • 401 Unauthorized – User is not logged in.

  • 409 Conflict – Some error occurred when re-querying the balances after addition. Provided tags do not exist. Check message for details.

  • 500 Internal Server Error – Internal rotki error

  • 502 Bad Gateway – Error occurred with some external service query such as blockstream or haskoin. Check message for details.

Editing BTC/BCH xpubs

PATCH /api/(version)/blockchains/(blockchain)/xpub

Note

Only "BCH" and "BTC" are the supported blockchain values for Xpubs.

Doing a PATCH on the xpubs endpoint will edit the label and tag of an extended public key for bitcoin/bitcoin cash mainnet.

Example Request:

http

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

{
    "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk",
    "derivation_path": "m/0/0",
    "label": "my electrum xpub",
    "tags": ["public", "old"]
}

curl

curl -i -X PATCH http://localhost:5042/api/1/blockchains/BTC/xpub -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"derivation_path": "m/0/0", "label": "my electrum xpub", "tags": ["public", "old"], "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk"}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/blockchains/BTC/xpub --header="Content-Type: application/json;charset=UTF-8" --body-data='{"derivation_path": "m/0/0", "label": "my electrum xpub", "tags": ["public", "old"], "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk"}'

httpie

echo '{
  "derivation_path": "m/0/0",
  "label": "my electrum xpub",
  "tags": [
    "public",
    "old"
  ],
  "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk"
}' | http PATCH http://localhost:5042/api/1/blockchains/BTC/xpub Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/blockchains/BTC/xpub', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'derivation_path': 'm/0/0', 'label': 'my electrum xpub', 'tags': ['public', 'old'], 'xpub': 'xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk'})
Request JSON Object:

  • xpub (string) – The extended public key to edit

Request JSON Array of Objects:

  • derivation_path (string) – The derivation path from which to start deriving addresses relative to the xpub.

  • label (string[optional]) – An optional label to describe the new extended public key

  • tags (list[optional]) – An optional list of tags to attach to the xpub. Can be null. Should never be an empty list.

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": "1755.53"},
                     "GNO": {"amount": "1", "usd_value": "50"},
                     "RDN": {"amount": "1", "usd_value": "1.5"}
                 },
                 "total_usd_value": "1807.03",
            }}
        },
        "totals": {
            "BTC": {"amount": "1", "usd_value": "7540.15"},
            "ETH": {"amount": "10", "usd_value": "1650.53"},
            "RDN": {"amount": "1", "usd_value": "1.5"},
            "GNO": {"amount": "1", "usd_value": "50"}
    },
    "message": ""
}
Response JSON Object:

  • result (object) – An object containing the "per_account" and "totals" keys as also defined here.

Status Codes:

  • 200 OK – Xpub successfully edited

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

  • 401 Unauthorized – User is not logged in.

  • 409 Conflict – Some error occurred when re-querying the balances after addition. Provided tags do not exist. Check message for details.

  • 500 Internal Server Error – Internal rotki error

Deleting BTC/BCH xpubs

DELETE /api/(version)/blockchains/(blockchain)/xpub

Note

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

Note

Only "BCH" and "BTC" are the supported blockchain values for Xpubs.

Doing a DELETE on the xpubs endpoint will remove an extended public key for bitcoin/bitcoin cash mainnet. All derived addresses from the xpub will also be deleted.

Example Request:

http

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

{
    "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk",
    "derivation_path": "m/0/0"
}

curl

curl -i -X DELETE http://localhost:5042/api/1/blockchains/BTC/xpub -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"derivation_path": "m/0/0", "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk"}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/blockchains/BTC/xpub --header="Content-Type: application/json;charset=UTF-8" --body-data='{"derivation_path": "m/0/0", "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk"}'

httpie

echo '{
  "derivation_path": "m/0/0",
  "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk"
}' | http DELETE http://localhost:5042/api/1/blockchains/BTC/xpub Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/blockchains/BTC/xpub', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'derivation_path': 'm/0/0', 'xpub': 'xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk'})
Request JSON Object:

  • xpub (string) – The extended public key to remove

  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

Request JSON Array of Objects:

  • derivation_path (string) – The derivation path from which addresses were derived.

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": "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": "1755.53"},
                     "GNO": {"amount": "1", "usd_value": "50"},
                     "RDN": {"amount": "1", "usd_value": "1.5"}
                 },
                 "liabilities": {}
            }}
        },
        "totals": {
            "assets": {
                "BTC": {"amount": "1", "usd_value": "7540.15"},
                "ETH": {"amount": "10", "usd_value": "1650.53"},
                "RDN": {"amount": "1", "usd_value": "1.5"},
                "GNO": {"amount": "1", "usd_value": "50"}
            },
            "liabilities": {}
    },
    "message": ""
}
Response JSON Object:

  • result (object) – An object containing the "per_account" and "totals" keys as also defined here.

Status Codes:

  • 200 OK – Xpub successfully removed

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

  • 401 Unauthorized – User is not logged in.

  • 409 Conflict – Some error occurred when re-querying the balances after addition. Check message for details.

  • 500 Internal Server Error – Internal rotki error

  • 502 Bad Gateway – Error occurred with some external service query such as blockstream/haskoin. Check message for details.

Editing blockchain account data

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

Note

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

Supported blockchains with ENS domains: "BTC", "BCH", "ETH", "KSM", "DOT"

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

Example Request:

http

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

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

curl

curl -i -X PATCH http://localhost:5042/api/1/blockchains/eth/accounts -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"accounts": [{"address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "label": "my new metamask", "tags": ["public", "metamask"]}, {"address": "johndoe.eth", "label": "my hardware wallet"}]}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/blockchains/eth/accounts --header="Content-Type: application/json;charset=UTF-8" --body-data='{"accounts": [{"address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "label": "my new metamask", "tags": ["public", "metamask"]}, {"address": "johndoe.eth", "label": "my hardware wallet"}]}'

httpie

echo '{
  "accounts": [
    {
      "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",
      "label": "my new metamask",
      "tags": [
        "public",
        "metamask"
      ]
    },
    {
      "address": "johndoe.eth",
      "label": "my hardware wallet"
    }
  ]
}' | http PATCH http://localhost:5042/api/1/blockchains/eth/accounts Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/blockchains/eth/accounts', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'accounts': [{'address': '0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B', 'label': 'my new metamask', 'tags': ['public', 'metamask']}, {'address': 'johndoe.eth', 'label': 'my hardware wallet'}]})
Request JSON Object:

  • accounts (list[object]) – A list of account data to edit for the given blockchain

Request JSON Array of Objects:

  • address (string) – The address of the account to edit. Can either be a hexadecimal address or an ENS name.

  • label (string[optional]) – An optional label to edit for the account. Cannot be empty string.

  • tags (list[optional]) – An optional list of tags to attach to the account. Can be null. Should never be an empty list.

Example Response:

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

{
    "result" : [{
        "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",
        "label": "my new metamask",
        "tags": ["public", "metamask"]
     }, {
        "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b",
        "label": "my hardware wallet",
        "tags": null
     }],
     "message": "",
}
Response JSON Object:

  • result (list) – A list containing the blockchain account data as also defined here. Result is different depending on the blockchain type.

Status Codes:

Removing blockchain accounts

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

Note

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

Supported blockchains with ENS domains: "BTC", "BCH", "ETH", "KSM", "DOT"

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

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

If one of the given accounts to add is invalid the entire request will fail.

Example Request:

http

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

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

curl

curl -i -X DELETE http://localhost:5042/api/1/blockchains/eth/accounts -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"accounts": ["0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B"]}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/blockchains/eth/accounts --header="Content-Type: application/json;charset=UTF-8" --body-data='{"accounts": ["0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B"]}'

httpie

echo '{
  "accounts": [
    "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B"
  ]
}' | http DELETE http://localhost:5042/api/1/blockchains/eth/accounts Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/blockchains/eth/accounts', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'accounts': ['0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B']})
Request JSON Object:

  • accounts (list[string]) – A list of accounts to delete for the given blockchain. Each account Can either be a hexadecimal address or an ENS name.

  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

Example Response:

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

{
    "result": {
        "per_account": {
            "BTC": {
                "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"
                            }
                    }}]
        }},
        "totals": {
            "assets": {"BTC": {"amount": "1", "usd_value": "7540.15"}},
            "liabilities": {}
        }
    },
    "message": ""
}
Response JSON Object:

  • result (object) – An object containing the "per_account" and "totals" keys as also defined here.

Status Codes:

  • 200 OK – Accounts successfully deleted

  • 400 Bad Request – Provided JSON or data is in some way malformed. The accounts to remove contained invalid addresses or were an empty list.

  • 401 Unauthorized – User is not logged in.

  • 409 Conflict – Some error occurred when re-querying the balances after addition. Check message for details.

  • 500 Internal Server Error – Internal rotki error

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

Getting manually tracked balances

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

Note

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

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

Example Request:

http

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

curl

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

wget

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

httpie

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

python-requests

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

Example Response:

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

{
    "result": {
    "balances": [{
            "identifier": 1,
            "asset": "XMR",
            "label": "My monero wallet",
            "amount": "50.315",
            "usd_value": "2370.13839",
            "tags": ["public"],
            "location": "blockchain"
        }, {
            "identifier": 2,
            "asset": "BTC",
            "label": "My XPUB BTC wallet",
            "amount": "1.425",
            "usd_value": "9087.22",
            "location": "blockchain"
        }, {
            "identifier": 3,
            "asset": "ZEC",
            "label" "My favorite wallet",
            "amount": "76.2"
            "usd_value": "6067.77",
            "tags": ["private", "inheritance"],
            "location": "blockchain"
        }]
    "message": ""
}
Response JSON Object:

  • result (object) – An object containing all the manually tracked balances as defined here with additionally a current usd equivalent value per account.

Status Codes:

Adding manually tracked balances

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

Note

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

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

Example Request:

http

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

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

curl

curl -i -X PUT http://localhost:5042/api/1/balances/manual/ -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"balances": [{"asset": "XMR", "label": "My monero wallet", "amount": "50.315", "tags": ["public"], "location": "blockchain", "balance_type": "asset"}, {"asset": "BTC", "label": "My XPUB BTC wallet", "amount": "1.425", "location": "blockchain", "balance_type": "liability"}]}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/balances/manual/ --header="Content-Type: application/json;charset=UTF-8" --body-data='{"balances": [{"asset": "XMR", "label": "My monero wallet", "amount": "50.315", "tags": ["public"], "location": "blockchain", "balance_type": "asset"}, {"asset": "BTC", "label": "My XPUB BTC wallet", "amount": "1.425", "location": "blockchain", "balance_type": "liability"}]}'

httpie

echo '{
  "balances": [
    {
      "amount": "50.315",
      "asset": "XMR",
      "balance_type": "asset",
      "label": "My monero wallet",
      "location": "blockchain",
      "tags": [
        "public"
      ]
    },
    {
      "amount": "1.425",
      "asset": "BTC",
      "balance_type": "liability",
      "label": "My XPUB BTC wallet",
      "location": "blockchain"
    }
  ]
}' | http PUT http://localhost:5042/api/1/balances/manual/ Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/balances/manual/', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'balances': [{'asset': 'XMR', 'label': 'My monero wallet', 'amount': '50.315', 'tags': ['public'], 'location': 'blockchain', 'balance_type': 'asset'}, {'asset': 'BTC', 'label': 'My XPUB BTC wallet', 'amount': '1.425', 'location': 'blockchain', 'balance_type': 'liability'}]})
Request JSON Object:

  • balances (list[object]) – A list of manually tracked balances to add to rotki

Request JSON Array of Objects:

  • asset (string) – The asset that is being tracked

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

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

  • tags (list[optional]) – An optional list of tags to attach to the this manually tracked balance. Can be null. Should never be an empty list.

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

  • balance_type (string[optional]) – The type of the balance. Either “asset” or “liability”. By default it’s an asset.

Example Response:

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

{
    "result": {
    "balances": [{
            "identifier": 1,
            "asset": "XMR",
            "label": "My monero wallet",
            "amount": "50.315",
            "usd_value": "2370.13839",
            "tags": ["public"],
            "location": "blockchain",
             "balance_type": "asset"
        }, {
            "identifier" :2,
            "asset": "BTC",
            "label": "My XPUB BTC wallet",
            "amount": "1.425",
            "usd_value": "9087.22",
            "location": "blockchain",
            "balance_type": "asset"
        }, {
            "identifier": 3
            "asset": "ZEC",
            "label" "My favorite wallet",
            "amount": "76.2"
            "usd_value": "6067.77",
            "tags": ["private", "inheritance"]
            "location": "blockchain",
            "balance_type": "asset"
        }]
    "message": ""
}
Response JSON Object:

  • result (object) – An object containing all the manually tracked balances as defined here with additionally a current usd equivalent value per account.

Status Codes:

  • 200 OK – Balances successfully added

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

  • 401 Unauthorized – User is not logged in.

  • 409 Conflict – Provided tags do not exist. Check message for details.

  • 500 Internal Server Error – Internal rotki error

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

Editing manually tracked balances

PATCH /api/(version)/balances/manual

Note

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

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

Example Request:

http

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

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

curl

curl -i -X PATCH http://localhost:5042/api/1/balances/manual/ -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"balances": [{"identifier": 1, "asset": "XMR", "label": "My monero wallet", "amount": "4.5", "location": "blockchain", "balance_type": "asset"}, {"identifier": 3, "asset": "ETH", "label": "My favorite wallet", "amount": "10", "tags": [], "location": "kraken", "balance_type": "liability"}]}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/balances/manual/ --header="Content-Type: application/json;charset=UTF-8" --body-data='{"balances": [{"identifier": 1, "asset": "XMR", "label": "My monero wallet", "amount": "4.5", "location": "blockchain", "balance_type": "asset"}, {"identifier": 3, "asset": "ETH", "label": "My favorite wallet", "amount": "10", "tags": [], "location": "kraken", "balance_type": "liability"}]}'

httpie

echo '{
  "balances": [
    {
      "amount": "4.5",
      "asset": "XMR",
      "balance_type": "asset",
      "identifier": 1,
      "label": "My monero wallet",
      "location": "blockchain"
    },
    {
      "amount": "10",
      "asset": "ETH",
      "balance_type": "liability",
      "identifier": 3,
      "label": "My favorite wallet",
      "location": "kraken",
      "tags": []
    }
  ]
}' | http PATCH http://localhost:5042/api/1/balances/manual/ Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/balances/manual/', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'balances': [{'identifier': 1, 'asset': 'XMR', 'label': 'My monero wallet', 'amount': '4.5', 'location': 'blockchain', 'balance_type': 'asset'}, {'identifier': 3, 'asset': 'ETH', 'label': 'My favorite wallet', 'amount': '10', 'tags': [], 'location': 'kraken', 'balance_type': 'liability'}]})
Request JSON Object:

  • accounts (list[object]) – A list of manual balances to edit. As defined here.

Example Response:

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

{
    "result": {
    "balances": [{
            "identifier" 1,
            "asset": "XMR",
            "label": "My monero wallet",
            "amount": "4.5",
            "usd_value": "210.548",
            "tags": ["public"],
            "location": "blockchain",
            "balance_type": "asset"
        }, {
            "identifier": 2,
            "asset": "BTC",
            "label": "My XPUB BTC wallet",
            "amount": "1.425",
            "usd_value": "9087.22",
            "location": "blockchain",
            "balance_type": "asset"
        }, {
            "identifier": 3,
            "asset": "ZEC",
            "label" "My favorite wallet",
            "amount": "10"
            "usd_value": "1330.85"
            "location": "kraken",
            "balance_type": "asset"
        }]
    "message": ""
}
Response JSON Object:

  • result (object) – An object containing all the manually tracked balances as defined here with additionally a current usd equivalent value per account.

Status Codes:

  • 200 OK – Balances successfully edited

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

  • 401 Unauthorized – User is not logged in.

  • 409 Conflict – Provided tags do not exist. Check message for details.

  • 500 Internal Server Error – Internal rotki error

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

Deleting manually tracked balances

DELETE /api/(version)/balances/manual/

Note

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

Doing a DELETE on the the manual balances endpoint with a list of identifiers of manually tracked balances will remove these balances from the database for the current user.

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

Example Request:

http

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

{"ids": [1, 3]}

curl

curl -i -X DELETE http://localhost:5042/api/1/balances/manual -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"ids": [1, 3]}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/balances/manual --header="Content-Type: application/json;charset=UTF-8" --body-data='{"ids": [1, 3]}'

httpie

echo '{
  "ids": [
    1,
    3
  ]
}' | http DELETE http://localhost:5042/api/1/balances/manual Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/balances/manual', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'ids': [1, 3]})
Request JSON Object:

  • balances (list[string]) – A list of labels of manually tracked balances to delete

Example Response:

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

{
    "result": {
    "balances": [{
            "identifier": 2,
            "asset": "BTC",
            "label": "My XPUB BTC wallet",
            "amount": "1.425",
            "usd_value": "9087.22",
            "location": "blockchain",
            "balance_type": "asset"
        }]
    "message": ""
}
Response JSON Object:

  • result (object) – An object containing all the manually tracked balances as defined here with additionally a current usd equivalent value per account.

Status Codes:

Getting watchers

GET /api/(version)/watchers

Note

This endpoint is only available for premium users

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

Example Request:

http

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

curl

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

wget

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

httpie

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

python-requests

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

Example Response:

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

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

  • result (object) – An list containing all the watcher results.

Request JSON Object:

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

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

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

Status Codes:
For makervault ratio the possible arguments are:

  • vault_id: The id of the vault to watcher

  • ratio: The target ratio to watch for

  • op: The comparison operator:

    • lt: less than the given ratio

    • le: less than or equal to the given ratio

    • gt: greater than the the given ratio

    • ge: greater than or equal to the given ratio

Adding new watcher

PUT /api/(version)/watchers/

Note

This endpoint is only available for premium users

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

Example Request:

http

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

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

curl

curl -i -X PUT http://localhost:5042/api/1/watchers/ -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"watchers": [{"type": "makervault_collateralization_ratio", "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}}, {"type": "makervault_collateralization_ratio", "args": {"ratio": "185.55", "op": "lt", "vault_id": "456"}}]}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/watchers/ --header="Content-Type: application/json;charset=UTF-8" --body-data='{"watchers": [{"type": "makervault_collateralization_ratio", "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}}, {"type": "makervault_collateralization_ratio", "args": {"ratio": "185.55", "op": "lt", "vault_id": "456"}}]}'

httpie

echo '{
  "watchers": [
    {
      "args": {
        "op": "gt",
        "ratio": "200.5",
        "vault_id": "24"
      },
      "type": "makervault_collateralization_ratio"
    },
    {
      "args": {
        "op": "lt",
        "ratio": "185.55",
        "vault_id": "456"
      },
      "type": "makervault_collateralization_ratio"
    }
  ]
}' | http PUT http://localhost:5042/api/1/watchers/ Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/watchers/', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'watchers': [{'type': 'makervault_collateralization_ratio', 'args': {'ratio': '200.5', 'op': 'gt', 'vault_id': '24'}}, {'type': 'makervault_collateralization_ratio', 'args': {'ratio': '185.55', 'op': 'lt', 'vault_id': '456'}}]})
Request JSON Object:

  • watchers (list[object]) – A list of watchers to add as defined in the above section but without an identifier. The identifier is created server-side and returned in the response.

Example Response:

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

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

  • result (object) – An object containing all the watchers, including the ones that were added. The watchers follow the schema defined above.

Status Codes:

Editing watchers

PATCH /api/(version)/watchers

Note

This endpoint is only available for premium users

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

Example Request:

http

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

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

curl

curl -i -X PATCH http://localhost:5042/api/1/watchers/ -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"watchers": [{"identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=", "type": "makervault_collateralization_ratio", "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}}, {"identifier": "7a4m7vRrLLOipwNmzhAVdo6FaGgr0XKGYLyjHqWa2KQ=", "type": "makervault_collateralization_ratio", "args": {"ratio": "185.55", "op": "lt", "vault_id": "456"}}]}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/watchers/ --header="Content-Type: application/json;charset=UTF-8" --body-data='{"watchers": [{"identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=", "type": "makervault_collateralization_ratio", "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}}, {"identifier": "7a4m7vRrLLOipwNmzhAVdo6FaGgr0XKGYLyjHqWa2KQ=", "type": "makervault_collateralization_ratio", "args": {"ratio": "185.55", "op": "lt", "vault_id": "456"}}]}'

httpie

echo '{
  "watchers": [
    {
      "args": {
        "op": "gt",
        "ratio": "200.5",
        "vault_id": "24"
      },
      "identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=",
      "type": "makervault_collateralization_ratio"
    },
    {
      "args": {
        "op": "lt",
        "ratio": "185.55",
        "vault_id": "456"
      },
      "identifier": "7a4m7vRrLLOipwNmzhAVdo6FaGgr0XKGYLyjHqWa2KQ=",
      "type": "makervault_collateralization_ratio"
    }
  ]
}' | http PATCH http://localhost:5042/api/1/watchers/ Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/watchers/', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'watchers': [{'identifier': '6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=', 'type': 'makervault_collateralization_ratio', 'args': {'ratio': '200.5', 'op': 'gt', 'vault_id': '24'}}, {'identifier': '7a4m7vRrLLOipwNmzhAVdo6FaGgr0XKGYLyjHqWa2KQ=', 'type': 'makervault_collateralization_ratio', 'args': {'ratio': '185.55', 'op': 'lt', 'vault_id': '456'}}]})
Request JSON Object:

  • watchers (list[object]) – A list of watcher to edit. As defined here.

Example Response:

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

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

  • result (object) – An object containing all the watchers as defined here

Status Codes:

Deleting watchers

DELETE /api/(version)/watchers/

Note

This endpoint is only available for premium users

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

Example Request:

http

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

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

curl

curl -i -X DELETE http://localhost:5042/api/1/watchers -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"watchers": ["6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ", "92Jm7vRrLLOipwNXzhAVdo6XaGAr0XKGYLyjHqWa2KA"]}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/watchers --header="Content-Type: application/json;charset=UTF-8" --body-data='{"watchers": ["6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ", "92Jm7vRrLLOipwNXzhAVdo6XaGAr0XKGYLyjHqWa2KA"]}'

httpie

echo '{
  "watchers": [
    "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ",
    "92Jm7vRrLLOipwNXzhAVdo6XaGAr0XKGYLyjHqWa2KA"
  ]
}' | http DELETE http://localhost:5042/api/1/watchers Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/watchers', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'watchers': ['6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ', '92Jm7vRrLLOipwNXzhAVdo6XaGAr0XKGYLyjHqWa2KA']})
Request JSON Object:

  • watchers (list[string]) – A list of identifier of watchers to delete

Example Response:

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

{
    "result": [{
      "identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=",
      "type": "makervault_collateralization_ratio",
      "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}
     }],
    "message": ""
}
Response JSON Object:

  • result (object) – An object containing all the watchers after deletion. The watchers follow the schema defined above.

Status Codes:

Dealing with ignored assets

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

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

Example Request:

http

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

curl

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

wget

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

httpie

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

python-requests

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

Example Response:

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

{
    "result": ["eip155:1/erc20:0xAf30D2a7E90d7DC361c8C4585e9BB7D2F6f15bc7", "eip155:1/erc20:0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413"]
    "message": ""
}
Response JSON Object:

  • result (list) – A list of asset names that are currently ignored.

Status Codes:
PUT /api/(version)/assets/ignored/

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

Example Request:

http

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

{"assets": ["eip155:1/erc20:0x6810e776880C02933D47DB1b9fc05908e5386b96"]}

curl

curl -i -X PUT http://localhost:5042/api/1/assets/ignored -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"assets": ["eip155:1/erc20:0x6810e776880C02933D47DB1b9fc05908e5386b96"]}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/assets/ignored --header="Content-Type: application/json;charset=UTF-8" --body-data='{"assets": ["eip155:1/erc20:0x6810e776880C02933D47DB1b9fc05908e5386b96"]}'

httpie

echo '{
  "assets": [
    "eip155:1/erc20:0x6810e776880C02933D47DB1b9fc05908e5386b96"
  ]
}' | http PUT http://localhost:5042/api/1/assets/ignored Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/assets/ignored', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'assets': ['eip155:1/erc20:0x6810e776880C02933D47DB1b9fc05908e5386b96']})
Request JSON Object:

  • assets (list) – A list of asset symbols to add to the ignored assets.

Example Response:

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

{
    "result": {"successful":[],"no_action":["eip155:1/erc20:0x255Aa6DF07540Cb5d3d297f0D0D4D84cb52bc8e6"]},
    "message": ""
}
Response JSON Object:

  • successful (list) – A list of asset identifiers that were added to the list of ignored assets.

  • no_action (list) – A list of assets that were already ignored and no action was taken on them.

Status Codes:
DELETE /api/(version)/assets/ignored/

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

Example Request:

http

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

{"assets": ["eip155:1/erc20:0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413"]}

curl

curl -i -X DELETE http://localhost:5042/api/1/assets/ignored -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"assets": ["eip155:1/erc20:0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413"]}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/assets/ignored --header="Content-Type: application/json;charset=UTF-8" --body-data='{"assets": ["eip155:1/erc20:0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413"]}'

httpie

echo '{
  "assets": [
    "eip155:1/erc20:0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413"
  ]
}' | http DELETE http://localhost:5042/api/1/assets/ignored Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/assets/ignored', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'assets': ['eip155:1/erc20:0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413']})
Request JSON Object:

  • assets (list) – A list of asset symbols to remove from the ignored assets.

Example Response:

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

{
    "result": {"successful":[],"no_action":["ETH"]},
    "message": ""
}
Response JSON Object:

  • successful (list) – A list of asset identifiers that were removed from the list of ignored assets.

  • no_action (list) – A list of assets that weren’t ignored and no action was taken on them.

Status Codes:

False positive in spam assets

POST /api/(version)/assets/ignored/whitelist

Doing a POST on this endpoint will mark the provided token as a false positive spam asset. This will remove it from the list of ignored assets, remove the spam value from the protocol field and add it to the list of false positives.

Example Request

http

PATH /api/1/assets/ignored/whitelist HTTP/1.1
Host: localhost:5042

{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}

curl

curl -i -X PATH http://localhost:5042/api/1/assets/ignored/whitelist --data-raw '{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}'

wget

wget -S -O- --method=PATH http://localhost:5042/api/1/assets/ignored/whitelist --body-data='{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}'

httpie

echo '{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}' | http PATH http://localhost:5042/api/1/assets/ignored/whitelist

python-requests

requests.path('http://localhost:5042/api/1/assets/ignored/whitelist', data='{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}')
Request JSON Array of Objects:

  • token (string) – The identifier of the evm token that will be marked as false positive

Example Response:

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

{
  "result": true,
  "message": ""
}
Response JSON Object:

  • result (bool) – Boolean denoting success or failure.

Status Codes:
GET /api/(version)/assets/ignored/whitelist

Doing a GET on this endpoint will return a list of the assets that are whitelisted.

Example Request

http

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

curl

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

wget

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

httpie

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

python-requests

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

Example Response:

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

{
  "result": ['eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F'],
  "message": ""
}
Response JSON Object:

  • result (bool) – list of the assets whitelisted.

Status Codes:
DELETE /api/(version)/assets/ignored/whitelist

Doing a DELETE on this endpoint will remove the provided token from the list of false positives.

Example Request

http

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

{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}

curl

curl -i -X DELETE http://localhost:5042/api/1/assets/ignored/whitelist --data-raw '{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/assets/ignored/whitelist --body-data='{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}'

httpie

echo '{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}' | http DELETE http://localhost:5042/api/1/assets/ignored/whitelist

python-requests

requests.delete('http://localhost:5042/api/1/assets/ignored/whitelist', data='{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}')
Request JSON Array of Objects:

  • token (string) – The identifier of the evm token that will be removed from the false positive whitelist

Example Response:

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

{
  "result": true,
  "message": ""
}
Response JSON Object:

  • result (bool) – Boolean denoting success or failure.

Status Codes:

Toggle spam status in evm tokens

POST /api/(version)/assets/evm/spam/

Doing a POST on this endpoint will mark the provided token as a spam token. It will move the token to the list of ignored assets and remove it from the list of whitelisted tokens. Any protocol value that the token might have will be overwritten.

Example Request

http

PATH /api/1/assets/evm/spam HTTP/1.1
Host: localhost:5042

{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}

curl

curl -i -X PATH http://localhost:5042/api/1/assets/evm/spam --data-raw '{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}'

wget

wget -S -O- --method=PATH http://localhost:5042/api/1/assets/evm/spam --body-data='{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}'

httpie

echo '{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}' | http PATH http://localhost:5042/api/1/assets/evm/spam

python-requests

requests.path('http://localhost:5042/api/1/assets/evm/spam', data='{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}')
Request JSON Array of Objects:

  • token (string) – The identifier of the evm token that will be marked as spam

Example Response:

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

{
  "result": true,
  "message": ""
}
Response JSON Object:

  • result (bool) – Boolean denoting success or failure.

Status Codes:
DELETE /api/(version)/assets/evm/spam/

Doing a DELETE on this endpoint will remove the spam protocol from the token setting it to null. It will also remove the token from the list of ignored assets.

Example Request

http

DELETE /api/1/assets/evm/spam HTTP/1.1
Host: localhost:5042

{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}

curl

curl -i -X DELETE http://localhost:5042/api/1/assets/evm/spam --data-raw '{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/assets/evm/spam --body-data='{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}'

httpie

echo '{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}' | http DELETE http://localhost:5042/api/1/assets/evm/spam

python-requests

requests.delete('http://localhost:5042/api/1/assets/evm/spam', data='{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}')
Request JSON Array of Objects:

  • token (string) – The identifier of the evm token that will be updated removing the protocol value of spam.

Example Response:

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

{
  "result": true,
  "message": ""
}
Response JSON Object:

  • result (bool) – Boolean denoting success or failure.

Status Codes:

Dealing with ignored actions

PUT /api/(version)/actions/ignored

Doing a PUT on the ignored actions endpoint will add action identifiers for ignoring of a given action type during accounting. Returns the list of all ignored action identifiers of the given type after the addition.

Example Request:

http

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

{"action_type": "history event", "data": ["Z231-XH23K"]}

curl

curl -i -X PUT http://localhost:5042/api/1/actions/ignored -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"action_type": "history event", "data": ["Z231-XH23K"]}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/actions/ignored --header="Content-Type: application/json;charset=UTF-8" --body-data='{"action_type": "history event", "data": ["Z231-XH23K"]}'

httpie

echo '{
  "action_type": "history event",
  "data": [
    "Z231-XH23K"
  ]
}' | http PUT http://localhost:5042/api/1/actions/ignored Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/actions/ignored', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'action_type': 'history event', 'data': ['Z231-XH23K']})
Request JSON Object:

  • action_type (str) – A type of actions whose ignored ids to add. Defined above. Depending on the type, the data field is different.

  • data (list) – The data to ignore. For type “evm_transaction” it’s an object with the following keys: "evm_chain" with the name of the evm chain the transaction happened in and "tx_hash" the string of the transaction hash to ignore. For all other types it’s a list of strings representing the identifier of the action to ignore.

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)/actions/ignored/

Doing a DELETE on the ignored actions endpoint removes action ids from the list of actions of the given type to be ignored during accounting.

Example Request:

http

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

{
    "action_type": "evm transaction",
    "data": [{
        "evm_chain": "ethereum",
        "tx_hash": "0x34d9887286d8c427e5bf18004c464d150190780e83e89a47906cc63a07267780"
    }, {
        "evm_chain": "optimism",
        "tx_hash": "0x14d9887286d3c427e5bf18004c464d150190780e83e89a47906cc63a07267780"
    }]
}

curl

curl -i -X DELETE http://localhost:5042/api/1/actions/ignored -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"action_type": "evm transaction", "data": [{"evm_chain": "ethereum", "tx_hash": "0x34d9887286d8c427e5bf18004c464d150190780e83e89a47906cc63a07267780"}, {"evm_chain": "optimism", "tx_hash": "0x14d9887286d3c427e5bf18004c464d150190780e83e89a47906cc63a07267780"}]}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/actions/ignored --header="Content-Type: application/json;charset=UTF-8" --body-data='{"action_type": "evm transaction", "data": [{"evm_chain": "ethereum", "tx_hash": "0x34d9887286d8c427e5bf18004c464d150190780e83e89a47906cc63a07267780"}, {"evm_chain": "optimism", "tx_hash": "0x14d9887286d3c427e5bf18004c464d150190780e83e89a47906cc63a07267780"}]}'

httpie

echo '{
  "action_type": "evm transaction",
  "data": [
    {
      "evm_chain": "ethereum",
      "tx_hash": "0x34d9887286d8c427e5bf18004c464d150190780e83e89a47906cc63a07267780"
    },
    {
      "evm_chain": "optimism",
      "tx_hash": "0x14d9887286d3c427e5bf18004c464d150190780e83e89a47906cc63a07267780"
    }
  ]
}' | http DELETE http://localhost:5042/api/1/actions/ignored Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/actions/ignored', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'action_type': 'evm transaction', 'data': [{'evm_chain': 'ethereum', 'tx_hash': '0x34d9887286d8c427e5bf18004c464d150190780e83e89a47906cc63a07267780'}, {'evm_chain': 'optimism', 'tx_hash': '0x14d9887286d3c427e5bf18004c464d150190780e83e89a47906cc63a07267780'}]})
Request JSON Object:

  • action_type (str) – As defined in PUT above.

  • data (list) – As defined in PUT above.

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:

Querying general information

GET /api/(version)/info

Doing a GET on the info endpoint will return general information about rotki. Under the version key we get info on the current version of rotki. When check_for_updates is true if there is a newer version then "download_url" will be populated. If not then only "our_version" and "latest_version" will be. There is a possibility that latest version may not be populated due to github not being reachable. Also we return the data directory and other information.

Note

This endpoint also accepts parameters as query arguments.

Example Request:

http

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

{"check_for_updates": true}

curl

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

wget

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

httpie

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

python-requests

requests.get('http://localhost:5042/api/1/info', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'check_for_updates': True})
Request JSON Object:

  • check_for_updates (bool) – If true will perform an external query to check the latest version available and get the download link.

Example Response:

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

{
  "result": {
          "version": {
                  "our_version": "1.0.3",
                  "latest_version": "1.0.4",
                  "download_url": "https://github.com/rotki/rotki/releases/tag/v1.0.4"
          },
          "data_directory": "/home/username/.local/share/rotki/data",
          "log_level": "DEBUG",
          "accept_docker_risk": false,
          "backend_default_arguments": {
                  "max_logfiles_num": 3,
                  "max_size_in_mb_all_logs": 300,
                  "sqlite_instructions": 5000
          }
  },
  "message": ""
}
Response JSON Object:

  • our_version (str) – The version of rotki present in the system

  • latest_version (str) – The latest version of rotki available

  • download_url (str) – URL link to download the latest version

  • data_directory (str) – The rotki data directory

  • log_level (str) – The log level used in the backend. Can be DEBUG, INFO, WARN, ERROR or CRITICAL.

  • accept_docker_risk (bool) – A boolean indicating if the user has passed an environment variable to the backend process acknowledging the security issues with the docker setup: https://github.com/rotki/rotki/issues/5176

  • backend_default_arguments (object) – A mapping of backend arguments to their default values so that the frontend can know about them.

Status Codes:

Sending a Ping

GET /api/(version)/ping

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

Example Request:

http

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

curl

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

wget

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

httpie

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

python-requests

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

Example Response:

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

{
    "result": true,
    "message": ""
}
Response JSON Object:

  • result (bool) – The result field in this response is a simple boolean value indicating success or failure.

Status Codes:

Data imports

PUT /api/(version)/import

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

Note

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

Note

If you want to provide a stream of data instead of a path, you can call POST on this endpoint and provide the stream in filepath variable.

Example Request:

http

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

{"source": "cointracking", "filepath": "/path/to/data/file", "timestamp_format": "%d/%m/%Y %H:%M:%S"}

curl

curl -i -X PUT http://localhost:5042/api/1/import -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"filepath": "/path/to/data/file", "source": "cointracking", "timestamp_format": "%d/%m/%Y %H:%M:%S"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/import --header="Content-Type: application/json;charset=UTF-8" --body-data='{"filepath": "/path/to/data/file", "source": "cointracking", "timestamp_format": "%d/%m/%Y %H:%M:%S"}'

httpie

echo '{
  "filepath": "/path/to/data/file",
  "source": "cointracking",
  "timestamp_format": "%d/%m/%Y %H:%M:%S"
}' | http PUT http://localhost:5042/api/1/import Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/import', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'filepath': '/path/to/data/file', 'source': 'cointracking', 'timestamp_format': '%d/%m/%Y %H:%M:%S'})
Request JSON Object:

  • source (str) – The source of the data to import. Valid values are "cointracking", "cryptocom", "blockfi_transactions", "blockfi_trades", "nexo", "shapeshift_trades", "uphold_transactions", "bitmex_wallet_history", "bisq_trades", "binance", "rotki_events", "rotki_trades", "bitcoin_tax", "bitstamp", "bittrex", "kucoin".

  • filepath (str) – The filepath to the data for importing

  • timestamp_format (str) – Optional. Custom format to use for dates in the CSV file. Should follow rules at Datetime docs.

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:

ERC20 token info

GET /api/(version)/blockchains/evm/erc20details

Doing a GET to this endpoint will return basic information about a token by calling the decimals/name/symbol methods.

Note

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

Example Request:

http

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

{"address": "0x6B175474E89094C44Da98b954EedeAC495271d0F", "evm_chain": "optimism"}

curl

curl -i -X GET http://localhost:5042/api/1/blockchains/eth/erc20details -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0x6B175474E89094C44Da98b954EedeAC495271d0F", "evm_chain": "optimism"}'

wget

wget -S -O- http://localhost:5042/api/1/blockchains/eth/erc20details --header="Content-Type: application/json;charset=UTF-8" --body-data='{"address": "0x6B175474E89094C44Da98b954EedeAC495271d0F", "evm_chain": "optimism"}'

httpie

echo '{
  "address": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
  "evm_chain": "optimism"
}' | http http://localhost:5042/api/1/blockchains/eth/erc20details Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/blockchains/eth/erc20details', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'address': '0x6B175474E89094C44Da98b954EedeAC495271d0F', 'evm_chain': 'optimism'})
Request JSON Object:

  • address (str) – The checksumed address of a contract

  • evm_chain (str) – The name of the evm chain to check for token info e.g. "ethereum", "optimism" etc.

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

Example Response:

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

{
    "result": {
       "decimals": 18,
       "symbol": "DAI",
       "name": "Dai Stablecoin"
     },
    "message": ""
}
Response JSON Object:

  • result (object) – The result field in this response is a object with a minimum of one attribute.

  • decimals (int) – Number of decimals for the requested contract. null if this information is not available on chain.

  • symbol (str) – Symbol for the requested contract. null if this information is not available on chain.

  • name (str) – Name for the requested contract. null if this information is not available on chain.

  • message (str) – Empty string if there is no issues with the contract, for example, it not existing on the chain.

Status Codes:

All Binance markets

GET /api/(version)/exchanges/binance/pairs

Doing a GET to this endpoint will return all the market pairs available at binance.

Note

This endpoint will only return information if either Binance or Binance US are configured

Example Request:

http

GET /api/1/exchanges/binance/pairs?location=binance HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET 'http://localhost:5042/api/1/exchanges/binance/pairs?location=binance'

wget

wget -S -O- 'http://localhost:5042/api/1/exchanges/binance/pairs?location=binance'

httpie

http 'http://localhost:5042/api/1/exchanges/binance/pairs?location=binance'

python-requests

requests.get('http://localhost:5042/api/1/exchanges/binance/pairs?location=binance')
Query Parameters:

  • location (string) – Either binance or binanceus locations. This argument will filter the result based on the exchange type.

Example Response:

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

{
    "result": ["BTCUSD", "ETHUSD", "XRPUSD"],
    "message": ""
}
Status Codes:

  • 200 OK – Pairs successfully queried

  • 502 Bad Gateway – Failed to query pairs from the binance API and the database.

User selected Binance markets

GET /api/(version)/exchanges/binance/pairs/(exchange account name)

Doing a GET to this endpoint will return the market pairs that the user has selected to be queried at binance.

Example Request:

http

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

curl

curl -i -X GET http://localhost:5042/api/1/exchanges/binance/pairs/testExchange

wget

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

httpie

http http://localhost:5042/api/1/exchanges/binance/pairs/testExchange

python-requests

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

Example Response:

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

{
    "result": ["BTCUSD", "ETHUSD"],
    "message": ""
}

Querying NFTs

GET /api/(version)/nfts

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 NFTs endpoint will query all NFTs for all user tracked addresses.

Example Request:

http

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

{"async_query": false, "ignore_cache": true}

curl

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

wget

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

httpie

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

python-requests

requests.get('http://localhost:5042/api/1/nfts', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': False, 'ignore_cache': True})
Request JSON Object:

  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

Parameters:

  • 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": {
    "addresses": {
      "0xeE3766e4F996DC0e0F8c929954EAAFef3441de87": [
        {
          "token_identifier": "8636",
          "name": "BASTARD GAN PUNK V2 #8636",
          "background_color": null,
          "image_url": "https://lh3.googleusercontent.com/kwF-39qZlluEalQnNv-yMxbntzNdc3g00pK2xALkpoir9ooWttVUO2hVFWOgPtOkJOHufYRajfn-nNFdjruRQ4YaMgOYHEB8E4CdjBk",
          "external_link": "https://www.bastardganpunks.club/v2/8636",
          "price_in_asset": "0.025",
          "price_asset": "ETH",
          "price_usd": "250",
          "collection": {
            "name": "BASTARD GAN PUNKS V2",
            "banner_image": "https://lh3.googleusercontent.com/InX38GA4YmuR2ukDhN0hjf8-Qj2U3Tdw3wD24IsbjuXNtrTZXNwWiIeWR9bJ_-rEUOnQgkpLbj71TDKrzNzHLHkOSRdLo8Yd2tE3_jg=s2500",
            "description": "VERSION 2 OF BASTARD GAN PUNKS ARE COOLER, BETTER AND GOOFIER THAN BOTH BOOMER CRYPTOPUNKS & VERSION 1 BASTARD GAN PUNKS. THIS TIME, ALL CRYPTOPUNK ATTRIBUTES ARE EXTRACTED AND A NEW DATASET OF ALL COMBINATIONS OF THEM ARE TRAINED WITH GAN TO GIVE BIRTH TO EVEN MORE BADASS ONES. ALSO EACH ONE HAS A UNIQUE STORY GENERATED FROM MORE THAN 10K PUNK & EMO SONG LYRICS VIA GPT-2 LANGUAGE PROCESSING ALGORITHM. \r\n\r\nBASTARDS ARE SLOWLY DEGENERATING THE WORLD. ADOPT ONE TO KICK EVERYONE'S ASSES!\r\n\r\nDISCLAIMER: THIS PROJECT IS NOT AFFILIATED WITH LARVA LABS",
            "large_image": "https://lh3.googleusercontent.com/vF8johTucYy6yycIOJTM94LH-wcDQIPTn9-eKLMbxajrm7GZfJJWqxdX6uX59pA4n4n0QNEn3bh1RXcAFLeLzJmq79aZmIXVoazmVw=s300"
          }
        }
      ]
    },
    "entries_found": 95,
    "entries_limit": 500
  },
  "message": ""
}
Response JSON Object:

  • addresses (object) – A mapping of ethereum addresses to list of owned NFTs.

  • entries_found (int) – The number of NFT entries found. If non-premium and the free limit has been hit this will be equal to the limit, since we stop searching after the limit.

  • entries_limit (int) – The free limit for NFTs.

  • token_identifier (string) – The identifier of the specific NFT token for the given contract type. This is not a unique id across all NFTs.

  • background_color (string) – [Optional]. A color for the background of the image of the NFT. Can be Null.

  • image_url (string) – [Optional]. Link to the image of the NFT. Can be Null.

  • name (string) – [ Optional] The name of the NFT. Can be Null.

  • external_link (string) – [Optional]. A link to the page of the creator of the NFT. Can be Null.

  • permalink (string) – [Optional]. A link to the NFT in opensea.

  • price_in_asset (string) – The last known price of the NFT in price_asset. Can be zero.

  • price_asset (string) – The identifier of the asset used for price_in_asset.

  • price_usd (string) – The last known price of the NFT in USD. Can be zero.

Status Codes:

Show NFT Balances

GET /api/(version)/nfts/balances

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 NFTs balances endpoint will query all NFTs for all user tracked addresses and return those whose price can be detected.

Example Request:

http

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

{"async_query": false, "ignore_cache": false, "offset": 3, "limit": 1}

curl

curl -i -X GET http://localhost:5042/api/1/nfts/balances -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": false, "ignore_cache": false, "limit": 1, "offset": 3}'

wget

wget -S -O- http://localhost:5042/api/1/nfts/balances --header="Content-Type: application/json;charset=UTF-8" --body-data='{"async_query": false, "ignore_cache": false, "limit": 1, "offset": 3}'

httpie

echo '{
  "async_query": false,
  "ignore_cache": false,
  "limit": 1,
  "offset": 3
}' | http http://localhost:5042/api/1/nfts/balances Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/nfts/balances', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': False, 'ignore_cache': False, 'limit': 1, 'offset': 3})
Request JSON Object:

  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not

  • owner_addresses (list[string][optional]) – A list of evm addresses. If provided, only nfts owned by these addresses will be returned.

  • name (string[optional]) – Optional nfts name to filter by.

  • collection_name (string[optional]) – Optional nfts collection_name to filter by.

  • ignored_assets_handling (string[optional]) – A flag to specify how to handle ignored assets. Possible values are ‘none’, ‘exclude’ and ‘show_only’. You can write ‘none’ in order to not handle them in any special way (meaning to show them too). This is the default. You can write ‘exclude’ if you want to exclude them from the result. And you can write ‘show_only’ if you want to only see the ignored assets in the result.

  • 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_attributes (list[string][optional]) – This is the list of attributes of the nft by which to order the results. By default we sort using name.

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

  • lps_handling (string[optional]) – A flag to specify how to handle LP NFTs. Possible values are ‘all_nfts’ (default), ‘only_lps’ and ‘exclude_lps’. You can use ‘only_lps’ if you want to only include LPs NFTs in the result or you can use ‘exclude_lps’ if you want NFTs not marked as LP positions.

Parameters:

  • 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": {
          "entries": [
            {
              "id": "unique id",
              "name": "a name",
              "collection_name": "A collection name",
              "manually_input": true,
              "price_asset": "ETH",
              "price_in_asset": "1",
              "usd_price": "2501.15"
              "image_url": "https://storage.opensea.io/files/305952feb5321a50d5d4f6ab6c16da1f.mov",
              "is_lp": false
            }, {
              "id": "unique id 2",
              "name": null,
              "collection_name": "A collection name",
              "manually_input": false,
              "price_asset": "USD",
              "price_in_asset": "150.55",
              "usd_price": "150.55"
              "image_url": "https://lh3.googleusercontent.com/xJpOAw7P96jdPgs91w7ZQMTq91tvcCva4J2RYHh7LjFufod_UP9FE0bVjhp1cYpbx2p1qFFj2NDFf3oS0eEcNI3L5w",
              "is_lp": true
            },
          ],
          "entries_found": 2,
          "entries_total": 10,
          "total_usd_value": "2651.70"
      },
      "message": ""
  }
Response JSON Object:

  • entries (object) – A list of nfts balances. name can also be null. collection_name can be null if nft does not have a collection.

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

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

  • total_usd_value (int) – Total usd value of the nfts in the filter.

Status Codes:

Querying database information

GET /api/(version)/database/info

Doing a GET on the database information will query information about the global database. If a user is logged in it will also query info on the user’s DB and potential backups.

Example Request:

http

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

curl

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

wget

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

httpie

http http://localhost:5042/api/1/history/database/info

python-requests

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

Example Response:

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

{
    "result": {
        "globaldb": {"globaldb_assets_version": 10, "globaldb_schema_version": 2},
        "userdb": {
            "info": {
                "filepath": "/home/username/.local/share/rotki/data/user/rotkehlchen.db",
                "size": 5590482,
                "version": 30
            },
            "backups": [{
                "size": 323441, "time": 1626382287, "version": 27
            }, {
                "size": 623441, "time": 1623384287, "version": 24
            }]
    }
    "message": ""
}
Response JSON Object:

  • globaldb (object) – An object with information on the global DB

  • globaldb_assets_version (int) – The version of the global database’s assets.

  • globaldb_schema_version (int) – The version of the global database’s schema.

  • userdb (object) – An object with information on the currently logged in user’s DB. If there is no currently logged in user this is an empty object.

  • info (object) – Under the userdb this contains the info of the currently logged in user. It has the path to the DB file, the size in bytes and the DB version.

  • backups (list) – Under the userdb this contains the list of detected backups (if any) for the user db. Each list entry is an object with the size in bytes of the backup, the unix timestamp in which it was taken and the user DB version.

Status Codes:

Creating a database backup

PUT /api/(version)/database/backups

Doing a PUT on the database backups endpoint will immediately create a backup of the current user’s database.

Example Request:

http

PUT /api/1/history/database/backups HTTP/1.1
Host: localhost:5042

curl

curl -i -X PUT http://localhost:5042/api/1/history/database/backups

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/history/database/backups

httpie

http PUT http://localhost:5042/api/1/history/database/backups

python-requests

requests.put('http://localhost:5042/api/1/history/database/backups')

Example Response:

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

{
    "result": "/path/to/created/1633042045_rotkehlchen_db_v28.backup",
    "message": ""
}
Response JSON Object:

  • result (string) – The full path of the newly created database backup

Status Codes:

Deleting a database backup

DELETE /api/(version)/database/backups

Doing a DELETE on the database backups endpoint with the backup filepath will delete it.

Example Request:

http

DELETE /api/1/history/database/backups HTTP/1.1
Host: localhost:5042

{"file": "/path/to/created/1633042045_rotkehlchen_db_v28.backup"}

curl

curl -i -X DELETE http://localhost:5042/api/1/history/database/backups --data-raw '{"file": "/path/to/created/1633042045_rotkehlchen_db_v28.backup"}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/history/database/backups --body-data='{"file": "/path/to/created/1633042045_rotkehlchen_db_v28.backup"}'

httpie

echo '{"file": "/path/to/created/1633042045_rotkehlchen_db_v28.backup"}' | http DELETE http://localhost:5042/api/1/history/database/backups

python-requests

requests.delete('http://localhost:5042/api/1/history/database/backups', data='{"file": "/path/to/created/1633042045_rotkehlchen_db_v28.backup"}')

Example Response:

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

{
    "result": true,
    "message": ""
}
Response JSON Object:

  • result (bool) – True for success

Status Codes:

Downloading a database backup

GET /api/(version)/database/backups

Doing a GET on the database backups endpoint with the backup filepath will download it.

Example Request:

http

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

{"file": "/path/to/created/1633042045_rotkehlchen_db_v28.backup"}

curl

curl -i -X GET http://localhost:5042/api/1/history/database/backups --data-raw '{"file": "/path/to/created/1633042045_rotkehlchen_db_v28.backup"}'

wget

wget -S -O- http://localhost:5042/api/1/history/database/backups --body-data='{"file": "/path/to/created/1633042045_rotkehlchen_db_v28.backup"}'

httpie

echo '{"file": "/path/to/created/1633042045_rotkehlchen_db_v28.backup"}' | http http://localhost:5042/api/1/history/database/backups

python-requests

requests.get('http://localhost:5042/api/1/history/database/backups', data='{"file": "/path/to/created/1633042045_rotkehlchen_db_v28.backup"}')

Example Response:

HTTP/1.1 200 OK
Content-Type: application/octet-stream
Status Codes:

Get associated locations

GET /api/(version)/locations/associated

Doing a GET on this endpoint will return a list of locations where the user has information. It contains locations imported in CSV, exchanges and DeFi locations.

Example Request:

http

GET /api/1/locations/associated HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/api/1/locations/associated

wget

wget -S -O- http://localhost:5042/api/1/locations/associated

httpie

http http://localhost:5042/api/1/locations/associated

python-requests

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

Example Response:

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

{
    "result": ["nexo", "kraken", "uniswap"],
    "message": ""
}
Status Codes:

Staking events

GET /api/(version)/staking/kraken

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 staking events for the desired location. At the moment the only valid location is kraken. If the retrieval of new information fails the information at the database will be returned

Example Request:

http

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

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

curl

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

wget

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

httpie

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

python-requests

requests.get('http://localhost:5042/api/1/staking/kraken', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_timestamp': 1451606400, 'only_cache': False, 'to_timestamp': 1571663098})
Request JSON Object:

  • limit (int) – Optional. 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_attributes (list[string]) – Optional. This is the list of attributes of the history by which to order the results. If none is given ‘timestamp’ is assumed. Valid values are: [‘timestamp’, ‘location’, ‘amount’].

  • ascending (list[bool]) – Optional. False by default. Defines the order by which results are returned depending on the chosen order by attribute.

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

  • 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": [
          {
              "event_type": "unstake asset",
              "asset": "ETH2",
              "timestamp": 1636740198,
              "location": "kraken",
              "amount": "0.0600000000",
              "usd_value": "278.7345000000000"
          },
          {
            "event_type": "get reward",
            "asset": "ETH2",
            "timestamp": 1636864588,
            "location": "kraken",
            "amount": "0.0000103220",
            "usd_value": "0.0478582110500"
          },
          {
              "event_type": "stake asset",
              "asset": "ETH",
              "timestamp": 1636738550,
              "location": "kraken",
              "amount": "0.0600000000",
              "usd_value": "278.7345000000000"
          }
        ],
        "entries_found": 3,
        "entries_total": 3,
        "entries_limit": -1,
        "total_usd_value": "0.02",
        "assets": ["ETH2", "ETH"],
        "received": [
            {
                "asset": "ETH2",
                "amount": "0.0000103220",
                "usd_value": "0.21935353362"
            }
        ]
    },
    "message": ""
}
Response JSON Array of Objects:

  • timestamp (int) – The timestamp at which the event occurred

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

  • amount (string) – The amount related to the event

  • asset (string) – Asset involved in the event

  • event_type (string) – Type of event. Can be reward, deposit asset or remove asset.

  • message (string) – It won’t be empty if the query to external services fails for some reason.

  • total_usd_value (string) – Sum of the USD value for the assets received computed at the time of acquisition of each event.

Response JSON Object:

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

  • assets (list[string]) – Assets involved in events ignoring all filters.

  • received (list[object]) – Assets received with the total amount received for each asset and the aggregated USD value at time of acquisition.

Status Codes:

Export assets added by the user

PUT /api/(version)/assets/user

Calling this endpoint with PUT and action download will create a zip file with the assets that are not included by default with vanilla rotki. If no destination folder is provided the generated file is returned with headers application/zip.

Example Request:

http

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

{"action": "download", "destination": "/home/user/Downloads"}

curl

curl -i -X PUT http://localhost:5042/api/1/assets/user -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"action": "download", "destination": "/home/user/Downloads"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/assets/user --header="Content-Type: application/json;charset=UTF-8" --body-data='{"action": "download", "destination": "/home/user/Downloads"}'

httpie

echo '{
  "action": "download",
  "destination": "/home/user/Downloads"
}' | http PUT http://localhost:5042/api/1/assets/user Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/assets/user', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'action': 'download', 'destination': '/home/user/Downloads'})

Example Response:

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

{
    "result": {
          "file": "/home/user/Downloads/assets.zip"
    },
    "message": ""
}
Response JSON Array of Objects:

  • action (string) – Action performed on the endpoint

  • destination (string) – Folder where the generated files will be saved

Status Codes:

Import assets added by the user

PUT /api/(version)/assets/user
POST /api/(version)/assets/user

Doing a put or a post to this endpoint will import the assets in the json file provided. The file has to follow the rotki expected format and will be verified.

Note

If doing a POST the action field is not required.

Note

This endpoint can be called asynchronously.

Example Request:

http

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

{"action": "upload", "file": "/tmp/assets.zip"}

curl

curl -i -X POST http://localhost:5042/api/1/assets/user -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"action": "upload", "file": "/tmp/assets.zip"}'

wget

wget -S -O- http://localhost:5042/api/1/assets/user --header="Content-Type: application/json;charset=UTF-8" --post-data='{"action": "upload", "file": "/tmp/assets.zip"}'

httpie

echo '{
  "action": "upload",
  "file": "/tmp/assets.zip"
}' | http POST http://localhost:5042/api/1/assets/user Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/assets/user', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'action': 'upload', 'file': '/tmp/assets.zip'})
Response JSON Array of Objects:

  • action (string) – Action performed on the endpoint

  • file (string) – The path to the file to upload for PUT. The file itself for POST.

Example Response:

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

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

Handling snapshot manipulation

GET /api/(version)/snapshots/(timestamp)

Doing a GET on this endpoint without any action query parameter will return the database snapshot for the specified timestamp in JSON.

Example Request:

http

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

curl

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

wget

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

httpie

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

python-requests

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

Example Response:

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

{
    "result": {
        "balances_snapshot": [
              {
                  "timestamp": 149095883,
                  "category": "asset",
                  "asset_identifier": "AVAX",
                  "amount": "1000.00",
                  "usd_value": "12929.00",
              }
          ],
        "location_data_snapshot": [
              {
                  "timestamp": 149095883,
                  "location": "external",
                  "usd_value": "12929.00"
              },
              {
                  "timestamp": 149095883,
                  "location": "total",
                  "usd_value": "12929.00"
              }
        ]
    },
    "message": ""
}
Response JSON Object:

  • result (object) – A dictionary representing the snapshot at the specified timestamp.

Status Codes:
GET /api/(version)/snapshots/(timestamp)

Doing a GET on this endpoint with action 'export' will export the database snapshot for the specified timestamp to CSV files and save them in the given directory.

Example Request:

http

GET /api/1/snapshots/149095883?action=export&path=%2Fhome%2Fuser%2Fdocuments HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

curl

curl -i -X GET 'http://localhost:5042/api/1/snapshots/149095883?action=export&path=%2Fhome%2Fuser%2Fdocuments' -H "Content-Type: application/json;charset=UTF-8"

wget

wget -S -O- 'http://localhost:5042/api/1/snapshots/149095883?action=export&path=%2Fhome%2Fuser%2Fdocuments' --header="Content-Type: application/json;charset=UTF-8"

httpie

http 'http://localhost:5042/api/1/snapshots/149095883?action=export&path=%2Fhome%2Fuser%2Fdocuments' Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/snapshots/149095883?action=export&path=%2Fhome%2Fuser%2Fdocuments', headers={'Content-Type': 'application/json;charset=UTF-8'})
Reqquery str path:

The directory in which to write the exported CSV files.

Reqquery str action:

The action to be performed by the endpoint. Can be one of 'export', 'download'.

Example Response:

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

{
    "result": true
    "message": ""
}
Response JSON Object:

  • result (bool) – Boolean denoting success or failure of the query.

Status Codes:

  • 200 OK – Files were exported successfully.

  • 400 Bad Request – Provided query parameter(s) is in some way malformed or given path is not a directory.

  • 401 Unauthorized – No user is currently logged in.

  • 409 Conflict – No snapshot data found for the given timestamp. No permissions to write in the given directory. Check error message.

  • 500 Internal Server Error – Internal rotki error.

GET /api/(version)/snapshots/(timestamp)

Doing a GET on this endpoint with action 'download' will download database snapshot for the specified timestamp as a zip file.

Example Request:

http

GET /api/1/snapshots/149095883?action=download HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

curl

curl -i -X GET 'http://localhost:5042/api/1/snapshots/149095883?action=download' -H "Content-Type: application/json;charset=UTF-8"

wget

wget -S -O- 'http://localhost:5042/api/1/snapshots/149095883?action=download' --header="Content-Type: application/json;charset=UTF-8"

httpie

http 'http://localhost:5042/api/1/snapshots/149095883?action=download' Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/snapshots/149095883?action=download', headers={'Content-Type': 'application/json;charset=UTF-8'})
Reqquery str action:

The action to be performed by the endpoint. Can be one of 'export', 'download'.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/zip
Status Codes:
DELETE /api/(version)/snapshots

Doing a DELETE on this endpoint will delete the snapshot for the specified timestamp.

Example Request:

http

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

{"timestamp": 149095883}

curl

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

wget

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

httpie

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

python-requests

requests.delete('http://localhost:5042/api/1/snapshots', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'timestamp': 149095883})
Request JSON Object:

  • timestamp (int) – The epoch timestamp representing the time of the snapshot to be deleted.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/zip
Status Codes:
PATCH /api/(version)/snapshots/(timestamp)

Doing a PATCH on this endpoint will replace the snapshot at the specified timestamp with the provided payload.

Example Request:

http

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

  {
      "balances_snapshot": [
          {
              "timestamp": 149095883,
              "category": "asset",
              "asset_identifier": "AVAX",
              "amount": "1000.00",
              "usd_value": "12929.00"
          }
      ],
      "location_data_snapshot": [
          {
              "timestamp": 149095883,
              "location": "external",
              "usd_value": "12929.00"
          },
          {
              "timestamp": 149095883,
              "location": "total",
              "usd_value": "12929.00"
          }
      ]
  }

curl

curl -i -X PATCH http://localhost:5042/api/1/snapshots/ -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"balances_snapshot": [{"timestamp": 149095883, "category": "asset", "asset_identifier": "AVAX", "amount": "1000.00", "usd_value": "12929.00"}], "location_data_snapshot": [{"timestamp": 149095883, "location": "external", "usd_value": "12929.00"}, {"timestamp": 149095883, "location": "total", "usd_value": "12929.00"}]}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/snapshots/ --header="Content-Type: application/json;charset=UTF-8" --body-data='{"balances_snapshot": [{"timestamp": 149095883, "category": "asset", "asset_identifier": "AVAX", "amount": "1000.00", "usd_value": "12929.00"}], "location_data_snapshot": [{"timestamp": 149095883, "location": "external", "usd_value": "12929.00"}, {"timestamp": 149095883, "location": "total", "usd_value": "12929.00"}]}'

httpie

echo '{
  "balances_snapshot": [
    {
      "amount": "1000.00",
      "asset_identifier": "AVAX",
      "category": "asset",
      "timestamp": 149095883,
      "usd_value": "12929.00"
    }
  ],
  "location_data_snapshot": [
    {
      "location": "external",
      "timestamp": 149095883,
      "usd_value": "12929.00"
    },
    {
      "location": "total",
      "timestamp": 149095883,
      "usd_value": "12929.00"
    }
  ]
}' | http PATCH http://localhost:5042/api/1/snapshots/ Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/snapshots/', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'balances_snapshot': [{'timestamp': 149095883, 'category': 'asset', 'asset_identifier': 'AVAX', 'amount': '1000.00', 'usd_value': '12929.00'}], 'location_data_snapshot': [{'timestamp': 149095883, 'location': 'external', 'usd_value': '12929.00'}, {'timestamp': 149095883, 'location': 'total', 'usd_value': '12929.00'}]})
Request JSON Object:

  • balances_snapshot (list) – The list of objects representing the balances of an account to be updated. All fields are required i.e "timestamp", "category", "asset_identifier", "amount", "usd_value".

  • location_data_snapshot (list) – The list of objects representing the location data to be updated. All fields are required i.e "timestamp", "location", "usd_value".

Example Response:

HTTP/1.1 200 OK
Content-Type: application/zip
Status Codes:
PUT /api/(version)/snapshots
POST /api/(version)/snapshots

Doing either a PUT or a POST on this import endpoint will import database snapshot from the specified paths in the request body. PUT expect paths to the files to be imported. POST expects the files to be uploaded as multipart/form-data.

Example Request:

http

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

{
    "balances_snapshot_file": "/path/to/balances_snapshot_import.csv",
    "location_data_snapshot_file": "/path/to/location_data_snapshot.csv"
}

curl

curl -i -X PUT http://localhost:5042/api/1/snapshots -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"balances_snapshot_file": "/path/to/balances_snapshot_import.csv", "location_data_snapshot_file": "/path/to/location_data_snapshot.csv"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/snapshots --header="Content-Type: application/json;charset=UTF-8" --body-data='{"balances_snapshot_file": "/path/to/balances_snapshot_import.csv", "location_data_snapshot_file": "/path/to/location_data_snapshot.csv"}'

httpie

echo '{
  "balances_snapshot_file": "/path/to/balances_snapshot_import.csv",
  "location_data_snapshot_file": "/path/to/location_data_snapshot.csv"
}' | http PUT http://localhost:5042/api/1/snapshots Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/snapshots', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'balances_snapshot_file': '/path/to/balances_snapshot_import.csv', 'location_data_snapshot_file': '/path/to/location_data_snapshot.csv'})
Request JSON Object:

  • balances_snapshot_file (str) – The path to a balances_snapshot_import.csv file that was previously exported.

  • location_data_snapshot_file (str) – The path to a location_data_snapshot.csv file that was previously exported.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/zip
Status Codes:

Get ENS names

POST /api/(version)/names/ens/reverse

Doing a POST on the ENS reverse endpoint will return the ENS names for the given ethereum addresses from cache if found and from blockchain otherwise. If ignore_cache is true, then the entire cache will be recreated

Note

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

Example Request:

http

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

  {
      "ethereum_addresses": ["0x1", "0x2"]
  }

.. http:example:: curl wget httpie python-requests

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

      {
          "ethereum_addresses": ["0x1", "0x2"],
          "ignore_cache": true
      }

curl

curl -i -X POST http://nohost/api/1/names/ens/reverse --data-raw '{

      "ethereum_addresses": ["0x1", "0x2"]

  }



.. http:example:: curl wget httpie python-requests



      POST /api/1/naminens/reverse HTTP/1.1

      Host: localhost:5042

      Content-Type: application/json;charset=UTF-8



      {

          "ethereum_addresses": ["0x1", "0x2"],

          "ignore_cache": true

      }'

wget

wget -S -O- http://nohost/api/1/names/ens/reverse --post-data='{

      "ethereum_addresses": ["0x1", "0x2"]

  }



.. http:example:: curl wget httpie python-requests



      POST /api/1/naminens/reverse HTTP/1.1

      Host: localhost:5042

      Content-Type: application/json;charset=UTF-8



      {

          "ethereum_addresses": ["0x1", "0x2"],

          "ignore_cache": true

      }'

httpie

echo '{

      "ethereum_addresses": ["0x1", "0x2"]

  }



.. http:example:: curl wget httpie python-requests



      POST /api/1/naminens/reverse HTTP/1.1

      Host: localhost:5042

      Content-Type: application/json;charset=UTF-8



      {

          "ethereum_addresses": ["0x1", "0x2"],

          "ignore_cache": true

      }' | http POST http://nohost/api/1/names/ens/reverse

python-requests

requests.post('http://nohost/api/1/names/ens/reverse', data='{\r\n\n      "ethereum_addresses": ["0x1", "0x2"]\r\n\n  }\r\n\n\r\n\n.. http:example:: curl wget httpie python-requests\r\n\n\r\n\n      POST /api/1/naminens/reverse HTTP/1.1\r\n\n      Host: localhost:5042\r\n\n      Content-Type: application/json;charset=UTF-8\r\n\n\r\n\n      {\r\n\n          "ethereum_addresses": ["0x1", "0x2"],\r\n\n          "ignore_cache": true\r\n\n      }')
Request JSON Object:

  • ethereum_addresses (list) – A list of ethereum addresses to get names for.

  • ignore_cache (bool) – If true, the entire cache will be updated.

Example Response:

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

{
    "result": {
        "0x1": "name1",
        "0x2": "name2"
    },
    "message": "",
}
Response JSON Object:

  • result (object) – A dictionary of ethereum address to ENS name.

  • message (str) – Error message if any errors occurred.

Status Codes:

Get mappings from addressbook

POST /api/(version)/names/addressbook

Doing a POST on the addressbook endpoint with either /global or /private postfix with a list of addresses will return found address mappings with the specified filter arguments. If no filter argument is specified, all known mappings are returned.

Example Request

http

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

{
  "offset": 0,
  "limit": 1,
  "blockchain": "eth",
  "name_substring": "neighbour",
  "addresses": [
    {"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth"},
    {"address": "bc1qamhqfr5z2ypehv0sqq784hzgd6ws2rjf6v46w8", "blockchain": "btc"},
    {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"}
   ]
}

curl

curl -i -X POST http://localhost:5042/api/1/names/addressbook/global -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"addresses": [{"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth"}, {"address": "bc1qamhqfr5z2ypehv0sqq784hzgd6ws2rjf6v46w8", "blockchain": "btc"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"}], "blockchain": "eth", "limit": 1, "name_substring": "neighbour", "offset": 0}'

wget

wget -S -O- http://localhost:5042/api/1/names/addressbook/global --header="Content-Type: application/json;charset=UTF-8" --post-data='{"addresses": [{"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth"}, {"address": "bc1qamhqfr5z2ypehv0sqq784hzgd6ws2rjf6v46w8", "blockchain": "btc"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"}], "blockchain": "eth", "limit": 1, "name_substring": "neighbour", "offset": 0}'

httpie

echo '{
  "addresses": [
    {
      "address": "0x9531c059098e3d194ff87febb587ab07b30b1306",
      "blockchain": "eth"
    },
    {
      "address": "bc1qamhqfr5z2ypehv0sqq784hzgd6ws2rjf6v46w8",
      "blockchain": "btc"
    },
    {
      "address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"
    }
  ],
  "blockchain": "eth",
  "limit": 1,
  "name_substring": "neighbour",
  "offset": 0
}' | http POST http://localhost:5042/api/1/names/addressbook/global Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/names/addressbook/global', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'addresses': [{'address': '0x9531c059098e3d194ff87febb587ab07b30b1306', 'blockchain': 'eth'}, {'address': 'bc1qamhqfr5z2ypehv0sqq784hzgd6ws2rjf6v46w8', 'blockchain': 'btc'}, {'address': '0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD'}], 'blockchain': 'eth', 'limit': 1, 'name_substring': 'neighbour', 'offset': 0})
Request JSON Object:

  • limit (int[optional]) – This signifies the limit of records to return as per the sql spec.

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

  • name_substring (str[optional]) – The substring to use as filter for the name to be found in the addressbook.

  • blockchain (str[optional]) – The blockchain in which to use the provided name.

  • addresses (object[optional]) – List of addresses that the backend should find names for.

Example Response

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

{
    "result": {
      "entries": [
        { "address": "bc1qamhqfr5z2ypehv0sqq784hzgd6ws2rjf6v46w8", "name": "mtgox", "blockchain": "btc" },
        { "address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "name": "My dear friend Tom", "blockchain": "eth" },
        { "address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD", "name": "Neighbour Frank", "blockchain": "eth" }
       ],
      "entries_found": 1,
      "entries_total": 3
    },
    "message": ""
}
Response JSON Object:

  • entries (object) – An array of address objects. Each entry is composed of the address under the "address" key and other metadata like "name" and "blockchain" for each address.

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

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

  • message (str) – Error message if any errors occurred.

Status Codes:

Insert mappings into addressbook

PUT /api/(version)/names/addressbook

Doing a PUT on the addressbook endpoint with either /global or /private postfix with a list of entries, each entry containing address and a name will add these entries to the addressbook.

Example Request

http

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

{
  "entries": [
    {"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth", "name": "Dude ABC"},
    {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD", "name": "Dude XYZ"}
  ]
}

curl

curl -i -X PUT http://localhost:5042/api/1/names/addressbook/private -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"entries": [{"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth", "name": "Dude ABC"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD", "name": "Dude XYZ"}]}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/names/addressbook/private --header="Content-Type: application/json;charset=UTF-8" --body-data='{"entries": [{"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth", "name": "Dude ABC"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD", "name": "Dude XYZ"}]}'

httpie

echo '{
  "entries": [
    {
      "address": "0x9531c059098e3d194ff87febb587ab07b30b1306",
      "blockchain": "eth",
      "name": "Dude ABC"
    },
    {
      "address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD",
      "name": "Dude XYZ"
    }
  ]
}' | http PUT http://localhost:5042/api/1/names/addressbook/private Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/names/addressbook/private', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'entries': [{'address': '0x9531c059098e3d194ff87febb587ab07b30b1306', 'blockchain': 'eth', 'name': 'Dude ABC'}, {'address': '0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD', 'name': 'Dude XYZ'}]})
Request JSON Object:

  • entries (object) – A list of entries to be added to the addressbook

Example Response

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

{
    "result": true,
    "message": ""
}
Response JSON Object:

  • result (bool) – A boolean which is true in the case that entries were added successfully.

  • message (str) – Error message if any errors occurred.

Status Codes:

Update mappings in the addressbook

PATCH /api/(version)/names/addressbook

Doing a PATCH on the addressbook endpoint with either /global or /private postfix with a list of entries, each entry containing address and a name will updates these entries’ names in the addressbook

Example Request

http

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

{
  "entries": [
    {"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "name": "Dude ABC"},
    {"address": "13EcxFSXEFmJfxGXSQYLfgEXXGZBSF1P753MyHauw5NV4tAV", "name": "Polkacomma"},
    {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD", "name": "Dude XYZ"}
  ]
}

curl

curl -i -X PATCH http://localhost:5042/api/1/names/addressbook/private -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"entries": [{"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "name": "Dude ABC"}, {"address": "13EcxFSXEFmJfxGXSQYLfgEXXGZBSF1P753MyHauw5NV4tAV", "name": "Polkacomma"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD", "name": "Dude XYZ"}]}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/names/addressbook/private --header="Content-Type: application/json;charset=UTF-8" --body-data='{"entries": [{"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "name": "Dude ABC"}, {"address": "13EcxFSXEFmJfxGXSQYLfgEXXGZBSF1P753MyHauw5NV4tAV", "name": "Polkacomma"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD", "name": "Dude XYZ"}]}'

httpie

echo '{
  "entries": [
    {
      "address": "0x9531c059098e3d194ff87febb587ab07b30b1306",
      "name": "Dude ABC"
    },
    {
      "address": "13EcxFSXEFmJfxGXSQYLfgEXXGZBSF1P753MyHauw5NV4tAV",
      "name": "Polkacomma"
    },
    {
      "address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD",
      "name": "Dude XYZ"
    }
  ]
}' | http PATCH http://localhost:5042/api/1/names/addressbook/private Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/names/addressbook/private', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'entries': [{'address': '0x9531c059098e3d194ff87febb587ab07b30b1306', 'name': 'Dude ABC'}, {'address': '13EcxFSXEFmJfxGXSQYLfgEXXGZBSF1P753MyHauw5NV4tAV', 'name': 'Polkacomma'}, {'address': '0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD', 'name': 'Dude XYZ'}]})
Request JSON Object:

  • entries (object) – A list of entries to be updated in the addressbook.

  • address (str) – The address that will be tracked in the addressbook.

  • blockchain (str[optional]) – The blockchain in which to use the provided name.

  • name (str) – Name to be used.

Example Response

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

{
    "result": true,
    "message": ""
}
Response JSON Object:

  • result (bool) – A boolean which is true in case if entries were updated successfully.

  • message (str) – Error message if any errors occurred.

Status Codes:

Delete mappings in the addressbook

DELETE /api/(version)/names/addressbook

Doing a DELETE on the addressbook endpoint with either /global or /private postfix with a list of addresses will delete mappings in the addressbook of the specified addresses

Example Request

http

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

{
  "addresses": [
    {"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth"},
    {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"}
  ]
}

curl

curl -i -X DELETE http://localhost:5042/api/1/names/addressbook/global -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"addresses": [{"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"}]}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/names/addressbook/global --header="Content-Type: application/json;charset=UTF-8" --body-data='{"addresses": [{"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"}]}'

httpie

echo '{
  "addresses": [
    {
      "address": "0x9531c059098e3d194ff87febb587ab07b30b1306",
      "blockchain": "eth"
    },
    {
      "address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"
    }
  ]
}' | http DELETE http://localhost:5042/api/1/names/addressbook/global Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/names/addressbook/global', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'addresses': [{'address': '0x9531c059098e3d194ff87febb587ab07b30b1306', 'blockchain': 'eth'}, {'address': '0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD'}]})
Request JSON Object:

  • entries (object) – A list of addresses to be deleted from the addressbook

  • address (str) – The address that will be deleted in the addressbook.

  • blockchain (str[optional]) – The blockchain for which to delete the name mapping. If is not provided the names for all the chains will be deleted.

Example Response

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

{
    "result": true,
    "message": ""
}
Response JSON Object:

  • result (bool) – A boolean which is true in case if entries were deleted successfully.

  • message (str) – Error message if any errors occurred.

Status Codes:

Search for all known names of an address

POST /api/(version)/names

Doing a POST on all names endpoint with a list of addresses will search for names of these addresses in all places and return a name for each address if found. Only one name is returned. The priority of the returned names adheres to the following order: private addressbook > blockchain account labels > global addressbook > ethereum tokens > hardcoded mappings > ENS names.

Example Request

http

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

{
  "addresses": [
    {"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth"},
    {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"}
  ]
}

curl

curl -i -X POST http://localhost:5042/api/1/names -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"addresses": [{"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"}]}'

wget

wget -S -O- http://localhost:5042/api/1/names --header="Content-Type: application/json;charset=UTF-8" --post-data='{"addresses": [{"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"}]}'

httpie

echo '{
  "addresses": [
    {
      "address": "0x9531c059098e3d194ff87febb587ab07b30b1306",
      "blockchain": "eth"
    },
    {
      "address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"
    }
  ]
}' | http POST http://localhost:5042/api/1/names Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/names', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'addresses': [{'address': '0x9531c059098e3d194ff87febb587ab07b30b1306', 'blockchain': 'eth'}, {'address': '0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD'}]})
Request JSON Object:

  • addresses (object) – List of addresses that the backend should find names for

  • address (str) – The address that will be queried in the addressbook.

  • blockchain (str[optional]) – The chain for which to find names. If is not provided the names are searched for all chains.

Example Response

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

{
    "result": {
        "0x9531c059098e3d194ff87febb587ab07b30b1306": "My blockchain account 1",
        "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD": "Neighbour Frank",
    },
    "message": ""
}
Response JSON Object:

  • result (object) – A dictionary of mappings. Address -> name.

  • message (str) – Error message if any errors occurred.

Status Codes:

Handling user notes

POST /api/(version)/notes

Doing a POST on this endpoint will return all the user notes present in the database.

Example Request:

http

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

{"from_timestamp": 12345677, "to_timestamp": 12345679, "title_substring": "#"}

curl

curl -i -X POST http://localhost:5042/api/1/notes -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_timestamp": 12345677, "title_substring": "#", "to_timestamp": 12345679}'

wget

wget -S -O- http://localhost:5042/api/1/notes --header="Content-Type: application/json;charset=UTF-8" --post-data='{"from_timestamp": 12345677, "title_substring": "#", "to_timestamp": 12345679}'

httpie

echo '{
  "from_timestamp": 12345677,
  "title_substring": "#",
  "to_timestamp": 12345679
}' | http POST http://localhost:5042/api/1/notes Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/notes', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_timestamp': 12345677, 'title_substring': '#', 'to_timestamp': 12345679})
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_attributes (list[string]) – This is the list of attributes of the note by which to order the results. By default we sort using last_update_timestamp.

  • ascending (list[bool]) – Should the order be ascending? 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.

  • title_substring (string) – The substring to use as filter for the title of the notes.

Example Response:

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

{
    "result": {
          "entries": [{
                  "identifier": 1,
                  "title": "#1",
                  "content": "Hello, World!",
                  "location": "manual balances",
                  "last_update_timestamp": 12345678,
                  "is_pinned": true
              },
              {
                  "identifier": 2,
                  "title": "#2",
                  "content": "Hi",
                  "location": "manual balances",
                  "last_update_timestamp": 12345699,
                  "is_pinned": false
          }],
          "entries_found": 2,
          "entries_total": 2,
          "entries_limit": -1
      },
    "message": ""
}
Response JSON Object:

  • result (object) – An array of objects representing user note entries.

  • identifier (int) – The unique identifier of the user note.

  • title (str) – The title of the note.

  • content (str) – The content of the note.

  • location (str) – The location inside the application the note was taken.

  • last_update_timestamp (int) – The timestamp the note was last updated.

  • is_pinned (bool) – Whether the note has been pinned by the user or not.

  • 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:
DELETE /api/(version)/notes

Doing a DELETE on this endpoint will delete a user note for the specified identifier.

Example Request:

http

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

{"identifier": 149095883}

curl

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

wget

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

httpie

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

python-requests

requests.delete('http://localhost:5042/api/1/notes', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'identifier': 149095883})
Request JSON Object:

  • identifier (int) – The identifier of the user note you’re trying to delete.

Example Response:

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

{"result": true, "message": ""}
Status Codes:
PATCH /api/(version)/notes

Doing a PATCH on this endpoint will update the content of an already existing user note.

Example Request:

http

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

  {
      "identifier": 2,
      "title": "#2",
      "content": "Go to bed",
      "location": "manual balances",
      "last_update_timestamp": 12345699,
      "is_pinned": false
  }

curl

curl -i -X PATCH http://localhost:5042/api/1/notes -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"content": "Go to bed", "identifier": 2, "is_pinned": false, "last_update_timestamp": 12345699, "location": "manual balances", "title": "#2"}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/notes --header="Content-Type: application/json;charset=UTF-8" --body-data='{"content": "Go to bed", "identifier": 2, "is_pinned": false, "last_update_timestamp": 12345699, "location": "manual balances", "title": "#2"}'

httpie

echo '{
  "content": "Go to bed",
  "identifier": 2,
  "is_pinned": false,
  "last_update_timestamp": 12345699,
  "location": "manual balances",
  "title": "#2"
}' | http PATCH http://localhost:5042/api/1/notes Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/notes', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'content': 'Go to bed', 'identifier': 2, 'is_pinned': False, 'last_update_timestamp': 12345699, 'location': 'manual balances', 'title': '#2'})
Request JSON Object:

  • identifier (int) – The unique identifier of the user note.

  • title (str) – The title of the note.

  • content (str) – The content of the note.

  • location (str) – The location inside the application the note was taken.

  • last_update_timestamp (int) – The timestamp the note was last updated.

Response JSON Object:

  • is_pinned (bool) – Whether the note has been pinned by the user or not.

Example Response:

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

{"result": true, "message": ""}
Status Codes:
PUT /api/(version)/notes

Doing a PUT on this endpoint will add a new user note to the DB.

Example Request:

http

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

{
      "title": "#5",
      "content": "Go to bed now",
      "location": "history events"
}

curl

curl -i -X PUT http://localhost:5042/api/1/notes -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"content": "Go to bed now", "location": "history events", "title": "#5"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/notes --header="Content-Type: application/json;charset=UTF-8" --body-data='{"content": "Go to bed now", "location": "history events", "title": "#5"}'

httpie

echo '{
  "content": "Go to bed now",
  "location": "history events",
  "title": "#5"
}' | http PUT http://localhost:5042/api/1/notes Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/notes', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'content': 'Go to bed now', 'location': 'history events', 'title': '#5'})
Request JSON Object:

  • title (str) – The title of the note to be created.

  • content (str) – The content of the note to be created.

  • location (str) – The location inside the application the note was taken.

Example Response:

HTTP/1.1 201 OK
Content-Type: application/zip

{"result": 1, "message": ""}
Response JSON Object:

  • result (int) – The unique identifier of the note created.

Status Codes:

Custom Assets

POST /api/(version)/assets/custom

Doing a POST on this endpoint will return all the custom assets present in the database using the filter parameters.

Example Request:

http

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

{"name": "land", "custom_asset_type": "real estate"}

curl

curl -i -X POST http://localhost:5042/api/1/assets/custom -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"custom_asset_type": "real estate", "name": "land"}'

wget

wget -S -O- http://localhost:5042/api/1/assets/custom --header="Content-Type: application/json;charset=UTF-8" --post-data='{"custom_asset_type": "real estate", "name": "land"}'

httpie

echo '{
  "custom_asset_type": "real estate",
  "name": "land"
}' | http POST http://localhost:5042/api/1/assets/custom Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/assets/custom', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'custom_asset_type': 'real estate', 'name': 'land'})
Request JSON Object:

  • limit (int[optional]) – This signifies the limit of records to return as per the sql spec.

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

  • name (string[optional]) – The name of the custom asset to be used as a filter.

  • identifier (string[optional]) – The identifier of the custom asset to be used as a filter.

  • custom_asset_type (string[optional]) – The type of the custom asset to be used as a filter.

  • order_by_attributes (list[string][optional]) – This is the list of attributes of the custom asset by which to order the results. By default we sort using name.

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

Example Response:

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

{
    "result": {
          "entries": [{
                  "identifier": "00fe5f97-882b-42e5-b0e0-39ebd3a99156'",
                  "name": "House",
                  "notes": "Apartment purchase",
                  "custom_asset_type": "real estate"
              },
              {
                  "identifier": "333c248f-7c64-41f4-833b-2fad96c4ea6b",
                  "name": "Ferrari",
                  "notes": "Exotic car inheritance from lineage",
                  "custom_asset_types": "vehicles"
          }],
          "entries_found": 2,
          "entries_total": 2,
      },
    "message": ""
}
Response JSON Object:

  • result (object) – An array of objects representing custom assets entries.

  • identifier (str) – The unique identifier of the custom asset.

  • name (str) – The name of the custom asset.

  • notes (str) – The notes used as a description of the custom asset. This field can be null.

  • custom_asset_type (str) – The type/category of the custom asset.

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

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

Status Codes:
DELETE /api/(version)/assets/custom

Doing a DELETE on this endpoint will delete a custom asset for the specified identifier.

Example Request:

http

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

{"identifier": "aca42c5d-36f1-4a8b-af28-5aeb322748b5"}

curl

curl -i -X DELETE http://localhost:5042/api/1/assets/custom -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"identifier": "aca42c5d-36f1-4a8b-af28-5aeb322748b5"}'

wget

wget -S -O- --method=DELETE http://localhost:5042/api/1/assets/custom --header="Content-Type: application/json;charset=UTF-8" --body-data='{"identifier": "aca42c5d-36f1-4a8b-af28-5aeb322748b5"}'

httpie

echo '{
  "identifier": "aca42c5d-36f1-4a8b-af28-5aeb322748b5"
}' | http DELETE http://localhost:5042/api/1/assets/custom Content-Type:"application/json;charset=UTF-8"

python-requests

requests.delete('http://localhost:5042/api/1/assets/custom', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'identifier': 'aca42c5d-36f1-4a8b-af28-5aeb322748b5'})
Request JSON Object:

  • identifier (str) – The identifier of the custom asset you’re trying to delete.

Example Response:

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

{"result": true, "message": ""}
Status Codes:
PATCH /api/(version)/assets/custom

Doing a PATCH on this endpoint will update the content of an already existing custom asset.

Example Request:

http

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

  {
      "identifier": "de0b49aa-65e1-4b4e-94b5-d1cd3e4baee1",
      "name": "Hotel",
      "notes": "Hotel from ma",
      "custom_asset_type": "real estate"
  }

curl

curl -i -X PATCH http://localhost:5042/api/1/assets/custom -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"custom_asset_type": "real estate", "identifier": "de0b49aa-65e1-4b4e-94b5-d1cd3e4baee1", "name": "Hotel", "notes": "Hotel from ma"}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/assets/custom --header="Content-Type: application/json;charset=UTF-8" --body-data='{"custom_asset_type": "real estate", "identifier": "de0b49aa-65e1-4b4e-94b5-d1cd3e4baee1", "name": "Hotel", "notes": "Hotel from ma"}'

httpie

echo '{
  "custom_asset_type": "real estate",
  "identifier": "de0b49aa-65e1-4b4e-94b5-d1cd3e4baee1",
  "name": "Hotel",
  "notes": "Hotel from ma"
}' | http PATCH http://localhost:5042/api/1/assets/custom Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/assets/custom', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'custom_asset_type': 'real estate', 'identifier': 'de0b49aa-65e1-4b4e-94b5-d1cd3e4baee1', 'name': 'Hotel', 'notes': 'Hotel from ma'})
Request JSON Object:

  • identifier (str) – The unique identifier of the custom asset to update.

  • name (str) – The name of the custom asset.

  • custom_asset_type (str) – The type/category of the custom asset.

  • notes (str[optional]) – The notes that serve as a description of the custom asset. This is optional.

Example Response:

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

{"result": true, "message": ""}
Status Codes:
PUT /api/(version)/assets/custom

Doing a PUT on this endpoint will add a new custom asset to the DB.

Example Request:

http

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

{
      "name": "Yacht",
      "custom_asset_type": "flex"
}

curl

curl -i -X PUT http://localhost:5042/api/1/assets/custom -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"custom_asset_type": "flex", "name": "Yacht"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/assets/custom --header="Content-Type: application/json;charset=UTF-8" --body-data='{"custom_asset_type": "flex", "name": "Yacht"}'

httpie

echo '{
  "custom_asset_type": "flex",
  "name": "Yacht"
}' | http PUT http://localhost:5042/api/1/assets/custom Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/assets/custom', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'custom_asset_type': 'flex', 'name': 'Yacht'})
Request JSON Object:

  • name (str) – The name of the custom asset to be created.

  • custom_asset_type (str) – The type/category of the custom asset.

  • notes (str[optional]) – The notes of the custom asset to be created. This is optional.

Example Response:

HTTP/1.1 201 OK
Content-Type: application/zip

{"result": "c0c991f0-6511-4b0d-83fc-40fde8495874", "message": ""}
Response JSON Object:

  • result (str) – The unique identifier of the custom asset created.

Status Codes:
GET /api/(version)/assets/custom/types

Doing a GET on this endpoint will return all the custom asset types in the DB sorted in ascending order.

Example Request:

http

GET /api/1/assets/custom/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/custom/types -H "Content-Type: application/json;charset=UTF-8"

wget

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

httpie

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

python-requests

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

Example Response:

HTTP/1.1 201 OK
Content-Type: application/zip

{"result": ["medals", "real estate", "stocks"], "message": ""}
Response JSON Object:

  • result (list[str]) – The list of custom asset types in the DB.

Status Codes:

Events Details

GET /api/(version)/history/events/details

Doing a GET on this endpoint will return the details of a history event.

Example Request:

http

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

{"identifier": 137}

curl

curl -i -X GET http://localhost:5042/api/1/history/events/details -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"identifier": 137}'

wget

wget -S -O- http://localhost:5042/api/1/history/events/details --header="Content-Type: application/json;charset=UTF-8" --body-data='{"identifier": 137}'

httpie

echo '{
  "identifier": 137
}' | http http://localhost:5042/api/1/history/events/details Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/history/events/details', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'identifier': 137})
Request JSON Object:

  • identifier (int) – The identifier of the event to be queried.

Example Response:

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

{
    "result": {
        "sub_swaps": [
            {"from_amount": "100.0", "to_amount": "0.084", "from_asset": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2", "to_asset": "ETH"},
            {"from_amount": "0.084", "to_amount": "98.2", "from_asset": "ETH", "to_asset": "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7"}
        ]
    },
    "message": ""
}
Response JSON Object:

  • result (object) – A dictionary with the details. It may contain one of the following amount of details.

  • sub_swaps (list) – A list with the details of each sub-swap. Each entry contains the following keys: from_amount, to_amount, from_asset, to_asset.

  • liquity_staking (dict) – Information about assets that were staked in liquity in this event.

Status Codes:

Add EVM Transaction By Hash

PUT /api/(version)/blockchains/evm/transactions/add-hash

Doing a PUT on this endpoint will add an EVM transaction to the database and associate it with the provided address. .. note:: This endpoint can also be queried asynchronously by using "async_query": true.

Example Request:

http

PUT /api/1/blockchains/evm/transactions/add-hash HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{
  "evm_chain": "ethereum",
  "tx_hash": "0x65d53653c584cde22e559cec4667a7278f75966360590b725d87055fb17552ba",
  "associated_address": "0xb8553D9ee35dd23BB96fbd679E651B929821969B",
  "async_query": true
}

curl

curl -i -X PUT http://localhost:5042/api/1/blockchains/evm/transactions/add-hash -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"associated_address": "0xb8553D9ee35dd23BB96fbd679E651B929821969B", "async_query": true, "evm_chain": "ethereum", "tx_hash": "0x65d53653c584cde22e559cec4667a7278f75966360590b725d87055fb17552ba"}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/blockchains/evm/transactions/add-hash --header="Content-Type: application/json;charset=UTF-8" --body-data='{"associated_address": "0xb8553D9ee35dd23BB96fbd679E651B929821969B", "async_query": true, "evm_chain": "ethereum", "tx_hash": "0x65d53653c584cde22e559cec4667a7278f75966360590b725d87055fb17552ba"}'

httpie

echo '{
  "associated_address": "0xb8553D9ee35dd23BB96fbd679E651B929821969B",
  "async_query": true,
  "evm_chain": "ethereum",
  "tx_hash": "0x65d53653c584cde22e559cec4667a7278f75966360590b725d87055fb17552ba"
}' | http PUT http://localhost:5042/api/1/blockchains/evm/transactions/add-hash Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/blockchains/evm/transactions/add-hash', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'associated_address': '0xb8553D9ee35dd23BB96fbd679E651B929821969B', 'async_query': True, 'evm_chain': 'ethereum', 'tx_hash': '0x65d53653c584cde22e559cec4667a7278f75966360590b725d87055fb17552ba'})
Request JSON Object:

  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not.

  • evm_chain (str) – The name of the evm chain for the transaction to the added e.g. "ethereum", "optimism" etc.

  • tx_hash (str) – The hash of the transaction to be added.

  • associated_address (str) – The address to be associated with the transaction. The address must be one that is already tracked by rotki.

Example Response:

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

{
    "result": true
    "message": ""
}
Response JSON Object:

  • result (bool) – It contains a boolean representing the status of the request.

Status Codes:

  • 200 OK – The transaction was saved successfully.

  • 400 Bad Request – Provided JSON is in some way malformed. Transaction is already present in DB. Address provided is not tracked by rotki.

  • 404 Not Found – Transaction hash not found for the specified chain.

  • 401 Unauthorized – No user is currently logged in.

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

Get Binance Savings Interests History

POST /api/(version)/exchange/(location)/savings

Doing a POST on this endpoint will return all history events relating to interest payments for the specified location. .. note:

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

Example Request:

http

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

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

curl

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

wget

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

httpie

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

python-requests

requests.post('http://localhost:5042/api/1/exchange/binance/savings', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_timestamp': 1451606400, 'only_cache': False, 'to_timestamp': 1571663098})
Request JSON Object:

  • async_query (bool) – Boolean denoting whether this is an asynchronous query or not.

  • limit (int) – Optional. 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_attributes (list[string]) – Optional. This is the list of attributes of the history by which to order the results. If none is given ‘timestamp’ is assumed. Valid values are: [‘timestamp’, ‘location’, ‘amount’].

  • ascending (list[bool]) – Optional. False by default. Defines the order by which results are returned depending on the chosen order by attribute.

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

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

  • location (string) – This represents the exchange’s name. Can only be one of “binance” or “binanceus”.

Example Response:

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

{
  "result": {
    "entries": [
      {
        "timestamp": 1587233562,
        "location": "binance",
        "asset": "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F",
        "amount": "0.00987654",
        "usd_value": "0.05432097"
      },
      {
        "timestamp": 1577233578,
        "location": "binance",
        "asset": "eip155:1/erc20:0x4Fabb145d64652a948d72533023f6E7A623C7C53",
        "amount": "0.00006408",
        "usd_value": "0.00070488"
      }
    ],
    "entries_found": 2,
    "entries_limit": 100,
    "entries_total": 2,
    "total_usd_value": "0.05502585",
    "assets": [
      "eip155:1/erc20:0x4Fabb145d64652a948d72533023f6E7A623C7C53",
      "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F"
    ],
    "received": [
      {
        "asset": "eip155:1/erc20:0x4Fabb145d64652a948d72533023f6E7A623C7C53",
        "amount": "0.00006408",
        "usd_value": "0.00070488"
      },
      {
        "asset": "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F",
        "amount": "0.00987654",
        "usd_value": "0.05432097"
      }
    ]
  },
  "message": ""
}
Response JSON Array of Objects:

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

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

  • amount (string) – The amount related to the event.

  • asset (string) – Asset involved in the event.

  • message (string) – It won’t be empty if the query to external services fails for some reason.

Response JSON Object:

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

  • total_usd_value (string) – Sum of the USD value for the assets received computed at the time of acquisition of each event.

  • assets (list[string]) – Assets involved in events ignoring all filters.

  • received (list[object]) – Assets received with the total amount received for each asset and the aggregated USD value at time of acquisition.

Status Codes:

Get all EVM Chains

GET /api/(version)/blockchains/evm/all

Doing a GET request on this endpoint will return a list of all EVM chain IDs and their names and labels.

Example Request

http

GET /api/(version)/blockchains/evm/all HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8

{}

Example Response

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

{
    "result": [
        {"id": 1, "name": "ethereum", "label": "Ethereum"},
        {"id": 10, "name": "optimism", "label": "Optimism"},
        {"id": 56, "name": "binance", "label": "Binance Smart Chain"},
        {"id": 100, "name": "gnosis", "label": "Gnosis"},
        {"id": 137, "name": "polygon_pos", "label": "Polygon POS"},
        {"id": 250, "name": "fantom", "label": "Fantom"},
        {"id": 42161, "name": "arbitrum_one", "label": "Arbitrum One"},
        {"id": 8453, "name": "base", "label": "Base"},
        {"id": 43114, "name": "avalanche", "label": "Avalanche"},
        {"id": 42220, "name": "celo", "label": "Celo"}
    ],
    "message": ""
}
Response JSON Array of Objects:

  • result – Returns a list of all EVM chains IDs, their names and labels. name is what is used to describe the chain when dealing from/to the API. label is the label to use in the frontend to display the chain.

Status Codes:

Get avatar for an ens name

GET /api/(version)/avatars/ens/<ens_name>

Doing a GET on this endpoint will return the avatar that is currently set for the provided ens name. If successful, responses include an ETag header for caching.

Example Request

http

GET /api/1/avatars/ens/rotki.eth HTTP/1.1
Host: localhost:5042
Content-Type: application/json;charset=UTF-8

{}

curl

curl -i -X GET http://localhost:5042/api/1/avatars/ens/rotki.eth -H "Content-Type: application/json;charset=UTF-8"

wget

wget -S -O- http://localhost:5042/api/1/avatars/ens/rotki.eth --header="Content-Type: application/json;charset=UTF-8"

httpie

http http://localhost:5042/api/1/avatars/ens/rotki.eth Content-Type:"application/json;charset=UTF-8"

python-requests

requests.get('http://localhost:5042/api/1/avatars/ens/rotki.eth', headers={'Content-Type': 'application/json;charset=UTF-8'})
Request JSON Object:

  • ens_name (string) – The ens name to check avatar for. It should have .eth postfix.

Example Response:

HTTP/1.1 200 OK
Content-Type: image/png
Status Codes:

  • 200 OK – The avatar was successfully found and returned.

  • 304 Not Modified – Avatar image 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 – Invalid ens name provided (it doesn’t end with .eth).

  • 404 Not Found – There is no avatar set for the given ens name.

  • 409 Conflict – Avatar was requested for an ens name that is not currently in the database or we couldn’t query the blockchain.

Clear Icons/Avatars Cache

POST /api/(version)/cache/<cache_type>/clear

Doing a POST on this endpoint will clear the cache of avatars/icons depending on the cache_type. Valid options of cache_type are icons & avatars.

Example Request

http

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

{
   "entries": ["ETH", "BTC"]
}

curl

curl -i -X POST http://localhost:5042/api/1/cache/icons/clear -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"entries": ["ETH", "BTC"]}'

wget

wget -S -O- http://localhost:5042/api/1/cache/icons/clear --header="Content-Type: application/json;charset=UTF-8" --post-data='{"entries": ["ETH", "BTC"]}'

httpie

echo '{
  "entries": [
    "ETH",
    "BTC"
  ]
}' | http POST http://localhost:5042/api/1/cache/icons/clear Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/cache/icons/clear', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'entries': ['ETH', 'BTC']})

http

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

{
   "entries": ["rotki.eth", "nebolax.eth"]
}

curl

curl -i -X POST http://localhost:5042/api/1/cache/avatars/clear -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"entries": ["rotki.eth", "nebolax.eth"]}'

wget

wget -S -O- http://localhost:5042/api/1/cache/avatars/clear --header="Content-Type: application/json;charset=UTF-8" --post-data='{"entries": ["rotki.eth", "nebolax.eth"]}'

httpie

echo '{
  "entries": [
    "rotki.eth",
    "nebolax.eth"
  ]
}' | http POST http://localhost:5042/api/1/cache/avatars/clear Content-Type:"application/json;charset=UTF-8"

python-requests

requests.post('http://localhost:5042/api/1/cache/avatars/clear', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'entries': ['rotki.eth', 'nebolax.eth']})
Request JSON Array of Objects:

  • entries (optional[string]) – An array of the icons/avatars to be cleared from the cache. All icons/avatars are deleted in the cache if null.

Example Response:

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

Event Mappings

GET /api/(version)/history/events/type_mappings

Doing a GET on this endpoint will return a mapping of history events types and subtypes to a EventCategory representation. We also return properties such icon, label and color for event types.

Example Request

http

GET /history/events/type_mappings HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/history/events/type_mappings

wget

wget -S -O- http://localhost:5042/history/events/type_mappings

httpie

http http://localhost:5042/history/events/type_mappings

python-requests

requests.get('http://localhost:5042/history/events/type_mappings')

Example Response

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

{
  "result":{
    "global_mappings":{
      "spend":{
        "fee":"gas",
        "return wrapped":"send",
        "donate":"donate",
        "none":"send"
      }
    },
    "entry_type_mappings":{
      "eth withdrawal event":{
        "staking":{
          "remove asset":{
              "is_exit":"stake exit",
              "not_exit":"withdraw"
          }
        }
      }
    },
    "per_protocol_mappings":{
      "ethereum":{
        "aave":{
          "spend":{
            "payback debt":"repay",
            "liquidate":"liquidate"
          }
        }
      },
      "optimism":{
        "aave":{
          "spend":{
            "payback debt":"repay",
            "liquidate":"liquidate"
          }
        }
      },
      "polygon pos":{
        "aave":{
          "spend":{
            "payback debt":"repay",
            "liquidate":"liquidate"
          }
        }
      },
    },
    "event_category_details":{
      "send":{
        "direction": "out",
        "counterparty_mappings": {
          "default": {
            "label":"send",
            "icon":"mdi-arrow-up",
      }}},
      "receive":{
        "direction": "in",
        "counterparty_mappings": {
          "default": {
            "label":"receive",
            "icon":"mdi-arrow-down",
            "color":"green"
      }}},
      "fee":{
        "direction": "out",
        "counterparty_mappings": {
          "default": {
            "label":"fee",
            "icon":"mdi-account-cash",
      }, "gas": {
            "label":"gas fee",
            "icon":"mdi-fire",
      }}},
      "gas":{
        "label":"gas_fee",
        "icon":"mdi-fire",
      },
      "receive":{
        "label":"receive",
        "icon":"mdi-arrow-down",
        "color":"green"
      }
    }
  }
}
Response JSON Object:

  • global_mappings (object) – keys of this object are the history event types names and values are mappings of subtypes’ names to the EventCategory name. Contains mappings that should be applied if there is no a specific protocol rule.

  • type_mappings (object) – the keys of this mapping are entry types and it contains the combinations of event type and subtype that would overwritte the information in global_mappings only for that entry type.

  • per_protocol_mappings (object) – same as global_mappings but contains specific mappings per chain and protocol.

  • event_category_details (object) – This is a mapping of EventCategory to its direction and mapping of counterparty to details. For all the EventCategoryDetails mapping there is a "default" key mapping to the default details. For some exceptions there is also other keys which are counterparties. Such as for spend/fee and counterparty gas.

  • label (string) – Label to show in the frontend for the event type.

  • icon (string) – Icon to be used by the frontend for this event type.

  • color[optional] (string) – Optional color to apply to the icon

Resjon object accounting_events_icons:

Mapping of accounting event type to its corresponding icon name.

Status Codes:

Getting all available counterparties

GET /api/(version)/history/events/counterparties

Doing a GET on this endpoint will return information for all the counterparties used for decoding events in the backend.

Example Request

http

GET /history/events/counterparties HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/history/events/counterparties

wget

wget -S -O- http://localhost:5042/history/events/counterparties

httpie

http http://localhost:5042/history/events/counterparties

python-requests

requests.get('http://localhost:5042/history/events/counterparties')

Example Response

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

{
  "result":[
      {
        "identifier":"1inch-v1",
        "label":"1inch",
        "image":"/assets/images/defi/1inch.svg"
      },
      {
        "identifier":"1inch-v2",
        "label":"1inch",
        "image":"/assets/images/defi/1inch.svg"
      }
  ]
}
Response JSON Object:

  • identifier (string) – value used by the backend to represent the counterparty.

  • label (string) – Name displayed in the frontend.

  • image (string) – Relative path to the counterparty image.

Status Codes:

Getting EVM products

GET /api/(version)/history/events/products

Doing a GET on this endpoint will return information for all the counterparties and the products that they use. Also it will return a list of all the available product values.

Example Request

http

GET /history/events/products HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/history/events/products

wget

wget -S -O- http://localhost:5042/history/events/products

httpie

http http://localhost:5042/history/events/products

python-requests

requests.get('http://localhost:5042/history/events/products')

Example Response

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

{
  "result":{
    "mappings":{
      "convex":[
        "gauge",
        "staking"
      ],
      "curve":[
        "gauge"
      ]
    },
    "products":[
      "pool",
      "staking",
      "gauge"
    ]
  },
  "message":""
}
Response JSON Object:

  • mappings (object) – A mapping of each counterparty to a list with the products that they use

  • products (object) – A list of all the available products

Status Codes:

Get all valid locations

GET /api/(version)/locations/all

Doing a GET on this endpoint will return all the possible location values.

Example Request

http

GET /locations/all HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/locations/all

wget

wget -S -O- http://localhost:5042/locations/all

httpie

http http://localhost:5042/locations/all

python-requests

requests.get('http://localhost:5042/locations/all')

Example Response

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

{
  "result":{
    "locations": {
      "ethereum": {"image": "ethereum.svg"},
      "optimism": {"image": "optimism.svg"},
      "ftx": {"image": "ftx.svg", "is_exchange": true},
      "kraken": {
        "image": "kraken.svg",
        "exchange_detail": {
          "is_exchange_with_key": true
        }
      },
      "kucoin": {
        "image": "kucoin.svg",
        "exchange_detail": {
          "is_exchange_with_key": true,
          "is_exchange_with_passphrase": true
        }
      },
      "bitpanda": {
        "image": "bitpanda.svg",
        "exchange_detail": {
          "is_exchange_with_key": true,
          "is_exchange_without_api_secret": true
        }
      },
      "external": {"icon": "mdi-book"}
  }
}
Response JSON Object:

  • locations (list[string]) – A mapping of locations to their details. Can contain image or icon depending on whether a known image should be used or an icon from the icon set. Additionally, it can contain a display_name if a special name needs to be used. If the location is an exchange, it may also include an is_exchange key, or an exchange_details object if the location has more details for the exchange data. The exchange_details object can contain is_exchange_with_key for exchanges requiring an API key, is_exchange_with_passphrase for exchanges needing an API key and passphrase, and is_exchange_without_api_secret for exchanges that do not require an API secret key, all within the exchange_detail object.

Status Codes:

Refresh general cache

POST /api/(version)/cache/general/refresh

Doing a POST on this endpoint will refresh the entire cache (curve, makerdao, yearn, velodrome).

Note

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

Example Request

http

POST /cache/general/refresh HTTP/1.1
Host: localhost:5042

curl

curl -i -X POST http://localhost:5042/cache/general/refresh

wget

wget -S -O- http://localhost:5042/cache/general/refresh

httpie

http POST http://localhost:5042/cache/general/refresh

python-requests

requests.post('http://localhost:5042/cache/general/refresh')

Example Response

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

{
  "result": true,
  "message": ""
}
Response JSON Object:

  • result (bool) – Is true if all the caches were refreshed successfully.

Status Codes:

Getting Metadata For Airdrops

GET /api/(version)/airdrops/metadata

Doing a GET on this endpoint will return metadata for all the airdrops that are supported by rotki.

Example Request

http

GET /airdrops/metadata HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/airdrops/metadata

wget

wget -S -O- http://localhost:5042/airdrops/metadata

httpie

http http://localhost:5042/airdrops/metadata

python-requests

requests.get('http://localhost:5042/airdrops/metadata')

Example Response

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

{
   "result":[
      {
         "identifier": "uniswap",
         "name": "Uniswap",
         "icon": "uniswap.svg",
         "icon_url": "https://raw.githubusercontent.com/rotki/data/main/airdrops/icons/uniswap.svg"
      },
      {
         "identifier": "1inch",
         "name": "1inch",
         "icon": "1inch.svg"
      }
   ],
   "message": "",
}
Response JSON Object:

  • identifier (string) – The identifier of the airdrop.

  • name (string) – The name of the airdrop.

  • icon (string) – The icon of the airdrop.

Status Codes:

Getting Metadata For Defi Protocols

GET /api/(version)/defi/metadata

Doing a GET on this endpoint will return metadata for all the defi protocols that are supported by rotki.

Example Request

http

GET /defi/metadata HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/defi/metadata

wget

wget -S -O- http://localhost:5042/defi/metadata

httpie

http http://localhost:5042/defi/metadata

python-requests

requests.get('http://localhost:5042/defi/metadata')

Example Response

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

{
   "result":[
      {
         "identifier": "uniswapv1",
         "name": "Uniswap V1",
         "icon": "uniswap.svg"
      },
      {
         "identifier": "oneinch_liquidity",
         "name": "1inch Liquidity Protocol",
         "icon": "1inch.svg"
      }
   ],
   "message": ""
}
Response JSON Object:

  • identifier (string) – The identifier of the defi protocol.

  • name (string) – The name of the defi protocol.

  • icon (string) – The icon of the defi protocol.

Status Codes:

Dealing with skipped external events

GET /api/(version)/history/skipped_external_events

Doing a GET on this endpoint will return a summary of skipped external events in the DB.

Example Request

http

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

curl

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

wget

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

httpie

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

python-requests

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

Example Response

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

{
  "result": {
      "locations": {
          "kraken": 5,
          "binance": 3
      },
      "total": 8
  },
  "message": ""
}
Response JSON Object:

  • result (bool) – The mapping of skipped event locations to the number of skipped events per location.

Status Codes:
PUT /api/(version)/history/skipped_external_events
PATCH /api/(version)/history/skipped_external_events

Doing a PUT on this endpoint with a filepath path as argument will export all skipped external events in a csv to that directory. Doing a PATCH on this endpoint will download all skipped external events in a csv file.

Example Request:

http

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

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

curl

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

wget

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

python-requests

requests.put('http://localhost:5042/api/1/history/skipped_external_events', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'directory_path': '/home/username/path/to/csvdir'})

Example Response:

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

{
    "result": true,
    "message": ""
}
Response JSON Object:

  • result (bool) – Boolean denoting success or failure.

Status Codes:
POST /api/(version)/history/skipped_external_events

Doing a POST on this endpoint will try to reprocess all skipped external events saved in the DB.

Example Request

http

POST /api/1/history/skipped_external_events HTTP/1.1
Host: localhost:5042

curl

curl -i -X POST http://localhost:5042/api/1/history/skipped_external_events

wget

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

httpie

http POST http://localhost:5042/api/1/history/skipped_external_events

python-requests

requests.post('http://localhost:5042/api/1/history/skipped_external_events')

Example Response

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

{
  "result": {"total": 10, "successful": 5},
  "message": ""
}
Response JSON Object:

  • total (int) – The total number of skipped events that we tried to reprocess

  • succesfull (int) – The number of skipped events that we reprocessed successfully and were thus deleted from the skipped events table.

Status Codes:

Managing custom accounting rules

POST /api/(version)/accounting/rules

Doing a POST on this endpoint will allow querying the accounting rules by a list of possible values. This endpoint allows pagination.

Example Request

http

POST /api/1/accounting/rules HTTP/1.1
Host: localhost:5042

{
   "event_types":["deposit", "withdrawal"],
   "counterparties":["uniswap", "compound"]
}

curl

curl -i -X POST http://localhost:5042/api/1/accounting/rules --data-raw '{

   "event_types":["deposit", "withdrawal"],

   "counterparties":["uniswap", "compound"]

}'

wget

wget -S -O- http://localhost:5042/api/1/accounting/rules --post-data='{

   "event_types":["deposit", "withdrawal"],

   "counterparties":["uniswap", "compound"]

}'

httpie

echo '{

   "event_types":["deposit", "withdrawal"],

   "counterparties":["uniswap", "compound"]

}' | http POST http://localhost:5042/api/1/accounting/rules

python-requests

requests.post('http://localhost:5042/api/1/accounting/rules', data='{\r\n\n   "event_types":["deposit", "withdrawal"],\r\n\n   "counterparties":["uniswap", "compound"]\r\n\n}')
Request JSON Array of Objects:

  • event_types (optional[array[string]]) – List of possible event types to use while filtering.

  • event_subtypes (optional[array[string]]) – List of possible event subtypes to use while filtering.

  • counterparties (optional[array[string]]) – List of possible counterparties to use while filtering. Instead of a string a null value can also be given to mean counterparty being None.

Example Response

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

{
"result":{
   "entries":[{
      "taxable":false,
      "count_cost_basis_pnl": {"value": true},
      "count_entire_amount_spend":{"value": false},
      "accounting_treatment":null,
      "identifier":2,
      "event_type":"staking",
      "event_subtype":"spend",
      "counterparty":"compound"
   }],
   "entries_found":1,
   "entries_total":1,
   "entries_limit":-1
},
"message":""
}
Response JSON Object:

  • entries (array) – List of all the rules with their identifier. For the meaning of each field refer to Request JSON Array of Objects

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

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

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

Status Codes:
PUT /api/(version)/accounting/rules

Doing a PUT request on this endpoint will allow to create a new accounting rule.

Example Request

http

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

{
   "taxable": {"value": true},
   "count_entire_amount_spend":{"value": false, "linked_setting": "include_crypto2crypto"},
   "count_cost_basis_pnl":{"value": true},
   "event_type":"staking",
   "event_subtype":"spend",
   "counterparty": "compound",
   "accounting_treatment":"swap"
}

curl

curl -i -X PUT http://localhost:5042/api/1/accounting/rules -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"accounting_treatment": "swap", "count_cost_basis_pnl": {"value": true}, "count_entire_amount_spend": {"linked_setting": "include_crypto2crypto", "value": false}, "counterparty": "compound", "event_subtype": "spend", "event_type": "staking", "taxable": {"value": true}}'

wget

wget -S -O- --method=PUT http://localhost:5042/api/1/accounting/rules --header="Content-Type: application/json;charset=UTF-8" --body-data='{"accounting_treatment": "swap", "count_cost_basis_pnl": {"value": true}, "count_entire_amount_spend": {"linked_setting": "include_crypto2crypto", "value": false}, "counterparty": "compound", "event_subtype": "spend", "event_type": "staking", "taxable": {"value": true}}'

httpie

echo '{
  "accounting_treatment": "swap",
  "count_cost_basis_pnl": {
    "value": true
  },
  "count_entire_amount_spend": {
    "linked_setting": "include_crypto2crypto",
    "value": false
  },
  "counterparty": "compound",
  "event_subtype": "spend",
  "event_type": "staking",
  "taxable": {
    "value": true
  }
}' | http PUT http://localhost:5042/api/1/accounting/rules Content-Type:"application/json;charset=UTF-8"

python-requests

requests.put('http://localhost:5042/api/1/accounting/rules', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'accounting_treatment': 'swap', 'count_cost_basis_pnl': {'value': True}, 'count_entire_amount_spend': {'linked_setting': 'include_crypto2crypto', 'value': False}, 'counterparty': 'compound', 'event_subtype': 'spend', 'event_type': 'staking', 'taxable': {'value': True}})
Request JSON Array of Objects:

  • taxable (object) – If value is set to true if the event should be considered as taxable. Allows to link the property to an accounting setting.

  • count_entire_amount_spend (object) – If value is set to true then the entire amount is counted as a spend. Which means an expense (negative pnl). Allows to link the property to an accounting setting.

  • count_cost_basis_pnl (object) – If value is set to true then we also count any profit/loss the asset may have had compared to when it was acquired. Allows to link the property to an accounting setting.

  • linked_setting (string) – If it takes any value this property will take the value of the provided setting. Can be either include_gas_costs or include_crypto2crypto.

  • event_type (string) – The event type that the rule targets.

  • event_subtype (string) – The event subtype that the rule targets.

  • counterparty (optional[string]) – The counterparty that the rule targets.

  • accounting_treatment – Special rule to handle pairs of events. Can be swap or swap with fee

Example Response:

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

{
   "result": true,
   "message": ""
}
Response JSON Object:

  • result (bool) – Boolean denoting success or failure.

Status Codes:
PATCH /api/(version)/accounting/rules

Doing a PATCH on this endpoint allows to edit an accounting rule. Takes the same parameters as the PUT verb plus the identifier of the entry being updated.

Example Request:

http

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

  {
     "identifier": 1,
     "taxable": true,
     "count_entire_amount_spend": {"value": false},
     "count_cost_basis_pnl":{"value": true},
     "event_type": "staking",
     "event_subtype": "spend",
     "counterparty": "uniswap",
     "accounting_treatment": "swap"
  }

curl

curl -i -X PATCH http://localhost:5042/api/1/accounting/rules -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"accounting_treatment": "swap", "count_cost_basis_pnl": {"value": true}, "count_entire_amount_spend": {"value": false}, "counterparty": "uniswap", "event_subtype": "spend", "event_type": "staking", "identifier": 1, "taxable": true}'

wget

wget -S -O- --method=PATCH http://localhost:5042/api/1/accounting/rules --header="Content-Type: application/json;charset=UTF-8" --body-data='{"accounting_treatment": "swap", "count_cost_basis_pnl": {"value": true}, "count_entire_amount_spend": {"value": false}, "counterparty": "uniswap", "event_subtype": "spend", "event_type": "staking", "identifier": 1, "taxable": true}'

httpie

echo '{
  "accounting_treatment": "swap",
  "count_cost_basis_pnl": {
    "value": true
  },
  "count_entire_amount_spend": {
    "value": false
  },
  "counterparty": "uniswap",
  "event_subtype": "spend",
  "event_type": "staking",
  "identifier": 1,
  "taxable": true
}' | http PATCH http://localhost:5042/api/1/accounting/rules Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/accounting/rules', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'accounting_treatment': 'swap', 'count_cost_basis_pnl': {'value': True}, 'count_entire_amount_spend': {'value': False}, 'counterparty': 'uniswap', 'event_subtype': 'spend', 'event_type': 'staking', 'identifier': 1, 'taxable': True})

Request JSON Array of Objects

Request JSON Array of Objects:

  • identifier (integer) – The id of the rule being updated.

Example Response:

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

{
  "result": true,
  "message": ""
}
Response JSON Object:

  • result (bool) – Boolean denoting success or failure.

Status Codes:
DELETE /api/(version)/accounting/rules

Doing a DELETE on this endpoint allows deleting a rule by their identifier.

Example Request:

http

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

{
  "identifier": 2
}

curl

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

wget

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

httpie

echo '{
  "identifier": 2
}' | http PATCH http://localhost:5042/api/1/accounting/rules Content-Type:"application/json;charset=UTF-8"

python-requests

requests.patch('http://localhost:5042/api/1/accounting/rules', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'identifier': 2})
Request JSON Array of Objects:

  • identifier (integer) – The identifier of the rule that will be deleted

Example Response:

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

{
  "result": true,
  "message": ""
}
Response JSON Object:

  • result (bool) – Boolean denoting success or failure.

Status Codes:

Accounting rules linkable properties

GET /api/(version)/accounting/rules/info

Doing a GET on this endpoint will return a mapping of the properties that can be linked for accounting rules.

Example Request

http

GET /api/1/accounting/rules/info HTTP/1.1
Host: localhost:5042

curl

curl -i -X GET http://localhost:5042/api/1/accounting/rules/info

wget

wget -S -O- http://localhost:5042/api/1/accounting/rules/info

httpie

http http://localhost:5042/api/1/accounting/rules/info

python-requests

requests.get('http://localhost:5042/api/1/accounting/rules/info')

Example Response

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

{
  "result": {
      "count_entire_amount_spend":["include_gas_costs", "include_crypto2crypto"],
      "count_cost_basis_pnl":["include_gas_costs", "include_crypto2crypto"]
   },
  "message": ""
}
Response JSON Object:

  • result (object) – A mapping of the properties that can be linked to the list of settings configurations that can be used for that field.

Status Codes:

Solving conflicts in accounting rules

POST /api/(version)/accounting/rules/conflicts

Doing a POST on this endpoint will return the list of conflicts for accounting rules providing the local version and remote version to compare them. It allows pagination by limit and offset.

Example Request

http

POST /api/1/accounting/rules/conflicts HTTP/1.1
Host: localhost:5042

curl

curl -i -X POST http://localhost:5042/api/1/accounting/rules/conflicts

wget

wget -S -O- http://localhost:5042/api/1/accounting/rules/conflicts

httpie

http POST http://localhost:5042/api/1/accounting/rules/conflicts

python-requests

requests.post('http://localhost:5042/api/1/accounting/rules/conflicts')

Example Response

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

{
"result":{
   "entries":[
      {
         "local_id": 1,
         "local_data":{
            "taxable":{
               "value":true,
               "linked_setting":"include_crypto2crypto"
            },
            "count_cost_basis_pnl":{
               "value":true
            },
            "count_entire_amount_spend":{
               "value":false,
               "linked_setting":"include_crypto2crypto"
            },
            "accounting_treatment":"None",
            "event_type":"spend",
            "event_subtype":"return wrapped",
            "counterparty":"compound"
         },
         "remote_data":{
            "taxable":{
               "value":false
            },
            "count_cost_basis_pnl":{
               "value":false
            },
            "count_entire_amount_spend":{
               "value":false
            },
            "accounting_treatment":"swap",
            "event_type":"spend",
            "event_subtype":"return wrapped",
            "counterparty":"compound"
         }
      }
   ],
   "entries_found":1,
   "entries_total":1,
   "entries_limit":-1
},
"message":""
}
Response JSON Object:

  • result (object) – An object, mapping identifiers to the local and remote version of the conflict.

Status Codes:
PATCH /api/(version)/accounting/rules/conflicts

Doing a PATCH on this endpoint will apply a conflict resolution method for the selected accounting rules.

Example Request

Note

Either conflicts or solve_all_using need to be provided but not both together.

http

PATH /api/1/accounting/rules/conflicts HTTP/1.1
Host: localhost:5042

{"conflicts": [{"local_id": "1", "solve_using": "remote"}]}

curl

curl -i -X PATH http://localhost:5042/api/1/accounting/rules/conflicts --data-raw '{"conflicts": [{"local_id": "1", "solve_using": "remote"}]}'

wget

wget -S -O- --method=PATH http://localhost:5042/api/1/accounting/rules/conflicts --body-data='{"conflicts": [{"local_id": "1", "solve_using": "remote"}]}'

httpie

echo '{"conflicts": [{"local_id": "1", "solve_using": "remote"}]}' | http PATH http://localhost:5042/api/1/accounting/rules/conflicts

python-requests

requests.path('http://localhost:5042/api/1/accounting/rules/conflicts', data='{"conflicts": [{"local_id": "1", "solve_using": "remote"}]}')
Request JSON Array of Objects:

  • local_id (string) – The identifier of the rule that will be updated.

  • solve_using (string) – Either remote or local.

  • solve_all_using (string) – Either remote or local. If this is given it should be the only key in the request.

Example Response:

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

{
  "result": true,
  "message": ""
}
Response JSON Object:

  • result (bool) – Boolean denoting success or failure.

Status Codes: