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
200 OK – Users query is successful
500 Internal Server Error – Internal rotki error
- PUT /api/(version)/users
By doing a
PUT
at this endpoint you can create a new userNote
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"], "taxable_ledger_actions": ["income", "airdrop"], "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 – User already exists. Another user is already logged in. Given Premium API credentials are invalid. Permission error while trying to access the directory where rotki saves data.
500 Internal Server Error – Internal rotki error
- POST /api/(version)/users/(username)
By doing a
POST
at this endpoint, you can login to the user withusername
.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 istrue
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"], "taxable_ledger_actions": ["income", "airdrop"], "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
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 totrue
, so that the user will login using the latest backup of the encrypted database. In this case the response will contain an emptyresult
key and an explanatorymessage
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 theresult
key and the message under themessage
key. The payload has the following keys:local_size
,remote_size
,local_last_modified
,remote_last_modified
.
400 Bad Request – Provided JSON is in some way malformed
401 Unauthorized – Provided password is wrong for the user or some other authentication error.
409 Conflict – Another user is already logged in. User does not exist. There was a fatal error during the upgrade of the DB. Permission error while trying to access the directory where rotki saves data.
500 Internal Server Error – 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 isusername
. 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
200 OK – Logged out successfully
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – No user is logged in, or current logged in user is different to the one requested for logout.
500 Internal Server Error – Internal rotki error
- 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
200 OK – API key/secret set successfully
400 Bad Request – Provided JSON is in some way malformed. For example invalid API key format
401 Unauthorized – Provided API key/secret does not authenticate.
409 Conflict – User is not logged in, or user does not exist
500 Internal Server Error – Internal rotki error
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
200 OK – API key/secret deleted successfully
400 Bad Request – Provided call is in some way malformed.
409 Conflict – User is not logged in, or user does not exist, or db operation error
500 Internal Server Error – Internal rotki error
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
200 OK – API key/secret deleted successfully
400 Bad Request – Provided call is in some way malformed.
401 Unauthorized – The user does not have premium access.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – The external premium service could not be reached or returned unexpected response.
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
200 OK – Password changed successfully
401 Unauthorized – Password mismatch
400 Bad Request – Provided call is in some way malformed. For example a user who is not logged in has been specified.
409 Conflict – User is not logged in, or user does not exist, or db operation error
500 Internal Server Error – Internal rotki error
Getting or modifying external services API credentials
- GET /api/(version)/external_services
By doing a GET on the external services endpoint you can get all the credentials that the user has set for external services such as etherscan, cryptocompare e.t.c.
Entries are returned only for the services that have had an api key setup.
Example Request:
http
GET /api/1/external_services HTTP/1.1 Host: localhost:5042 Content-Type: application/json
curl
curl -i -X GET http://localhost:5042/api/1/external_services -H "Content-Type: application/json"
wget
wget -S -O- http://localhost:5042/api/1/external_services --header="Content-Type: application/json"
httpie
http http://localhost:5042/api/1/external_services Content-Type:application/json
python-requests
requests.get('http://localhost:5042/api/1/external_services', headers={'Content-Type': 'application/json'})
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "etherscan": {"api_key": "foooooookey"}, "cryptocompare": {"api_key": "boooookey"}, "opensea": {"api_key": "goooookey"} }, "message": "" }
- Response JSON Object
result (object) – The result object contains as many entries as the external services. Each entry’s key is the name and the value is another object of the form
{"api_key": "foo"}
- Status Codes
200 OK – Querying of external service credentials was successful
409 Conflict – There is no logged in user
500 Internal Server Error – Internal rotki error
- PUT /api/(version)/external_services
By doing a PUT on the external services endpoint you can save credentials for external services such as etherscan, cryptocompare e.t.c. If a credential already exists for a service it is overwritten.
Returns external service entries after the additions.
Example Request:
http
PUT /api/1/external_services HTTP/1.1 Host: localhost:5042 Content-Type: application/json { "services": [{"name": "etherscan", "api_key": "goookey"}] }
curl
curl -i -X PUT http://localhost:5042/api/1/external_services -H "Content-Type: application/json" --data-raw '{"services": [{"name": "etherscan", "api_key": "goookey"}]}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/external_services --header="Content-Type: application/json" --body-data='{"services": [{"name": "etherscan", "api_key": "goookey"}]}'
httpie
echo '{ "services": [ { "api_key": "goookey", "name": "etherscan" } ] }' | http PUT http://localhost:5042/api/1/external_services Content-Type:application/json
python-requests
requests.put('http://localhost:5042/api/1/external_services', headers={'Content-Type': 'application/json'}, json={'services': [{'name': 'etherscan', 'api_key': 'goookey'}]})
- Request JSON Object
services (list) – The services parameter is a list of services along with their api keys.
- Request JSON Array of Objects
name (string) – Each entry in the list should have a name for the service. Valid ones are
"etherscan"
,"cryptocompare"
,"beaconchain"
,"loopring"
,"covalent"
and"opensea"
.api_key (string) – Each entry in the list should have an api_key entry
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "etherscan": {"api_key": "goookey"}, "cryptocompare": {"api_key": "boooookey"} }, "message": "" }
- Response JSON Object
result (object) – The result object contains as many entries as the external services. Each entry’s key is the name and the value is another object of the form
{"api_key": "foo"}
- Status Codes
200 OK – Saving new external service credentials was successful
400 Bad Request – Provided JSON is in some way malformed, of invalid value provided.
409 Conflict – There is no logged in user
500 Internal Server Error – Internal rotki error
- 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
200 OK – Deleting external service credentials was successful
400 Bad Request – Provided JSON is in some way malformed, of invalid value provided.
409 Conflict – There is no logged in user
500 Internal Server Error – Internal rotki error
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"], "taxable_ledger_actions": ["income", "airdrop"], "ssf_graph_multiplier": 2, "non_sync_exchanges": [{"location": "binance", "name": "binance1"}], "cost_basis_method": "fifo", "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 tonull
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.
taxable_ledger_actions (list) – A list of strings denoting the ledger action types that will be taken into account in the profit/loss calculation during accounting. All others will only be taken into account in the cost basis and will not be taxed.
ssf_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.
- Status Codes
200 OK – Querying of settings was successful
409 Conflict – There is no logged in user
500 Internal Server Error – Internal rotki error
- 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 tonull
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.
main_currency (string[optional]) – The FIAT currency to use for all profit/loss calculation. USD by default.
date_display_format (string[optional]) – The format in which to display dates in the UI. Default is
"%d/%m/%Y %H:%M:%S %Z"
.submit_usage_analytics (bool[optional]) – A boolean denoting wether or not to submit anonymous usage analytics to the rotki server.
active_module (list) – A list of strings denoting the active modules with which rotki should run.
current_price_oracles (list) – A list of strings denoting the price oracles rotki should query in specific order for requesting current prices.
historical_price_oracles (list) – A list of strings denoting the price oracles rotki should query in specific order for requesting historical prices.
taxable_ledger_actions (list) – A list of strings denoting the ledger action types that will be taken into account in the profit/loss calculation during accounting. All others will only be taken into account in the cost basis and will not be taxed.
- Response JSON Object
ssf_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.
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"], "taxable_ledger_actions": ["income", "airdrop"], "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
200 OK – Modifying settings was successful
400 Bad Request – Provided JSON is in some way malformed, of invalid value for a setting.
409 Conflict – No user is logged in or tried to set eth rpc endpoint that could not be reached.
500 Internal Server Error – Internal rotki error
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
200 OK – Querying of the backend configuration was successful
500 Internal Server Error – Internal rotki error
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
200 OK – Querying was successful
409 Conflict – No user is logged.
500 Internal Server Error – Internal rotki error
- 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
200 OK – Insertion was successful.
409 Conflict – No user is logged or entrie couldn’t be created.
500 Internal Server Error – Internal rotki error
- 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
200 OK – Update was successful.
409 Conflict – No user is logged or entrie couldn’t be updated.
500 Internal Server Error – Internal rotki error
- 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
200 OK – Deletion was successful.
409 Conflict – No user is logged or failed to delete because the node name is not in the database.
500 Internal Server Error – Internal rotki error
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
200 OK – Querying was successful
500 Internal Server Error – Internal rotki error
- 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
200 OK – The task’s outcome is successfully returned or pending
400 Bad Request – Provided JSON is in some way malformed
404 Not Found – There is no task with the given task id
409 Conflict – No user is currently logged in
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Problem contacting a remote service
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
200 OK – Successful query
400 Bad Request – Provided JSON is in some way malformed.
409 Conflict – Nft module is 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.
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
200 OK – Successful query
409 Conflict – No user is logged in.
500 Internal Server Error – Internal rotki error
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
200 OK – Price successfully added
400 Bad Request – Provided JSON is in some way malformed.
409 Conflict – Nft module is 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.
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
200 OK – The exchange rates have been successfully returned
400 Bad Request – Provided JSON is in some way malformed. Empty currencies list given
500 Internal Server Error – Internal rotki error
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
200 OK – Operation sent to database.
400 Bad Request – Provided JSON is in some way malformed.
500 Internal Server Error – Internal rotki error
- 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
200 OK – Operation sent to database.
400 Bad Request – Provided JSON is in some way malformed.
500 Internal Server Error – Internal rotki error
- 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
200 OK – Operation executed.
400 Bad Request – Provided information is in some way malformed.
500 Internal Server Error – Internal rotki error
- 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
200 OK – true if any entry was deleted, false otherwise.
400 Bad Request – Provided information is in some way malformed.
500 Internal Server Error – Internal rotki error
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
200 OK – The exchanges list has been successfully setup
409 Conflict – No user is logged in.
500 Internal Server Error – Internal rotki error
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
200 OK – The exchange has been successfully setup
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – No user is logged in. The exchange has already been registered. The API key/secret is invalid or some other error.
500 Internal Server Error – Internal rotki error
- DELETE /api/(version)/exchanges
Doing a DELETE on this endpoint for a particular exchange name will delete the exchange from the database for the current user.
Example Request:
http
DELETE /api/1/exchanges HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"name": "my kraken key", "location": "kraken"}
curl
curl -i -X DELETE http://localhost:5042/api/1/exchanges -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"location": "kraken", "name": "my kraken key"}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/exchanges --header="Content-Type: application/json;charset=UTF-8" --body-data='{"location": "kraken", "name": "my kraken key"}'
httpie
echo '{ "location": "kraken", "name": "my kraken key" }' | http DELETE http://localhost:5042/api/1/exchanges Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/1/exchanges', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'location': 'kraken', 'name': 'my kraken key'})
- Request JSON Object
name (string) – The name of the exchange whose key to delete
location (string) – The location of the exchange to delete
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true "message": "" }
- Response JSON Object
result (bool) – A boolean indicating success or failure
- Status Codes
200 OK – The exchange has been successfully deleted
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – No user is logged in. The exchange is not registered or some other error
500 Internal Server Error – Internal rotki error
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
200 OK – The exchange has been successfully edited
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – No user is logged in. The exchange can not be found. The new exchange credentials were invalid.
500 Internal Server Error – Internal rotki error
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 theignore_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
200 OK – Balances successfully queried.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – User is not logged in.Exchange is not registered or some other exchange query error. Check error message for details.
500 Internal Server Error – Internal rotki error
- 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
200 OK – Balances successfully queried.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – User is not logged in. Some exchange query error. Check error message for details.
500 Internal Server Error – Internal rotki error
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
200 OK – Data successfully purged.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – User is not logged in. Exchange is not registered or some other error. Check error message for details.
500 Internal Server Error – Internal rotki error
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
200 OK – Data successfully purged.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – User is not logged in or some other error. Check error message for details.
500 Internal Server Error – Internal rotki error
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, "data": [{ "evm_chain": "ethereum", "addresses": ["0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "0xed8Bdb5895B8B7f9Fdb3C087628FD8410E853D48"] }, { "evm_chain": "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, "data": [{"evm_chain": "ethereum", "addresses": ["0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "0xed8Bdb5895B8B7f9Fdb3C087628FD8410E853D48"]}, {"evm_chain": "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, "data": [{"evm_chain": "ethereum", "addresses": ["0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "0xed8Bdb5895B8B7f9Fdb3C087628FD8410E853D48"]}, {"evm_chain": "optimism"}]}'
httpie
echo '{ "async_query": false, "data": [ { "addresses": [ "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "0xed8Bdb5895B8B7f9Fdb3C087628FD8410E853D48" ], "evm_chain": "ethereum" }, { "evm_chain": "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, 'data': [{'evm_chain': 'ethereum', 'addresses': ['0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12', '0xed8Bdb5895B8B7f9Fdb3C087628FD8410E853D48']}, {'evm_chain': 'optimism'}]})
- Request JSON Object
data (list) – A list of data explaining what transactions to decode. Each data entry consists of an
"evm_chain"
key specifying the evm chain for which to decode tx_hashes and an"addresses"
key which is an optional list of addresses for which to request decoding of pending transactions in that chain. If the list of addresses is not passed or is null then all transactions for that chain are decoded. Passing an empty list is not allowed.
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
200 OK – Transactions successfully decoded.
409 Conflict – User is not logged in or some other error. Check error message for details.
500 Internal Server Error – Internal rotki error
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
200 OK – Data successfully purged.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – User is not logged in or some other error. Check error message for details.
500 Internal Server Error – Internal rotki error
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", "evm_chain_name": "ethereum", "native_token": "ETH"}, {"id": "OPTIMISM", "name": "optimism", "type": "evm", "evm_chain_name": "optimism", "native_token": "ETH"}, {"id": "arbitrum_one", "name": "Arbitrum One", "type": "evm", "evm_chain_name": "arbitrum_one", "native_token": "ETH"}, {"id": "AVAX", "name": "avalanche", "type": "evm", "evm_chain_name": "avalanche", "native_token": "AVAX"}, {"id": "ETH2", "name": "ethereum beaconchain", "type": "eth2", "native_token": "ETH2"}, {"id": "DOT", "name": "polkadot", "type": "substrate", "native_token": "DOT"}, {"id": "KSM", "name": "kusama", "type": "substrate", "native_token": "KSM"}, {"id": "BTC", "name": "bitcoin", "type": "bitcoin", "native_token": "BTC"}, {"id": "BCH", "name": "bitcoin cash", "type": "bitcoin", "native_token": "BCH"}, {"id": "POLYGON_POS", "name": "polygon pos", "type": "evm", "native_token": "eip155:137/erc20:0x0000000000000000000000000000000000001010"} ] "message": "" }
- Response JSON Object
result (object) – Contains all supported chains’ ID, name, type, EVM chain name (if applicable).
- Status Codes
200 OK – Success
500 Internal Server Error – Internal rotki error
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
200 OK – Cache successfully created.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – User is not logged in or some other error. Check error message for details.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – The oracle could not be queried due to an error on their side.
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
200 OK – Cache successfully delete.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – User is not logged in or some other error. Check error message for details.
500 Internal Server Error – Internal rotki error
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
200 OK – Cache successfully delete.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – User is not logged in or some other error. Check error message for details.
500 Internal Server Error – Internal rotki error
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
200 OK – Oracles successfully queried
500 Internal Server Error – Internal rotki error
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
200 OK – Data successfully purged.
409 Conflict – User is not logged in or some other error. Check error message for details.
500 Internal Server Error – Internal rotki error
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
200 OK – Transactions successfully queried
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – User is not logged in or some other error. Check error message for details.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – An external service used in the query such as etherscan could not be reached or returned unexpected response.
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 requeried.
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 requeried.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Status Codes
200 OK – Transactions successfully decoded.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – One of the given hashes does not correspond to a transaction according to the nodes we contacted.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Problem contacting a remote service
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
200 OK – Tag successfully created.
400 Bad Request – Provided request JSON is in some way malformed. Or no field to edit was given.
409 Conflict – User is not logged in. Tag with the given name does not exist.
500 Internal Server Error – Internal rotki error
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
200 OK – Tag successfully removed.
400 Bad Request – Provided request JSON is in some way malformed.
409 Conflict – User is not logged in. Tag with the given name does not exist.
500 Internal Server Error – Internal rotki error
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
andAVAX
.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 theignore_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 409
User is not logged in. Invalid blockchain, or problems querying the given blockchain
- statuscode 500
Internal rotki error
- statuscode 502
An external service used in the query such as etherscan or blockchain.info could not be reached or returned unexpected response.
Querying all balances
Note
This endpoint can also be queried asynchronously by using
"async_query": true
Note
This endpoint also 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 theignore_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
200 OK – Balances successfully queried.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – User is not logged in.
500 Internal Server Error – Internal rotki error
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 beevm_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.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 exlude 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 haveETH
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 forVET
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 exampleerc20
.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
200 OK – Assets successfully queried.
500 Internal Server Error – Internal rotki error
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
200 OK – Assets successfully queried.
400 Bad Request – One of the identifiers is not valid. Provided JSON is in some way malformed.
500 Internal Server Error – Internal rotki error.
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
200 OK – Assets successfully queried.
400 Bad Request – Provided JSON is in some way malformed.
500 Internal Server Error – Internal rotki error.
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 exlude 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
200 OK – Assets successfully queried.
400 Bad Request – Provided JSON is in some way malformed.
500 Internal Server Error – Internal rotki error.
Querying owned assets
- GET /api/(version)/assets/
Doing a GET on the assets endpoint will return a list of all assets ever owned.
Example Request:
http
GET /api/1/assets/ HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/assets/
wget
wget -S -O- http://localhost:5042/api/1/assets/
httpie
http http://localhost:5042/api/1/assets/
python-requests
requests.get('http://localhost:5042/api/1/assets/')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": ["EUR", "USD", "ETH", "BTC"], "message": "" }
- Response JSON Object
result (list) – A list of asset symbols owned by the user
- Status Codes
200 OK – Assets successfully queried.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – No user is currently logged in.
500 Internal Server Error – Internal rotki error
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
200 OK – Tokens successfully detected.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – No user is currently logged in.
500 Internal Server Error – Internal rotki error
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
200 OK – Asset types successfully queries
400 Bad Request – Provided JSON is in some way malformed
500 Internal Server Error – Internal rotki error
Adding custom asset
- PUT /api/(version)/assets/all
Doing a PUT on the all assets endpoint will allow you to add a new asset in the global rotki DB. Returns the identifier of the newly added asset.
Example Request:
http
PUT /api/1/assets/all HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "name": "foo", "symbol": "FOO", "started": 1614636432, "forked": "SCT", "swapped_for": "SCK", "coingecko": "foo-coin", "cryptocompare": "FOO" }
curl
curl -i -X PUT http://localhost:5042/api/1/assets/all -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"coingecko": "foo-coin", "cryptocompare": "FOO", "forked": "SCT", "name": "foo", "started": 1614636432, "swapped_for": "SCK", "symbol": "FOO"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/assets/all --header="Content-Type: application/json;charset=UTF-8" --body-data='{"coingecko": "foo-coin", "cryptocompare": "FOO", "forked": "SCT", "name": "foo", "started": 1614636432, "swapped_for": "SCK", "symbol": "FOO"}'
httpie
echo '{ "coingecko": "foo-coin", "cryptocompare": "FOO", "forked": "SCT", "name": "foo", "started": 1614636432, "swapped_for": "SCK", "symbol": "FOO" }' | http PUT http://localhost:5042/api/1/assets/all Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/assets/all', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'coingecko': 'foo-coin', 'cryptocompare': 'FOO', 'forked': 'SCT', 'name': 'foo', 'started': 1614636432, 'swapped_for': 'SCK', 'symbol': 'FOO'})
- Request JSON Object
name (string) – The name of the asset. Required.
symbol (string) – The symol of the asset. Required.
started (integer) – The time the asset started existing. Optional
forked (string) – The identifier of an asset from which this asset got forked. For example ETC would have ETH as forked. Optional.
swapped_for (string) – The identifier of an asset for which this asset got swapped for. For example GNT got swapped for GLM. Optional.
- Response JSON Array of Objects
coingecko (string) – The coingecko identifier for the asset. can be missing if not known.
cryptocompare (string) – The cryptocompare identifier for the asset. can be missing if not known.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": {"identifier": "4979582b-ee8c-4d45-b461-15c4220de666"}, "message": "" }
- Response JSON Object
identifier (string) – The identifier of the newly added token.
- Status Codes
200 OK – Asset successfully added.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – Some conflict at addition. For example an asset with the same type, name and symbol already exists.
500 Internal Server Error – Internal rotki error
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
200 OK – Asset successfully edited.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – Some conflict at editing. For example identifier does not exist in the DB.
500 Internal Server Error – Internal rotki error
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
200 OK – Pending asset updates information is successfully queried
400 Bad Request – Provided JSON is in some way malformed
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Error while trying to reach the remote for asset updates.
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
200 OK – Update was successfully applied (if any).
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – Conflicts were found during update. The conflicts should also be returned. No user is currently logged in.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Error while trying to reach the remote for asset updates.
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 andhard
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
orhard
.
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
200 OK – Reset of the globaldb performed.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – Conflicts were found during the reset.
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
200 OK – Asset successfully replaced.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – Some conflict at replacing or user is not logged in.
500 Internal Server Error – Internal rotki error
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
200 OK – Icon successfully uploaded
500 Internal Server Error – Internal rotki error
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 requeried 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
200 OK – Icon successfully deleted and requeried.
400 Bad Request – Provided JSON is in some way malformed.
404 Not Found – Unable to refresh icon at the moment.
500 Internal Server Error – Internal rotki error
Statistics for netvalue over time
- GET /api/(version)/statistics/netvalue/
Note
This endpoint is only available for premium users
Doing a GET on the statistics netvalue over time endpoint will return all the saved historical data points with user’s history
Example Request:
http
GET /api/1/statistics/netvalue/ HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/statistics/netvalue/
wget
wget -S -O- http://localhost:5042/api/1/statistics/netvalue/
httpie
http http://localhost:5042/api/1/statistics/netvalue/
python-requests
requests.get('http://localhost:5042/api/1/statistics/netvalue/')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "times": [1571992200, 1572078657], "data": ["15000", "17541.23"] }, "message": "" }
- Response JSON Object
times (list[integer]) – A list of timestamps for the returned data points
data (list[string]) – A list of net usd value for the corresponding timestamps. They are matched by list index.
- Status Codes
200 OK – Netvalue statistics successfully queried.
400 Bad Request – Provided JSON is in some way malformed.
409 Conflict – No user is currently logged in or currently logged in user does not have a premium subscription.
500 Internal Server Error – Internal rotki error.
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
200 OK – Single asset balance statistics successfully queried
400 Bad Request – Provided JSON is in some way malformed or data is invalid.
409 Conflict – No user is currently logged in or currently logged in user does not have a premium subscription.
500 Internal Server Error – Internal rotki error
Statistics for value distribution
- GET /api/(version)/statistics/value_distribution/
Doing a GET on the statistics value distribution endpoint with the
"distribution_by": "location"
argument will return the distribution of netvalue across all locations.Note
This endpoint is only available for premium users
Note
This endpoint also accepts parameters as query arguments.
Example Request:
http
GET /api/1/statistics/value_distribution/ HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"distribution_by": "location"}
curl
curl -i -X GET http://localhost:5042/api/1/statistics/value_distribution/ -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"distribution_by": "location"}'
wget
wget -S -O- http://localhost:5042/api/1/statistics/value_distribution/ --header="Content-Type: application/json;charset=UTF-8" --body-data='{"distribution_by": "location"}'
httpie
echo '{ "distribution_by": "location" }' | http http://localhost:5042/api/1/statistics/value_distribution/ Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/statistics/value_distribution/', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'distribution_by': 'location'})
- Request JSON Object
distribution_by (str) – The type of distribution to return. It can only be
"location"
or"asset"
.
- Parameters
distribution_by (str) – The type of distribution to return. It can only be
"location"
or"asset"
.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": [{ "time": 1571992200, "location": "kraken", "usd_value": "8901.1" }, { "time": 1571992200, "location": "binance", "usd_value": "9501.3" }], "message": "" }
- Response JSON Object
result (list(object)) – A list of location data entries.
- Response JSON Array of Objects
time (integer) – The timestamp of the entry
location (string) – The location of the entry.
usd_value (string) – The value of the entry in $.
- Status Codes
200 OK – Value distribution successfully queried.
400 Bad Request – Provided JSON is in some way malformed or data is invalid.
409 Conflict – No user is currently logged in or currently logged in user does not have a premium subscription.
500 Internal Server Error – Internal rotki error.
- GET /api/(version)/statistics/value_distribution/
Note
This endpoint is only available for premium users
Doing a GET on the statistics value distribution endpoint with the
"distribution_by": "asset"
argument will return the distribution of netvalue across all assets.Example Request:
http
GET /api/1/statistics/value_distribution/ HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"distribution_by": "asset"}
curl
curl -i -X GET http://localhost:5042/api/1/statistics/value_distribution/ -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"distribution_by": "asset"}'
wget
wget -S -O- http://localhost:5042/api/1/statistics/value_distribution/ --header="Content-Type: application/json;charset=UTF-8" --body-data='{"distribution_by": "asset"}'
httpie
echo '{ "distribution_by": "asset" }' | http http://localhost:5042/api/1/statistics/value_distribution/ Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/statistics/value_distribution/', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'distribution_by': 'asset'})
- Request JSON Object
distribution_by (str) – The type of distribution to return. It can only be
"location"
or"asset"
.
- Parameters
distribution_by (str) – The type of distribution to return. It can only be
"location"
or"asset"
.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": [{ "time": 1571992200, "asset": "BTC", "amount": "1.2" "usd_value": "8901.1" }, { "time": 1571992200, "asset": "ETH", "amount": "80.44", "usd_value": "9501.3" }], "message": "" }
- Response JSON Object
result (list(object)) – A list of asset balance data entries. Each entry contains the timestamp of the entry, the assets, the amount in asset and the equivalent usd value at the time.
- Response JSON Array of Objects
time (integer) – The timestamp of the balance entry.
asset (string) – The name of the asset for the balance entry.
amount (string) – The amount in asset for the balance entry.
usd_value (string) – The amount in $ for the balance entry at the time of query.
- Status Codes
200 OK – Value distribution successfully queried.
400 Bad Request – Provided JSON is in some way malformed or data is invalid.
409 Conflict – No user is currently logged in or currently logged in user does not have a premium subscription.
500 Internal Server Error – Internal rotki error.
Statistics rendering code
- GET /api/(version)/statistics/renderer/
Doing a GET on the statistics renderer will return the code to render the statistics if the currently logged in user is a premium user.
Note
This endpoint is only available for premium users
Example Request:
http
GET /api/1/statistics/renderer/ HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/statistics/renderer/
wget
wget -S -O- http://localhost:5042/api/1/statistics/renderer/
httpie
http http://localhost:5042/api/1/statistics/renderer/
python-requests
requests.get('http://localhost:5042/api/1/statistics/renderer/')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": "code goes here" "message": "" }
- Response JSON Object
result (string) – The source code of the renderer.
- Status Codes
200 OK – Rendering code successfully returned.
400 Bad Request – Provided JSON is in some way malformed.
409 Conflict – No user is currently logged in or currently logged in user does not have a premium subscription. There is a problem reaching the rotki server.
500 Internal Server Error – Internal rotki error.
Dealing with trades
- GET /api/(version)/trades
Note
This endpoint can also be queried asynchronously by using
"async_query": true
Note
This endpoint also accepts parameters as query arguments.
Doing a GET on this endpoint will return all trades of the current user. They can be further filtered by time range and/or location. If the user is not premium and has more than 250 trades then the returned trades will be limited to that number. Any filtering will also be limited to those first 250 trades. Trades are returned most recent first.
Example Request:
http
GET /api/1/trades HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"from_timestamp": 1451606400, "to_timestamp": 1571663098, "location": "external", "only_cache": false}
curl
curl -i -X GET http://localhost:5042/api/1/trades -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_timestamp": 1451606400, "location": "external", "only_cache": false, "to_timestamp": 1571663098}'
wget
wget -S -O- http://localhost:5042/api/1/trades --header="Content-Type: application/json;charset=UTF-8" --body-data='{"from_timestamp": 1451606400, "location": "external", "only_cache": false, "to_timestamp": 1571663098}'
httpie
echo '{ "from_timestamp": 1451606400, "location": "external", "only_cache": false, "to_timestamp": 1571663098 }' | http http://localhost:5042/api/1/trades Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/trades', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_timestamp': 1451606400, 'location': 'external', 'only_cache': False, 'to_timestamp': 1571663098})
- Request JSON Object
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"
.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 ofquote_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
200 OK – Trades are successfully returned
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – No user is logged in.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Error reaching the remote from which the trades got requested
- 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 ofquote_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 inlink (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
200 OK – Trades was successfully added.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – No user is currently logged in.
500 Internal Server Error – Internal rotki error
- 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
200 OK – Trades was successfully edited.
400 Bad Request – Provided JSON is in some way malformed.
409 Conflict – No user is logged in. The given trade identifier to edit does not exist.
500 Internal Server Error – Internal rotki error.
- 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 returnsfalse
.message (string) – Returns
""
ifresult
isTrue
else returns the error message.
- Status Codes
200 OK – Trades was successfully deleted.
400 Bad Request – Provided JSON is in some way malformed.
409 Conflict – No user is logged in. The given trade identifier to delete does not exist.
500 Internal Server Error – Internal rotki error.
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.
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 infee (string) – The fee that was paid, if anything, for this deposit/withdrawal
link (string) – Optional unique exchange identifier for the deposit/withdrawal
- Status Codes
200 OK – Deposits/withdrawals are successfully returned
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – No user is logged in.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Error querying the remote for the asset movements
Dealing with ledger actions
- GET /api/(version)/ledgeractions
Note
This endpoint can also be queried asynchronously by using
"async_query": true
Note
This endpoint also accepts parameters as query arguments.
Doing a GET on this endpoint will return all ledger actions of the current user. That means income, loss, expense and other actions. They can be further filtered by time range and/or location. If the user is not premium and has more than 50 actions then the returned results will be limited to that number. Any filtering will also be limited to those first 50 actions. Actions are returned most recent first.
Example Request:
http
GET /api/1/ledgeractions HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"from_timestamp": 1451606400, "to_timestamp": 1571663098, "location": "blockchain"}
curl
curl -i -X GET http://localhost:5042/api/1/ledgeractions -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_timestamp": 1451606400, "location": "blockchain", "to_timestamp": 1571663098}'
wget
wget -S -O- http://localhost:5042/api/1/ledgeractions --header="Content-Type: application/json;charset=UTF-8" --body-data='{"from_timestamp": 1451606400, "location": "blockchain", "to_timestamp": 1571663098}'
httpie
echo '{ "from_timestamp": 1451606400, "location": "blockchain", "to_timestamp": 1571663098 }' | http http://localhost:5042/api/1/ledgeractions Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/ledgeractions', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_timestamp': 1451606400, 'location': 'blockchain', 'to_timestamp': 1571663098})
- Request JSON Object
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 ledger actions table by which to order the results. If none is given ‘timestamp’ is assumed. Valid values are: [‘timestamp’, ‘location’, ‘type’, ‘amount’, ‘rate’].
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.
asset (string) – Optionally filter by action asset. A valid asset has to be provided. If missing asset filtering does not happen.
location (string) – Optionally filter actions by location. A valid location name has to be provided. If missing location filtering does not happen.
type (string) – Optionally filter by ledger action type. A valid action type to be provided. If missing action type filtering does not happen.
only_cache (bool) – Optional. If this is true then the equivalent exchange/location is not queried, but only what is already in the DB is returned.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "entries": [{ "entry": { "identifier": 344, "timestamp": 1491606401, "action_type": "loss", "location": "blockchain", "amount": "1550", "asset": "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F", "rate": "0.85", "rate_asset": "EUR", "link": "https://etherscan.io/tx/0xea5594ad7a1e552f64e427b501676cbba66fd91bac372481ff6c6f1162b8a109" "notes": "The DAI I lost in the pickle finance hack" }, "ignored_in_accounting": false }], "entries_found": 1, "entries_total": 1, "entries_limit": 50, "message": "" }
- Response JSON Object
entries (object) – An array of action objects and their metadata. Each entry is composed of the ledger action entry under the
"entry"
key and other metadata like"ignored_in_accounting"
for each action.entries_found (int) – The 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 (int) – The uniquely identifying identifier for this action.
timestamp (int) – The timestamp at which the action occurred
action_type (string) – The type of action. Valid types are:
income
,loss
,donation received
,expense
anddividends income
.location (string) – A valid location at which the action happened.
amount (string) – The amount of asset for the action
asset (string) – The asset for the action
rate (string) – Optional. If given then this is the rate in
rate_asset
for theasset
of the action.rate_asset (string) – Optional. If given then this is the asset for which
rate
is given.link (string) – Optional unique identifier or link to the action. Can be an empty string
notes (string) – Optional notes about the action. Can be an empty string
- Status Codes
200 OK – Actions are successfully returned
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – No user is logged in.
500 Internal Server Error – Internal rotki error
- PUT /api/(version)/ledgeractions
Doing a PUT on this endpoint adds a new ledgeraction to rotki’s currently logged in user. The identifier of the new created action is returned.
Example Request:
http
PUT /api/1/ledgeraction HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "action": { "timestamp": 1491606401, "action_type": "income", "location": "external", "amount": "1", "asset": "ETH", "rate": "650", "rate_asset": "EUR", "link": "Optional unique identifier", "notes": "Eth I received for being pretty" }}
curl
curl -i -X PUT http://localhost:5042/api/1/ledgeraction -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"action": {"action_type": "income", "amount": "1", "asset": "ETH", "link": "Optional unique identifier", "location": "external", "notes": "Eth I received for being pretty", "rate": "650", "rate_asset": "EUR", "timestamp": 1491606401}}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/ledgeraction --header="Content-Type: application/json;charset=UTF-8" --body-data='{"action": {"action_type": "income", "amount": "1", "asset": "ETH", "link": "Optional unique identifier", "location": "external", "notes": "Eth I received for being pretty", "rate": "650", "rate_asset": "EUR", "timestamp": 1491606401}}'
httpie
echo '{ "action": { "action_type": "income", "amount": "1", "asset": "ETH", "link": "Optional unique identifier", "location": "external", "notes": "Eth I received for being pretty", "rate": "650", "rate_asset": "EUR", "timestamp": 1491606401 } }' | http PUT http://localhost:5042/api/1/ledgeraction Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/ledgeraction', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'action': {'action_type': 'income', 'amount': '1', 'asset': 'ETH', 'link': 'Optional unique identifier', 'location': 'external', 'notes': 'Eth I received for being pretty', 'rate': '650', 'rate_asset': 'EUR', 'timestamp': 1491606401}})
The request object is the same as above, a LedgerAction entry.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": {"identifier": 1}, "message": "" }
- Response JSON Object
result (object) – The identifier of the newly created ledger action
- Status Codes
200 OK – Ledger action was successfully added.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – No user is currently logged in.
500 Internal Server Error – Internal rotki error
- PATCH /api/(version)/ledgeractions
Doing a PATCH on this endpoint edits an existing ledger action in rotki’s currently logged in user using the given
identifier
.Example Request:
http
PATCH /api/1/ledgeractions HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "identifier": 55, "timestamp": 1491606401, "action_type": "income", "location": "external", "amount": "2", "asset": "ETH", "rate": "650", "rate_asset": "EUR", "link": "Optional unique identifier", "notes": "Eth I received for being pretty" }
curl
curl -i -X PATCH http://localhost:5042/api/1/ledgeractions -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"action_type": "income", "amount": "2", "asset": "ETH", "identifier": 55, "link": "Optional unique identifier", "location": "external", "notes": "Eth I received for being pretty", "rate": "650", "rate_asset": "EUR", "timestamp": 1491606401}'
wget
wget -S -O- --method=PATCH http://localhost:5042/api/1/ledgeractions --header="Content-Type: application/json;charset=UTF-8" --body-data='{"action_type": "income", "amount": "2", "asset": "ETH", "identifier": 55, "link": "Optional unique identifier", "location": "external", "notes": "Eth I received for being pretty", "rate": "650", "rate_asset": "EUR", "timestamp": 1491606401}'
httpie
echo '{ "action_type": "income", "amount": "2", "asset": "ETH", "identifier": 55, "link": "Optional unique identifier", "location": "external", "notes": "Eth I received for being pretty", "rate": "650", "rate_asset": "EUR", "timestamp": 1491606401 }' | http PATCH http://localhost:5042/api/1/ledgeractions Content-Type:"application/json;charset=UTF-8"
python-requests
requests.patch('http://localhost:5042/api/1/ledgeractions', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'action_type': 'income', 'amount': '2', 'asset': 'ETH', 'identifier': 55, 'link': 'Optional unique identifier', 'location': 'external', 'notes': 'Eth I received for being pretty', 'rate': '650', 'rate_asset': 'EUR', 'timestamp': 1491606401})
The request object is the same as above, a LedgerAction entry, with the addition of the identifier which signifies which ledger action entry will be edited.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "entries": [{ "entry": { "identifier": 55, "timestamp": 1491606401, "action_type": "income" "location": "external", "amount": "2", "asset": "ETH", "rate": "650", "rate_asset": "EUR", "link": "Optional unique identifier", "notes": "Eth I received for being pretty" }, "ignored_in_accounting": false }], "entries_found": 1, "entries_limit": 50, "message": "" }
- Response JSON Object
entries (object) – An array of action objects after editing. Same schema as the get method.
entries_found (int) – The amount of actions found for the user. That disregards the filter and shows all actions found.
entries_limit (int) – The actions limit for the account tier of the user. If unlimited then -1 is returned.
- Status Codes
200 OK – Actions was successfully edited.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – No user is logged in.
500 Internal Server Error – Internal rotki error
- DELETE /api/(version)/ledgeractions
Doing a DELETE on this endpoint deletes an existing ledger action in rotki’s currently logged in user using the
identifier
.Example Request:
http
DELETE /api/1/ledgeractions HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"identifiers" : [55]}
curl
curl -i -X DELETE http://localhost:5042/api/1/ledgeractions -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"identifiers": [55]}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/ledgeractions --header="Content-Type: application/json;charset=UTF-8" --body-data='{"identifiers": [55]}'
httpie
echo '{ "identifiers": [ 55 ] }' | http DELETE http://localhost:5042/api/1/ledgeractions Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/1/ledgeractions', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'identifiers': [55]})
- Request JSON Object
identifiers (integer) – The list of identifiers of the actions 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 returnsfalse
.message (string) – Returns
""
ifresult
isTrue
else return the error message.
- Status Codes
200 OK – Action was successfully removed.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – No user is logged in.
500 Internal Server Error – Internal rotki error
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.
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 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 to provide more information about the location. When we use this structure in blockchains, it is used to specify the user address. For exchange events it’s the exchange name assigned by the user.
entry_types (object) – An object with two keys named ‘values’ and ‘behaviour’. ‘values’ is a list of entry types to optionally filter by. ‘behaviour’ is optional and is a string with the value ‘include’ or ‘exclude’ which defines the filtering behaviour. 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: 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, "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, "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, "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, "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, "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
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
200 OK – Events succesfully queried
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – No user is logged in or failure at event addition.
500 Internal Server Error – Internal rotki error
- PUT /api/(version)/history/events
Doing a PUT on this endpoint can add a new evm event to rotki. For each entry evm chain also has to be specified. The unique identifier for the entry is returned as success.
Example Request:
http
PUT /api/1/history/events HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "tx_hash": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "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" }
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", "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, "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", "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, "tx_hash": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e"}'
httpie
echo '{ "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "balance": { "amount": "1.542", "usd_value": "1.675" }, "counterparty": "0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE", "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, "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', '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, 'tx_hash': '0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e'})
- 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.
timestamp (int) – The timestamp of the entry
location (string) – The location of the entry. Such as “ethereum”, “optimism”, etc.
event_type (string) – The main event type of the entry. Possible event types can be seen in HistoryEventType enum.
asset (string) – The asset identifier for this entry
balance (object) – The amount/usd value of the event. If not known usd_value can also be “0”.
location_label (string) – 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) – 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.
event_subtype (string) – Optional. An optional subtype for the entry. Possible event types can be seen in HistoryEventSubType enum.
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.
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
200 OK – Entry is successfully added.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – No user is logged in or failure at event addition.
500 Internal Server Error – Internal rotki error
- 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 { "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", "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", "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", "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', '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 is the same as above, a base history entry, 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
200 OK – Event was successfully edited.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – No user is logged in. Or event to edit was not found in the DB or edit is not allowed.
500 Internal Server Error – Internal rotki error
- 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
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
200 OK – Events were queried succesfully
400 Bad Request – Provided JSON is in some way malformed.
409 Conflict – Module for the given events is not active.
500 Internal Server Error – Internal rotki error.
502 Bad Gateway – An external service used in the query such as beaconchain could not be reached or returned an unexpected response.
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
200 OK – Messages popped and read successfully.
500 Internal Server Error – Internal rotki error.
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
200 OK – History processed and returned successfully
400 Bad Request – Provided JSON is in some way malformed.
409 Conflict – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
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"], "taxable_ledger_actions": [ "income", "expense", "loss", "dividends income", "donation received", "grant" ], "pnl_csv_with_formulas": true, "pnl_csv_have_summary": false, "ssf_graph_multiplier": 0, "last_data_migration": 3, "non_syncing_exchanges": [] }, "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
200 OK – Debugging history data returned successfully
400 Bad Request – Provided JSON is in some way malformed.
409 Conflict – No user is currently logged in. Error occured when creating history events for pnl debug data.
500 Internal Server Error – Internal rotki error.
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