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 in 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 a detailed explanation of how each one can be used to interact with rotki.
Colibri endpoints
Note
Endpoints in this section are served by Colibri (Rust service), not the Python backend.
They do not use the /api/(version)/ prefix.
Getting or modifying Colibri configuration
- GET /settings/configuration
Doing a
GETon this Colibri endpoint returns runtime configuration values for the Rust service. This endpoint does not use the/api/(version)/prefix.Example Request:
http
GET /settings/configuration HTTP/1.1 Host: localhost:4343
curl
curl -i -X GET http://localhost:4343/settings/configuration
wget
wget -S -O- http://localhost:4343/settings/configuration
httpie
http http://localhost:4343/settings/configurationpython-requests
requests.get('http://localhost:4343/settings/configuration')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "loglevel": { "value": "INFO", "is_default": true } }, "message": "" }
- Response JSON Object:
loglevel (object) – The current logging level of Colibri.
value (string) – Value used for the configuration.
is_default (bool) –
trueif the setting uses Colibri’s default value andfalseotherwise.
- Status Codes:
200 OK – Querying of the Colibri configuration was successful.
- PUT /settings/configuration
Doing a
PUTon this Colibri endpoint modifies Colibri’s log level at runtime. This endpoint does not use the/api/(version)/prefix.Example Request:
http
PUT /settings/configuration HTTP/1.1 Host: localhost:4343 Content-Type: application/json { "loglevel": "TRACE" }
curl
curl -i -X PUT http://localhost:4343/settings/configuration -H "Content-Type: application/json" --data-raw '{"loglevel": "TRACE"}'
wget
wget -S -O- --method=PUT http://localhost:4343/settings/configuration --header="Content-Type: application/json" --body-data='{"loglevel": "TRACE"}'
httpie
echo '{ "loglevel": "TRACE" }' | http PUT http://localhost:4343/settings/configuration Content-Type:application/json
python-requests
requests.put('http://localhost:4343/settings/configuration', headers={'Content-Type': 'application/json'}, json={'loglevel': 'TRACE'})
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "loglevel": { "value": "TRACE", "is_default": false } }, "message": "" }
- Request JSON Object:
loglevel (string) – The logging level to set. Must be one of:
TRACE,DEBUG,INFO,WARNING,ERROR,CRITICAL,OFF.
- Status Codes:
200 OK – Colibri configuration was successfully updated.
400 Bad Request – Provided
loglevelis not supported.500 Internal Server Error – Internal Colibri error.
Query oracle prices
- GET /prices/oracle
Doing a
GETon this endpoint returns rows from the globalprice_historytable. Results are ordered bytimestamp DESC, from_asset, to_asset, source_type.Example Request:
http
GET /prices/oracle?from_asset=ETH&to_asset=USD&source_type=defillama&from_timestamp=1700000000&to_timestamp=1800000000&limit=50&offset=0 HTTP/1.1 Host: localhost:4343
curl
curl -i -X GET 'http://localhost:4343/prices/oracle?from_asset=ETH&to_asset=USD&source_type=defillama&from_timestamp=1700000000&to_timestamp=1800000000&limit=50&offset=0'
wget
wget -S -O- 'http://localhost:4343/prices/oracle?from_asset=ETH&to_asset=USD&source_type=defillama&from_timestamp=1700000000&to_timestamp=1800000000&limit=50&offset=0'
httpie
http 'http://localhost:4343/prices/oracle?from_asset=ETH&to_asset=USD&source_type=defillama&from_timestamp=1700000000&to_timestamp=1800000000&limit=50&offset=0'
python-requests
requests.get('http://localhost:4343/prices/oracle?from_asset=ETH&to_asset=USD&source_type=defillama&from_timestamp=1700000000&to_timestamp=1800000000&limit=50&offset=0')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "entries": [ { "from_asset": "ETH", "to_asset": "USD", "source_type": "defillama", "timestamp": 1700000100, "price": "2012.42" } ], "entries_found": 1, "entries_total": 3, "entries_limit": -1 }, "message": "" }
- Query Parameters:
from_asset (string[optional]) – Filter by
price_history.from_assetto_asset (string[optional]) – Filter by
price_history.to_assetsource_type (string[optional]) – Price oracle/source filter. Accepted values are db chars
A..``I`` (case-insensitive) or oracle namesmanual,coingecko,cryptocompare,fiat(preferred),xratescom(legacy alias),manualcurrent/manual_current,defillama,uniswap2/uniswapv2,uniswap3/uniswapv3,alchemy.blockchainis rejected because it is not stored inprice_history.from_timestamp (integer[optional]) – Inclusive lower bound for
timestampto_timestamp (integer[optional]) – Inclusive upper bound for
timestamplimit (integer[optional]) – Number of rows to return. Defaults to
100.offset (integer[optional]) – Pagination offset. Defaults to
0.
- Response JSON Object:
result.entries (list) – A list of matching
price_historyrows.from_asset (string) – The source asset identifier.
to_asset (string) – The quote asset identifier.
source_type (string) – Oracle source name (
manual,coingecko,cryptocompare,fiat,manualcurrent,defillama,uniswapv2,uniswapv3,alchemy).timestamp (integer) – UNIX timestamp in seconds.
price (string) – Price stored as string.
result.entries_found (int) – The number of entries matching the requested supplied filters.
result.entries_total (int) – The total number of entries in the database, ignoring any filters or pagination.
result.entries_limit (int) – The limit of entries that can be returned. Since this is a free endpoint this is always
-1.
- Status Codes:
200 OK – Query was successful.
400 Bad Request – Invalid
source_typevalue.500 Internal Server Error – Internal Colibri error.
Handling user creation, sign-in, log-out and querying
- GET /api/(version)/users
By doing a
GETat 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
PUTat 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"], "ssf_graph_multiplier": 2, "non_sync_exchanges": [{"location": "binance", "name": "binance1"}] } }, "message": "" }
- Response JSON Object:
result (object) – For successful requests, result contains the currently connected exchanges, and the user’s settings. For details on the user settings refer to the Getting or modifying settings section.
- Status Codes:
200 OK – Adding the new user was successful
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – Another user is already logged in. User already exists. Given Premium API credentials are invalid. Permission error while trying to access the directory where rotki saves data.
500 Internal Server Error – Internal rotki error
- POST /api/(version)/users/(username)
By doing a
POSTat 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"yesbe 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
falseso 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 istruethen the latest backup will be used and the login will proceed as usual.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "exchanges": [ {"location": "kraken", "name": "kraken1", "kraken_account_type": "starter"}, {"location": "poloniex", "name": "poloniex1"}, {"location": "binance", "name": "binance1"} ], "settings": { "have_premium": true, "version": "6", "last_write_ts": 1571552172, "premium_should_sync": true, "include_crypto2crypto": true, "last_data_upload_ts": 1571552172, "ui_floating_precision": 2, "taxfree_after_period": 31536000, "balance_save_frequency": 24, "include_gas_costs": true, "ksm_rpc_endpoint": "http://localhost:9933", "main_currency": "USD", "date_display_format": "%d/%m/%Y %H:%M:%S %Z", "last_balance_save": 1571552172, "submit_usage_analytics": true, "active_modules": ["makerdao_dsr", "makerdao_vaults", "aave"], "current_price_oracles": ["cryptocompare", "coingecko"], "historical_price_oracles": ["cryptocompare", "coingecko"], "ssf_graph_multiplier": 2, "non_sync_exchanges": [{"location": "binance", "name": "binance1"}] } }, "message": "" }
- Response JSON Object:
result (object) – For successful requests, result contains the currently connected exchanges,and the user’s settings. For details on the user settings refer to the Getting or modifying settings section.
- Status Codes:
200 OK – Logged in successfully
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 emptyresultkey and an explanatorymessageon 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 theresultkey and the message under themessagekey. The payload has the following keys:local_size,remote_size,local_last_modified,remote_last_modified.
400 Bad Request – Provided JSON is in some way malformed
401 Unauthorized – Provided password is wrong for the user or some other authentication error.
409 Conflict – User does not exist. Another user is already logged in. There was a fatal error during the upgrade of the DB. Permission error while trying to access the directory where rotki saves data.
500 Internal Server Error – Generic internal rotki error
542 – Internal rotki error relating to the database. Check message for more details.
- PATCH /api/(version)/users/(username)
By doing a
PATCHat 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
PATCHat 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
403 Forbidden – 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
DELETEat 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.
403 Forbidden – Logged in User does not have premium.
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
PUTat 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
PUT /api/1/premium/sync HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "action": "download" }
curl
curl -i -X PUT http://localhost:5042/api/1/premium/sync -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"action": "download"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/premium/sync --header="Content-Type: application/json;charset=UTF-8" --body-data='{"action": "download"}'
httpie
echo '{ "action": "download" }' | http PUT http://localhost:5042/api/1/premium/sync Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('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
PATCHat 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 successful
400 Bad Request – Provided call is in some way malformed. For example a user who is not logged in has been specified.
401 Unauthorized – Password mismatch
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":"key1"}, "blockscout":{"api_key":"key2"}, "cryptocompare": {"api_key":"boooookey"}, "opensea": {"api_key":"goooookey"}, "monerium": {"username":"Ben", "password":"secure"} }, "message":"" }
- Response JSON Object:
result (object) – The result object contains as many entries as the external services. Each entry’s key is the name and the value is another object of the form
{"api_key": "foo"}. Themoneriumservice has a different structure than the rest. Hasusernameandpasswordkeys. Thegnosis_payservice at the moment is hacky. Need to provide the auth js session token in place of the api key.
- Status Codes:
200 OK – Querying of external service credentials was successful
401 Unauthorized – 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.
Some credentials like monerium can’t be input if the user is not premium.
Returns external service entries after the additions.
Example Request:
http
PUT /api/1/external_services HTTP/1.1 Host: localhost:5042 Content-Type: application/json { "services": [{"name": "etherscan", "api_key": "goookey"}] }
curl
curl -i -X PUT http://localhost:5042/api/1/external_services -H "Content-Type: application/json" --data-raw '{"services": [{"name": "etherscan", "api_key": "goookey"}]}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/external_services --header="Content-Type: application/json" --body-data='{"services": [{"name": "etherscan", "api_key": "goookey"}]}'
httpie
echo '{ "services": [ { "api_key": "goookey", "name": "etherscan" } ] }' | http PUT http://localhost:5042/api/1/external_services Content-Type:application/json
python-requests
requests.put('http://localhost:5042/api/1/external_services', headers={'Content-Type': 'application/json'}, json={'services': [{'name': 'etherscan', 'api_key': 'goookey'}]})
- Request JSON Object:
services (list) – The services parameter is a list of services along with their api keys.
- Request JSON Array of Objects:
name (string) – Each entry in the list should have a name for the service. Valid ones are
"etherscan","cryptocompare","beaconchain","loopring","opensea",blockscout,monerium.api_key (string[optional]) – Each entry in the list should have an api_key entry except for monerium.
username (string[optional]) – The monerium entry should have a username key. For monerium the user should have premium.
password (string[optional]) – The monerium entry should have a password key. For monerium the user should have premium.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "etherscan": {"api_key": "goookey"}, "cryptocompare": {"api_key": "boooookey"} }, "message": "" }
- Response JSON Object:
result (object) – The result object contains as many entries as the external services.
- Status Codes:
200 OK – Saving new external service credentials was successful
400 Bad Request – Provided JSON is in some way malformed, of invalid value provided.
401 Unauthorized – There is no logged in user
403 Forbidden – Logged in user does not have premium and requested to add credentials that can only work for premium.
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"], "evm_indexers_order": { "ethereum": ["etherscan", "blockscout", "routescan"], "optimism": ["blockscout", "etherscan", "routescan"] }, "default_evm_indexer_order": ["etherscan", "blockscout", "routescan"], "ssf_graph_multiplier": 2, "non_sync_exchanges": [{"location": "binance", "name": "binance1"}], "cost_basis_method": "fifo", "oracle_penalty_threshold_count": 5, "oracle_penalty_duration": 1800, "auto_delete_calendar_entries": true, "auto_create_calendar_reminders": true, "address_name_priority": ["private_addressbook", "blockchain_account", "global_addressbook", "ethereum_tokens", "hardcoded_mappings", "ens_names"], "ask_user_upon_size_discrepancy": true, "auto_detect_tokens": true, "csv_export_delimiter": ",", "asset_movement_amount_tolerance": "0.000001", "asset_movement_time_range": 54000, "suppress_missing_key_msg_services": ["etherscan"], "auto_create_profit_events": false, "internal_txs_to_repull": 20, "internal_tx_conflict_repull_frequency": 3600 }, "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
-1which will then set the taxfree_after_period tonullwhich 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.
evm_indexers_order (object) – Mapping of EVM chain names to the ordered list of indexers to query per chain. Example:
{"ethereum": ["etherscan", "blockscout", "routescan"]}.default_evm_indexer_order (list) – Default order to use for chains where no specific indexer order has been given.
ssf_graph_multiplier (int) – A multiplier to the snapshot saving frequency for zero amount graphs. Originally 0 by default. If set it denotes the multiplier of the snapshot saving frequency at which to insert 0 save balances for a graph between two saved values.
cost_basis_method (string) – Defines which method to use during the cost basis calculation. Currently supported: fifo, lifo.
address_name_priority (string) – Defines the priority to search for address names. From first to last location in this array, the first name found will be displayed.
infer_zero_timed_balances (bool) – A boolean denoting whether to infer zero timed balances for assets that have no balance at a specific time. This is useful for showing zero balance periods in graphs.
query_retry_limit (int) – The number of times to retry a query to external services before giving up. Default is 5.
connect_timeout (int) – The number of seconds to wait before giving up on establishing a connection to an external service. Default is 30.
read_timeout (int) – The number of seconds to wait for the first byte after a connection to an external service has been established. Default is 30.
oracle_penalty_threshold_count (int) – The number of failures after which an oracle is penalized. Default is 5.
oracle_penalty_duration (int) – The duration in seconds for which an oracle is penalized. Default is 1800.
auto_delete_calendar_entries (bool) – A boolean denoting whether calendar entries are automatically deleted when related blockchain accounts are removed. Default is
true.auto_create_calendar_reminders (bool) – A boolean denoting whether reminders are created automatically for calendar entries based on the decoded history events. Default is
true.ask_user_upon_size_discrepancy (bool) – A boolean denoting whether to prompt the user for confirmation each time the remote database is bigger than the local one or directly force push. Default is
true.auto_detect_tokens (bool) – A boolean denoting whether to automatically detect and add tokens for EVM addresses. Default is
true.csv_export_delimiter (string) – The delimiter character to use when exporting data to CSV files. Default is
",".asset_movement_amount_tolerance (string) – The tolerance value used when matching asset movement amounts with onchain events. Must be a positive decimal number. Default is
"0.000001".asset_movement_time_range (int) – The time range before/after the asset movement (depending on if its a deposit/withdrawal) in which to check for possible matching events. Default is 54000 (15 hours). Note: there is also a 1 hour tolerance on the other side of the asset movement, since some exchanges do not provide accurate timestamps.
suppress_missing_key_msg_services (list) – A list of services for which the missing api key WS message should be suppressed. Empty list by default.
auto_create_profit_events (bool) – A boolean denoting whether profit history events are automatically created when protocol withdrawal events exceed deposits during historical balances processing. Default is
false.internal_txs_to_repull (int) – The number of internal transaction conflicts to repull per periodic task run. Must be at least 1. Default is 20.
internal_tx_conflict_repull_frequency (int) – The frequency in seconds at which internal transaction conflicts are re-pulled. Must be at least 30. Default is 3600 (every hour).
- 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
-1which will then set the taxfree_after_period tonullwhich means there is no taxfree period.balance_save_frequency (int[optional]) – The number of hours after which user balances should be saved in the DB again. This is useful for the statistics kept in the DB for each user. Default is 24 hours. Can’t be less than 1 hour.
include_gas_costs (bool[optional]) – A boolean denoting whether gas costs should be counted as loss in profit/loss calculation.
ksm_rpc_endpoint (string[optional]) – A URL denoting the rpc endpoint for the Kusama node to use when contacting the Kusama blockchain. If it can not be reached or if it is invalid any default public node (e.g. Parity) is used instead.
dot_rpc_endpoint (string[optional]) – A URL denoting the rpc endpoint for the Polkadot node to use when contacting the Polkadot blockchain. If it can not be reached or if it is invalid any default public node (e.g. Parity) is used instead.
beacon_rpc_endpoint (string[optional]) – A URL denoting the rpc endpoint for the ethereum consensus layer beacon node to use when contacting the consensus layer. If it can not be reached or if it is invalid beaconcha.in is used.
main_currency (string[optional]) – The FIAT currency to use for all profit/loss calculation. USD by default.
date_display_format (string[optional]) – The format in which to display dates in the UI. Default is
"%d/%m/%Y %H:%M:%S %Z".submit_usage_analytics (bool[optional]) – A boolean denoting whether or not to submit anonymous usage analytics to the rotki server.
active_module (list) – A list of strings denoting the active modules with which rotki should run.
current_price_oracles (list) – A list of strings denoting the price oracles rotki should query in specific order for requesting current prices.
historical_price_oracles (list) – A list of strings denoting the price oracles rotki should query in specific order for requesting historical prices.
evm_indexers_order (object[optional]) – Mapping of EVM chain names to the ordered list of indexers to query per chain. Each list must contain the available indexers without duplicates.
non_syncing_exchanges (list) – A list of objects with the keys
nameandlocationof the exchange. These exchanges will be ignored when querying the trades. Example:[{"name": "my_exchange", "location": "binance"}].internal_txs_to_repull (int[optional]) – The number of internal transaction conflicts to repull per periodic task run. Must be at least 1. Default is 20.
internal_tx_conflict_repull_frequency (int[optional]) – The frequency in seconds at which internal transaction conflicts are re-pulled. Must be at least 30. Default is 3600 (every hour).
- Response JSON Object:
default_evm_indexer_order (list[optional]) – Default order to use for chains where no specific indexer order has been given.
ssf_graph_multiplier (int) – A multiplier to the snapshot saving frequency for zero amount graphs. Originally 0 by default. If set it denotes the multiplier of the snapshot saving frequency at which to insert 0 save balances for a graph between two saved values.
infer_zero_timed_balances (bool) – A boolean denoting whether to infer zero timed balances for assets that have no balance at a specific time. This is useful for showing zero balance periods in graphs.
query_retry_limit (int) – The number of times to retry a query to external services before giving up. Default is 5.
connect_timeout (int) – The number of seconds to wait before giving up on establishing a connection to an external service. Default is 30.
read_timeout (int) – The number of seconds to wait for the first byte after a connection to an external service has been established. Default is 30.
oracle_penalty_threshold_count (int) – The number of failures after which an oracle is penalized. Default is 5.
oracle_penalty_duration (int) – The duration in seconds for which an oracle is penalized. Default is 1800.
auto_delete_calendar_entries (bool[optional]) – A boolean denoting whether calendar entries are automatically deleted when related blockchain accounts are removed.
auto_create_calendar_reminders (bool[optional]) – A boolean denoting whether reminders are created automatically for calendar entries based on the decoded history events.
ask_user_upon_size_discrepancy (bool[optional]) – A boolean denoting whether to prompt the user for confirmation each time the remote database is bigger than the local one or directly force push.
auto_detect_tokens (bool[optional]) – A boolean denoting whether to automatically detect and add tokens for EVM addresses.
csv_export_delimiter (string[optional]) – The delimiter character to use when exporting data to CSV files.
asset_movement_amount_tolerance (string[optional]) – The tolerance value used when matching asset movement amounts with onchain events. Must be a positive decimal number.
asset_movement_time_range (int[optional]) – The time range before/after the asset movement (depending on if its a deposit/withdrawal) in which to check for possible matching events. Default is 54000 (15 hours). Note: there is also a 1 hour tolerance on the other side of the asset movement, since some exchanges do not provide accurate timestamps.
suppress_missing_key_msg_services (list[optional]) – A list of services for which the missing api key WS message should be suppressed. Empty list by default.
auto_create_profit_events (bool[optional]) – A boolean denoting whether profit history events are automatically created when protocol withdrawal events exceed deposits during historical balances processing.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "have_premium": false, "version": "6", "last_write_ts": 1571552172, "premium_should_sync": true, "include_crypto2crypto": true, "last_data_upload_ts": 1571552172, "ui_floating_precision": 4, "taxfree_after_period": 31536000, "balance_save_frequency": 24, "include_gas_costs": false, "ksm_rpc_endpoint": "http://localhost:9933", "main_currency": "USD", "date_display_format": "%d/%m/%Y %H:%M:%S %Z", "last_balance_save": 1571552172, "submit_usage_analytics": true, "active_modules": ["makerdao_dsr", "makerdao_vaults", "aave"], "current_price_oracles": ["cryptocompare"], "historical_price_oracles": ["coingecko", "cryptocompare"], "ssf_graph_multiplier": 2, "non_sync_exchanges": [{"location": "binance", "name": "binance1"}], "auto_delete_calendar_entries": true, "auto_create_calendar_reminders": true, "ask_user_upon_size_discrepancy": true, "auto_detect_tokens": true, "csv_export_delimiter": ",", "asset_movement_amount_tolerance": "0.000001", "asset_movement_time_range": 54000, "suppress_missing_key_msg_services": ["etherscan"], "auto_create_profit_events": false, "internal_txs_to_repull": 20, "internal_tx_conflict_repull_frequency": 3600 }, "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.
401 Unauthorized – No user is logged in.
409 Conflict – Tried to set eth rpc endpoint that could not be reached.
500 Internal Server Error – Internal rotki error
Getting or modifying 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 }, "loglevel": { "value": "DEBUG", "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.
loglevel (object) – The current logging level of the backend.
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
- PUT /api/(version)/settings/configuration
By doing a PUT, you can modify the backend log level at runtime. Currently, only the
loglevelparameter is supported for modification.Example Request:
http
PUT /api/1/settings/configuration HTTP/1.1 Host: localhost:5042 Content-Type: application/json { "loglevel": "TRACE" }
curl
curl -i -X PUT http://localhost:5042/api/1/settings/configuration -H "Content-Type: application/json" --data-raw '{"loglevel": "TRACE"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/settings/configuration --header="Content-Type: application/json" --body-data='{"loglevel": "TRACE"}'
httpie
echo '{ "loglevel": "TRACE" }' | http PUT http://localhost:5042/api/1/settings/configuration Content-Type:application/json
python-requests
requests.put('http://localhost:5042/api/1/settings/configuration', headers={'Content-Type': 'application/json'}, json={'loglevel': 'TRACE'})
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 }, "loglevel": { "value": "TRACE", "is_default": false } }, "message": "" }
- Request JSON Object:
loglevel (string) – The logging level to set. Must be one of:
TRACE,DEBUG,INFO,WARNING,ERROR,CRITICAL.
- Status Codes:
200 OK – Backend configuration was successfully updated
400 Bad Request – Provided loglevel is not supported
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/nodespython-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", "is_archive": true }, { "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", "is_archive": false } ], "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.
is_archive (bool) – [Optional] Only present for RPC nodes that are currently connected. Not applicable to indexers (e.g., etherscan). True if the node is an archive node, false otherwise.
- 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 entry 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 entry 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
DELETE /api/1/blockchains/eth/nodes HTTP/1.1 Host: localhost:5042 Content-Type: application/json { "identifier": 8 }
curl
curl -i -X DELETE http://localhost:5042/api/1/blockchains/eth/nodes -H "Content-Type: application/json" --data-raw '{"identifier": 8}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/blockchains/eth/nodes --header="Content-Type: application/json" --body-data='{"identifier": 8}'
httpie
echo '{ "identifier": 8 }' | http DELETE http://localhost:5042/api/1/blockchains/eth/nodes Content-Type:application/json
python-requests
requests.delete('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
- POST /api/(version)/blockchains/(blockchain)/nodes
By doing a POST on this endpoint the app will try to connect to the provided node. If no node is provided then the app will try to connect to all the nodes tracked for the chain.
Example Request:
http
POST /api/1/blockchains/eth/nodes HTTP/1.1 Host: localhost:5042 Content-Type: application/json { "identifier": 8 }
curl
curl -i -X POST http://localhost:5042/api/1/blockchains/eth/nodes -H "Content-Type: application/json" --data-raw '{"identifier": 8}'
wget
wget -S -O- http://localhost:5042/api/1/blockchains/eth/nodes --header="Content-Type: application/json" --post-data='{"identifier": 8}'
httpie
echo '{ "identifier": 8 }' | http POST http://localhost:5042/api/1/blockchains/eth/nodes Content-Type:application/json
python-requests
requests.post('http://localhost:5042/api/1/blockchains/eth/nodes', headers={'Content-Type': 'application/json'}, json={'identifier': 8})
- Response JSON Object:
identifier[optional] (int) – Id of the node that will be connected.
Example Response:
The following is an example response of querying Ethereum nodes information.
HTTP/1.1 200 OK Content-Type: application/json { "result": { errors: [{ "name": "Cloudflare", "error": "Example error" }] }, }, "message": "" }
- resjson list errors:
A list with information about the web3 nodes that couldn’t be connected. Empty if all the nodes were connected.
- resjson string name:
Name of the node.
- resjson string error:
Reason why the node wasn’t connected.
- Status Codes:
200 OK – Connection logic executed.
400 Bad Request – Wrong blockchain provided.
409 Conflict – No user is logged or failed because the blockchain is not valid or the node identifier 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/taskspython-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/42python-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", "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
401 Unauthorized – No user is currently logged in
404 Not Found – There is no task with the given task id
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Problem contacting a remote service
Cancel ongoing async tasks
- DELETE /api/(version)/tasks/(task_id)
By calling this endpoint with a particular task identifier you can cancel the ongoing task with that identifier. Keep in mind that this may leave stuff half-finished since the canceled task may be stopped in the middle.
Example Request:
http
DELETE /api/1/tasks/42 HTTP/1.1 Host: localhost:5042curl
curl -i -X DELETE http://localhost:5042/api/1/tasks/42wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/tasks/42httpie
http DELETE http://localhost:5042/api/1/tasks/42python-requests
requests.delete('http://localhost:5042/api/1/tasks/42')Example Response:
The following is an example response of a successfully canceled task
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – True if the task was canceled and false otherwise.
- Status Codes:
200 OK – The task was successfully canceled.
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is currently logged in
404 Not Found – There is no task with the given task id.
500 Internal Server Error – Internal rotki error
Trigger an async task
- POST /api/(version)/tasks/trigger
Triggers an async task. This endpoint bypasses the normal background task scheduling and runs the task immediately.
Note
This endpoint can be queried asynchronously by using
"async_query": true.Example Request:
http
POST /api/(version)/tasks/trigger HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"task": "historical_balance_processing"}
curl
curl -i -X POST 'http://localhost:5042/api/(version)/tasks/trigger' -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"task": "historical_balance_processing"}'
wget
wget -S -O- 'http://localhost:5042/api/(version)/tasks/trigger' --header="Content-Type: application/json;charset=UTF-8" --post-data='{"task": "historical_balance_processing"}'
httpie
echo '{ "task": "historical_balance_processing" }' | http POST 'http://localhost:5042/api/(version)/tasks/trigger' Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/(version)/tasks/trigger', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'task': 'historical_balance_processing'})
- reqjson str task:
Name of the task to run. Valid values are
historical_balance_processingandasset_movement_matching.asset_movement_matchingrequires the premium capabilityasset_movement_matching.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "message": "", "result": true, "status_code": 200 }
- resjson bool result:
True on success
- statuscode 200:
Task started successfully
- statuscode 401:
User is not logged in
- statuscode 403:
Task is not available for the current premium tier
- statuscode 500:
Internal Rotki error
Enable or disable the periodic task scheduler
- PUT /api/(version)/tasks/scheduler
Enables or disables the periodic task scheduler. This should be called by the frontend once initial data loading is complete (transaction decoding, balances fetch, asset movement matching, historical balance processing). This ensures background tasks that require exclusive database write access (like backup sync) don’t run during DB upgrades, migrations, and asset updates.
Example Request:
http
PUT /api/(version)/tasks/scheduler HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"enabled": true}
curl
curl -i -X PUT 'http://localhost:5042/api/(version)/tasks/scheduler' -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"enabled": true}'
wget
wget -S -O- --method=PUT 'http://localhost:5042/api/(version)/tasks/scheduler' --header="Content-Type: application/json;charset=UTF-8" --body-data='{"enabled": true}'
httpie
echo '{ "enabled": true }' | http PUT 'http://localhost:5042/api/(version)/tasks/scheduler' Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/(version)/tasks/scheduler', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'enabled': True})
- reqjson bool enabled:
Whether to enable (true) or disable (false) the scheduler.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "message": "", "result": { "enabled": true }, "status_code": 200 }
- resjson object result:
Object containing the new scheduler state
- statuscode 200:
Operation completed successfully
- statuscode 401:
User is not logged in
- statuscode 500:
Internal Rotki error
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", "price": "2505.13" }, { "asset": "nft_uniqueid2", "manually_input": false, "price_asset": "USD", "price_in_asset": "155.13", "price": "155.13" }] "message": "" }
- Response JSON Object:
result (object) – A list of results of assets along with their prices in the user’s preferred currency.
- 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
401 Unauthorized – 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,GBPNote
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. Timestamps for which no price is found will be omitted from the response. If
only_cache_periodis provided, the endpoint will only return prices found in cache within the specified time period around each timestamp. This is useful for scenarios requiring immediate responses, such as graph rendering.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
only_cache_period (integer) – (Optional) Time period in seconds around each timestamp to search for cached prices. If omitted, falls back to querying historical prices
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
Adds the price of an asset against another asset at a certain timestamp to the database. If a historical price for the specified asset pair, timestamp and
source_typealready 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", "source_type": "coingecko" }
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", "source_type": "coingecko", "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", "source_type": "coingecko", "timestamp": 1611166335, "to_asset": "USD"}'
httpie
echo '{ "from_asset": "eip155:1/erc20:0xD71eCFF9342A5Ced620049e616c5035F1dB98620", "price": "1.20", "source_type": "coingecko", "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', 'source_type': 'coingecko', '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.
source_type (string) – Required. Historical price source/oracle. Common values include
manual,coingecko,cryptocompare,fiat,defillama,uniswapv2,uniswapv3andalchemy.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (object) – true if the historical 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 a previously stored historical price entry if it already exists in the database for the provided asset pair, timestamp and
source_type. Returns false if no entry was updated.Example Request:
http
PATCH /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", "source_type": "coingecko" }
curl
curl -i -X PATCH 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", "source_type": "coingecko", "timestamp": 1611166335, "to_asset": "USD"}'
wget
wget -S -O- --method=PATCH 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", "source_type": "coingecko", "timestamp": 1611166335, "to_asset": "USD"}'
httpie
echo '{ "from_asset": "eip155:1/erc20:0xD71eCFF9342A5Ced620049e616c5035F1dB98620", "price": "1.20", "source_type": "coingecko", "timestamp": 1611166335, "to_asset": "USD" }' | http PATCH http://localhost:5042/api/1/assets/prices/historical Content-Type:"application/json;charset=UTF-8"
python-requests
requests.patch('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', 'source_type': 'coingecko', '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.
source_type (string) – Required. Historical price source/oracle.
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 a historical price of an asset against another asset at a certain timestamp from the database for the provided
source_type.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, "source_type": "coingecko" }
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", "source_type": "coingecko", "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", "source_type": "coingecko", "timestamp": 1611166335, "to_asset": "USD"}'
httpie
echo '{ "from_asset": "eip155:1/erc20:0xD71eCFF9342A5Ced620049e616c5035F1dB98620", "source_type": "coingecko", "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', 'source_type': 'coingecko', '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.
source_type (string) – Required. Historical price source/oracle.
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/exchangespython-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": "okx", "name": "okx1", "okx_location": "global"}, {"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
401 Unauthorized – 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 for the exchange. Required for all exchanges except Bitpanda, which only uses API key.
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
401 Unauthorized – No user is logged in
409 Conflict – 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
401 Unauthorized – No user is logged in.
409 Conflict – 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", "okx_location": "eea"}
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", "okx_location": "eea", "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", "okx_location": "eea", "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", "okx_location": "eea", "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', 'okx_location': 'eea', '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”.
okx_location (string) – Optional. An optional setting for okx. The location of the user’s account, needed to route to specific subdomain API. Valid values are “global”, “eea” and “usd”.
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
401 Unauthorized – No user is logged in.
409 Conflict – 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. If a USD value threshold is provided, only balances with USD value greater than the threshold are 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_TIMEthe cached value will be returned. If you want to skip the cache add theignore_cache: trueargument. Can also be passed as a query argument.Example Request:
http
GET /api/1/exchanges/balances/binance?value_threshold=1000 HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET 'http://localhost:5042/api/1/exchanges/balances/binance?value_threshold=1000'
wget
wget -S -O- 'http://localhost:5042/api/1/exchanges/balances/binance?value_threshold=1000'
httpie
http 'http://localhost:5042/api/1/exchanges/balances/binance?value_threshold=1000'
python-requests
requests.get('http://localhost:5042/api/1/exchanges/balances/binance?value_threshold=1000')
- 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.
- Query Parameters:
value_threshold (decimal) – Optional. If provided, only returns balances with value greater than this threshold. This is in the user’s preferred currency.
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
401 Unauthorized – User is not logged in.
409 Conflict – 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. If a value threshold is provided, only balances with value greater than the threshold are returned.
Note
This endpoint can also be queried asynchronously by using
"async_query": trueExample Request:
http
GET /api/1/exchanges/balances?value_threshold=1000 HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET 'http://localhost:5042/api/1/exchanges/balances?value_threshold=1000'
wget
wget -S -O- 'http://localhost:5042/api/1/exchanges/balances?value_threshold=1000'
httpie
http 'http://localhost:5042/api/1/exchanges/balances?value_threshold=1000'
python-requests
requests.get('http://localhost:5042/api/1/exchanges/balances?value_threshold=1000')
- 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
- Query Parameters:
value_threshold (decimal) – Optional. If provided, only returns balances with value greater than this threshold. This is in the user’s preferred currency.
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
401 Unauthorized – User is not logged in.
409 Conflict – 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
401 Unauthorized – User is not logged in.
409 Conflict – Exchange is not registered or some other error. Check error message for details.
500 Internal Server Error – Internal rotki error
Managing blockchain transactions
- DELETE /api/(version)/blockchains/transactions
Doing a DELETE on the blockchain transactions endpoint will delete locally saved transaction data. If nothing is given all transaction data will be deleted. Can specify the chain to only delete all transactions of that chain. Or even further chain and tx_hash to delete only a specific transaction’s data (although this is only supported for EVM and EVM-like chains). If chain is Bitcoin or Bitcoin Cash, the cached last queried block will also be deleted to allow all txs to be requeried.
Example Request:
http
DELETE /api/1/blockchains/transactions HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"chain": "eth", "tx_ref": "0x6826b8646578ff457ba01bfe6a2cc77e3d6e40a849e45a97ca12dfd9150cd901"}
curl
curl -i -X DELETE http://localhost:5042/api/1/blockchains/transactions -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"chain": "eth", "tx_ref": "0x6826b8646578ff457ba01bfe6a2cc77e3d6e40a849e45a97ca12dfd9150cd901"}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/blockchains/transactions --header="Content-Type: application/json;charset=UTF-8" --body-data='{"chain": "eth", "tx_ref": "0x6826b8646578ff457ba01bfe6a2cc77e3d6e40a849e45a97ca12dfd9150cd901"}'
httpie
echo '{ "chain": "eth", "tx_ref": "0x6826b8646578ff457ba01bfe6a2cc77e3d6e40a849e45a97ca12dfd9150cd901" }' | http DELETE http://localhost:5042/api/1/blockchains/transactions Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/1/blockchains/transactions', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'chain': 'eth', 'tx_ref': '0x6826b8646578ff457ba01bfe6a2cc77e3d6e40a849e45a97ca12dfd9150cd901'})
- Request JSON Object:
chain (string) – Optional. The name of the chain for which to delete transaction.
"eth","optimism","zksync_lite"etc. If not given all transactions for all chains are purged. This is using the backend’s SupportedBlockchain with the limitation being only chains for which we save transactions.tx_ref (string) – Optional. The transaction to delete. If given only the specific transaction is deleted. This should always be given in combination with the chain argument.
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
401 Unauthorized – User is not logged.
409 Conflict – Other error. Check error message for details.
500 Internal Server Error – Internal rotki error
- PUT /api/(version)/blockchains/transactions
Doing a PUT on this endpoint will add a transaction to the database and associate it with the provided address. Supports EVM chains and Solana.
Note
This endpoint can also be queried asynchronously by using
"async_query": true.Example Request (EVM):
http
PUT /api/1/blockchains/transactions HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "blockchain": "ethereum", "tx_ref": "0x65d53653c584cde22e559cec4667a7278f75966360590b725d87055fb17552ba", "associated_address": "0xb8553D9ee35dd23BB96fbd679E651B929821969B", "async_query": true }
curl
curl -i -X PUT http://localhost:5042/api/1/blockchains/transactions -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"associated_address": "0xb8553D9ee35dd23BB96fbd679E651B929821969B", "async_query": true, "blockchain": "ethereum", "tx_ref": "0x65d53653c584cde22e559cec4667a7278f75966360590b725d87055fb17552ba"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/blockchains/transactions --header="Content-Type: application/json;charset=UTF-8" --body-data='{"associated_address": "0xb8553D9ee35dd23BB96fbd679E651B929821969B", "async_query": true, "blockchain": "ethereum", "tx_ref": "0x65d53653c584cde22e559cec4667a7278f75966360590b725d87055fb17552ba"}'
httpie
echo '{ "associated_address": "0xb8553D9ee35dd23BB96fbd679E651B929821969B", "async_query": true, "blockchain": "ethereum", "tx_ref": "0x65d53653c584cde22e559cec4667a7278f75966360590b725d87055fb17552ba" }' | http PUT http://localhost:5042/api/1/blockchains/transactions Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/blockchains/transactions', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'associated_address': '0xb8553D9ee35dd23BB96fbd679E651B929821969B', 'async_query': True, 'blockchain': 'ethereum', 'tx_ref': '0x65d53653c584cde22e559cec4667a7278f75966360590b725d87055fb17552ba'})
Example Request (Solana):
http
PUT /api/1/blockchains/transactions HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "blockchain": "solana", "tx_ref": "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW", "associated_address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", "async_query": true }
curl
curl -i -X PUT http://localhost:5042/api/1/blockchains/transactions -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"associated_address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", "async_query": true, "blockchain": "solana", "tx_ref": "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/blockchains/transactions --header="Content-Type: application/json;charset=UTF-8" --body-data='{"associated_address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", "async_query": true, "blockchain": "solana", "tx_ref": "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW"}'
httpie
echo '{ "associated_address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", "async_query": true, "blockchain": "solana", "tx_ref": "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW" }' | http PUT http://localhost:5042/api/1/blockchains/transactions Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/blockchains/transactions', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'associated_address': '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM', 'async_query': True, 'blockchain': 'solana', 'tx_ref': '5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW'})
- Request JSON Object:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not.
blockchain (str) – The blockchain name for the transaction to be added (e.g.
"ethereum","optimism","solana").tx_ref (str) – The transaction reference (hash for EVM chains, signature for Solana) to be added.
associated_address (str) – The address to be associated with the transaction. The address must be one that is already tracked by rotki.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true "message": "" }
- Response JSON Object:
result (bool) – It contains a boolean representing the status of the request.
- Status Codes:
200 OK – The transaction was saved successfully.
400 Bad Request – Provided JSON is in some way malformed. Transaction is already present in DB. Address provided is not tracked by rotki.
404 Not Found – Transaction reference not found for the specified blockchain.
401 Unauthorized – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
502 Bad Gateway – An external service used in the query such as etherscan could not be reached or returned unexpected response.
- GET /api/(version)/blockchains/evm/transactions/lookup
Doing a GET on this endpoint will look up metadata for an EVM transaction. If the transaction and its receipt are already present in the database, the saved data is returned. Otherwise rotki will query the chain, validate that the transaction exists, save the transaction and receipt data, and return the metadata.
This is useful for forms that accept an EVM transaction hash and need to auto-populate transaction-derived fields such as the timestamp.
Note
This endpoint can also be queried asynchronously by using
"async_query": true.Example Request:
http
GET /api/1/blockchains/evm/transactions/lookup HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "async_query": false, "tx_hash": "0x65d53653c584cde22e559cec4667a7278f75966360590b725d87055fb17552ba", "evm_chain": "ethereum", "related_address": "0xb8553D9ee35dd23BB96fbd679E651B929821969B" }
curl
curl -i -X GET http://localhost:5042/api/1/blockchains/evm/transactions/lookup -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": false, "evm_chain": "ethereum", "related_address": "0xb8553D9ee35dd23BB96fbd679E651B929821969B", "tx_hash": "0x65d53653c584cde22e559cec4667a7278f75966360590b725d87055fb17552ba"}'
wget
wget -S -O- http://localhost:5042/api/1/blockchains/evm/transactions/lookup --header="Content-Type: application/json;charset=UTF-8" --body-data='{"async_query": false, "evm_chain": "ethereum", "related_address": "0xb8553D9ee35dd23BB96fbd679E651B929821969B", "tx_hash": "0x65d53653c584cde22e559cec4667a7278f75966360590b725d87055fb17552ba"}'
httpie
echo '{ "async_query": false, "evm_chain": "ethereum", "related_address": "0xb8553D9ee35dd23BB96fbd679E651B929821969B", "tx_hash": "0x65d53653c584cde22e559cec4667a7278f75966360590b725d87055fb17552ba" }' | http http://localhost:5042/api/1/blockchains/evm/transactions/lookup Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/blockchains/evm/transactions/lookup', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': False, 'evm_chain': 'ethereum', 'related_address': '0xb8553D9ee35dd23BB96fbd679E651B929821969B', 'tx_hash': '0x65d53653c584cde22e559cec4667a7278f75966360590b725d87055fb17552ba'})
- Request JSON Object:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not.
tx_hash (str) – The EVM transaction hash to look up.
evm_chain (str) – The EVM chain name for the transaction, e.g.
"ethereum","optimism"or"base".related_address (str) – A tracked address on the requested EVM chain to relate to the transaction when it needs to be fetched and saved.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "tx_hash": "0x65d53653c584cde22e559cec4667a7278f75966360590b725d87055fb17552ba", "evm_chain": "ethereum", "timestamp": 1713350400, "block_number": 19680000, "from_address": "0xb8553D9ee35dd23BB96fbd679E651B929821969B", "to_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "value": "0", "gas": "21000", "gas_price": "1000000000", "gas_used": "21000", "nonce": 7, "was_fetched": true }, "message": "" }
- Response JSON Object:
result (object) – The transaction metadata.
result.tx_hash (string) – The transaction hash.
result.evm_chain (string) – The EVM chain name.
result.timestamp (int) – The transaction timestamp in seconds.
result.block_number (int) – The block number containing the transaction.
result.from_address (string) – The transaction sender.
result.to_address (string) – The transaction recipient. Can be null for contract creation transactions.
result.value (string) – The native token value transferred, in wei.
result.gas (string) – The transaction gas limit.
result.gas_price (string) – The transaction gas price.
result.gas_used (string) – The gas used by the transaction.
result.nonce (int) – The sender nonce.
result.was_fetched (bool) – True if rotki had to query and save the transaction before returning it. False if transaction and receipt data were already present in the database.
- Status Codes:
200 OK – Transaction metadata was returned successfully.
400 Bad Request – Provided JSON is in some way malformed, the transaction hash/chain is invalid, or
related_addressis not tracked on the requested chain.401 Unauthorized – No user is currently logged in.
404 Not Found – The transaction does not exist on the requested chain.
409 Conflict – Temporary external service/node error. The request can be retried.
500 Internal Server Error – Internal rotki error.
502 Bad Gateway – The transaction data could not be deserialized or an external service/node returned an unexpected response.
- POST /api/(version)/blockchains/transactions
Doing a POST on the blockchain transactions endpoint will refresh/query blockchain transactions for the specified accounts within the given time range.
Note
This endpoint can also be queried asynchronously by using
"async_query": true.Example Request:
http
POST /api/1/blockchains/transactions HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "async_query": true, "from_timestamp": 1451606400, "to_timestamp": 1571663098, "accounts": [ {"address": "0x9531C059098e3d194fF87FebB587aB07B30B1306", "blockchain": "eth"}, {"address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "blockchain": "optimism"}, {"address": "DYH6x4JoTXUUc4GJUcBYv4gPRApbfTsoZEeD318ernQY", "blockchain": "solana"} ] }
curl
curl -i -X POST http://localhost:5042/api/1/blockchains/transactions -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"accounts": [{"address": "0x9531C059098e3d194fF87FebB587aB07B30B1306", "blockchain": "eth"}, {"address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "blockchain": "optimism"}, {"address": "DYH6x4JoTXUUc4GJUcBYv4gPRApbfTsoZEeD318ernQY", "blockchain": "solana"}], "async_query": true, "from_timestamp": 1451606400, "to_timestamp": 1571663098}'
wget
wget -S -O- http://localhost:5042/api/1/blockchains/transactions --header="Content-Type: application/json;charset=UTF-8" --post-data='{"accounts": [{"address": "0x9531C059098e3d194fF87FebB587aB07B30B1306", "blockchain": "eth"}, {"address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "blockchain": "optimism"}, {"address": "DYH6x4JoTXUUc4GJUcBYv4gPRApbfTsoZEeD318ernQY", "blockchain": "solana"}], "async_query": true, "from_timestamp": 1451606400, "to_timestamp": 1571663098}'
httpie
echo '{ "accounts": [ { "address": "0x9531C059098e3d194fF87FebB587aB07B30B1306", "blockchain": "eth" }, { "address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "blockchain": "optimism" }, { "address": "DYH6x4JoTXUUc4GJUcBYv4gPRApbfTsoZEeD318ernQY", "blockchain": "solana" } ], "async_query": true, "from_timestamp": 1451606400, "to_timestamp": 1571663098 }' | http POST http://localhost:5042/api/1/blockchains/transactions Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/blockchains/transactions', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'accounts': [{'address': '0x9531C059098e3d194fF87FebB587aB07B30B1306', 'blockchain': 'eth'}, {'address': '0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12', 'blockchain': 'optimism'}, {'address': 'DYH6x4JoTXUUc4GJUcBYv4gPRApbfTsoZEeD318ernQY', 'blockchain': 'solana'}], 'async_query': True, 'from_timestamp': 1451606400, 'to_timestamp': 1571663098})
- Request JSON Object:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not.
from_timestamp (int) – The timestamp from which to start querying transactions. Given in unix time.
to_timestamp (int) – The timestamp until which to query transactions. Given in unix time.
accounts (list[object]) – Optional. A list of blockchain account objects. If not provided, transactions for all tracked accounts will be refreshed.
- Request JSON Array of Objects:
address (string) – The address of the account.
blockchain (string) – The blockchain of the account (e.g.,
"eth","optimism","polygon_pos","solana").
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – Boolean indicating whether the transaction refresh was successful.
- Status Codes:
200 OK – Transactions were successfully refreshed.
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is currently logged in.
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.
Decode transactions that haven’t been decoded yet
- POST /api/(version)/blockchains/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. Transactions already decoded won’t be re-decoded unless ignore_cache is set to true.
Note
This endpoint can also be queried asynchronously by using
"async_query": trueExample Request:
http
POST /api/1/blockchains/transactions/decode HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "async_query": false, "ignore_cache": false, "chain": "eth" }
curl
curl -i -X POST http://localhost:5042/api/1/blockchains/transactions/decode -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": false, "chain": "eth", "ignore_cache": false}'
wget
wget -S -O- http://localhost:5042/api/1/blockchains/transactions/decode --header="Content-Type: application/json;charset=UTF-8" --post-data='{"async_query": false, "chain": "eth", "ignore_cache": false}'
httpie
echo '{ "async_query": false, "chain": "eth", "ignore_cache": false }' | http POST http://localhost:5042/api/1/blockchains/transactions/decode Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/blockchains/transactions/decode', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': False, 'chain': 'eth', 'ignore_cache': False})
- Request JSON Object:
ignore_cache (bool) – Defaults to false. If set to true then all events will be redecoded, not only those that have not yet been decoded.
chain (string) – The name of the chain for which to decode transactions. The possible values are limited to the chains for which we support transaction decoding (solana, zksync lite, and all supported EVM chains except for avalanche).
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": {"decoded_tx_number": 4}, "message": "" }
- Response JSON Object:
decoded_tx_number (int) – Number of transactions that were decoded.
- Status Codes:
200 OK – Transactions successfully decoded.
401 Unauthorized – User is not logged in.
409 Conflict – Some other error. Check error message for details.
500 Internal Server Error – Internal rotki error
- PUT /api/(version)/blockchains/transactions/decode
Doing a PUT on the transactions decoding endpoint will request deleting and re-querying of all the transaction data and decoding events for the specified transactions.
Note
This endpoint can also be queried asynchronously by using
"async_query": trueExample Request:
http
PUT /api/1/blockchains/transactions/decode HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "async_query": true, "chain": "eth", "tx_refs": [ "0xe33041d0ae336cd4c588a313b7f8649db07b79c5107424352b9e52a6ea7a9742", "0xe11031d0ae336cd4c588a313b7f8649db07b79c5107424352b9e52a6ea7a9712" ], "delete_custom": true }
curl
curl -i -X PUT http://localhost:5042/api/1/blockchains/transactions/decode -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": true, "chain": "eth", "delete_custom": true, "tx_refs": ["0xe33041d0ae336cd4c588a313b7f8649db07b79c5107424352b9e52a6ea7a9742", "0xe11031d0ae336cd4c588a313b7f8649db07b79c5107424352b9e52a6ea7a9712"]}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/blockchains/transactions/decode --header="Content-Type: application/json;charset=UTF-8" --body-data='{"async_query": true, "chain": "eth", "delete_custom": true, "tx_refs": ["0xe33041d0ae336cd4c588a313b7f8649db07b79c5107424352b9e52a6ea7a9742", "0xe11031d0ae336cd4c588a313b7f8649db07b79c5107424352b9e52a6ea7a9712"]}'
httpie
echo '{ "async_query": true, "chain": "eth", "delete_custom": true, "tx_refs": [ "0xe33041d0ae336cd4c588a313b7f8649db07b79c5107424352b9e52a6ea7a9742", "0xe11031d0ae336cd4c588a313b7f8649db07b79c5107424352b9e52a6ea7a9712" ] }' | http PUT http://localhost:5042/api/1/blockchains/transactions/decode Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/blockchains/transactions/decode', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': True, 'chain': 'eth', 'delete_custom': True, 'tx_refs': ['0xe33041d0ae336cd4c588a313b7f8649db07b79c5107424352b9e52a6ea7a9742', '0xe11031d0ae336cd4c588a313b7f8649db07b79c5107424352b9e52a6ea7a9712']})
- Request JSON Object:
chain (string) – The name of the chain for which to decode transactions.
tx_refs (list) – A list of transaction hashes/signatures from the specified chain to redecode.
delete_custom (bool) – Boolean denoting whether to delete any customized events of the transaction or not. Default is false
custom_indexers_order (list[string][optional]) – Optional ordered list of indexers (
etherscan,blockscoutorroutescan) to prioritize when redecoding EVM transactions for the given request.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": "" }
- Status Codes:
200 OK – Transaction successfully repulled and decoded.
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – The given transaction references do not correspond to an onchain transaction according to the nodes we contacted.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Problem contacting a remote service
- GET /api/(version)/blockchains/transactions/decode
Doing a GET on the transactions decoding endpoint will return a breakdown of the number of transactions that are not decoded.
Note
This endpoint can also be queried asynchronously by using
"async_query": trueExample Request:
http
GET /api/1/blockchains/transactions/decode HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"async_query": false}
curl
curl -i -X GET http://localhost:5042/api/1/blockchains/transactions/decode -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": false}'
wget
wget -S -O- http://localhost:5042/api/1/blockchains/transactions/decode --header="Content-Type: application/json;charset=UTF-8" --body-data='{"async_query": false}'
httpie
echo '{ "async_query": false }' | http http://localhost:5042/api/1/blockchains/transactions/decode Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/blockchains/transactions/decode', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': False})
Example Response:
HTTP/1.1 200 OK Content-Type: application/json {"result": {"ethereum": {"undecoded": 1, "total": 2}, "optimism": {"undecoded": 1, "total": 1}, "base": {"undecoded": 1, "total": 1}}, "message": "" }
- Response JSON Object:
result (object) – A mapping of the chain name to the number of transactions missing the decoding and the total number of transactions. If a chain doesn’t have undecoded transactions it doesn’t appear on the mapping.
- Status Codes:
200 OK – Transactions successfully counted.
401 Unauthorized – User is not logged in.
409 Conflict – Other error. Check error message for details.
500 Internal Server Error – Internal rotki error
- GET /api/(version)/blockchains/transactions/internal/conflicts
Doing a GET on the internal transaction conflicts endpoint returns unresolved EVM transactions that require action due to detected internal transaction conflicts.
Example Request:
http
GET /api/1/blockchains/transactions/internal/conflicts HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"async_query": false, "fixed": false, "failed": false, "limit": 50, "offset": 0}
curl
curl -i -X GET http://localhost:5042/api/1/blockchains/transactions/internal/conflicts -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": false, "failed": false, "fixed": false, "limit": 50, "offset": 0}'
wget
wget -S -O- http://localhost:5042/api/1/blockchains/transactions/internal/conflicts --header="Content-Type: application/json;charset=UTF-8" --body-data='{"async_query": false, "failed": false, "fixed": false, "limit": 50, "offset": 0}'
httpie
echo '{ "async_query": false, "failed": false, "fixed": false, "limit": 50, "offset": 0 }' | http http://localhost:5042/api/1/blockchains/transactions/internal/conflicts Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/blockchains/transactions/internal/conflicts', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': False, 'failed': False, 'fixed': False, 'limit': 50, 'offset': 0})
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "entries": [ { "chain": "ethereum", "tx_hash": "0xe33041d0ae336cd4c588a313b7f8649db07b79c5107424352b9e52a6ea7a9742", "timestamp": 1700000000, "action": "repull", "repull_reason": "all_zero_gas", "group_identifier": "0xe33041d0ae336cd4c588a313b7f8649db07b79c5107424352b9e52a6ea7a9742", "last_retry_ts": 1700000000, "last_error": "rpc timeout" } ], "entries_found": 1, "entries_total": 3, "entries_limit": 50 }, "message": "" }
- Response JSON Object:
result.entries (list[object]) – The list of unresolved internal transaction conflicts that need action.
result.entries.chain (string) – Chain name.
result.entries.tx_hash (string) – Transaction hash in hex format.
result.entries.timestamp (int) – Unix timestamp of the transaction, or
nullif the transaction is not found in the local database.result.entries.action (string) – Required action. Either
repullorfix_redecode.result.entries.repull_reason (string) – Reason for repull. Values are
all_zero_gasandother.nullforfix_redecoderows.result.entries.redecode_reason (string) – Reason for redecode. Values are
mixed_zero_gas,duplicate_exact_rowsandmixed_zero_gas_and_duplicate.nullforrepullrows.result.entries.group_identifier (string) – Group identifier of history events linked to
tx_hash.nullwhen no linked events are found.result.entries.last_retry_ts (int) – Unix timestamp of the most recent repull retry, or
nullif no retry has failed yet.result.entries.last_error (string) – Error from the most recent failed repull retry, or
nullif no retry has failed yet.result.entries_found (int) – Number of entries matching the applied filters. Ignores pagination.
result.entries_total (int) – Total number of entries matching the applied filters.
result.entries_limit (int) – Applied limit value.
-1when no limit is provided.
- Request JSON Object:
limit (int[optional]) – Maximum number of rows to return.
offset (int[optional]) – Number of rows to skip.
tx_hash (string[optional]) – Filter rows by a specific EVM transaction hash.
chain (string[optional]) – Filter rows by chain name (e.g.
"ethereum","optimism").from_timestamp (int[optional]) – Unix timestamp. Only return rows whose transaction timestamp is greater than or equal to this value. Defaults to
0.to_timestamp (int[optional]) – Unix timestamp. Only return rows whose transaction timestamp is less than or equal to this value. Defaults to current time. Rows without a known transaction timestamp are always included.
fixed (bool[optional]) – If
true, return fixed rows. Defaults tofalse(unfixed rows).failed (bool[optional]) – If
true, return only rows with a recorded failed retry (last_retry_ts and last_error set).order_by_attributes (list[optional]) – List of attributes to order by. Valid values:
chain,tx_hash,timestamp,action,repull_reason,redecode_reason,last_retry_ts,last_error. Defaults to["chain", "tx_hash"].ascending (list[optional]) – List of booleans corresponding to each
order_by_attributesentry.truefor ascending,falsefor descending.
- Status Codes:
200 OK – Conflicts successfully returned.
401 Unauthorized – User is not logged in.
409 Conflict – Other error. Check error message for details.
500 Internal Server Error – Internal rotki error
- POST /api/(version)/blockchains/transactions/internal/conflicts
Doing a POST on the internal transaction conflicts endpoint returns only conflict counts split by
fixedstatus. Unlike GET, this endpoint does not return entries and does not accept filter parameters.Example Request:
http
POST /api/1/blockchains/transactions/internal/conflicts HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"async_query": false}
curl
curl -i -X POST http://localhost:5042/api/1/blockchains/transactions/internal/conflicts -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": false}'
wget
wget -S -O- http://localhost:5042/api/1/blockchains/transactions/internal/conflicts --header="Content-Type: application/json;charset=UTF-8" --post-data='{"async_query": false}'
httpie
echo '{ "async_query": false }' | http POST http://localhost:5042/api/1/blockchains/transactions/internal/conflicts Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/blockchains/transactions/internal/conflicts', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': False})
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "pending": 2, "failed": 1 }, "message": "" }
- Response JSON Object:
result.pending (int) – Number of rows with
fixed = 0andlast_retry_tsunset.result.failed (int) – Number of rows with
fixed = 0andlast_retry_tsset.
- Status Codes:
200 OK – Counts successfully returned.
401 Unauthorized – User is not logged in.
409 Conflict – 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
DELETEon/api/(version)/blockchains/eth/modules/datain 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
DELETEon/api/(version)/blockchains/eth/modules/datain which case all module data will be purged. Apart from the standard modules we have 2 virtual modules for purging DB data. They are “gnosis_pay” and “cowswap”.
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
401 Unauthorized – User is not logged in.
409 Conflict – 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", "native_token": "ETH", "image": "ethereum.svg", "evm_chain_name": "ethereum" }, { "id": "eth2", "name": "Ethereum Staking", "type": "eth2", "native_token": "ETH2", "image": "ethereum.svg" }, { "id": "btc", "name": "bitcoin", "type": "bitcoin", "native_token": "BTC", "image": "bitcoin.svg" }, { "id": "bch", "name": "bitcoin cash", "type": "bitcoin", "native_token": "BCH", "image": "bitcoin-cash.svg" }, { "id": "ksm", "name": "kusama", "type": "substrate", "native_token": "KSM", "image": "kusama.svg" }, { "id": "avax", "name": "avalanche", "type": "evm", "native_token": "AVAX", "image": "avalanche.svg", "evm_chain_name": "avalanche" }, { "id": "dot", "name": "polkadot", "type": "substrate", "native_token": "DOT", "image": "polkadot.svg" }, { "id": "optimism", "name": "optimism", "type": "evm", "native_token": "ETH", "image": "optimism.svg", "evm_chain_name": "optimism" }, { "id": "polygon_pos", "name": "Polygon PoS", "type": "evm", "native_token": "eip155:137/erc20:0x0000000000000000000000000000000000001010", "image": "polygon_pos.svg", "evm_chain_name": "polygon_pos" }, { "id": "arbitrum_one", "name": "Arbitrum One", "type": "evm", "native_token": "ETH", "image": "arbitrum_one.svg", "evm_chain_name": "arbitrum_one" }, { "id": "base", "name": "base", "type": "evm", "native_token": "ETH", "image": "base.svg", "evm_chain_name": "base" }, { "id": "gnosis", "name": "gnosis", "type": "evm", "native_token": "XDAI", "image": "gnosis.svg", "evm_chain_name": "gnosis" }, { "id": "zksync_lite", "name": "zksync", "type": "evmlike", "native_token": "ETH", "image": "zksync_lite.svg", } ], "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": trueDoing 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
401 Unauthorized – User is not logged in.
409 Conflict – 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
401 Unauthorized – User is not logged in.
409 Conflict – 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": trueExample 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
401 Unauthorized – User is not logged in.
409 Conflict – 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.
401 Unauthorized – User is not logged in.
409 Conflict – Some other error. Check error message for details.
500 Internal Server Error – Internal rotki error
Querying blockchain transactions
- POST /api/(version)/blockchains/transactions/
Note
This endpoint can also be queried asynchronously by using
"async_query": trueDoing a POST on the blockchains transactions endpoint will query all transactions for all the tracked user addresses and save them to the DB. Caller can also specify a list of accounts to further filter the query, where each account contains an address and optionally its blockchain.
Example Request:
http
POST /api/1/blockchains/transactions HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "accounts": [{ "address": "0x3CAdbeB58CB5162439908edA08df0A305b016dA8", "blockchain": "optimism" }, { "address": "0xF2Eb18a344b2a9dC769b1914ad035Cbb614Fd238" }], "from_timestamp": 1514764800, "to_timestamp": 1572080165 }
curl
curl -i -X POST http://localhost:5042/api/1/blockchains/transactions -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"accounts": [{"address": "0x3CAdbeB58CB5162439908edA08df0A305b016dA8", "blockchain": "optimism"}, {"address": "0xF2Eb18a344b2a9dC769b1914ad035Cbb614Fd238"}], "from_timestamp": 1514764800, "to_timestamp": 1572080165}'
wget
wget -S -O- http://localhost:5042/api/1/blockchains/transactions --header="Content-Type: application/json;charset=UTF-8" --post-data='{"accounts": [{"address": "0x3CAdbeB58CB5162439908edA08df0A305b016dA8", "blockchain": "optimism"}, {"address": "0xF2Eb18a344b2a9dC769b1914ad035Cbb614Fd238"}], "from_timestamp": 1514764800, "to_timestamp": 1572080165}'
httpie
echo '{ "accounts": [ { "address": "0x3CAdbeB58CB5162439908edA08df0A305b016dA8", "blockchain": "optimism" }, { "address": "0xF2Eb18a344b2a9dC769b1914ad035Cbb614Fd238" } ], "from_timestamp": 1514764800, "to_timestamp": 1572080165 }' | http POST http://localhost:5042/api/1/blockchains/transactions Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/blockchains/transactions', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'accounts': [{'address': '0x3CAdbeB58CB5162439908edA08df0A305b016dA8', 'blockchain': 'optimism'}, {'address': '0xF2Eb18a344b2a9dC769b1914ad035Cbb614Fd238'}], 'from_timestamp': 1514764800, 'to_timestamp': 1572080165})
- Request JSON Object:
accounts (list[string]) – List of accounts to filter by. Each account contains a required
addressfield which is a blockchain address and an optionalblockchainfield 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_timestampuntil now are returned.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (object) – true for success
- Status Codes:
200 OK – Transactions successfully queried
400 Bad Request – Provided JSON is in some way malformed
401 Unauthorized – User is not logged in.
409 Conflict – 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.
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.
401 Unauthorized – User is not logged in.
409 Conflict – 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.
401 Unauthorized – User is not logged in.
409 Conflict – Tag with the given name does not exist.
500 Internal Server Error – Internal rotki error
Querying onchain balances
- GET /api/(version)/balances/blockchains/(blockchain)/
Query on-chain balances for tracked accounts. Specify a blockchain to query only that chain. Available blockchains:
BTC,BCH,ETH,ETH2,KSM,DOT,AVAX,SOL.When addresses are provided, those addresses are read from the blockchain balances cache for the selected blockchain. Results include balances above the
value_thresholdif specified.Note
This endpoint can be queried asynchronously using
"async_query": true.Note
This endpoint is cache-only. To force a refresh use
POST /api/(version)/balances/blockchains/(blockchain)/.Example Request:
http
GET /api/1/balances/blockchains/?value_threshold=1000 HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET 'http://localhost:5042/api/1/balances/blockchains/?value_threshold=1000'
wget
wget -S -O- 'http://localhost:5042/api/1/balances/blockchains/?value_threshold=1000'
httpie
http 'http://localhost:5042/api/1/balances/blockchains/?value_threshold=1000'
python-requests
requests.get('http://localhost:5042/api/1/balances/blockchains/?value_threshold=1000')
- Request JSON Object:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
addresses (list[str]) – Optional. List of blockchain addresses to query balances for. If not provided, all tracked addresses are queried.
- Parameters:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
addresses (list[str]) – Optional. List of blockchain addresses to query balances for. If not provided, all tracked addresses are queried.
- Query Parameters:
value_threshold (decimal) – Optional. If provided, only returns balances with value (in user’s preferred currency) greater than this threshold.
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": { "address": {"amount": "10", "usd_value": "1650.53"} }, "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F": { "address": {"amount": "15", "usd_value": "15.21"} }, "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7": { "makerdao vault": {"amount": "3", "usd_value": "54"} } }, "liabilities": { "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F": { "makerdao vault": {"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 USD value as of the request. For EVM accounts, balances are organized by category:"address"represents tokens held directly in the address and available for use, while protocol-specific labels (like"makerdao vault","aave","morpho") show tokens locked in DeFi protocols. ETH accounts may have an optional liabilities key with the same structure. BTC accounts are separated in standalone accounts and in accounts that have been derived from an xpub. The xpub ones are listed in a list under the"xpubs"key. Each entry has the xpub, the derivation path and the list of addresses and their balances.- resjson object total:
The blockchain balances in total per asset. Has 2 keys. One for assets and one for liabilities. The liabilities key may be missing if no liabilities exist.
- statuscode 200:
Balances successfully queried.
- statuscode 400:
Provided JSON is in some way malformed
- statuscode 401:
User is not logged in.
- statuscode 409:
Invalid blockchain, or problems querying the given blockchain
- statuscode 500:
Internal rotki error
- statuscode 502:
An external service used in the query such as etherscan or blockchain.info could not be reached or returned unexpected response.
Querying all balances
Note
This endpoint can also be queried asynchronously by using
"async_query": trueNote
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_TIMEthe cached value will be returned. If you want to skip the cache add theignore_cache: trueargument. 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%", "value": "180" }, "BTC": { "amount": "0.5", "percentage_of_net_value": "90%", "value": "4000" }, "EUR": { "amount": "2", "percentage_of_net_value": "0.5%", "value": "2.8" } }, "liabilities": { "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F": { "amount": "100", "value": "102.5", "percentage_of_net_value": "1%" } }, "location": { "banks": { "percentage_of_net_value": "0.5%", "value": "2.8" }, "binance": { "percentage_of_net_value": "9.5%", "value": "180" }, "blockchain": { "percentage_of_net_value": "90%", "value": "4000" } }, "net_value": "4080.3" }, "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 liability."percentage_of_net_value"is the percentage the user’s net worth that this asset or liability represents. And finally"value"is the total value this asset/liability is worth in the user’s main currency 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. Finally, there is a"net_value"key which represents the total net value of all assets minus liabilities in the user’s main currency.
- Status Codes:
200 OK – Balances successfully queried.
400 Bad Request – Provided JSON is in some way malformed
401 Unauthorized – 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_typeif 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.show_whitelisted_assets_only (bool) – If set to true then only whitelisted spam tokens are queried.
ignored_assets_handling (string) – A flag to specify how to handle ignored assets. Possible values are ‘none’, ‘exclude’ and ‘show_only’. You can write ‘none’ in order to not handle them in any special way (meaning to show them too). This is the default. You can write ‘exclude’ if you want to exclude them from the result. And you can write ‘show_only’ if you want to only see the ignored assets in the result.
identifiers (list[string]) – A list of asset identifiers to filter by. Optional.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": [ { "identifier": "eip155:1/erc20:0xB6eD7644C69416d67B522e20bC294A9a9B405B31", "evm_address": "0xB6eD7644C69416d67B522e20bC294A9a9B405B31", "evm_chain":"ethereum", "token_kind":"erc20", "decimals": 8, "name": "0xBitcoin", "started": 1517875200, "symbol": "0xBTC", "asset_type": "evm token" "cryptocompare":"0xbtc", "coingecko":"0xbtc", "protocol":"None" }, { "identifier": "DCR", "name": "Decred", "started": 1450137600, "symbol": "DCR", "asset_type": "own chain" }, { "identifier": "eip155:1/erc20:0xcC4eF9EEAF656aC1a2Ab886743E98e97E090ed38", "evm_address": "0xcC4eF9EEAF656aC1a2Ab886743E98e97E090ed38", "evm_chain":"ethereum", "token_kind":"erc20", "decimals": 18, "name": "DigitalDevelopersFund", "started": 1498504259, "symbol": "DDF", "asset_type": "evm token" "cryptocompare":"DDF", "coingecko":"ddf", "protocol":"None" }, { "identifier": "ETC", "forked": "ETH", "name": "Ethereum classic", "started": 1469020840, "symbol": "ETC", "asset_type": "own chain" }, { "identifier": "KRW", "name": "Korean won", "symbol": "KRW", "asset_type": "fiat" }, { "identifier": "eip155:1/erc20:0xD850942eF8811f2A866692A623011bDE52a462C1", "evm_address": "0xD850942eF8811f2A866692A623011bDE52a462C1", "evm_chain":"ethereum", "token_kind":"erc20", "decimals": 18, "name": "Vechain Token", "started": 1503360000, "swapped_for": "VET", "symbol": "VEN", "asset_type": "evm token", "coingecko": "vechain" "cryptocompare":"VET", "coingecko":"vet", "protocol":"None" }, { "identifier": "eip155:1/erc721:0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/1234", "evm_address": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", "evm_chain":"ethereum", "token_kind":"erc721", "name": "Bored Ape Yacht Club #1234", "symbol": "BAYC", "asset_type": "evm token", "collectible_id": "1234", "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
ETCwould haveETHhere.swapped_for (string) – An optional attribute representing another asset for which this asset was swapped for. For example
VENtokens were at some point swapped forVETtokens.symbol (string) – The symbol used for this asset. This is not guaranteed to be unique.
evm_address (string) – If the type is
evm_tokenthen this will be the hexadecimal address of the token’s contract.evm_chain (string) – If the type is
evm_tokenthen this will be the name of the evm chain. “ethereum”, “optimism” etc.token_kind (string) – If the type is
evm_tokenthen this will be the token type, for exampleerc20.decimals (integer) – If the type is
evm_tokenthen 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.
collectible_id (string) – Only present for ERC721 tokens. The token ID of the NFT.
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_assetthis is a string field with notes added by the user.custom_asset_type (string) – If the type is
custom_assetthis 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 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", "coingecko": "oxbitcoin", "cryptocompare": "0XBTC" }, "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", "main_asset": "BTC" } } }, "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. The properties
"name","symbol", and"main_asset"are always present.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.
coingecko (string) – This value might not be included in all the results. It is the coingecko identifier for the asset.
cryptocompare (string) – This value might not be included in all the results. It is the cryptocompare identifier for the 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. Optional.
address (string) – An address to be used to search for. Optional.
chain_id (int[optional]) – Chain id of a supported EVM chain used to filter the result
owner_addresses (list[string][optional]) – A list of evm addresses. If provided, only nfts owned by these addresses will be returned.
name (string[optional]) – Optional nfts name to filter by.
collection_name (string[optional]) – Optional nfts collection_name to filter by.
ignored_assets_handling (string[optional]) – A flag to specify how to handle ignored assets. Possible values are ‘none’, ‘exclude’ and ‘show_only’. You can write ‘none’ in order to not handle them in any special way (meaning to show them too). This is the default. You can write ‘exclude’ if you want to exclude them from the result. And you can write ‘show_only’ if you want to only see the ignored assets in the result.
Note
Either value or address need to be provided when calling this endpoint.
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
401 Unauthorized – 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": trueExample 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
401 Unauthorized – 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 user assets
- 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. This supports fiat assets, crypto assets, EVM tokens, and Solana tokens. Returns the identifier of the newly added asset.
Example Request (EVM Token):
http
PUT /api/1/assets/all HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "asset_type": "evm token", "address": "0x6B175474E89094C44Da98b954EedeAC495271d0F", "evm_chain": "ethereum", "token_kind": "erc20", "name": "Dai Stablecoin", "symbol": "DAI", "decimals": 18 }
curl
curl -i -X PUT http://localhost:5042/api/1/assets/all -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0x6B175474E89094C44Da98b954EedeAC495271d0F", "asset_type": "evm token", "decimals": 18, "evm_chain": "ethereum", "name": "Dai Stablecoin", "symbol": "DAI", "token_kind": "erc20"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/assets/all --header="Content-Type: application/json;charset=UTF-8" --body-data='{"address": "0x6B175474E89094C44Da98b954EedeAC495271d0F", "asset_type": "evm token", "decimals": 18, "evm_chain": "ethereum", "name": "Dai Stablecoin", "symbol": "DAI", "token_kind": "erc20"}'
httpie
echo '{ "address": "0x6B175474E89094C44Da98b954EedeAC495271d0F", "asset_type": "evm token", "decimals": 18, "evm_chain": "ethereum", "name": "Dai Stablecoin", "symbol": "DAI", "token_kind": "erc20" }' | 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={'address': '0x6B175474E89094C44Da98b954EedeAC495271d0F', 'asset_type': 'evm token', 'decimals': 18, 'evm_chain': 'ethereum', 'name': 'Dai Stablecoin', 'symbol': 'DAI', 'token_kind': 'erc20'})
Example Request (Solana Token):
http
PUT /api/1/assets/all HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "asset_type": "solana token", "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "token_kind": "spl_token", "name": "USD Coin", "symbol": "USDC", "decimals": 6 }
curl
curl -i -X PUT http://localhost:5042/api/1/assets/all -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "asset_type": "solana token", "decimals": 6, "name": "USD Coin", "symbol": "USDC", "token_kind": "spl_token"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/assets/all --header="Content-Type: application/json;charset=UTF-8" --body-data='{"address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "asset_type": "solana token", "decimals": 6, "name": "USD Coin", "symbol": "USDC", "token_kind": "spl_token"}'
httpie
echo '{ "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "asset_type": "solana token", "decimals": 6, "name": "USD Coin", "symbol": "USDC", "token_kind": "spl_token" }' | 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={'address': 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', 'asset_type': 'solana token', 'decimals': 6, 'name': 'USD Coin', 'symbol': 'USDC', 'token_kind': 'spl_token'})
Example Request (ERC721 NFT):
http
PUT /api/1/assets/all HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "asset_type": "evm token", "address": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", "evm_chain": "ethereum", "token_kind": "erc721", "name": "Bored Ape Yacht Club", "symbol": "BAYC", "collectible_id": "1234", "decimals": 0 }
curl
curl -i -X PUT http://localhost:5042/api/1/assets/all -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", "asset_type": "evm token", "collectible_id": "1234", "decimals": 0, "evm_chain": "ethereum", "name": "Bored Ape Yacht Club", "symbol": "BAYC", "token_kind": "erc721"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/assets/all --header="Content-Type: application/json;charset=UTF-8" --body-data='{"address": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", "asset_type": "evm token", "collectible_id": "1234", "decimals": 0, "evm_chain": "ethereum", "name": "Bored Ape Yacht Club", "symbol": "BAYC", "token_kind": "erc721"}'
httpie
echo '{ "address": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", "asset_type": "evm token", "collectible_id": "1234", "decimals": 0, "evm_chain": "ethereum", "name": "Bored Ape Yacht Club", "symbol": "BAYC", "token_kind": "erc721" }' | 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={'address': '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D', 'asset_type': 'evm token', 'collectible_id': '1234', 'decimals': 0, 'evm_chain': 'ethereum', 'name': 'Bored Ape Yacht Club', 'symbol': 'BAYC', 'token_kind': 'erc721'})
- Request JSON Object:
name (string) – The name of the asset. Required.
symbol (string) – The symbol of the asset. Required.
address (string) – The contract address for EVM tokens or mint address for Solana tokens. Required when asset_type is
"evm token"or"solana token".evm_chain (string) – The EVM chain name such as
"ethereum","optimism". Required when asset_type is"evm token".token_kind (string) – The token standard. For EVM tokens:
"erc20"or"erc721". For Solana tokens:"spl_token"or"spl_nft". Required when asset_type is"evm token"or"solana token".decimals (integer) – The number of decimal places the token uses. Required when asset_type is
"evm token"or"solana token".collectible_id (string) – The NFT token ID. Must be a positive integer. Only valid when token_kind is
"erc721".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.
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 (EVM Token):
HTTP/1.1 200 OK Content-Type: application/json { "result": {"identifier": "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F"}, "message": "" }
Example Response (Solana Token):
HTTP/1.1 200 OK Content-Type: application/json { "result": {"identifier": "sol:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}, "message": "" }
Example Response (ERC721 NFT):
HTTP/1.1 200 OK Content-Type: application/json { "result": {"identifier": "eip155:1/erc721:0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/1234"}, "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 user assets
- PATCH /api/(version)/assets/all
Doing a PATCH on the user assets endpoint will allow you to edit an existing asset in the global rotki DB.
Example Request (EVM Token):
http
PATCH /api/1/assets/all HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "identifier": "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F", "asset_type": "evm token", "address": "0x6B175474E89094C44Da98b954EedeAC495271d0F", "evm_chain": "ethereum", "token_kind": "erc20", "name": "Dai Stablecoin Updated", "symbol": "DAI", "decimals": 18 }
curl
curl -i -X PATCH http://localhost:5042/api/1/assets/all -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0x6B175474E89094C44Da98b954EedeAC495271d0F", "asset_type": "evm token", "decimals": 18, "evm_chain": "ethereum", "identifier": "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F", "name": "Dai Stablecoin Updated", "symbol": "DAI", "token_kind": "erc20"}'
wget
wget -S -O- --method=PATCH http://localhost:5042/api/1/assets/all --header="Content-Type: application/json;charset=UTF-8" --body-data='{"address": "0x6B175474E89094C44Da98b954EedeAC495271d0F", "asset_type": "evm token", "decimals": 18, "evm_chain": "ethereum", "identifier": "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F", "name": "Dai Stablecoin Updated", "symbol": "DAI", "token_kind": "erc20"}'
httpie
echo '{ "address": "0x6B175474E89094C44Da98b954EedeAC495271d0F", "asset_type": "evm token", "decimals": 18, "evm_chain": "ethereum", "identifier": "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F", "name": "Dai Stablecoin Updated", "symbol": "DAI", "token_kind": "erc20" }' | 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={'address': '0x6B175474E89094C44Da98b954EedeAC495271d0F', 'asset_type': 'evm token', 'decimals': 18, 'evm_chain': 'ethereum', 'identifier': 'eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F', 'name': 'Dai Stablecoin Updated', 'symbol': 'DAI', 'token_kind': 'erc20'})
Example Request (ERC721 NFT):
http
PATCH /api/1/assets/all HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "identifier": "eip155:1/erc721:0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/1234", "asset_type": "evm token", "address": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", "evm_chain": "ethereum", "token_kind": "erc721", "name": "Bored Ape Yacht Club Updated", "symbol": "BAYC", "collectible_id": "1234", "decimals": 0 }
curl
curl -i -X PATCH http://localhost:5042/api/1/assets/all -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", "asset_type": "evm token", "collectible_id": "1234", "decimals": 0, "evm_chain": "ethereum", "identifier": "eip155:1/erc721:0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/1234", "name": "Bored Ape Yacht Club Updated", "symbol": "BAYC", "token_kind": "erc721"}'
wget
wget -S -O- --method=PATCH http://localhost:5042/api/1/assets/all --header="Content-Type: application/json;charset=UTF-8" --body-data='{"address": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", "asset_type": "evm token", "collectible_id": "1234", "decimals": 0, "evm_chain": "ethereum", "identifier": "eip155:1/erc721:0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/1234", "name": "Bored Ape Yacht Club Updated", "symbol": "BAYC", "token_kind": "erc721"}'
httpie
echo '{ "address": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", "asset_type": "evm token", "collectible_id": "1234", "decimals": 0, "evm_chain": "ethereum", "identifier": "eip155:1/erc721:0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/1234", "name": "Bored Ape Yacht Club Updated", "symbol": "BAYC", "token_kind": "erc721" }' | 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={'address': '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D', 'asset_type': 'evm token', 'collectible_id': '1234', 'decimals': 0, 'evm_chain': 'ethereum', 'identifier': 'eip155:1/erc721:0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/1234', 'name': 'Bored Ape Yacht Club Updated', 'symbol': 'BAYC', 'token_kind': 'erc721'})
- Request JSON Object:
asset (object) – Asset to edit. For details on the possible fields see here. The identifier field is required to specify which 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 user assets
- DELETE /api/(version)/assets/all
Doing a DELETE on the user 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) – Identifier 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": trueNote
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": trueDoing 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
trueif all went fine or 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
401 Unauthorized – User is not logged in.
409 Conflict – Conflicts were found during update. The conflicts should also be returned.
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,
softwhere the API will try to reset the state of packaged assets without modifying assets added by the user andhardmode 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
softorhard.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (object) –
trueif 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
401 Unauthorized – User is not logged in.
409 Conflict – Some conflict at replacing.
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 (string) – 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 re-queried from CoinGecko and saved to the filesystem.
Example Request:
http
PATCH /api/1/assets/icon/modify HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"asset": "eip155:1/erc20:0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e"}
curl
curl -i -X PATCH http://localhost:5042/api/1/assets/icon/modify -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"asset": "eip155:1/erc20:0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e"}'
wget
wget -S -O- --method=PATCH http://localhost:5042/api/1/assets/icon/modify --header="Content-Type: application/json;charset=UTF-8" --body-data='{"asset": "eip155:1/erc20:0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e"}'
httpie
echo '{ "asset": "eip155:1/erc20:0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e" }' | http PATCH http://localhost:5042/api/1/assets/icon/modify Content-Type:"application/json;charset=UTF-8"
python-requests
requests.patch('http://localhost:5042/api/1/assets/icon/modify', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'asset': 'eip155:1/erc20:0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e'})
- Request JSON Object:
asset (string) – Identifier of the asset to be refreshed.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json {"result": true, "message": ""}
- Status Codes:
200 OK – Icon successfully deleted and re-queried.
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
Get asset location mappings for a location
- POST /api/(version)/assets/locationmappings
Doing a POST on the asset location mappings endpoint will return all the paginated location assets mappings for the given filter.
Example Request
http
POST /api/1/assets/locationmappings/ HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "offset": 20, "limit": 2 }
curl
curl -i -X POST http://localhost:5042/api/1/assets/locationmappings/ -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"limit": 2, "offset": 20}'
wget
wget -S -O- http://localhost:5042/api/1/assets/locationmappings/ --header="Content-Type: application/json;charset=UTF-8" --post-data='{"limit": 2, "offset": 20}'
httpie
echo '{ "limit": 2, "offset": 20 }' | http POST http://localhost:5042/api/1/assets/locationmappings/ Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/assets/locationmappings/', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'limit': 2, 'offset': 20})
- Request JSON Object:
location[optional] (str) – If given, filter the returned mappings only for the location. Possible values can be any supported exchange,
nullto get the mappings that are common for all exchanges, or omitting it to get all the mappings.location_symbol[optional] (str) – Filter the exchange symbols using the provided string.
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.
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": { "entries": [ { "asset": "eip155:1/erc20:0x6810e776880C02933D47DB1b9fc05908e5386b96", "location_symbol": "GNO", "location": "binance"}, { "asset": "eip155:1/erc20:0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE", "location_symbol": "SHIB", "location": "kraken"} ], "entries_found": 1500, "entries_total": 1500 }, "message": "" }
- Response JSON Object:
entries (object) – An array of mapping objects. Each entry is composed of the asset identifier under the
"asset"key, its ticker symbol used in the location under the"location_symbol"key, and its location under the"location"key.entries_found (int) – The number of entries found for the current filter. Ignores pagination.
entries_total (int) – The number of total entries ignoring all filters.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – Mappings were returned successfully.
400 Bad Request – Provided JSON is in some way malformed.
500 Internal Server Error – Internal rotki error.
Insert asset location mappings for a location
- PUT /api/(version)/assets/locationmappings
Doing a PUT on the asset location mappings endpoint with a list of entries, and each entry containing an asset’s identifier, its location, and its location symbol will save these mappings in the DB.
Example Request
http
PUT /api/1/assets/locationmappings HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "entries": [ { "asset": "eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", "location_symbol": "UNI", "location": "kucoin"}, { "asset": "eip155:1/erc20:0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF", "location_symbol": "IMX", "location": "kraken"} ] }
curl
curl -i -X PUT http://localhost:5042/api/1/assets/locationmappings -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"entries": [{"asset": "eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", "location_symbol": "UNI", "location": "kucoin"}, {"asset": "eip155:1/erc20:0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF", "location_symbol": "IMX", "location": "kraken"}]}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/assets/locationmappings --header="Content-Type: application/json;charset=UTF-8" --body-data='{"entries": [{"asset": "eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", "location_symbol": "UNI", "location": "kucoin"}, {"asset": "eip155:1/erc20:0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF", "location_symbol": "IMX", "location": "kraken"}]}'
httpie
echo '{ "entries": [ { "asset": "eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", "location": "kucoin", "location_symbol": "UNI" }, { "asset": "eip155:1/erc20:0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF", "location": "kraken", "location_symbol": "IMX" } ] }' | http PUT http://localhost:5042/api/1/assets/locationmappings Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/assets/locationmappings', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'entries': [{'asset': 'eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984', 'location_symbol': 'UNI', 'location': 'kucoin'}, {'asset': 'eip155:1/erc20:0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF', 'location_symbol': 'IMX', 'location': 'kraken'}]})
- Request JSON Object:
entries (object) – A list of mappings containing
"asset","location_symbol", and"location"to be saved in the database
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – A boolean which is true in the case the mappings were added successfully.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – Mappings were added successfully.
400 Bad Request – Provided JSON is in some way malformed.
409 Conflict – Some of the provided mappings already exist in the database or assets have incorrect format.
500 Internal Server Error – Internal rotki error.
Update asset location mappings for a location
- PATCH /api/(version)/assets/locationmappings
Doing a PATCH on the asset location mappings endpoint with a list of entries, and each entry containing an asset’s identifier, its location, and its location symbol will updates these mappings in the DB.
Example Request
http
PATCH /api/1/assets/locationmappings HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "location": "kucoin", "entries": [ { "asset": "eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", "location_symbol": "UNI", "location": "kraken"}, { "asset": "eip155:1/erc20:0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF", "location_symbol": "IMX", "location": "kucoin"} ] }
curl
curl -i -X PATCH http://localhost:5042/api/1/assets/locationmappings -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"entries": [{"asset": "eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", "location_symbol": "UNI", "location": "kraken"}, {"asset": "eip155:1/erc20:0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF", "location_symbol": "IMX", "location": "kucoin"}], "location": "kucoin"}'
wget
wget -S -O- --method=PATCH http://localhost:5042/api/1/assets/locationmappings --header="Content-Type: application/json;charset=UTF-8" --body-data='{"entries": [{"asset": "eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", "location_symbol": "UNI", "location": "kraken"}, {"asset": "eip155:1/erc20:0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF", "location_symbol": "IMX", "location": "kucoin"}], "location": "kucoin"}'
httpie
echo '{ "entries": [ { "asset": "eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", "location": "kraken", "location_symbol": "UNI" }, { "asset": "eip155:1/erc20:0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF", "location": "kucoin", "location_symbol": "IMX" } ], "location": "kucoin" }' | http PATCH http://localhost:5042/api/1/assets/locationmappings Content-Type:"application/json;charset=UTF-8"
python-requests
requests.patch('http://localhost:5042/api/1/assets/locationmappings', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'entries': [{'asset': 'eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984', 'location_symbol': 'UNI', 'location': 'kraken'}, {'asset': 'eip155:1/erc20:0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF', 'location_symbol': 'IMX', 'location': 'kucoin'}], 'location': 'kucoin'})
- Request JSON Object:
entries (object) – A list of mappings containing
"asset","location_symbol", and"location"to be updated in the database.
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – A boolean which is true in case the mappings were updated successfully.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – Mappings were updated successfully.
400 Bad Request – Provided JSON is in some way malformed.
409 Conflict – Some of the provided mappings don’t exist in the database or assets have incorrect format.
500 Internal Server Error – Internal rotki error.
Delete asset location mappings for a location
- DELETE /api/(version)/assets/locationmappings
Doing a DELETE on the asset location mappings endpoint with a list of entries, and each entry containing an asset’s location, and its location symbol will delete these mappings from the DB.
Example Request
http
DELETE /api/1/assets/locationmappings HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "entries": [ {"location_symbol": "UNI", "location": "kraken"}, {"location_symbol": "IMX", "location": "kucoin"} ] }
curl
curl -i -X DELETE http://localhost:5042/api/1/assets/locationmappings -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"entries": [{"location_symbol": "UNI", "location": "kraken"}, {"location_symbol": "IMX", "location": "kucoin"}]}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/assets/locationmappings --header="Content-Type: application/json;charset=UTF-8" --body-data='{"entries": [{"location_symbol": "UNI", "location": "kraken"}, {"location_symbol": "IMX", "location": "kucoin"}]}'
httpie
echo '{ "entries": [ { "location": "kraken", "location_symbol": "UNI" }, { "location": "kucoin", "location_symbol": "IMX" } ] }' | http DELETE http://localhost:5042/api/1/assets/locationmappings Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/1/assets/locationmappings', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'entries': [{'location_symbol': 'UNI', 'location': 'kraken'}, {'location_symbol': 'IMX', 'location': 'kucoin'}]})
- Request JSON Object:
entries (object) – A list of objects containing
"location_symbol"and"location"whose mappings should be deleted from the database.
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – A boolean which is true in case the mappings were deleted successfully.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – Mappings were deleted successfully.
400 Bad Request – Provided JSON is in some way malformed.
409 Conflict – Some of the provided asset identifiers don’t exist in the database for the given location or their format is incorrect.
500 Internal Server Error – Internal rotki error.
Get asset mappings for a counterparty
- POST /api/(version)/assets/counterpartymappings
Doing a POST on the counterparty asset mappings endpoint will return all the paginated counterparty assets mappings for the given filter.
Example Request
http
POST /api/1/assets/counterpartymappings/ HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "offset": 20, "limit": 2 }
curl
curl -i -X POST http://localhost:5042/api/1/assets/counterpartymappings/ -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"limit": 2, "offset": 20}'
wget
wget -S -O- http://localhost:5042/api/1/assets/counterpartymappings/ --header="Content-Type: application/json;charset=UTF-8" --post-data='{"limit": 2, "offset": 20}'
httpie
echo '{ "limit": 2, "offset": 20 }' | http POST http://localhost:5042/api/1/assets/counterpartymappings/ Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/assets/counterpartymappings/', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'limit': 2, 'offset': 20})
- Request JSON Object:
counterparty[optional] (str) – If given, filter the returned mappings only for the counterparty. Possible values can be any supported counterparty, or omitting it to get all the mappings.
counterparty_symbol[optional] (str) – Filter the counterparty symbols using the provided string.
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.
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": { "entries": [ { "asset": "eip155:1/erc20:0x6810e776880C02933D47DB1b9fc05908e5386b96", "counterparty_symbol": "GNO", "counterparty": "hyperliquid"}, { "asset": "eip155:1/erc20:0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE", "counterparty_symbol": "SHIB", "counterparty": "hyperliquid"} ], "entries_found": 1500, "entries_total": 1500 }, "message": "" }
- Response JSON Object:
entries (object) – An array of mapping objects. Each entry is composed of the asset identifier under the
"asset"key, its ticker symbol used in the counterparty under the"counterparty_symbol"key, and its counterparty under the"counterparty"key.entries_found (int) – The number of entries found for the current filter. Ignores pagination.
entries_total (int) – The number of total entries ignoring all filters.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – Mappings were returned successfully.
400 Bad Request – Provided JSON is in some way malformed.
500 Internal Server Error – Internal rotki error.
Insert asset mappings for a counterparty
- PUT /api/(version)/assets/counterpartymappings
Doing a PUT on the counterparty asset mappings endpoint with a list of entries, and each entry containing an asset’s identifier, its counterparty and its counterparty symbol will save these mappings in the DB.
Example Request
http
PUT /api/1/assets/counterpartymappings HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "entries": [ { "asset": "eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", "counterparty_symbol": "UNI", "counterparty": "hyperliquid"}, { "asset": "eip155:1/erc20:0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF", "counterparty_symbol": "IMX", "counterparty": "hyperliquid"} ] }
curl
curl -i -X PUT http://localhost:5042/api/1/assets/counterpartymappings -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"entries": [{"asset": "eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", "counterparty_symbol": "UNI", "counterparty": "hyperliquid"}, {"asset": "eip155:1/erc20:0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF", "counterparty_symbol": "IMX", "counterparty": "hyperliquid"}]}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/assets/counterpartymappings --header="Content-Type: application/json;charset=UTF-8" --body-data='{"entries": [{"asset": "eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", "counterparty_symbol": "UNI", "counterparty": "hyperliquid"}, {"asset": "eip155:1/erc20:0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF", "counterparty_symbol": "IMX", "counterparty": "hyperliquid"}]}'
httpie
echo '{ "entries": [ { "asset": "eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", "counterparty": "hyperliquid", "counterparty_symbol": "UNI" }, { "asset": "eip155:1/erc20:0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF", "counterparty": "hyperliquid", "counterparty_symbol": "IMX" } ] }' | http PUT http://localhost:5042/api/1/assets/counterpartymappings Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/assets/counterpartymappings', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'entries': [{'asset': 'eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984', 'counterparty_symbol': 'UNI', 'counterparty': 'hyperliquid'}, {'asset': 'eip155:1/erc20:0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF', 'counterparty_symbol': 'IMX', 'counterparty': 'hyperliquid'}]})
- Request JSON Object:
entries (object) – A list of mappings containing
"asset","counterparty_symbol", and"counterparty"to be saved in the database
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – A boolean which is true in the case the mappings were added successfully.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – Mappings were added successfully.
400 Bad Request – Provided JSON is in some way malformed.
409 Conflict – Some of the provided mappings already exist in the database or assets have incorrect format.
500 Internal Server Error – Internal rotki error.
Update asset mappings for a counterparty
- PATCH /api/(version)/assets/counterpartymappings
Doing a PATCH on the counterparty asset mappings endpoint with a list of entries, and each entry containing an asset’s identifier, its counterparty, and its counterparty symbol will updates these mappings in the DB.
Example Request
http
PATCH /api/1/assets/counterpartymappings HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "location": "kucoin", "entries": [ { "asset": "eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", "counterparty_symbol": "UNI", "counterparty": "hyperliquid"}, { "asset": "eip155:1/erc20:0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF", "counterparty_symbol": "IMX", "counterparty": "hyperliquid"} ] }
curl
curl -i -X PATCH http://localhost:5042/api/1/assets/counterpartymappings -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"entries": [{"asset": "eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", "counterparty_symbol": "UNI", "counterparty": "hyperliquid"}, {"asset": "eip155:1/erc20:0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF", "counterparty_symbol": "IMX", "counterparty": "hyperliquid"}], "location": "kucoin"}'
wget
wget -S -O- --method=PATCH http://localhost:5042/api/1/assets/counterpartymappings --header="Content-Type: application/json;charset=UTF-8" --body-data='{"entries": [{"asset": "eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", "counterparty_symbol": "UNI", "counterparty": "hyperliquid"}, {"asset": "eip155:1/erc20:0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF", "counterparty_symbol": "IMX", "counterparty": "hyperliquid"}], "location": "kucoin"}'
httpie
echo '{ "entries": [ { "asset": "eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", "counterparty": "hyperliquid", "counterparty_symbol": "UNI" }, { "asset": "eip155:1/erc20:0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF", "counterparty": "hyperliquid", "counterparty_symbol": "IMX" } ], "location": "kucoin" }' | http PATCH http://localhost:5042/api/1/assets/counterpartymappings Content-Type:"application/json;charset=UTF-8"
python-requests
requests.patch('http://localhost:5042/api/1/assets/counterpartymappings', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'entries': [{'asset': 'eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984', 'counterparty_symbol': 'UNI', 'counterparty': 'hyperliquid'}, {'asset': 'eip155:1/erc20:0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF', 'counterparty_symbol': 'IMX', 'counterparty': 'hyperliquid'}], 'location': 'kucoin'})
- Request JSON Object:
entries (object) – A list of mappings containing
"asset","counterparty_symbol", and"counterparty"to be updated in the database.
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – A boolean which is true in case the mappings were updated successfully.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – Mappings were updated successfully.
400 Bad Request – Provided JSON is in some way malformed.
409 Conflict – Some of the provided mappings don’t exist in the database or assets have incorrect format.
500 Internal Server Error – Internal rotki error.
Delete asset mappings for a counterparty
- DELETE /api/(version)/assets/counterpartymappings
Doing a DELETE on the counterparty asset mappings endpoint with a list of entries, and each entry containing an asset’s counterparty, and its counterparty symbol will delete these mappings from the DB.
Example Request
http
DELETE /api/1/assets/counterpartymappings HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "entries": [ {"counterparty_symbol": "UNI", "counterparty": "hyperliquid"}, {"counterparty_symbol": "IMX", "counterparty": "hyperliquid"} ] }
curl
curl -i -X DELETE http://localhost:5042/api/1/assets/counterpartymappings -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"entries": [{"counterparty_symbol": "UNI", "counterparty": "hyperliquid"}, {"counterparty_symbol": "IMX", "counterparty": "hyperliquid"}]}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/assets/counterpartymappings --header="Content-Type: application/json;charset=UTF-8" --body-data='{"entries": [{"counterparty_symbol": "UNI", "counterparty": "hyperliquid"}, {"counterparty_symbol": "IMX", "counterparty": "hyperliquid"}]}'
httpie
echo '{ "entries": [ { "counterparty": "hyperliquid", "counterparty_symbol": "UNI" }, { "counterparty": "hyperliquid", "counterparty_symbol": "IMX" } ] }' | http DELETE http://localhost:5042/api/1/assets/counterpartymappings Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/1/assets/counterpartymappings', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'entries': [{'counterparty_symbol': 'UNI', 'counterparty': 'hyperliquid'}, {'counterparty_symbol': 'IMX', 'counterparty': 'hyperliquid'}]})
- Request JSON Object:
entries (object) – A list of objects containing
"counterparty_symbol"and"counterparty"whose mappings should be deleted from the database.
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – A boolean which is true in case the mappings were deleted successfully.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – Mappings were deleted successfully.
400 Bad Request – Provided JSON is in some way malformed.
409 Conflict – Some of the provided asset identifiers don’t exist in the database for the given counterparty or their format is incorrect.
500 Internal Server Error – Internal rotki error.
Statistics for netvalue over time
- GET /api/(version)/statistics/netvalue/
Doing a GET on the statistics netvalue over time endpoint will return all the saved historical data points with user’s history. For non-premium users this returns up to 2 weeks of data in the past.
Example Request:
http
GET /api/1/statistics/netvalue/ HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/statistics/netvalue/
wget
wget -S -O- http://localhost:5042/api/1/statistics/netvalue/
httpie
http http://localhost:5042/api/1/statistics/netvalue/python-requests
requests.get('http://localhost:5042/api/1/statistics/netvalue/')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "times": [1571992200, 1572078657], "data": ["15000", "17541.23"] }, "message": "" }
- Response JSON Object:
times (list[integer]) – A list of timestamps for the returned data points
data (list[string]) – A list of net usd value for the corresponding timestamps. They are matched by list index.
- Status Codes:
200 OK – Netvalue statistics successfully queried.
400 Bad Request – Provided JSON is in some way malformed.
500 Internal Server Error – Internal rotki error.
- Statuscode 401:
No user is currently logged in.
Statistics for asset or collection balance over time
- POST /api/(version)/statistics/balance
Note
This endpoint is only available for premium users
Doing a POST on the statistics asset/collection balance over time endpoint will return all saved balance entries for an asset. Optionally you can filter for a specific time range by providing appropriate arguments. Depending on the given argument this will either query a single asset or a collection of assets.
Example Request:
http
POST /api/1/statistics/balance HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"from_timestamp": 1514764800, "to_timestamp": 1572080165, "asset": "BTC"}
curl
curl -i -X POST http://localhost:5042/api/1/statistics/balance -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"asset": "BTC", "from_timestamp": 1514764800, "to_timestamp": 1572080165}'
wget
wget -S -O- http://localhost:5042/api/1/statistics/balance --header="Content-Type: application/json;charset=UTF-8" --post-data='{"asset": "BTC", "from_timestamp": 1514764800, "to_timestamp": 1572080165}'
httpie
echo '{ "asset": "BTC", "from_timestamp": 1514764800, "to_timestamp": 1572080165 }' | http POST http://localhost:5042/api/1/statistics/balance Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/statistics/balance', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'asset': 'BTC', 'from_timestamp': 1514764800, 'to_timestamp': 1572080165})
- Request JSON Object:
from_timestamp (int) – The timestamp after which to return saved balances for the asset. If not given zero is considered as the start.
to_timestamp (int) – The timestamp until which to return saved balances for the asset. If not given all balances until now are returned.
asset (string) – Identifier of the asset. This is mutually exclusive with the collection id. If this is given then only a single asset’s balances will be queried. If not given a collection_id MUST be given.
collection_id (integer) – Collection id to query. This is mutually exclusive with the asset. If this is given then combined balances of all assets of the collection are returned. If not given an asset MUST be given.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": [{ "time": 1571992200, "amount": "1.1", "usd_value": "8901.1" }, { "time": 15720001, "amount": "1.2", "usd_value": "9501.3" }], "message": "" }
- Response JSON Object:
result (list(object)) – A list of asset balance entries.
- Response JSON Array of Objects:
time (integer) – The timestamp of the balance entry.
amount (number) – The amount of the balance entry.
usd_value (number) – The usd_value of the balance entry at the given timestamp.
- Status Codes:
200 OK – Single asset balance statistics successfully queried
400 Bad Request – Provided JSON is in some way malformed or data is invalid.
401 Unauthorized – No user is currently logged in
403 Forbidden – Logged in user does not have premium.
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.
401 Unauthorized – No user is currently logged in.
403 Forbidden – Logged in user does not have premium.
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.
401 Unauthorized – No user is currently logged in.
403 Forbidden – Logged in user does not have premium.
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.
401 Unauthorized – No user is currently logged in.
403 Forbidden – Logged in user does not have premium.
409 Conflict – There is a problem reaching the rotki server.
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.
otherargs (object) – Check the documentation of the remaining arguments here.
state_markers (list[string]) – Optional. A list of state markers to filter events by. Events matching any of the specified markers will be returned. Valid values are
customized,profit adjustment,matched,imported from csv. If not provided, no marker filtering is applied.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "events": [{ "entry": { "identifier": 1, "entry_type": "evm event", "asset": "ETH", "amount": "0.00863351371344", "counterparty": "gas", "group_identifier": "10x8d822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f", "event_subtype": "fee", "event_type": "spend", "location": "ethereum", "location_label": "0x6e15887E2CEC81434C16D587709f64603b39b545", "notes": "Burn 0.00863351371344 ETH for gas", "sequence_index": 0, "timestamp": 1642802807, "event_accounting_rule_status": "not processed", "tx_ref": "0x8d822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f", "address": null, "product": null }, "states": ["customized"], "hidden": true, "ignored_in_accounting": false, "has_details": false, "grouped_events_num": 1 }, { "entry": { "identifier": 2, "entry_type": "evm event", "asset": "ETH", "amount": "0.00163351371344", "counterparty": "gas", "group_identifier": "10x1c822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f", "event_subtype": "fee", "event_type": "spend", "location": "ethereum", "location_label": "0xce15887E2CEC81434C16D587709f64603b39b545", "notes": "Burn 0.00863351371344 ETH for gas", "sequence_index": 0, "timestamp": 1642802807, "event_accounting_rule_status": "not processed", "tx_ref": "0x1c822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f", "address": null, "product": null }, "ignored_in_accounting": false, "has_details": false, "grouped_events_num": 3 }, { "entry": { "identifier": 3, "entry_type": "eth_withdrawal_event", "asset": "ETH", "amount": "0.00163351371344", "group_identifier": "EW_1454_20453", "event_subtype": "remove_asset", "event_type": "staking", "location": "ethereum", "location_label": "0xce15887E2CEC81434C16D587709f64603b39b545", "notes": "Withdraw 0.00163351371344 ETH from validator 1454", "sequence_index": 0, "timestamp": 1652802807, "event_accounting_rule_status": "not processed", "validator_index": 1454, "is_exit": false }, "hidden": true, "ignored_in_accounting": false, "has_details": false, "grouped_events_num": 1 }, { "entry": { "identifier": 4, "entry_type": "eth_block_event", "asset": "ETH", "amount": "0.00163351371344", "group_identifier": "evm_1_block_15534342", "event_subtype": "block_production", "event_type": "staking", "location": "ethereum", "location_label": "0xce15887E2CEC81434C16D587709f64603b39b545", "notes": "Validator 1454 produced block 15534342 with 0.00163351371344 going to 0xce15887E2CEC81434C16D587709f64603b39b545 as the block reward", "sequence_index": 0, "timestamp": 1652802807, "event_accounting_rule_status": "not processed", "validator_index": 1454, "block_number": 15534342 }, "ignored_in_accounting": false, "has_details": false, "grouped_events_num": 2 }, { "entry": { "identifier": 5, "entry_type": "eth deposit event", "asset": "ETH", "amount": "32", "counterparty": "eth2", "group_identifier": "10x2c822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f", "event_subtype": "deposit asset", "event_type": "staking", "location": "ethereum", "location_label": "0xA215887E2CEC81434C16D587709f64603b39b545", "notes": "Deposit 32 ETH to validator 4242", "sequence_index": 15, "timestamp": 1642802807, "event_accounting_rule_status": "not processed", "tx_ref": "0x2c822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f", "address": "0x00000000219ab540356cBB839Cbe05303d7705Fa", "product": "staking", "validator_index": 4242 }, "ignored_in_accounting": false, "has_details": false, "grouped_events_num": 3 }, { "entry": { "identifier": 6, "entry_type": "asset movement event", "timestamp": 1739575021000, "event_type": "deposit", "event_subtype": "deposit asset", "location": "binanceus", "location_label": "Binance US 1", "asset": "eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "amount": "200", "group_identifier": "269b64de6a51caa372a3b455341a41a9da2ae743794e81011b5da1c3b6e1195b", "sequence_index": 0, "extra_data": { "address": "0x29aE5D9A1f28f82c358f8DF5A029bC0D5452b66E", "transaction_id": "0x94a0c141c92b5acbad63aad1edea819a4aba2a39c01203eadd537436b3dd6a63" }, "user_notes": "From my metamask wallet", "auto_notes": "Deposit 200 USDC to Binance US" }, "event_accounting_rule_status": "has rule" }, { "entry": { "identifier": 7, "entry_type": "swap event", "timestamp": 1732150909806, "event_type": "trade", "event_subtype": "spend", "location": "kraken", "location_label": null, "asset": "USD", "amount": "32.2400", "group_identifier": "9e0bfb56dbe8c3d4d3a71584740826df3f901cb0c55a11ee33887afefc7a99d7", "sequence_index": 0, "extra_data": null, "auto_notes": "Swap 32.2400 USD in Kraken" }, "grouped_events_num": 3, "event_accounting_rule_status": "has rule" }, { "entry": { "identifier": 8, "entry_type": "swap event", "timestamp": 1732150909806, "event_type": "trade", "event_subtype": "receive", "location": "kraken", "location_label": null, "asset": "XMR", "amount": "0.2000496400", "group_identifier": "9e0bfb56dbe8c3d4d3a71584740826df3f901cb0c55a11ee33887afefc7a99d7", "sequence_index": 1, "extra_data": null, "auto_notes": "Receive 0.2000496400 XMR after a swap in Kraken" }, "grouped_events_num": 3, "event_accounting_rule_status": "processed" }, { "entry": { "identifier": 9, "entry_type": "swap event", "timestamp": 1732150909806, "event_type": "trade", "event_subtype": "fee", "location": "kraken", "location_label": null, "asset": "USD", "amount": "0.1290", "group_identifier": "9e0bfb56dbe8c3d4d3a71584740826df3f901cb0c55a11ee33887afefc7a99d7", "sequence_index": 2, "extra_data": null, "auto_notes": "Spend 0.1290 USD as Kraken swap fee" }, "grouped_events_num": 3, "event_accounting_rule_status": "processed" }, [{ "entry": { "timestamp": 1569924575000, "event_type": "multi trade", "event_subtype": "spend", "location": "ethereum", "location_label": null, "asset": "ETH", "amount": "0.123", "identifier": 10, "entry_type": "evm swap event", "group_identifier": "10x8d822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f", "sequence_index": 5, "extra_data": null, "tx_ref": "0x8d822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f", "counterparty": null, "product": null, "address": null }, "event_accounting_rule_status": "not processed" }, { "entry": { "timestamp": 1569924575000, "event_type": "multi trade", "event_subtype": "spend", "location": "ethereum", "location_label": null, "asset": "eip155:1/erc20:0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599", "amount": "0.0032", "identifier": 7, "entry_type": "evm swap event", "group_identifier": "10x8d822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f", "sequence_index": 6, "extra_data": null, "tx_ref": "0x8d822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f", "counterparty": null, "product": null, "address": null }, "event_accounting_rule_status": "not processed" }, { "entry": { "timestamp": 1569924575000, "event_type": "multi trade", "event_subtype": "receive", "location": "ethereum", "location_label": null, "asset": "eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "amount": "120", "identifier": 8, "entry_type": "evm swap event", "group_identifier": "10x8d822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f", "sequence_index": 7, "extra_data": null, "tx_ref": "0x8d822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f", "counterparty": null, "product": null, "address": null }, "event_accounting_rule_status": "not processed" }, { "entry": { "timestamp": 1569924575000, "event_type": "multi trade", "event_subtype": "fee", "location": "ethereum", "location_label": null, "asset": "ETH", "amount": "0.0002", "identifier": 10, "entry_type": "evm swap event", "group_identifier": "10x8d822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f", "sequence_index": 9, "extra_data": null, "tx_ref": "0x8d822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f", "counterparty": null, "product": null, "address": null }, "event_accounting_rule_status": "not processed" }], "entries_found": 95, "entries_limit": 500, "entries_total": 1000 }, "message": "" }
- Response JSON Object:
events (list) – A list of history events, with some events grouped into sub-lists (for instance the spend/receive/fee events making up a swap). Each event is an object comprised of the event entry object and various metadata fields and flags. See below for the complete structure.
events[].entry.identifier (string) – Common key. This is the identifier of a single event.
events[].entry.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".events[].entry.group_identifier (string) – Common key. An 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.
events[].entry.actual_group_identifier (string[optional]) – The actual group identifier of the event as stored in the DB. Used when events from different underlying groups are all joined into a single group for display in the frontend.
events[].entry.sequence_index (int) – Common key. This is an index that tries to provide the order of history entries for a single group_identifier.
events[].entry.timestamp (int) – Common key. The timestamp of the entry
events[].entry.event_accounting_rule_status (string) – Common key. It explains the status of accounting rules for the event. Possible values are:
has rule: Meaning the event has a rule.processed: meaning the event will be processed because it is affected by another event.not processedmeaning it doesn’t have any rule and won’t be processed by accounting.events[].entry.location (string) – Common key. The location of the entry. Such as “ethereum”, “optimism”, etc.
events[].entry.asset (string) – Common key. The asset involved in the event.
events[].entry.amount (object) – Common key. The amount of the asset involved in the event.
events[].entry.event_type (string) – Common key. The type of the event. Valid values are retrieved from the backend.
events[].entry.event_subtype (string) – Common key. The subtype of the event. Valid values are retrieved from the backend.
events[].entry.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.
events[].entry.user_notes (string) – Common key. Custom notes for the event set by the user. Can be missing.
events[].entry.auto_notes (string) – Common key. Autogenerated string description of the event. Can be missing.
events[].entry.tx_ref (string) – Evm event, Solana event & eth deposit key. The transaction hash of the event.
events[].entry.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.
events[].entry.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.
events[].entry.address (string) – Evm event & eth deposit key. This is the address of the contract the event interacts with if there is one.
events[].entry.validator_index (int) – Eth staking (withdrawal + block production + eth deposit) key. The index of the validator related to the event.
events[].entry.is_exit (bool) – Eth withdrawal event key. A boolean denoting if the withdrawal is a full exit or not.
events[].entry.block_number (int) – Eth block event key. An integer representing the number of the block for which the event is made.
events[].entry.extra_data (object) – Optional. Additional data specific to the event type.
events[].states (list) – Optional. List of state tags for the event. Valid states are
customized,profit adjustment,matched,imported from csv.events[].hidden (bool) – Optional. If true, this event should be hidden in the UI due to consolidation of events.
events[].ignored_in_accounting (bool) – Set to true when the user has marked this event as ignored.
events[].has_ignored_assets (bool) – Optional. Set to true when the event group contains ignored assets, indicating that some events may have been excluded by ignored assets filtering.
events[].has_details (bool) – If true, it is possible to call /history/events/details endpoint to retrieve extra information about the event.
events[].grouped_events_num (int) – Optional. Present when
aggregate_by_group_idsis true. The number of events under this group identifier. The consumer has to query this endpoint again withaggregate_by_group_idsset to false and with thegroup_identifiersfilter set to the identifier of the events having more than 1 event.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 successfully 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 event to rotki. For each entry type, the specified arguments are different. The unique identifier for the entry is returned as success.
Example Request:
- PUT /api/(version)/history/events
http
PUT /api/1/history/events HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "entry_type": "history event", "group_identifier": "RE_xxxxxxxxxx", "location": "ethereum", "timestamp": 1569924574, "amount": "1.542", "sequence_index": 162, "event_type": "informational", "event_subtype": "approve", "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "user_notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE" }
curl
curl -i -X PUT http://localhost:5042/api/1/history/events -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"amount": "1.542", "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "entry_type": "history event", "event_subtype": "approve", "event_type": "informational", "group_identifier": "RE_xxxxxxxxxx", "location": "ethereum", "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "sequence_index": 162, "timestamp": 1569924574, "user_notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/history/events --header="Content-Type: application/json;charset=UTF-8" --body-data='{"amount": "1.542", "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "entry_type": "history event", "event_subtype": "approve", "event_type": "informational", "group_identifier": "RE_xxxxxxxxxx", "location": "ethereum", "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "sequence_index": 162, "timestamp": 1569924574, "user_notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE"}'
httpie
echo '{ "amount": "1.542", "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "entry_type": "history event", "event_subtype": "approve", "event_type": "informational", "group_identifier": "RE_xxxxxxxxxx", "location": "ethereum", "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "sequence_index": 162, "timestamp": 1569924574, "user_notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE" }' | 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={'amount': '1.542', 'asset': 'eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359', 'entry_type': 'history event', 'event_subtype': 'approve', 'event_type': 'informational', 'group_identifier': 'RE_xxxxxxxxxx', 'location': 'ethereum', 'location_label': '0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12', 'sequence_index': 162, 'timestamp': 1569924574, 'user_notes': 'Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE'})
- Request JSON Object:
sequence_index (int) – This is an index that tries to provide the order of history entries for a single group_identifier.
location (string) – The location of the entry. Such as “ethereum”, “optimism”, etc.
amount (object) – The amount of the event.
asset (string) – The asset identifier for this entry
group_identifier (string) – The group identifier to be used for the event.
event_type (string) – The main event type of the entry. Possible event types can be seen in the HistoryEventType enum.
event_subtype (string) – The subtype for the entry. Possible event types can be seen in the HistoryEventSubType enum.
location_label (string[optional]) – location_label is a string field that allows to provide more information about the location. For example when we use this structure in blockchains can be used to specify the source address.
user_notes (string[optional]) – This is the user editable part of the description of the event entry in plain text explaining what is being done.
Example Request:
- PUT /api/(version)/history/events
http
PUT /api/1/history/events HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "entry_type": "evm event", "tx_ref": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "group_identifier": "10x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "sequence_index": 162, "timestamp": 1569924574, "location": "ethereum", "event_type": "informational", "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "amount": "1.542", "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "user_notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE", "event_subtype": "approve", "counterparty": "0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE", "extra_data": {} }
curl
curl -i -X PUT http://localhost:5042/api/1/history/events -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"amount": "1.542", "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "counterparty": "0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE", "entry_type": "evm event", "event_subtype": "approve", "event_type": "informational", "extra_data": {}, "group_identifier": "10x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "location": "ethereum", "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "sequence_index": 162, "timestamp": 1569924574, "tx_ref": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "user_notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/history/events --header="Content-Type: application/json;charset=UTF-8" --body-data='{"amount": "1.542", "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "counterparty": "0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE", "entry_type": "evm event", "event_subtype": "approve", "event_type": "informational", "extra_data": {}, "group_identifier": "10x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "location": "ethereum", "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "sequence_index": 162, "timestamp": 1569924574, "tx_ref": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "user_notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE"}'
httpie
echo '{ "amount": "1.542", "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "counterparty": "0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE", "entry_type": "evm event", "event_subtype": "approve", "event_type": "informational", "extra_data": {}, "group_identifier": "10x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "location": "ethereum", "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "sequence_index": 162, "timestamp": 1569924574, "tx_ref": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "user_notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE" }' | 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={'amount': '1.542', 'asset': 'eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359', 'counterparty': '0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE', 'entry_type': 'evm event', 'event_subtype': 'approve', 'event_type': 'informational', 'extra_data': {}, 'group_identifier': '10x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e', 'location': 'ethereum', 'location_label': '0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12', 'sequence_index': 162, 'timestamp': 1569924574, 'tx_ref': '0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e', 'user_notes': 'Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE'})
- Request JSON Object:
tx_ref (string) – This is the transaction hash of the evm event
group_identifier (string[optional]) – The group identifier to be used for the event.
sequence_index (int) – This is an index that tries to provide the order of history entries for a single group_identifier.
location (string) – The location of the entry. Such as “ethereum”, “optimism”, etc.
amount (object) – The amount of the event.
asset (string) – The asset identifier for this entry
event_type (string) –
The main event type of the entry. Possible event types can be seen in the HistoryEventType enum.
event_subtype (string) –
The subtype for the entry. Possible event types can be seen in the HistoryEventSubType enum.
location_label (string[optional]) – location_label is a string field that allows to provide more information about the location. For example when we use this structure in blockchains can be used to specify the source address.
user_notes (string[optional]) – This is the user editable part of the description of the event entry in plain text explaining what is being done.
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.
product (string[optional]) – A defi product that this event is associated with (pool, gauge, etc).
address (string[optional]) – Any relevant address that this event interacted with.
extra_data (object[optional]) – An object containing any other data to be stored.
Example Request:
- PUT /api/(version)/history/events
http
PUT /api/1/history/events HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "entry_type": "eth block event", "group_identifier": "BLOCK_11", "timestamp": 1569924574, "amount": "1.542", "block_number": 11, "validator_index": 1, "fee_recipient": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "is_mev_reward": true }
curl
curl -i -X PUT http://localhost:5042/api/1/history/events -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"amount": "1.542", "block_number": 11, "entry_type": "eth block event", "fee_recipient": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "group_identifier": "BLOCK_11", "is_mev_reward": true, "timestamp": 1569924574, "validator_index": 1}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/history/events --header="Content-Type: application/json;charset=UTF-8" --body-data='{"amount": "1.542", "block_number": 11, "entry_type": "eth block event", "fee_recipient": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "group_identifier": "BLOCK_11", "is_mev_reward": true, "timestamp": 1569924574, "validator_index": 1}'
httpie
echo '{ "amount": "1.542", "block_number": 11, "entry_type": "eth block event", "fee_recipient": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "group_identifier": "BLOCK_11", "is_mev_reward": true, "timestamp": 1569924574, "validator_index": 1 }' | http PUT http://localhost:5042/api/1/history/events Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/history/events', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'amount': '1.542', 'block_number': 11, 'entry_type': 'eth block event', 'fee_recipient': '0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12', 'group_identifier': 'BLOCK_11', 'is_mev_reward': True, 'timestamp': 1569924574, 'validator_index': 1})
- Request JSON Object:
group_identifier (string[optional]) – The group identifier to be used for the event.
amount (object) – The amount of the event.
block_number (int) – This is the number of the block where the event took place.
validator_index (int) – This is the index of the validator.
fee_recipient (string) – an evm address field to specify the fee recipient in an “eth block event”.
is_mev_reward (bool) – true if the “eth block event” is an mev reward event.
Example Request:
- PUT /api/(version)/history/events
http
PUT /api/1/history/events HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "entry_type": "eth deposit event", "timestamp": 1569924574, "amount": "1.542", "tx_ref": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "group_identifier": "RE_xxxxxxxxxx", "validator_index": 1, "sequence_index": 162, "depositor": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "extra_data": {} }
curl
curl -i -X PUT http://localhost:5042/api/1/history/events -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"amount": "1.542", "depositor": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "entry_type": "eth deposit event", "extra_data": {}, "group_identifier": "RE_xxxxxxxxxx", "sequence_index": 162, "timestamp": 1569924574, "tx_ref": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "validator_index": 1}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/history/events --header="Content-Type: application/json;charset=UTF-8" --body-data='{"amount": "1.542", "depositor": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "entry_type": "eth deposit event", "extra_data": {}, "group_identifier": "RE_xxxxxxxxxx", "sequence_index": 162, "timestamp": 1569924574, "tx_ref": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "validator_index": 1}'
httpie
echo '{ "amount": "1.542", "depositor": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "entry_type": "eth deposit event", "extra_data": {}, "group_identifier": "RE_xxxxxxxxxx", "sequence_index": 162, "timestamp": 1569924574, "tx_ref": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "validator_index": 1 }' | http PUT http://localhost:5042/api/1/history/events Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/history/events', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'amount': '1.542', 'depositor': '0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12', 'entry_type': 'eth deposit event', 'extra_data': {}, 'group_identifier': 'RE_xxxxxxxxxx', 'sequence_index': 162, 'timestamp': 1569924574, 'tx_ref': '0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e', 'validator_index': 1})
- Request JSON Object:
tx_ref (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 group_identifier.
amount (object) – The amount of the event.
validator_index (int) – This is the index of the validator.
group_identifier (string[optional]) – The group identifier to be used for the event.
depositor (string) – an evm address field to specify the depositor in an “eth deposit event”.
extra_data (object[optional]) – An object containing any other data to be stored.
Example Request:
- PUT /api/(version)/history/events
http
PUT /api/1/history/events HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "entry_type": "eth withdrawal event", "timestamp": 1569924574, "amount": "1.542", "is_exit": true, "validator_index": 1, "withdrawal_address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "group_identifier": "EW_XX_XXXXX" }
curl
curl -i -X PUT http://localhost:5042/api/1/history/events -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"amount": "1.542", "entry_type": "eth withdrawal event", "group_identifier": "EW_XX_XXXXX", "is_exit": true, "timestamp": 1569924574, "validator_index": 1, "withdrawal_address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/history/events --header="Content-Type: application/json;charset=UTF-8" --body-data='{"amount": "1.542", "entry_type": "eth withdrawal event", "group_identifier": "EW_XX_XXXXX", "is_exit": true, "timestamp": 1569924574, "validator_index": 1, "withdrawal_address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12"}'
httpie
echo '{ "amount": "1.542", "entry_type": "eth withdrawal event", "group_identifier": "EW_XX_XXXXX", "is_exit": true, "timestamp": 1569924574, "validator_index": 1, "withdrawal_address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12" }' | http PUT http://localhost:5042/api/1/history/events Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/history/events', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'amount': '1.542', 'entry_type': 'eth withdrawal event', 'group_identifier': 'EW_XX_XXXXX', 'is_exit': True, 'timestamp': 1569924574, 'validator_index': 1, 'withdrawal_address': '0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12'})
- Request JSON Object:
group_identifier (string[optional]) – The group identifier to be used for the event.
amount (object) – The amount of the event.
validator_index (int) – This is the index of the validator.
withdrawal_address (string) – an evm address field to specify the withdrawer in an “eth withdrawal event”.
is_exit (bool) – true if the “eth withdrawal event” is an exit event.
Example Request:
- PUT /api/(version)/history/events
http
PUT /api/1/history/events HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "entry_type": "solana event", "tx_ref": "5j7s8K3nP9mL6wR2vT4xQ1zN8bY7cD5fE9gH2jK4mL6nP8rS3tV5wX7yZ9aB1cD3eF5gH7jK9mL1nP3rS5tV7wX9yZ", "timestamp": 1569924575, "amount": "1.5", "sequence_index": 1, "event_type": "trade", "event_subtype": "receive", "asset": "SOL", "location_label": "7Np41oeYqPefeNQEHSv1UDhYrehxin3NStESwCU85j7W", "user_notes": "received sol from swap" }
curl
curl -i -X PUT http://localhost:5042/api/1/history/events -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"amount": "1.5", "asset": "SOL", "entry_type": "solana event", "event_subtype": "receive", "event_type": "trade", "location_label": "7Np41oeYqPefeNQEHSv1UDhYrehxin3NStESwCU85j7W", "sequence_index": 1, "timestamp": 1569924575, "tx_ref": "5j7s8K3nP9mL6wR2vT4xQ1zN8bY7cD5fE9gH2jK4mL6nP8rS3tV5wX7yZ9aB1cD3eF5gH7jK9mL1nP3rS5tV7wX9yZ", "user_notes": "received sol from swap"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/history/events --header="Content-Type: application/json;charset=UTF-8" --body-data='{"amount": "1.5", "asset": "SOL", "entry_type": "solana event", "event_subtype": "receive", "event_type": "trade", "location_label": "7Np41oeYqPefeNQEHSv1UDhYrehxin3NStESwCU85j7W", "sequence_index": 1, "timestamp": 1569924575, "tx_ref": "5j7s8K3nP9mL6wR2vT4xQ1zN8bY7cD5fE9gH2jK4mL6nP8rS3tV5wX7yZ9aB1cD3eF5gH7jK9mL1nP3rS5tV7wX9yZ", "user_notes": "received sol from swap"}'
httpie
echo '{ "amount": "1.5", "asset": "SOL", "entry_type": "solana event", "event_subtype": "receive", "event_type": "trade", "location_label": "7Np41oeYqPefeNQEHSv1UDhYrehxin3NStESwCU85j7W", "sequence_index": 1, "timestamp": 1569924575, "tx_ref": "5j7s8K3nP9mL6wR2vT4xQ1zN8bY7cD5fE9gH2jK4mL6nP8rS3tV5wX7yZ9aB1cD3eF5gH7jK9mL1nP3rS5tV7wX9yZ", "user_notes": "received sol from swap" }' | 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={'amount': '1.5', 'asset': 'SOL', 'entry_type': 'solana event', 'event_subtype': 'receive', 'event_type': 'trade', 'location_label': '7Np41oeYqPefeNQEHSv1UDhYrehxin3NStESwCU85j7W', 'sequence_index': 1, 'timestamp': 1569924575, 'tx_ref': '5j7s8K3nP9mL6wR2vT4xQ1zN8bY7cD5fE9gH2jK4mL6nP8rS3tV5wX7yZ9aB1cD3eF5gH7jK9mL1nP3rS5tV7wX9yZ', 'user_notes': 'received sol from swap'})
- Request JSON Object:
tx_ref (string) – This is the transaction signature of the solana event
sequence_index (int) – This is an index that tries to provide the order of history entries for a single group_identifier.
amount (object) – The amount of the event.
asset (string) – The asset identifier for this entry
event_type (string) –
The main event type of the entry. Possible event types can be seen in the HistoryEventType enum.
event_subtype (string) –
The subtype for the entry. Possible event types can be seen in the HistoryEventSubType enum.
group_identifier (string[optional]) – The group identifier to be used for the event.
location_label (string[optional]) – location_label is a string field that allows to provide more information about the location. For example when we use this structure in blockchains can be used to specify the source address.
user_notes (string[optional]) – This is the user editable part of the description of the event entry in plain text explaining what is being done.
counterparty (string[optional]) – An identifier for a potential counterparty of the event entry. For a send it’s the target. For a receive it’s the sender. For bridged transfer it’s the bridge’s network identifier. For a protocol interaction it’s the protocol.
address (string[optional]) – Any relevant address that this event interacted with.
extra_data (object[optional]) – An object containing any other data to be stored.
Example Request:
- PUT /api/(version)/history/events
http
PUT /api/1/history/events HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "entry_type": "asset movement event", "event_subtype": "receive", "timestamp": 1569924574, "amount": "0.5", "asset": "ETH", "location": "binance", "fee": "0.001", "fee_asset": "ETH", "address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "transaction_id": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "user_notes": ["Example note", ""], "group_identifier": "AM_xxxxxxxxxx" }
curl
curl -i -X PUT http://localhost:5042/api/1/history/events -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "amount": "0.5", "asset": "ETH", "entry_type": "asset movement event", "event_subtype": "receive", "fee": "0.001", "fee_asset": "ETH", "group_identifier": "AM_xxxxxxxxxx", "location": "binance", "timestamp": 1569924574, "transaction_id": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "user_notes": ["Example note", ""]}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/history/events --header="Content-Type: application/json;charset=UTF-8" --body-data='{"address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "amount": "0.5", "asset": "ETH", "entry_type": "asset movement event", "event_subtype": "receive", "fee": "0.001", "fee_asset": "ETH", "group_identifier": "AM_xxxxxxxxxx", "location": "binance", "timestamp": 1569924574, "transaction_id": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "user_notes": ["Example note", ""]}'
httpie
echo '{ "address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "amount": "0.5", "asset": "ETH", "entry_type": "asset movement event", "event_subtype": "receive", "fee": "0.001", "fee_asset": "ETH", "group_identifier": "AM_xxxxxxxxxx", "location": "binance", "timestamp": 1569924574, "transaction_id": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "user_notes": [ "Example note", "" ] }' | 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={'address': '0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12', 'amount': '0.5', 'asset': 'ETH', 'entry_type': 'asset movement event', 'event_subtype': 'receive', 'fee': '0.001', 'fee_asset': 'ETH', 'group_identifier': 'AM_xxxxxxxxxx', 'location': 'binance', 'timestamp': 1569924574, 'transaction_id': '0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e', 'user_notes': ['Example note', '']})
- Request JSON Object:
event_subtype (string) – The direction subtype of the movement. Must be
"receive"or"spend".amount (object) – The amount being moved.
asset (string) – The identifier of the asset being moved (e.g. “ETH”, “BTC”)
location (string) – The location/exchange where the movement occurred
fee (string[optional]) – The fee amount charged for the movement. If provided, fee_asset must also be provided
fee_asset (string[optional]) – The identifier of the asset in which the fee was paid. If provided, fee must also be provided
address (string[optional]) – The address involved in the movement
transaction_id (string[optional]) – The transaction hash of the movement.
unique_id (string[optional]) – A unique identifier for this asset movement used in conjunction with the location to generate the group_identifier. It’s generally the uuid of the event in the exchange.
group_identifier (string[optional]) – Custom identifier for the event (overrides the value generated from unique_id and location)
- Response JSON Object:
user_notes[optional] (list) – Custom notes for each of the underlying events. Each note will be appended after the autogenerated event description.
Example Request:
- PUT /api/(version)/history/events
http
PUT /api/1/history/events HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "entry_type": "swap event", "timestamp": 1569924576000, "location": "binance", "spend_amount": "0.01", "spend_asset": "ETH", "receive_amount": "20", "receive_asset": "USD", "fees": [{ "amount": "0.000004", "asset": "ETH" }], "unique_id": "xxxxxxxxx", "user_notes": ["Example note", "", ""] }
curl
curl -i -X PUT http://localhost:5042/api/1/history/events -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"entry_type": "swap event", "fees": [{"amount": "0.000004", "asset": "ETH"}], "location": "binance", "receive_amount": "20", "receive_asset": "USD", "spend_amount": "0.01", "spend_asset": "ETH", "timestamp": 1569924576000, "unique_id": "xxxxxxxxx", "user_notes": ["Example note", "", ""]}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/history/events --header="Content-Type: application/json;charset=UTF-8" --body-data='{"entry_type": "swap event", "fees": [{"amount": "0.000004", "asset": "ETH"}], "location": "binance", "receive_amount": "20", "receive_asset": "USD", "spend_amount": "0.01", "spend_asset": "ETH", "timestamp": 1569924576000, "unique_id": "xxxxxxxxx", "user_notes": ["Example note", "", ""]}'
httpie
echo '{ "entry_type": "swap event", "fees": [ { "amount": "0.000004", "asset": "ETH" } ], "location": "binance", "receive_amount": "20", "receive_asset": "USD", "spend_amount": "0.01", "spend_asset": "ETH", "timestamp": 1569924576000, "unique_id": "xxxxxxxxx", "user_notes": [ "Example note", "", "" ] }' | 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={'entry_type': 'swap event', 'fees': [{'amount': '0.000004', 'asset': 'ETH'}], 'location': 'binance', 'receive_amount': '20', 'receive_asset': 'USD', 'spend_amount': '0.01', 'spend_asset': 'ETH', 'timestamp': 1569924576000, 'unique_id': 'xxxxxxxxx', 'user_notes': ['Example note', '', '']})
- Request JSON Object:
location (string) – The location/exchange where the swap occurred
spend_amount (string) – The amount being spent
spend_asset (string) – The identifier of the asset being spent (e.g. “USD”, “BTC”)
receive_amount (string) – The amount being received
receive_asset (string) – The identifier of the asset being received (e.g. “USD”, “BTC”)
fees (list[optional]) – List of objects for each fee associated with the swap containing the
amountandassetof each fee.unique_id (string[optional]) – A unique identifier for this swap used in conjunction with the location to generate the event_identifier. It’s generally the uuid of the event in the exchange if its an exchange event.
group_identifier (string[optional]) – Custom identifier for the event (overrides the value generated from unique_id and location)
location_label (string[optional]) – A string field that provides more information about the location. For swaps this is the name of the specific exchange where the swap occurred (for instance “Kraken 1”)
- Response JSON Object:
user_notes[optional] (list) – Custom notes for each of the underlying events. Each note will be appended after the autogenerated event description.
Example Request:
- PUT /api/(version)/history/events
http
PUT /api/1/history/events HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "entry_type": "evm swap event", "timestamp": 1569924575000, "location": "ethereum", "spend": [{ "amount": "0.16", "asset": "ETH", "user_notes": "Swap 0.16 ETH", "location_label": "0x6e15887E2CEC81434C16D587709f64603b39b545" }, { "amount": "0.07", "asset": "eip155:1/erc20:0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "user_notes": "Swap 0.07 WETH", "location_label": "0x6e15887E2CEC81434C16D587709f64603b39b545" }], "receive": [{ "amount": "0.003", "asset": "eip155:1/erc20:0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599", "user_notes": "Receive 0.003 WBTC after swap", "location_label": "0x213B71067BE19cd5dBea3600Db0626859Ff15E78" }], "fee": [{ "amount": "0.0002", "asset": "ETH", "user_notes": "Pay 0.0002 ETH as swap fee", "location_label": "0x6e15887E2CEC81434C16D587709f64603b39b545" }], "sequence_index": 0, "tx_ref": "0x8d822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f", "counterparty": "some counterparty", "address": "0xA090e606E30bD747d4E6245a1517EbE430F0057e" }
curl
curl -i -X PUT http://localhost:5042/api/1/history/events -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0xA090e606E30bD747d4E6245a1517EbE430F0057e", "counterparty": "some counterparty", "entry_type": "evm swap event", "fee": [{"amount": "0.0002", "asset": "ETH", "user_notes": "Pay 0.0002 ETH as swap fee", "location_label": "0x6e15887E2CEC81434C16D587709f64603b39b545"}], "location": "ethereum", "receive": [{"amount": "0.003", "asset": "eip155:1/erc20:0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599", "user_notes": "Receive 0.003 WBTC after swap", "location_label": "0x213B71067BE19cd5dBea3600Db0626859Ff15E78"}], "sequence_index": 0, "spend": [{"amount": "0.16", "asset": "ETH", "user_notes": "Swap 0.16 ETH", "location_label": "0x6e15887E2CEC81434C16D587709f64603b39b545"}, {"amount": "0.07", "asset": "eip155:1/erc20:0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "user_notes": "Swap 0.07 WETH", "location_label": "0x6e15887E2CEC81434C16D587709f64603b39b545"}], "timestamp": 1569924575000, "tx_ref": "0x8d822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/history/events --header="Content-Type: application/json;charset=UTF-8" --body-data='{"address": "0xA090e606E30bD747d4E6245a1517EbE430F0057e", "counterparty": "some counterparty", "entry_type": "evm swap event", "fee": [{"amount": "0.0002", "asset": "ETH", "user_notes": "Pay 0.0002 ETH as swap fee", "location_label": "0x6e15887E2CEC81434C16D587709f64603b39b545"}], "location": "ethereum", "receive": [{"amount": "0.003", "asset": "eip155:1/erc20:0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599", "user_notes": "Receive 0.003 WBTC after swap", "location_label": "0x213B71067BE19cd5dBea3600Db0626859Ff15E78"}], "sequence_index": 0, "spend": [{"amount": "0.16", "asset": "ETH", "user_notes": "Swap 0.16 ETH", "location_label": "0x6e15887E2CEC81434C16D587709f64603b39b545"}, {"amount": "0.07", "asset": "eip155:1/erc20:0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "user_notes": "Swap 0.07 WETH", "location_label": "0x6e15887E2CEC81434C16D587709f64603b39b545"}], "timestamp": 1569924575000, "tx_ref": "0x8d822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f"}'
httpie
echo '{ "address": "0xA090e606E30bD747d4E6245a1517EbE430F0057e", "counterparty": "some counterparty", "entry_type": "evm swap event", "fee": [ { "amount": "0.0002", "asset": "ETH", "location_label": "0x6e15887E2CEC81434C16D587709f64603b39b545", "user_notes": "Pay 0.0002 ETH as swap fee" } ], "location": "ethereum", "receive": [ { "amount": "0.003", "asset": "eip155:1/erc20:0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599", "location_label": "0x213B71067BE19cd5dBea3600Db0626859Ff15E78", "user_notes": "Receive 0.003 WBTC after swap" } ], "sequence_index": 0, "spend": [ { "amount": "0.16", "asset": "ETH", "location_label": "0x6e15887E2CEC81434C16D587709f64603b39b545", "user_notes": "Swap 0.16 ETH" }, { "amount": "0.07", "asset": "eip155:1/erc20:0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "location_label": "0x6e15887E2CEC81434C16D587709f64603b39b545", "user_notes": "Swap 0.07 WETH" } ], "timestamp": 1569924575000, "tx_ref": "0x8d822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f" }' | 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={'address': '0xA090e606E30bD747d4E6245a1517EbE430F0057e', 'counterparty': 'some counterparty', 'entry_type': 'evm swap event', 'fee': [{'amount': '0.0002', 'asset': 'ETH', 'user_notes': 'Pay 0.0002 ETH as swap fee', 'location_label': '0x6e15887E2CEC81434C16D587709f64603b39b545'}], 'location': 'ethereum', 'receive': [{'amount': '0.003', 'asset': 'eip155:1/erc20:0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599', 'user_notes': 'Receive 0.003 WBTC after swap', 'location_label': '0x213B71067BE19cd5dBea3600Db0626859Ff15E78'}], 'sequence_index': 0, 'spend': [{'amount': '0.16', 'asset': 'ETH', 'user_notes': 'Swap 0.16 ETH', 'location_label': '0x6e15887E2CEC81434C16D587709f64603b39b545'}, {'amount': '0.07', 'asset': 'eip155:1/erc20:0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', 'user_notes': 'Swap 0.07 WETH', 'location_label': '0x6e15887E2CEC81434C16D587709f64603b39b545'}], 'timestamp': 1569924575000, 'tx_ref': '0x8d822b87407698dd869e830699782291155d0276c5a7e5179cb173608554e41f'})
Sub-event schema (objects in the
spend,receive, andfeelists):- Request JSON Object:
identifier (list[int][optional]) – Identifier of the existing event (only used when editing).
amount (string) – The amounts being spent
asset (string) – The identifiers of the assets being spent (e.g. “USD”, “BTC”)
user_notes (string[optional]) – Custom notes for the event
location_label (string[optional]) – The user address associated with the event
Main schema:
- Request JSON Object:
tx_ref (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 group_identifier. This value will be the index of the first event in the swap event group, and other events in the group will be given consecutive indexes after this value.
location (string) – The location/exchange where the swap occurred
spend (list[object]) – List of spend events. See above for sub-event object specification.
receive (list[object]) – List of receive events.
fee (list[object][optional]) – List of fee events.
group_identifier (string[optional]) – Custom identifier for the event.
counterparty (string[optional]) – An identifier for a potential counterparty of the event entry. For evm swaps this is the protocol that the swap interacted with.
product (string[optional]) – A defi product that this event is associated with (pool, gauge, etc).
address (string[optional]) – Any relevant address that this event interacted with.
extra_data (object[optional]) – An object containing any other data to be stored.
Example Request:
- PUT /api/(version)/history/events
http
PUT /api/1/history/events HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "entry_type": "solana swap event", "timestamp": 1569924575000, "spend": [{ "amount": "100", "asset": "solana/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "user_notes": "Swap 100 USDC", "location_label": "7Np41oeYqPefeNQEHSv1UDhYrehxin3NStESwCU85j7W" }, { "amount": "0.5", "asset": "SOL", "location_label": "8Qp42peZrPfgfORFITw2VEiZsfiyjQOUyDxFTxDVk8Y" }], "receive": [{ "amount": "2.5", "asset": "solana/token:So11111111111111111111111111111111111111112", "location_label": "JUP4LHuHiLdG1qZfzN5JYKmZvSd5mE1kEWy1UQ8K8oP" }], "fee": [{ "amount": "0.001", "asset": "SOL" }], "sequence_index": 0, "tx_ref": "5BeydmN8zcpWknvki96jpQKeVz5Zdm3hS9zfzPY3MQGMPS66RjHHaKYbzt1YQmcUGcFvP8BZsXzSWt9kPDSo4o2t", "counterparty": "jupiter", "address": "7Np41oeYqPefeNQEHSv1UDhYrehxin3NStESwCU85j7W" }
curl
curl -i -X PUT http://localhost:5042/api/1/history/events -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "7Np41oeYqPefeNQEHSv1UDhYrehxin3NStESwCU85j7W", "counterparty": "jupiter", "entry_type": "solana swap event", "fee": [{"amount": "0.001", "asset": "SOL"}], "receive": [{"amount": "2.5", "asset": "solana/token:So11111111111111111111111111111111111111112", "location_label": "JUP4LHuHiLdG1qZfzN5JYKmZvSd5mE1kEWy1UQ8K8oP"}], "sequence_index": 0, "spend": [{"amount": "100", "asset": "solana/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "user_notes": "Swap 100 USDC", "location_label": "7Np41oeYqPefeNQEHSv1UDhYrehxin3NStESwCU85j7W"}, {"amount": "0.5", "asset": "SOL", "location_label": "8Qp42peZrPfgfORFITw2VEiZsfiyjQOUyDxFTxDVk8Y"}], "timestamp": 1569924575000, "tx_ref": "5BeydmN8zcpWknvki96jpQKeVz5Zdm3hS9zfzPY3MQGMPS66RjHHaKYbzt1YQmcUGcFvP8BZsXzSWt9kPDSo4o2t"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/history/events --header="Content-Type: application/json;charset=UTF-8" --body-data='{"address": "7Np41oeYqPefeNQEHSv1UDhYrehxin3NStESwCU85j7W", "counterparty": "jupiter", "entry_type": "solana swap event", "fee": [{"amount": "0.001", "asset": "SOL"}], "receive": [{"amount": "2.5", "asset": "solana/token:So11111111111111111111111111111111111111112", "location_label": "JUP4LHuHiLdG1qZfzN5JYKmZvSd5mE1kEWy1UQ8K8oP"}], "sequence_index": 0, "spend": [{"amount": "100", "asset": "solana/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "user_notes": "Swap 100 USDC", "location_label": "7Np41oeYqPefeNQEHSv1UDhYrehxin3NStESwCU85j7W"}, {"amount": "0.5", "asset": "SOL", "location_label": "8Qp42peZrPfgfORFITw2VEiZsfiyjQOUyDxFTxDVk8Y"}], "timestamp": 1569924575000, "tx_ref": "5BeydmN8zcpWknvki96jpQKeVz5Zdm3hS9zfzPY3MQGMPS66RjHHaKYbzt1YQmcUGcFvP8BZsXzSWt9kPDSo4o2t"}'
httpie
echo '{ "address": "7Np41oeYqPefeNQEHSv1UDhYrehxin3NStESwCU85j7W", "counterparty": "jupiter", "entry_type": "solana swap event", "fee": [ { "amount": "0.001", "asset": "SOL" } ], "receive": [ { "amount": "2.5", "asset": "solana/token:So11111111111111111111111111111111111111112", "location_label": "JUP4LHuHiLdG1qZfzN5JYKmZvSd5mE1kEWy1UQ8K8oP" } ], "sequence_index": 0, "spend": [ { "amount": "100", "asset": "solana/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "location_label": "7Np41oeYqPefeNQEHSv1UDhYrehxin3NStESwCU85j7W", "user_notes": "Swap 100 USDC" }, { "amount": "0.5", "asset": "SOL", "location_label": "8Qp42peZrPfgfORFITw2VEiZsfiyjQOUyDxFTxDVk8Y" } ], "timestamp": 1569924575000, "tx_ref": "5BeydmN8zcpWknvki96jpQKeVz5Zdm3hS9zfzPY3MQGMPS66RjHHaKYbzt1YQmcUGcFvP8BZsXzSWt9kPDSo4o2t" }' | 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={'address': '7Np41oeYqPefeNQEHSv1UDhYrehxin3NStESwCU85j7W', 'counterparty': 'jupiter', 'entry_type': 'solana swap event', 'fee': [{'amount': '0.001', 'asset': 'SOL'}], 'receive': [{'amount': '2.5', 'asset': 'solana/token:So11111111111111111111111111111111111111112', 'location_label': 'JUP4LHuHiLdG1qZfzN5JYKmZvSd5mE1kEWy1UQ8K8oP'}], 'sequence_index': 0, 'spend': [{'amount': '100', 'asset': 'solana/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', 'user_notes': 'Swap 100 USDC', 'location_label': '7Np41oeYqPefeNQEHSv1UDhYrehxin3NStESwCU85j7W'}, {'amount': '0.5', 'asset': 'SOL', 'location_label': '8Qp42peZrPfgfORFITw2VEiZsfiyjQOUyDxFTxDVk8Y'}], 'timestamp': 1569924575000, 'tx_ref': '5BeydmN8zcpWknvki96jpQKeVz5Zdm3hS9zfzPY3MQGMPS66RjHHaKYbzt1YQmcUGcFvP8BZsXzSWt9kPDSo4o2t'})
Sub-event schema (objects in the
spend,receive, andfeelists):- Request JSON Object:
identifier (list[int][optional]) – Identifier of the existing event (only used when editing).
amount (string) – The amounts being spent
asset (string) – The identifiers of the assets being spent (e.g. “USD”, “BTC”)
user_notes (string[optional]) – Custom notes for the event
location_label (string[optional]) – The user address associated with the event
Main schema:
- Request JSON Object:
tx_ref (string) – This is the transaction signature of the solana event
sequence_index (int) – This is an index that tries to provide the order of history entries for a single group_identifier. This value will be the index of the first event in the swap event group, and other events in the group will be given consecutive indexes after this value.
spend (list[object]) – List of spend events. See above for sub-event object specification.
receive (list[object]) – List of receive events.
fee (list[object][optional]) – List of fee events.
group_identifier (string[optional]) – Custom identifier for the event.
counterparty (string[optional]) – An identifier for a potential counterparty of the event entry. For solana swaps this is the protocol that the swap interacted with.
address (string[optional]) – Any relevant address that this event interacted with.
- Request JSON Object:
entry_type (string) – The type of the event that will be processed. Different validation is used based on the value for this field. Possible values are:
"history event","evm event","eth withdrawal event","eth block event","eth deposit event","asset movement event","swap event","evm swap event","solana swap event".timestamp (int) – The timestamp of the entry in milliseconds.
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 { "entry_type": "evm event", "identifier": 243, "group_identifier": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "sequence_index": 162, "timestamp": 1569924574, "location": "blockchain", "event_type": "informational", "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "amount": "1.542", "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "user_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 '{"amount": "1.542", "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "counterparty": "0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE", "entry_type": "evm event", "event_subtype": "approve", "event_type": "informational", "group_identifier": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "identifier": 243, "location": "blockchain", "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "sequence_index": 162, "timestamp": 1569924574, "user_notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE"}'
wget
wget -S -O- --method=PATCH http://localhost:5042/api/1/history/events --header="Content-Type: application/json;charset=UTF-8" --body-data='{"amount": "1.542", "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "counterparty": "0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE", "entry_type": "evm event", "event_subtype": "approve", "event_type": "informational", "group_identifier": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "identifier": 243, "location": "blockchain", "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "sequence_index": 162, "timestamp": 1569924574, "user_notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE"}'
httpie
echo '{ "amount": "1.542", "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "counterparty": "0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE", "entry_type": "evm event", "event_subtype": "approve", "event_type": "informational", "group_identifier": "0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e", "identifier": 243, "location": "blockchain", "location_label": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "sequence_index": 162, "timestamp": 1569924574, "user_notes": "Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE" }' | 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={'amount': '1.542', 'asset': 'eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359', 'counterparty': '0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE', 'entry_type': 'evm event', 'event_subtype': 'approve', 'event_type': 'informational', 'group_identifier': '0x64f1982504ab714037467fdd45d3ecf5a6356361403fc97dd325101d8c038c4e', 'identifier': 243, 'location': 'blockchain', 'location_label': '0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12', 'sequence_index': 162, 'timestamp': 1569924574, 'user_notes': 'Approve 1 SAI of 0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12 for spending by 0xdf869FAD6dB91f437B59F1EdEFab319493D4C4cE'})
The request object uses all the same arguments for each entry type as the add event endpoint, with the addition of the identifier which signifies which entry will be edited. When dealing with event types where all the events for an group_identifier are added/edited as a group (such as swap events and asset movements), use the identifier of the primary event in the group, i.e. for asset movements, the identifier of the deposit/withdrawal event, and for swap events, the identifier of the spend event. For events that are edited as a group but may have other events/groups with the same group_identifier (such as evm swap events), specify the identifiers of all the events in the group, for example:
"identifiers": [1,2,3,4]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 history events from the DB for the currently logged in user. Events can be deleted by specific identifiers or by using filter parameters. All provided filters are combined (intersection) to determine which events to delete. At least one filter parameter must be provided to prevent accidental mass deletion. If any of the identifiers are the last for their transaction hash the call fails, unless the
force_deleteargument 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]})
Example Request (delete by filter):
http
DELETE /api/1/history/events HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"asset": "ETH", "from_timestamp": 1609459200}
curl
curl -i -X DELETE http://localhost:5042/api/1/history/events -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"asset": "ETH", "from_timestamp": 1609459200}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/history/events --header="Content-Type: application/json;charset=UTF-8" --body-data='{"asset": "ETH", "from_timestamp": 1609459200}'
httpie
echo '{ "asset": "ETH", "from_timestamp": 1609459200 }' | 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={'asset': 'ETH', 'from_timestamp': 1609459200})
- Request JSON Object:
force_delete (bool) – If true, then even if an event is the last event of a transaction it will be deleted. False by default.
otherargs (object) – Check the documentation of the remaining filter arguments here. Note that
order_by_attributesandascendingare not applicable for deletion.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Status Codes:
200 OK – Events were successfully removed.
400 Bad Request – Provided JSON is in some way malformed or no filter parameters were provided.
409 Conflict – No user is logged in, one of the identifiers does not exist or does not match the provided filters, or one of the identifiers was for the last event in the corresponding transaction hash and force_delete was false.
500 Internal Server Error – Internal rotki error
Exporting History Events
- POST /api/(version)/history/events/export
Note
This endpoint can also be queried asynchronously by using
"async_query": trueDoing a POST on this endpoint with the given filter parameters will export a csv with all history events matching the filter to a file in the provided directory. Only the ‘directory_path’ argument is required. If no filter is used all the events will be exported.
Example Request:
http
POST /api/1/history/events/export HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "directory_path": "/home", "from_timestamp": 1500, "to_timestamp": 999999, "async_query": false }
curl
curl -i -X POST http://localhost:5042/api/1/history/events/export -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": false, "directory_path": "/home", "from_timestamp": 1500, "to_timestamp": 999999}'
wget
wget -S -O- http://localhost:5042/api/1/history/events/export --header="Content-Type: application/json;charset=UTF-8" --post-data='{"async_query": false, "directory_path": "/home", "from_timestamp": 1500, "to_timestamp": 999999}'
httpie
echo '{ "async_query": false, "directory_path": "/home", "from_timestamp": 1500, "to_timestamp": 999999 }' | http POST http://localhost:5042/api/1/history/events/export Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/history/events/export', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': False, 'directory_path': '/home', 'from_timestamp': 1500, 'to_timestamp': 999999})
- Request JSON Object:
match_exact_events (bool) – If set to true only the events that match the filter exactly will be exported otherwise the whole group of events that match the filter will be exported.
directory_path (string) – The directory in which to write the exported CSV file
otherargs (object) – Check the documentation of the remaining arguments here.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message" "", }
- Status Codes:
200 OK – Events successfully exported
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – No user is logged in or failure at event export.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Couldn’t fetch prices for all the events due to being rate limited.
- PUT /api/(version)/history/events/export
Note
This endpoint can also be queried asynchronously by using
"async_query": trueDoing a PUT on this endpoint with the given filter parameters will export a csv with all history events matching the filters that can be downloaded later via the /history/events/export/download endpoint. All arguments are optional. If no filter is used all the events will be downloaded.
Example Request:
http
PUT /api/1/history/events/export HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "from_timestamp": 1500, "to_timestamp": 999999, "async_query": false }
curl
curl -i -X PUT http://localhost:5042/api/1/history/events/export -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": false, "from_timestamp": 1500, "to_timestamp": 999999}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/history/events/export --header="Content-Type: application/json;charset=UTF-8" --body-data='{"async_query": false, "from_timestamp": 1500, "to_timestamp": 999999}'
httpie
echo '{ "async_query": false, "from_timestamp": 1500, "to_timestamp": 999999 }' | http PUT http://localhost:5042/api/1/history/events/export Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/history/events/export', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': False, 'from_timestamp': 1500, 'to_timestamp': 999999})
- Request JSON Object:
order_by_attributes (list[string]) – This is the list of attributes of the transaction by which to order the results.
ascending (list[bool]) – Should the order be ascending? This is the default. If set to false, it will be on descending order.
aggregate_by_group_ids (bool) – A boolean determining if results should be grouped by common group identifiers. If true, the result will return only the first event of each group but also the number of events the group has. Default is false.
from_timestamp (int) – The timestamp from which to start querying. Default is 0.
to_timestamp (int) – The timestamp until which to query. Default is now.
identifiers (list[int]) – List of unique integer identifiers of the history events to retrieve.
group_identifiers (list[string]) – An optional list of group identifiers to filter for.
event_types (list[string]) – An optional list of event types by which to filter the decoded events.
event_subtypes (list[string]) – An optional list of event subtypes by which to filter the decoded events.
location (list) – An optional location name to filter events only for that location.
location_labels (list[string]) – A list of location labels to optionally filter by. Location label is a string field that allows you to provide more information about the location. When used in blockchains, it is used to specify the user’s address. For exchange events, it’s the exchange name assigned by the user.
notes_substring (string) – An optional string to filter events by searching for a substring in the notes field. This searches both user notes and auto-generated notes.
entry_types (object) – An object with two keys named ‘values’ and ‘behavior’. ‘values’ is a list of entry types to optionally filter by. ‘behavior’ is optional and is a string with the value ‘include’ or ‘exclude’ which defines the filtering behavior. It defaults to ‘include’. Entry type is the event category and defines the schema. Possible values are: “history event,” “evm event,” “eth withdrawal event,” “eth block event,” “eth deposit event.”
asset (string) – The asset to optionally filter by.
tx_refs (list[string]) – An optional list of transaction references to filter for. This will make it an EVM/Solana event query.
counterparties (list[string]) – An optional list of counterparties to filter by. List of strings. 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.
addresses (list[string]) – An optional list of EVM addresses to filter by in the set of counterparty addresses. This will make it an EVM/Solana 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": true, "message": "" }
- Status Codes:
200 OK – Events successfully exported
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – No user is logged in or failure at event download.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Couldn’t fetch prices for all the events due to being rate limited.
Downloading Exported History Events
- GET /api/(version)/history/events/export/download
Doing a GET on this endpoint will download the CSV exported in a previous call to the export endpoint and specified here with file_path.
Example Request:
http
GET /api/1/history/events/export/download HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "file_path": "/tmp/tmprg88k0co/history_events.csv" }
curl
curl -i -X GET http://localhost:5042/api/1/history/events/export/download -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"file_path": "/tmp/tmprg88k0co/history_events.csv"}'
wget
wget -S -O- http://localhost:5042/api/1/history/events/export/download --header="Content-Type: application/json;charset=UTF-8" --body-data='{"file_path": "/tmp/tmprg88k0co/history_events.csv"}'
httpie
echo '{ "file_path": "/tmp/tmprg88k0co/history_events.csv" }' | http http://localhost:5042/api/1/history/events/export/download Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/history/events/export/download', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'file_path': '/tmp/tmprg88k0co/history_events.csv'})
- Request JSON Object:
file_path (string) – The CSV file to be downloaded.
Example Response:
HTTP/1.1 200 OK Content-Type: text/csv
- Status Codes:
200 OK – CSV successfully downloaded
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – No user is logged in or failure.
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"
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 successfully
400 Bad Request – Provided JSON is in some way malformed.
403 Forbidden – Logged in user does not have premium and requested a query type that is only available to premium users.
409 Conflict – Module for the given events is not active.
424 Failed Dependency – A required external service API key, such as beaconcha.in, is missing.
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 exchange history events
- POST /api/(version)/history/events/query/exchange
Doing a POST on this endpoint will query latest events for the given exchange and save them in the DB
Example Request:
http
POST /api/1/history/events/query/exchange HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "async_query": true, "name": "Kraken 1", "location": "kraken" }
curl
curl -i -X POST http://localhost:5042/api/1/history/events/query/exchange -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": true, "location": "kraken", "name": "Kraken 1"}'
wget
wget -S -O- http://localhost:5042/api/1/history/events/query/exchange --header="Content-Type: application/json;charset=UTF-8" --post-data='{"async_query": true, "location": "kraken", "name": "Kraken 1"}'
httpie
echo '{ "async_query": true, "location": "kraken", "name": "Kraken 1" }' | http POST http://localhost:5042/api/1/history/events/query/exchange Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/history/events/query/exchange', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': True, 'location': 'kraken', 'name': 'Kraken 1'})
- Request JSON Object:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
location (string) – The location of the exchange to query
name (string) – Optional. The name of the exchange to query. Queries all connected exchanges for the given location when omitted.
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 successfully
400 Bad Request – Provided JSON is in some way malformed.
409 Conflict – Module for the given events is not active or no market pairs are selected (when querying Binance).
500 Internal Server Error – Internal rotki error.
502 Bad Gateway – The exchange api could not be reached or returned an unexpected response.
Re-querying exchange history events in a range
- POST /api/(version)/history/events/query/exchange/range
Re-queries history events for a specific exchange between
start_tsandend_tsand stores only new events.Example Request:
http
POST /api/1/history/events/query/exchange/range HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "async_query": false, "location": "kraken", "name": "Kraken 1", "from_timestamp": 0, "to_timestamp": 1700000000 }
curl
curl -i -X POST http://localhost:5042/api/1/history/events/query/exchange/range -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": false, "from_timestamp": 0, "location": "kraken", "name": "Kraken 1", "to_timestamp": 1700000000}'
wget
wget -S -O- http://localhost:5042/api/1/history/events/query/exchange/range --header="Content-Type: application/json;charset=UTF-8" --post-data='{"async_query": false, "from_timestamp": 0, "location": "kraken", "name": "Kraken 1", "to_timestamp": 1700000000}'
httpie
echo '{ "async_query": false, "from_timestamp": 0, "location": "kraken", "name": "Kraken 1", "to_timestamp": 1700000000 }' | http POST http://localhost:5042/api/1/history/events/query/exchange/range Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/history/events/query/exchange/range', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': False, 'from_timestamp': 0, 'location': 'kraken', 'name': 'Kraken 1', 'to_timestamp': 1700000000})
- Request JSON Object:
async_query (bool) – Optional. Boolean denoting whether this is an asynchronous query or not (defaults to
false)location (string) – Exchange location identifier
name (string) – Name of the exchange entry to query
start_ts (int) – Start timestamp for the re-query (seconds since epoch)
end_ts (int) – End timestamp for the re-query (seconds since epoch)
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "queried_events": 2, "stored_events": 2, "skipped_events": 0, "actual_end_ts": 1700000000 }, "message": "" }
- Response JSON Object:
result.queried_events (int) – Number of events returned by the exchange
result.stored_events (int) – Number of new events stored in the database
result.skipped_events (int) – Number of events skipped because they already exist
result.actual_end_ts (int) – Last timestamp successfully processed
message (str) – Error message if any errors occurred
- Status Codes:
200 OK – Re-query completed successfully
400 Bad Request – Provided JSON is malformed
401 Unauthorized – No user is currently logged in
409 Conflict – Exchange entry is missing or the provided range is invalid
Match exchange asset movements with onchain events
- PUT /api/(version)/history/events/match/asset_movements
Matches exchange asset movement events with corresponding events, or mark the asset movement as having no corresponding event.
Note
This endpoint is only available for premium users
Example Request:
http
PUT /api/1/history/events/match/asset_movements HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "asset_movement": 123, "matched_events": [124] }
curl
curl -i -X PUT http://localhost:5042/api/1/history/events/match/asset_movements -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"asset_movement": 123, "matched_events": [124]}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/history/events/match/asset_movements --header="Content-Type: application/json;charset=UTF-8" --body-data='{"asset_movement": 123, "matched_events": [124]}'
httpie
echo '{ "asset_movement": 123, "matched_events": [ 124 ] }' | http PUT http://localhost:5042/api/1/history/events/match/asset_movements Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/history/events/match/asset_movements', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'asset_movement': 123, 'matched_events': [124]})
- Request JSON Object:
asset_movement (int) – DB identifier of the asset movement to match
matched_events (list[int][optional]) – List of DB identifiers of events to match with the asset movement. The asset movement is marked as having no match if this parameter is omitted or an empty list.
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 matched successfully
400 Bad Request – Provided JSON is in some way malformed
401 Unauthorized – No user is logged in
403 Forbidden – Logged in user does not have premium.
500 Internal Server Error – Internal rotki error
- GET /api/(version)/history/events/match/asset_movements
Get a list of unmatched asset movements group identifiers. This endpoint does not require premium.
Example Request:
http
GET /api/1/history/events/match/asset_movements?only_ignored=false HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET 'http://localhost:5042/api/1/history/events/match/asset_movements?only_ignored=false'
wget
wget -S -O- 'http://localhost:5042/api/1/history/events/match/asset_movements?only_ignored=false'
httpie
http 'http://localhost:5042/api/1/history/events/match/asset_movements?only_ignored=false'
python-requests
requests.get('http://localhost:5042/api/1/history/events/match/asset_movements?only_ignored=false')
- Reqquery bool[optional] only_ignored:
Flag indicating whether to return a list of the ignored asset movements, or the list of all movements that have not been matched or ignored yet.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": [ "ef2fcd9d69e358f184e5aae29f74b39e7613a13eaaae00717bde70a165cfd69f", "b4e1c0d8439c1abc501c2198f7ed86f3047d23caf7b49df6dbaa3d9b1753a934", ], "message": "" }
- Response JSON Object:
result (list) – A list of group identifiers for the unmatched asset movements.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – List of group identifiers returned successfully
400 Bad Request – Provided JSON is in some way malformed
409 Conflict – No user is logged in or failure
500 Internal Server Error – Internal rotki error
- POST /api/(version)/history/events/match/asset_movements
Find possible matching events for an unmatched asset movement.
Note
This endpoint is only available for premium users
Example Request:
http
POST /api/1/history/events/match/asset_movements HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "asset_movement": "ef2fcd9d69e358f184e5aae29f74b39e7613a13eaaae00717bde70a165cfd69f", "time_range": 7200, "only_expected_assets": true, "tolerance": "0.002" }
curl
curl -i -X POST http://localhost:5042/api/1/history/events/match/asset_movements -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"asset_movement": "ef2fcd9d69e358f184e5aae29f74b39e7613a13eaaae00717bde70a165cfd69f", "only_expected_assets": true, "time_range": 7200, "tolerance": "0.002"}'
wget
wget -S -O- http://localhost:5042/api/1/history/events/match/asset_movements --header="Content-Type: application/json;charset=UTF-8" --post-data='{"asset_movement": "ef2fcd9d69e358f184e5aae29f74b39e7613a13eaaae00717bde70a165cfd69f", "only_expected_assets": true, "time_range": 7200, "tolerance": "0.002"}'
httpie
echo '{ "asset_movement": "ef2fcd9d69e358f184e5aae29f74b39e7613a13eaaae00717bde70a165cfd69f", "only_expected_assets": true, "time_range": 7200, "tolerance": "0.002" }' | http POST http://localhost:5042/api/1/history/events/match/asset_movements Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/history/events/match/asset_movements', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'asset_movement': 'ef2fcd9d69e358f184e5aae29f74b39e7613a13eaaae00717bde70a165cfd69f', 'only_expected_assets': True, 'time_range': 7200, 'tolerance': '0.002'})
- Request JSON Object:
asset_movement (string) – Group identifier of the asset movement to find matches for.
time_range (int) – Time range in seconds to search for matches.
only_expected_assets (bool[optional]) – Flag indicating whether to limit the possible matches to only events with assets in the same collection as the asset movement’s asset. True by default.
tolerance (string) – The tolerance value used when matching asset movement amounts. Must be a positive decimal number.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "close_matches": [3, 4], "other_events": [2, 5] }, "message": "" }
- Response JSON Object:
close_matches (list) – List of event identifiers that closely match the asset movement criteria.
other_events (list) – List of other event identifiers within the time range.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – Possible matches returned successfully
400 Bad Request – Provided JSON is in some way malformed or asset movement not found
401 Unauthorized – No user is logged in
403 Forbidden – Logged in user does not have premium.
409 Conflict – Failure
500 Internal Server Error – Internal rotki error
- DELETE /api/(version)/history/events/match/asset_movements
Unlinks matched asset movements, or resets the asset movement to being simply unmatched if the asset movement is marked as having no corresponding event.
Note
This endpoint is only available for premium users
Example Request:
http
DELETE /api/1/history/events/match/asset_movements HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "identifier": 123 }
curl
curl -i -X DELETE http://localhost:5042/api/1/history/events/match/asset_movements -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"identifier": 123}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/history/events/match/asset_movements --header="Content-Type: application/json;charset=UTF-8" --body-data='{"identifier": 123}'
httpie
echo '{ "identifier": 123 }' | http DELETE http://localhost:5042/api/1/history/events/match/asset_movements Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/1/history/events/match/asset_movements', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'identifier': 123})
- Request JSON Object:
identifier (int) – DB identifier of an asset movement or an event matched with an asset movement to unlink.
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 unlinked successfully
400 Bad Request – Provided JSON is in some way malformed
401 Unauthorized – No user is logged in
403 Forbidden – Logged in user does not have premium.
409 Conflict – Failure.
500 Internal Server Error – Internal rotki error
Customized history event duplicates
- GET /api/(version)/history/events/duplicates/customized
Get group identifiers for customized event duplicate candidates.
Supports async execution via the async_query query parameter.
Example Request:
http
GET /api/1/history/events/duplicates/customized?async_query=false HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET 'http://localhost:5042/api/1/history/events/duplicates/customized?async_query=false'
wget
wget -S -O- 'http://localhost:5042/api/1/history/events/duplicates/customized?async_query=false'
httpie
http 'http://localhost:5042/api/1/history/events/duplicates/customized?async_query=false'
python-requests
requests.get('http://localhost:5042/api/1/history/events/duplicates/customized?async_query=false')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "auto_fix_group_ids": [ "0x7f9b1d9b3d6c80b6f699a25f3e91c408155cbff965d0f3a0df4d3a4f8f4b73c7" ], "manual_review_group_ids": [ "0xa8e4c2f6b79a1b9d6288a763dc6243cbce1e2c35c8b65ec79a9d35a1f4ec6a20" ], "ignored_group_ids": [ "0xc3d7e1a5b2f84096dab8e3c7f1a294d5e6b83c71f9a0d2e4b5c6d7e8f9a0b1c2" ] }, "message": "" }
- Reqquery bool[optional] async_query:
Whether to execute as an async task.
- Response JSON Object:
result.auto_fix_group_ids (list) – Group identifiers where a customized EVM/Solana event has a non-customized duplicate that only differs by sequence index.
result.manual_review_group_ids (list) – Group identifiers where customized and non-customized EVM/Solana events share asset and direction but are not exact matches.
result.ignored_group_ids (list) – Group identifiers that have been marked as ignored false positives.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – Group identifiers returned successfully
401 Unauthorized – No user is currently logged in
500 Internal Server Error – Internal rotki error
- POST /api/(version)/history/events/duplicates/customized
Remove non-customized duplicates that only differ by sequence index and return updated groups. Supports async execution via the async_query query parameter.
Example Request:
http
POST /api/1/history/events/duplicates/customized?async_query=false HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "group_identifiers": [ "0x7f9b1d9b3d6c80b6f699a25f3e91c408155cbff965d0f3a0df4d3a4f8f4b73c7" ] }
curl
curl -i -X POST 'http://localhost:5042/api/1/history/events/duplicates/customized?async_query=false' -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"group_identifiers": ["0x7f9b1d9b3d6c80b6f699a25f3e91c408155cbff965d0f3a0df4d3a4f8f4b73c7"]}'
wget
wget -S -O- 'http://localhost:5042/api/1/history/events/duplicates/customized?async_query=false' --header="Content-Type: application/json;charset=UTF-8" --post-data='{"group_identifiers": ["0x7f9b1d9b3d6c80b6f699a25f3e91c408155cbff965d0f3a0df4d3a4f8f4b73c7"]}'
httpie
echo '{ "group_identifiers": [ "0x7f9b1d9b3d6c80b6f699a25f3e91c408155cbff965d0f3a0df4d3a4f8f4b73c7" ] }' | http POST 'http://localhost:5042/api/1/history/events/duplicates/customized?async_query=false' Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/history/events/duplicates/customized?async_query=false', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'group_identifiers': ['0x7f9b1d9b3d6c80b6f699a25f3e91c408155cbff965d0f3a0df4d3a4f8f4b73c7']})
- Reqquery bool[optional] async_query:
Whether to execute as an async task.
- Request JSON Object:
group_identifiers (list[optional]) – Optional list of group identifiers to auto-fix. If omitted, all auto-fixable groups are processed.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "removed_event_identifiers": [123, 124], "auto_fix_group_ids": [], "manual_review_group_ids": [ "0xa8e4c2f6b79a1b9d6288a763dc6243cbce1e2c35c8b65ec79a9d35a1f4ec6a20" ] }, "message": "" }
- Response JSON Object:
result.removed_event_identifiers (list) – Event identifiers removed by the auto-fix operation.
result.auto_fix_group_ids (list) – Remaining auto-fixable group identifiers after removal.
result.manual_review_group_ids (list) – Remaining manual review group identifiers after removal.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – Auto-fix operation completed successfully
401 Unauthorized – No user is currently logged in
409 Conflict – Auto-fix failed due to a deletion constraint
500 Internal Server Error – Internal rotki error
- PUT /api/(version)/history/events/duplicates/customized
Mark the given group identifiers as ignored false positives. Returns the current list of all ignored group identifiers.
Supports async execution via the async_query query parameter.
Example Request:
http
PUT /api/1/history/events/duplicates/customized HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "group_identifiers": [ "0x7f9b1d9b3d6c80b6f699a25f3e91c408155cbff965d0f3a0df4d3a4f8f4b73c7" ] }
curl
curl -i -X PUT http://localhost:5042/api/1/history/events/duplicates/customized -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"group_identifiers": ["0x7f9b1d9b3d6c80b6f699a25f3e91c408155cbff965d0f3a0df4d3a4f8f4b73c7"]}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/history/events/duplicates/customized --header="Content-Type: application/json;charset=UTF-8" --body-data='{"group_identifiers": ["0x7f9b1d9b3d6c80b6f699a25f3e91c408155cbff965d0f3a0df4d3a4f8f4b73c7"]}'
httpie
echo '{ "group_identifiers": [ "0x7f9b1d9b3d6c80b6f699a25f3e91c408155cbff965d0f3a0df4d3a4f8f4b73c7" ] }' | http PUT http://localhost:5042/api/1/history/events/duplicates/customized Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/history/events/duplicates/customized', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'group_identifiers': ['0x7f9b1d9b3d6c80b6f699a25f3e91c408155cbff965d0f3a0df4d3a4f8f4b73c7']})
- Reqquery bool[optional] async_query:
Whether to execute as an async task.
- Request JSON Object:
group_identifiers (list) – List of group identifiers to mark as ignored false positives. Must contain at least one entry.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": [ "0x7f9b1d9b3d6c80b6f699a25f3e91c408155cbff965d0f3a0df4d3a4f8f4b73c7" ], "message": "" }
- Response JSON Object:
result (list) – All currently ignored group identifiers.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – Groups ignored successfully
400 Bad Request – Provided group identifiers are already ignored
401 Unauthorized – No user is currently logged in
500 Internal Server Error – Internal rotki error
- DELETE /api/(version)/history/events/duplicates/customized
Remove the ignored false positive markers for the given group identifiers. Returns the current list of all ignored group identifiers.
Supports async execution via the async_query query parameter.
Example Request:
http
DELETE /api/1/history/events/duplicates/customized HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "group_identifiers": [ "0x7f9b1d9b3d6c80b6f699a25f3e91c408155cbff965d0f3a0df4d3a4f8f4b73c7" ] }
curl
curl -i -X DELETE http://localhost:5042/api/1/history/events/duplicates/customized -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"group_identifiers": ["0x7f9b1d9b3d6c80b6f699a25f3e91c408155cbff965d0f3a0df4d3a4f8f4b73c7"]}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/history/events/duplicates/customized --header="Content-Type: application/json;charset=UTF-8" --body-data='{"group_identifiers": ["0x7f9b1d9b3d6c80b6f699a25f3e91c408155cbff965d0f3a0df4d3a4f8f4b73c7"]}'
httpie
echo '{ "group_identifiers": [ "0x7f9b1d9b3d6c80b6f699a25f3e91c408155cbff965d0f3a0df4d3a4f8f4b73c7" ] }' | http DELETE http://localhost:5042/api/1/history/events/duplicates/customized Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/1/history/events/duplicates/customized', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'group_identifiers': ['0x7f9b1d9b3d6c80b6f699a25f3e91c408155cbff965d0f3a0df4d3a4f8f4b73c7']})
- Reqquery bool[optional] async_query:
Whether to execute as an async task.
- Request JSON Object:
group_identifiers (list) – List of group identifiers to un-ignore. Must contain at least one entry.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": [], "message": "" }
- Response JSON Object:
result (list) – All currently ignored group identifiers after removal.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – Groups un-ignored successfully
400 Bad Request – Provided group identifiers are not currently ignored
401 Unauthorized – No user is currently logged in
500 Internal Server Error – Internal rotki error
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/messagespython-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": trueNote
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.
401 Unauthorized – No user is currently logged in.
409 Conflict – Fatal accounting error while processing the report.
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": trueDoing 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, "group_identifier": "0xb626d9d9e3a5b9ecbe0c2194cf96ab7561063c6d31e0e6799d56a589b8094609", "sequence_index": 0, "timestamp": 1651258550, "location": "blockchain", "asset": "ETH", "amount": "3.55448345", "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, "group_identifier": "0xa9905f5eaa664a53e6513f7ba2147dcebc3e54d4062df9df1925116b6a220014", "sequence_index": 0, "timestamp": 1651259834, "location": "blockchain", "accounting_event_type": "history base entry", "asset": "ETH", "amount": "0.009", "event_type": "spend", "event_subtype": "fee", "location_label": "0x19e4057A38a730be37c4DA690b103267AAE1d75d", "notes": "Burn 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}", "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": ["cryptocompare", "coingecko", "uniswapv3", "defillama", "alchemy"], "pnl_csv_with_formulas": true, "pnl_csv_have_summary": false, "ssf_graph_multiplier": 0, "last_data_migration": 3, "non_syncing_exchanges": [] "evmchains_to_skip_detection": [] }, "ignored_events_ids": ["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 occurred 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": trueDoing 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 Accounting rules
- POST /api/(version)/accounting/rules/export
Note
This endpoint can also be queried asynchronously by using
"async_query": trueDoing a POST on the Export Accounting rules endpoint will trigger an export of all the accounting rules from the DB into a file on the given
directory_path.Example Request:
http
POST /api/1/accounting/rules/transfer HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"directory_path": "/home/user/Documents"}
curl
curl -i -X POST http://localhost:5042/api/1/accounting/rules/transfer -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"directory_path": "/home/user/Documents"}'
wget
wget -S -O- http://localhost:5042/api/1/accounting/rules/transfer --header="Content-Type: application/json;charset=UTF-8" --post-data='{"directory_path": "/home/user/Documents"}'
httpie
echo '{ "directory_path": "/home/user/Documents" }' | http POST http://localhost:5042/api/1/accounting/rules/transfer Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/accounting/rules/transfer', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'directory_path': '/home/user/Documents'})
- Request JSON Object:
directory_path (string) – The directory in which to write the exported JSON file
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 export. If
directory_pathis not present, it will return the JSON data directly.
- Status Codes:
200 OK – File was exported successfully
400 Bad Request – Provided JSON is in some way malformed.
409 Conflict – No user is currently logged in. No permissions to write in the given directory. Check error message.
500 Internal Server Error – Internal rotki error.
Import Accounting rules
- PUT /api/(version)/accounting/rules/import
- PATCH /api/(version)/accounting/rules/import
Note
This endpoint can also be queried asynchronously by using
"async_query": trueDoing a PUT on the Import Accounting rules endpoint with a path to the exported accounting rules json file will import the accounting rules from it. Doing a PATCH on the Import Accounting rules endpoint with the exported accounting rules json as multipart/form-data will import the accounting rules from it.
Example Request:
http
PUT /api/1/accounting/rules/transfer HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "filepath": "/home/user/Documents/accounting_rules.json", "async_query": false }
curl
curl -i -X PUT http://localhost:5042/api/1/accounting/rules/transfer -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": false, "filepath": "/home/user/Documents/accounting_rules.json"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/accounting/rules/transfer --header="Content-Type: application/json;charset=UTF-8" --body-data='{"async_query": false, "filepath": "/home/user/Documents/accounting_rules.json"}'
httpie
echo '{ "async_query": false, "filepath": "/home/user/Documents/accounting_rules.json" }' | http PUT http://localhost:5042/api/1/accounting/rules/transfer Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/accounting/rules/transfer', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': False, 'filepath': '/home/user/Documents/accounting_rules.json'})
- Request JSON Object:
file (str) – The path to the exported accounting rules 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 import
- Status Codes:
200 OK – Import of accounting rules successfully
400 Bad Request – Provided JSON is in some way malformed. Import JSON contains some invalid data types.
409 Conflict – No user is currently logged in. JSON does not contain required keys. Error importing accounting rules. Check error message.
500 Internal Server Error – Internal rotki error.
Get missing acquisitions and prices
- GET /api/(version)/history/actionable_items
Note
This endpoint should be called after getting a PnL report data.
Doing a GET on the this endpoint will return all missing acquisitions and missing prices encountered during generation of the last PnL report.
Example Request:
http
GET /api/1/history/actionable_items HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8
curl
curl -i -X GET http://localhost:5042/api/1/history/actionable_items -H "Content-Type: application/json;charset=UTF-8"
wget
wget -S -O- http://localhost:5042/api/1/history/actionable_items --header="Content-Type: application/json;charset=UTF-8"
httpie
http http://localhost:5042/api/1/history/actionable_items Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/history/actionable_items', headers={'Content-Type': 'application/json;charset=UTF-8'})
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "report_id": 42, "missing_acquisitions": [ { "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359v", "time": 1428994442, "found_amount": "0", "missing_amount": "0.1" }, { "originating_event_id": 424242, "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "time": 1439048640, "found_amount": "0", "missing_amount": "14.36963" }, { "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "time": 1439994442, "found_amount": "0", "missing_amount": "0.0035000000" }, { "originating_event_id": 424242, "asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "time": 1439994442, "found_amount": "0", "missing_amount": "1.7500" } ], "missing_prices": [ { "from_asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "to_asset": "AVAX", "time": 1439994442, "rate_limited": false, }, { "from_asset": "eip155:1/erc20:0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359", "to_asset": "USD", "time": 1439995442, "rate_limited": true, } ] }, "message": "" }
- Response JSON Object:
result (object) – An object with missing acquisitions and prices data.
report_id (int) – [Optional – missing if no report was ran]. The id of the PnL report for which the actionable items were generated.
missing_prices (list) – A list that contains entries of missing prices found during PnL reporting.
missing_acquisitions (list) – A list that contains entries of missing acquisitions found during PnL reporting.
- Response JSON Array of Objects:
from_asset (str) – The asset whose price is missing.
to_asset (str) – The asset in which we want the price of from_asset.
time (int) – The timestamp for which the price is missing.
asset (str) – The asset that is involved in the event.
time – The timestamp this event took place in.
found_amount (str) – The matching amount found from an acquisition event for a spend.
missing_amount (str) – The corresponding acquisition amount we can’t find for a particular spend.
- Resjosnarr bool rate_limited:
True if we couldn’t get the price and any of the oracles got rate limited.
- Status Codes:
200 OK – Data were queried successfully.
409 Conflict – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
Querying history progress status
- GET /api/(version)/history/status
Doing a GET on the history’s query current status will return information about the progress of the current historical query process.
Example Request:
http
GET /api/1/history/status HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/history/status
wget
wget -S -O- http://localhost:5042/api/1/history/status
httpie
http http://localhost:5042/api/1/history/statuspython-requests
requests.get('http://localhost:5042/api/1/history/status')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "processing_state": "Querying kraken exchange history", "total_progress": "50%" } "message": "" }
- Response JSON Object:
processing_state (str) – The name of the task that is currently being executed for the history query and profit/loss report.
total_progress (str) – A percentage showing the total progress of the profit/loss report.
- Status Codes:
200 OK – Data were queried successfully.
409 Conflict – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
Query saved PnL Reports
- GET /api/(version)/reports/(report_id)
Doing a GET on the PnL reports endpoint with an optional report id will return information for that report or for all reports. Free users can only query up to 20 saved reports.
Example Request:
http
GET /api/1/reports/4 HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/reports/4
wget
wget -S -O- http://localhost:5042/api/1/reports/4
httpie
http http://localhost:5042/api/1/reports/4python-requests
requests.get('http://localhost:5042/api/1/reports/4')
- Request JSON Object:
report_id (int) – An optional id to limit the query to that specific report.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result":{ "entries":[ { "identifier":2, "timestamp":1637931305, "start_ts":15, "end_ts":1637928988, "first_processed_timestamp":null, "last_processed_timestamp": 1602042717, "settings": { "profit_currency": "USD", "taxfree_after_period": 365, "include_crypto2crypto": true, "calculate_past_cost_basis": true, "include_gas_costs": true, "cost_basis_method": "lifo", "eth_staking_taxable_after_withdrawal_enabled": true }, "overview": { "trade": {"free": "0", "taxable": "60.1"}, "transaction event": {"free": "0", "taxable": "40.442"}, "fee": {"free": "10", "taxable": "55.5"} } }, { "identifier":3, "timestamp":1637931305, "start_ts":0, "end_ts":1637928988, "first_processed_timestamp":null, "last_processed_timestamp": 1602042717, "settings": { "profit_currency": "USD", "taxfree_after_period": 365, "include_crypto2crypto": true, "calculate_past_cost_basis": true, "include_gas_costs": true, "cost_basis_method": "fifo", "eth_staking_taxable_after_withdrawal_enabled": false }, "overview": { "trade": {"free": "0", "taxable": "60.1"}, "fee": {"free": "10", "taxable": "55.5"} } }, { "identifier":4, "timestamp":1647931305, "start_ts":0, "end_ts":1637928988, "first_processed_timestamp":null, "last_processed_timestamp": 1602042717, "settings": { "profit_currency": "USD", "taxfree_after_period": 365, "include_crypto2crypto": true, "calculate_past_cost_basis": true, "include_gas_costs": true, "cost_basis_method": "fifo", "eth_staking_taxable_after_withdrawal_enabled": false }, "overview": { "asset movement": {"free": "0", "taxable": "5"}, "fee": {"free": "10", "taxable": "55.5"} } } ], "entries_found":3, "entries_limit":20 }, "message":"" }
- Response JSON Object:
identifier (int) – The identifier of the PnL report
start_ts (int) – The end unix timestamp of the PnL report
end_ts (int) – The end unix timestamp of the PnL report
first_processed_timestamp (int) – The timestamp of the first even we processed in the PnL report or 0 for empty report.
overview (object) – The overview contains an entry for totals per event type. Each entry contains pnl breakdown (free/taxable for now).
last_processed_timestamp (int) – The timestamp of the last processed action. This helps us figure out when was the last action the backend processed and if it was before the start of the PnL period to warn the user WHY the PnL is empty.
processed_actions (int) – The number of actions processed by the PnL report. This is not the same as the events shown within the report as some of them may be before the time period of the report started. This may be smaller than “total_actions”.
total_actions (int) – The total number of actions to be processed by the PnL report. This is not the same as the events shown within the report as some of them they may be before or after the time period of the report.
entries_found (int) – The number of reports found if called without a specific report id.
entries_limit (int) – -1 if there is no limit (premium). Otherwise the limit of saved reports to inspect is 20.
Settings This object contains an entry per PnL report setting. :resjson str profit_currency: The identifier of the asset used as profit currency in the PnL report. :resjson integer taxfree_after_period: An optional integer for the value of taxfree_after_period setting. Can be either null or an integer. :resjson bool include_crypto2crypto: The value of the setting used in the PnL report. :resjson bool calculate_past_cost_basis: The value of the setting used in the PnL report. :resjson bool include_gas_costs: The value of the setting used in the PnL report. :resjson str cost_basis_method: The method for cost basis calculation. Either fifo or lifo. :resjson bool eth_staking_taxable_after_withdrawal_enabled: A boolean indicating whether the staking of ETH is taxable only after the merge and withdrawals are enabled (true) or (false) if each eth staking event is considered taxable at the point of receiving if you can’t yet withdraw. :statuscode 200: Data were queried successfully. :statuscode 409: No user is currently logged in. :statuscode 500: Internal rotki error.
Get saved events of a PnL Report
- POST /api/(version)/reports/(report_id)/data
Doing a POST on the PnL reports data endpoint with a specific report id and optional pagination and timestamp filtering will query the events of the given report.
Example Request:
http
POST /api/1/reports/4/data HTTP/1.1 Host: localhost:5042
curl
curl -i -X POST http://localhost:5042/api/1/reports/4/data
wget
wget -S -O- http://localhost:5042/api/1/reports/4/data
httpie
http POST http://localhost:5042/api/1/reports/4/data
python-requests
requests.post('http://localhost:5042/api/1/reports/4/data')
- Request JSON Object:
report_id (int) – Optional. The id of the report to query as a view arg.
limit (int) – Optional. This signifies the limit of records to return as per the sql spec.
offset (int) – This signifies the offset from which to start the return of records per the sql spec.
from_timestamp (str) – Optional. A filter for the from_timestamp of the range of events to query.
to_timestamp (str) – Optional. A filter for the to_timestamp of the range of events to query.
order_by_attributes (list[string][optional]) – Optional. Default is [“timestamp”]. The list of the attributes to order results by. The attributes accepted for sorting are: asset, pnl_free, pnl_taxable and timestamp.
ascending (list[bool][optional]) – Optional. Default is [false]. The order in which to return results depending on the order by attribute.
event_type (str) – Optional. Not used yet. In the future will be a filter for the type of event to query.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "entries": [{ "asset": "BTC", "cost_basis": { "is_complete": true, "matched_acquisitions": [ { "amount": "0.001", "event": { "full_amount": "1", "index": 11, "rate": "100.1", "timestamp": 1458994442 }, "taxable": false} ]}, "free_amount": "1E-11", "location": "bitmex", "notes": "bitmex withdrawal", "pnl_free": "-1.0010E-9", "pnl_taxable": "0.00", "price": "9367.55", "taxable_amount": "0", "timestamp": 1566572401, "type": "asset movement" }, { "asset": "XMR", "cost_basis": null, "free_amount": "0", "location": "poloniex", "notes": "Buy XMR(Monero) with ETH(Ethereum).Amount in", "pnl_free": "0", "pnl_taxable": "0", "price": "12.47924607060", "taxable_amount": "1.40308443", "timestamp": 1539713238, "type": "trade" }], "entries_found": 2, "entries_total": 10, "entries_limit": 2 }, "message": "" }
- Response JSON Object:
asset (str) – The asset that is involved in the event.
cost_basis (object) – Can be null. An object describing the cost basis of the event if it’s a spend event. Contains a boolean attribute
"is_complete"to denoting if we have complete cost basis information for the spent asset or not. If not then this means that rotki does not know enough to properly calculate cost basis. The other attribute is"matched_acquisitions"a list of matched acquisition events from which the cost basis is calculated. Each event has an"amount"attribute denoting how much of the acquisition event this entry uses. A"taxable"attribute denoting if this acquisition concerns taxable or tax-free spend. Then there is also an event which shows the full event. It’s attributes show the full amount bought, when, at what rate and the index of the event in the PnL report.free_amount (str) – The amount of the event that counts as tax free.
taxable_amount (str) – The amount of the event that counts as taxable.
location (str) – The location this event took place in.
notes (str) – A description of the event.
pnl_free (str) – The non-taxable profit/loss caused by this event.
pnl_taxable (str) – The taxable profit/loss caused by this event.
price (str) – The price in profit_currency for asset used
taxable_amount – The amount of the event that counts as taxable.
timestamp (int) – The timestamp this event took place in.
type (str) – The type of event. Can be any of the possible accounting event types.
group_id (str) – Optional. Can be missing. An id signifying events that should be grouped together in the frontend. If missing no grouping needs to happen.
entries_found (int) – The number of entries matching the requested report id and any supplied filters. Additionally, for free users this is limited by FREE_PNL_EVENTS_LIMIT.
entries_total (int) – The total number of entries in the database, ignoring any filters or pagination.
entries_limit (int) – The limit of entries that can be returned.
- Status Codes:
200 OK – Report event data was successfully queried.
400 Bad Request – Report id does not exist.
409 Conflict – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
Export PnL report CSV
- GET /api/(version)/reports/(report_id)/export
Note
This exports the CSV for a specific saved PnL report using data from the transient DB, so it works after app restart.
Doing a GET on this endpoint will export the PnL report for the given report id to CSV files and save them in the given directory.
Example Request:
http
GET /api/1/reports/4/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/reports/4/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/reports/4/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/reports/4/export Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/reports/4/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 export
- Status Codes:
200 OK – File exported successfully
409 Conflict – No user is currently logged in. Report not found. No permissions to write in the given directory. Check error message.
500 Internal Server Error – Internal rotki error.
Download PnL report CSV
- GET /api/(version)/reports/(report_id)/download
Note
This downloads the CSV for a specific saved PnL report using data from the transient DB, so it works after app restart.
Doing a GET on this endpoint will download the PnL report for the given report id as a zip file. If no report exists, an error is returned.
Example Request:
http
GET /api/1/reports/4/download HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8
curl
curl -i -X GET http://localhost:5042/api/1/reports/4/download -H "Content-Type: application/json;charset=UTF-8"
wget
wget -S -O- http://localhost:5042/api/1/reports/4/download --header="Content-Type: application/json;charset=UTF-8"
httpie
http http://localhost:5042/api/1/reports/4/download Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/reports/4/download', headers={'Content-Type': 'application/json;charset=UTF-8'})
Purge PnL report and all its data
- DELETE /api/(version)/reports/(report_id)
Doing a DELETE on the PnL reports endpoint with a specific report will remove the given report and all of its saved events from the DB.
Example Request:
http
DELETE /api/1/reports/4 HTTP/1.1 Host: localhost:5042
curl
curl -i -X DELETE http://localhost:5042/api/1/reports/4
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/reports/4
httpie
http DELETE http://localhost:5042/api/1/reports/4
python-requests
requests.delete('http://localhost:5042/api/1/reports/4')
- Request JSON Object:
report_id (int) – The id of the report to delete as a view arg.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true "message": "" }
- Status Codes:
200 OK – Report was deleted.
400 Bad Request – Report id does not exist.
409 Conflict – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
Querying periodic data
- GET /api/(version)/periodic
Doing a GET on the periodic data endpoint will return data that would be usually frequently queried by an application. Check the example response to see what these data would be.
Example Request:
http
GET /api/1/periodic HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/periodic
wget
wget -S -O- http://localhost:5042/api/1/periodic
httpie
http http://localhost:5042/api/1/periodicpython-requests
requests.get('http://localhost:5042/api/1/periodic')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "last_balance_save": 1572345881, "connected_nodes": { "eth": ["nodeX", "nodeY"], "optimism": ["nodeW", "nodeZ"], "polygon_pos": ["nodeA", "nodeB"], }, "failed_to_connect": { "eth": ["nodeZ"] }, "last_data_upload_ts": 0 } "message": "" }
- Response JSON Object:
last_balance_save (int) – The last time (unix timestamp) at which balances were saved in the database.
last_data_upload_ts (int) – The last time (unix timestamp) at which a new DB was pushed to the remote as backup.
connected_nodes (object) – A dictionary containing the chain and a list of connected nodes.
[Optional] (object failed_to_connect) – A dictionary containing the chain and the nodes that rotki couldn’t connect with. If nothing failed for a chain we don’t include it in the mapping.
- Status Codes:
200 OK – Data were queried successfully.
409 Conflict – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
Getting blockchain account data
- GET /api/(version)/blockchains/(blockchain)/accounts
Note
Supported blockchains:
"BTC", "BCH", "ETH", "KSM", "DOT", "AVAX", "OPTIMISM"Doing a GET on the blockchains endpoint with a specific blockchain queries account data information for that blockchain.
Example Request:
http
GET /api/1/blockchains/eth/accounts HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/blockchains/eth/accounts
wget
wget -S -O- http://localhost:5042/api/1/blockchains/eth/accounts
httpie
http http://localhost:5042/api/1/blockchains/eth/accountspython-requests
requests.get('http://localhost:5042/api/1/blockchains/eth/accounts')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result" : [{ "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "label": "my new metamask", "tags": ["public", "metamask"] }, { "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b", "label": null, "tags": ["private"] }, { "address": "G7UkJAutjbQyZGRiP8z5bBSBPBJ66JbTKAkFDq3cANwENyX", "label": "my Kusama account", "tags": null }], "message": "", }
- Response JSON Object:
result (list) – A list with the account data details
- Response JSON Array of Objects:
address (string) – The address, which is the unique identifier of each account. For BTC blockchain query and if the entry is an xpub then this attribute is missing.
xpub (string) – The extended public key. This attribute only exists for BTC blockchain query and if the entry is an xpub
label (string) – The label to describe the account. Can also be null.
tags (list) – A list of tags associated with the account. Can also be null. Should never by an empty list.
- Status Codes:
200 OK – Account data successfully queried.
409 Conflict – User is not logged in.
500 Internal Server Error – Internal rotki error
Example Request:
http
GET /api/1/blockchains/BTC/accounts HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/blockchains/BTC/accounts
wget
wget -S -O- http://localhost:5042/api/1/blockchains/BTC/accounts
httpie
http http://localhost:5042/api/1/blockchains/BTC/accountspython-requests
requests.get('http://localhost:5042/api/1/blockchains/BTC/accounts')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result" : { "standalone": [{ "address": "bc1qc3qcxs025ka9l6qn0q5cyvmnpwrqw2z49qwrx5", "label": null, "tags": ["private"], }, { "address": "bc1qr4r8vryfzexvhjrx5fh5uj0s2ead8awpqspqra", "label": "some label", "tags": null, }], "xpubs": [{ "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk", "derivation_path": "m/0/0", "label": "ledger xpub", "tags": ["super secret", "awesome"], "addresses": [{ "address": "1LZypJUwJJRdfdndwvDmtAjrVYaHko136r", "label": "derived address", "tags": ["super secret", "awesome", "derived"] }, { "address": "1AMrsvqsJzDq25QnaJzX5BzEvdqQ8T6MkT", "label": null, "tags": null }] }, { "xpub": "zpub6quTRdxqWmerHdiWVKZdLMp9FY641F1F171gfT2RS4D1FyHnutwFSMiab58Nbsdu4fXBaFwpy5xyGnKZ8d6xn2j4r4yNmQ3Yp3yDDxQUo3q", "derivation_path": null, "label": "some label", "tags": null, "addresses": null, }] }, "message": "", }
- Response JSON Object:
result (list) – An object with the account data details. Has two attributes.
"standalone"for standalone addresses. That follows the same response format as above. And"xpub"for bitcoin xpubs. Below we will see the format of the xpub response.
- Response JSON Array of Objects:
xpub (string) – The extended public key string
derivation_path (string) – [Optional] If existing this is the derivation path from which to start deriving accounts from the xpub.
label (string) – [Optional] The label to describe the xpub. Can also be null.
tags (list) – [Optional] A list of tags associated with the account. Can also be null. Should never be an empty list.
addresses (list) – [Optional] A list of address objects derived by the account. Can also be null. The attributes of each object are as seen in the previous response.
- Status Codes:
200 OK – Account data successfully queried.
409 Conflict – User is not logged in.
500 Internal Server Error – Internal rotki error
Getting current ethereum MakerDAO DSR balance
- GET /api/(version)/blockchains/eth/modules/makerdao/dsrbalance
Doing a GET on the makerdao dsrbalance resource will return the current balance held in DSR by any of the user’s accounts that ever had DAI deposited in the DSR and also the current DSR percentage.
Note
This endpoint can also be queried asynchronously by using
"async_query": trueNote
This endpoint also accepts parameters as query arguments.
Example Request:
http
GET /api/1/blockchains/eth/modules/makerdao/dsrbalance HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/blockchains/eth/modules/makerdao/dsrbalance
wget
wget -S -O- http://localhost:5042/api/1/blockchains/eth/modules/makerdao/dsrbalance
httpie
http http://localhost:5042/api/1/blockchains/eth/modules/makerdao/dsrbalancepython-requests
requests.get('http://localhost:5042/api/1/blockchains/eth/modules/makerdao/dsrbalance')
- Request JSON Object:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "current_dsr": "8.022774065220581075333120100", "balances": { "0xA0B6B7fEa3a3ce3b9e6512c0c5A157a385e81056": { "amount": "125.24423", "value": "126.5231" }, "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237": { "amount": "456.323", "value": "460.212" } } }, "message": "" }
- Response JSON Object:
result (object) – A mapping of accounts to the number of DAI they have locked in DSR and the corresponding USD value. If an account is not in the mapping rotki does not see anything locked in DSR for it.
- Status Codes:
200 OK – DSR successfully queried.
409 Conflict – User is not logged in. Or makerdao module is not activated.
500 Internal Server Error – Internal rotki error.
502 Bad Gateway – An external service used in the query such as etherscan could not be reached or returned unexpected response.
Getting ethereum MakerDAO DSR historical report
- GET /api/(version)/blockchains/eth/modules/makerdao/dsrhistory
Note
This endpoint is only available for premium users
Doing a GET on the makerdao dsrhistory resource will return the history of deposits and withdrawals of each account to the DSR along with the amount of DAI gained at each step and other information
Note
This endpoint can also be queried asynchronously by using
"async_query": trueNote
This endpoint also accepts parameters as query arguments.
Example Request:
http
GET /api/1/blockchains/eth/modules/makerdao/dsrhistory HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/blockchains/eth/modules/makerdao/dsrhistory
wget
wget -S -O- http://localhost:5042/api/1/blockchains/eth/modules/makerdao/dsrhistory
httpie
http http://localhost:5042/api/1/blockchains/eth/modules/makerdao/dsrhistorypython-requests
requests.get('http://localhost:5042/api/1/blockchains/eth/modules/makerdao/dsrhistory')
- Request JSON Object:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "0xA0B6B7fEa3a3ce3b9e6512c0c5A157a385e81056": { "movements": [{ "movement_type": "deposit", "gain_so_far": { "amount": "0", "value": "0" }, "value": { "amount": "350", "value": "351.21" }, "block_number": 9128160, "timestamp": 1582706553, "tx_hash": "0x988aea85b54c5b2834b144e9f7628b524bf9faf3b87821aa520b7bcfb57ab289" }, { "movement_type": "deposit", "gain_so_far": { "amount": "0.875232", "value": "0.885292" }, "value": { "amount": "50", "value": "50.87" }, "block_number": 9129165, "timestamp": 1582806553, "tx_hash": "0x2a1bee69b9bafe031026dbcc8f199881b568fd767482b5436dd1cd94f2642443" }, { "movement_type": "withdrawal", "gain_so_far": { "amount": "1.12875932", "value": "1.34813" }, "value": { "amount": "350", "value": "353.12" }, "block_number": 9149160, "timestamp": 1592706553, "tx_hash": "0x618fc9542890a2f58ab20a3c12d173b3638af11fda813e61788e242b4fc9a756" }, { }], "gain_so_far": { "amount": "1.14875932", "value": "1.2323" } }, "0x1D7D7Eb7035B42F39f200AA3af8a65BC3475A237": { "movements": [{ "movement_type": "deposit", "gain_so_far": { "amount": "0", "value": "0" }, "value": { "amount": "550", "value": "553.43" }, "block_number": 9128174, "timestamp": 1583706553, "tx_hash": "0x2a1bee69b9bafe031026dbcc8f199881b568fd767482b5436dd1cd94f2642443" }], "gain_so_far": { "amount": "0.953423", "value": "0.998421" } } }, "message": "" }
- Response JSON Object:
result (object) – A mapping of accounts to the DSR history report of each account. If an account is not in the mapping rotki does not see anything locked in DSR for it.
movements (object) – A list of deposits/withdrawals to/from the DSR for each account.
gain_so_far (string) – The total gain so far in DAI from the DSR for this account. The amount is the DAI amount and the USD value is the added usd value of all the usd values of each movement again plus the usd value of the remaining taking into account current usd price
- Response JSON Array of Objects:
movement_type (string) – The type of movement involving the DSR. Can be either “deposit” or “withdrawal”.
gain_so_far (string) – The amount of DAI gained for this account in the DSR up until the moment of the given deposit/withdrawal along with the usd value equivalent of the DAI gained for this account in the DSR up until the moment of the given deposit/withdrawal. The rate is the DAI/USD rate at the movement’s timestamp.
value (string) – The amount of DAI deposited or withdrawn from the DSR along with the USD equivalent value of the amount of DAI deposited or withdrawn from the DSR. The rate is the DAI/USD rate at the movement’s timestamp.
block_number (int) – The block number at which the deposit or withdrawal occurred.
tx_hash (int) – The transaction hash of the DSR movement
- Status Codes:
200 OK – DSR history successfully queried.
401 Unauthorized – No user is currently logged in.
403 Forbidden – Logged in user does not have premium.
409 Conflict – Makerdao module is not activated.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – An external service used in the query such as etherscan could not be reached or returned unexpected response.
Getting MakerDAO vaults basic data
- GET /api/(version)/blockchains/eth/modules/makerdao/vaults
Doing a GET on the makerdao vault resource will return the basic information for each vault the user has
Note
This endpoint can also be queried asynchronously by using
"async_query": trueNote
This endpoint also accepts parameters as query arguments.
Example Request:
http
GET /api/1/blockchains/eth/modules/makerdao/vaults HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/blockchains/eth/modules/makerdao/vaults
wget
wget -S -O- http://localhost:5042/api/1/blockchains/eth/modules/makerdao/vaults
httpie
http http://localhost:5042/api/1/blockchains/eth/modules/makerdao/vaultspython-requests
requests.get('http://localhost:5042/api/1/blockchains/eth/modules/makerdao/vaults')
- Request JSON Object:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": [{ "identifier": 1, "collateral_type": "ETH-A", "owner": "0xA76a9560ffFD9fC603F7d6A30c37D79665207876", "collateral_asset": "ETH", "collateral": { "amount": "5.232", "value": "950.13" }, "debt": { "amount": "650", "value": "653.42" }, "collateralization_ratio": "234.21%", "liquidation_ratio": "150%", "liquidation_price": "125.1", "stability_fee": "0.00%", }, { "identifier": 55, "collateral_type": "USDC-A", "owner": "0xB26a9561ffFD9fC603F7d6A30c37D79665207876", "collateral_asset": "eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "collateral": { "amount": "150", "value": "150" }, "debt": { "amount": "50", "value": "53.2" }, "collateralization_ratio": "250.551%", "liquidation_ratio": "150%", "liquidation_price": "0.45", "stability_fee": "0.75%", }] "message": "" }
- Response JSON Object:
result (object) – A list of all vaults auto detected for the user’s accounts
- Response JSON Array of Objects:
identifier (string) – A unique integer identifier for the vault.
collateral_type (string) – The collateral_type of the vault. e.g. ETH-A. Various collateral types can be seen here: https://catflip.co/
owner (string) – The address of the owner of the vault.
collateral_asset (string) – The identifier of the asset deposited in the vault as collateral.
collateral (string) – The amount of collateral currently deposited in the vault along with the current value in USD of all the collateral in the vault according to the MakerDAO price feed.
debt (string) – The amount of DAI owed to the vault. So generated DAI plus the stability fee interest. Along with its current usd value.
collateralization_ratio (string) – A string denoting the percentage of collateralization of the vault.
liquidation_ratio (string) – This is the current minimum collateralization ratio. Less than this and the vault is going to get liquidated.
liquidation_price (string) – The USD price that the asset deposited in the vault as collateral at which the vault is going to get liquidated.
stability_fee (string) – The current annual interest rate you have to pay for borrowing collateral from this vault type.
- Status Codes:
200 OK – Vaults successfully queried
409 Conflict – User is not logged in. Or makerdao module is not activated.
500 Internal Server Error – Internal rotki error.
502 Bad Gateway – An external service used in the query such as etherscan could not be reached or returned unexpected response.
Getting MakerDAO vault details
- GET /api/(version)/blockchains/eth/modules/makerdao/vaultdetails
Note
This endpoint is only available for premium users
Doing a GET on the makerdao vault details resource will return additional details for each vault and also the list of vault events such as deposits, withdrawals, liquidations, debt generation and repayment.
To get the total amount of USD lost from the vault (including liquidations) the user should simply add
total_liquidated_usdandtotal_interest_owed.Note
This endpoint can also be queried asynchronously by using
"async_query": trueNote
This endpoint also accepts parameters as query arguments.
Example Request:
http
GET /api/1/blockchains/eth/modules/makerdao/vaultdetails HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/blockchains/eth/modules/makerdao/vaultdetails
wget
wget -S -O- http://localhost:5042/api/1/blockchains/eth/modules/makerdao/vaultdetails
httpie
http http://localhost:5042/api/1/blockchains/eth/modules/makerdao/vaultdetailspython-requests
requests.get('http://localhost:5042/api/1/blockchains/eth/modules/makerdao/vaultdetails')
- Request JSON Object:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": [{ "identifier": 1, "collateral_asset": "ETH", "creation_ts": 1589067898, "total_interest_owed": "0.02341", "total_liquidated": { "amount": "0", "value": "0" }, "events": [{ "event_type": "deposit", "value": { "amount": "5.551", "value": "120.32" }, "timestamp": 1589067899, "tx_hash": "0x678f31d49dd70d76c0ce441343c0060dc600f4c8dbb4cee2b08c6b451b6097cd" }, { "event_type": "generate", "value": { "amount": "325", "value": "12003.32" }, "timestamp": 1589067900, "tx_hash": "0x678f31d49dd70d76c0ce441343c0060dc600f4c8dbb4cee2b08c6b451b6097cd" }] }, { "identifier": 56, "collateral_asset": "eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "creation_ts": 1589067897, "total_interest_owed": "-751.32", "total_liquidated": { "amount": "1050.21", "value": "2501.234" }, "events": [{ "event_type": "deposit", "value": { "amount": "1050.21", "value": "10500.21" }, "timestamp": 1589067899, "tx_hash": "0x678f31d49dd70d76c0ce441343c0060dc600f4c8dbb4cee2b08c6b451b6097cd" }, { "event_type": "generate", "value": { "amount": "721.32", "value": "7213.2" }, "timestamp": 1589067900, "tx_hash": "0x678f31d49dd70d76c0ce441343c0060dc600f4c8dbb4cee2b08c6b451b6097cd" }, { "event_type": "liquidation", "value": { "amount": "500", "value": "5000" }, "timestamp": 1589068000, "tx_hash": "0x678f31d49dd70d76c0ce441343c0060dc600f4c8dbb4cee2b08c6b451b6097cd" }, { "event_type": "liquidation", "value": { "amount": "550.21", "value": "5502.1" }, "timestamp": 1589068001, "tx_hash": "0x678f31d49dd70d76c0ce441343c0060dc600f4c8dbb4cee2b08c6b451b6097cd" }] }] "message": "" }
- Response JSON Object:
result (object) – A list of all vault details detected.
events (object) – A list of all events that occurred for this vault
- Response JSON Array of Objects:
collateral_asset (string) – The identifier of the asset deposited in the vault as collateral.
creation_ts (int) – The timestamp of the vault’s creation.
total_interest_owed (string) – Total amount of DAI lost to the vault as interest rate. This can be negative, if the vault has been liquidated. In that case the negative number is the DAI that is out in the wild and does not need to be returned after liquidation. Even if the vault has been paid out this still shows how much interest was paid to the vault. So it’s past and future interest owed.
total_liquidated (string) – The total amount/usd_value of the collateral asset that has been lost to liquidation. Will be
0if no liquidations happened.event_type (string) – The type of the event. Valid types are:
["deposit", "withdraw", "generate", "payback", "liquidation"]value (string) – The amount/usd_value associated with the event. So collateral deposited/withdrawn, debt generated/paid back, amount of collateral lost in liquidation.
timestamp (int) – The unix timestamp of the event
tx_hash (string) – The transaction hash associated with the event.
- Status Codes:
200 OK – Vault details successfully queried
401 Unauthorized – User is not logged in.
403 Forbidden – Logged in user does not have premium.
409 Conflict – Makerdao module is not activated.
500 Internal Server Error – Internal rotki error.
502 Bad Gateway – An external service used in the query such as etherscan could not be reached or returned unexpected response.
Getting Liquity balances
- GET /api/(version)/blockchains/eth/modules/liquity/balances
Doing a GET on the liquity balances resource will return the balances that the user has in troves and the Total Collateral Ratio.
Note
This endpoint can also be queried asynchronously by using
"async_query": trueNote
This endpoint also accepts parameters as query arguments.
Note
This endpoint will provide different information if called with a premium account or not. With premium accounts information about staking is provided.
Example Request:
http
GET /api/1/blockchains/eth/modules/liquity/balances HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/blockchains/eth/modules/liquity/balances
wget
wget -S -O- http://localhost:5042/api/1/blockchains/eth/modules/liquity/balances
httpie
http http://localhost:5042/api/1/blockchains/eth/modules/liquity/balancespython-requests
requests.get('http://localhost:5042/api/1/blockchains/eth/modules/liquity/balances')
- Request JSON Object:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "balances": { "0x063c26fF1592688B73d8e2A18BA4C23654e2792E": { "collateral": { "asset": "ETH" "amount": "5.3100000000000005", "value": "16161.675300000001521815" }, "debt": { "asset": "eip155:1/erc20:0x5f98805A4E8be255a32880FDeC7F6728C6568bA0" "amount": "6029.001719188487", "value": "6089.29173638037187" }, "collateralization_ratio": "268.0655281381374051287323733", "liquidation_price": "1261.435199626818912670885158", "active": true, "trove_id": 148 } }, "total_collateral_ratio": "279754357977226400" }, "message": "" }
- Response JSON Object:
result (object) – A mapping of all accounts that currently have Liquity positions to
troveinformation.balances (object) – A mapping of all accounts that currently have Liquity positions to
troveinformation.total_collateral_ratio (integer) – Information about the Total Collateral Ratio in the protocol. Can be null in case of an error.
- Status Codes:
200 OK – Liquity balances successfully queried.
401 Unauthorized – User is not logged in.
409 Conflict – Liquity module is not activated.
500 Internal Server Error – Internal rotki error.
502 Bad Gateway – An external service used in the query such as etherscan could not be reached or returned unexpected response.
Getting Liquity staked amount
- GET /api/(version)/blockchains/eth/modules/liquity/staking
Doing a GET on the liquity balances resource will return the balances that the user has staked.
Note
This endpoint can also be queried asynchronously by using
"async_query": trueNote
This endpoint also accepts parameters as query arguments.
Note
This endpoint requires a premium account.
Example Request:
http
GET /api/1/blockchains/eth/modules/liquity/staking HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/blockchains/eth/modules/liquity/staking
wget
wget -S -O- http://localhost:5042/api/1/blockchains/eth/modules/liquity/staking
httpie
http http://localhost:5042/api/1/blockchains/eth/modules/liquity/stakingpython-requests
requests.get('http://localhost:5042/api/1/blockchains/eth/modules/liquity/staking')
- Request JSON Object:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "0x063c26fF1592688B73d8e2A18BA4C23654e2792E": { "balances": { "staked": { "asset": "ETH", "amount": "43.180853032438783295", "value": "43.180853032438783295", }, "lusd_rewards": { "asset": "eip155:1/erc20:0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D", "amount": "94477.70111867384658505", "value": "94477.70111867384658505", }, "eth_rewards": { "asset": "eip155:1/erc20:0x5f98805A4E8be255a32880FDeC7F6728C6568bA0", "amount": "10211401.723115634393264567", "value": "10211401.723115634393264567", } }, "proxies": { "0x063c26fF1592688B73d8e2A18BA4C23654e2792E": { "staked": { "asset": "ETH", "amount": "43.180853032438783295", "value": "43.180853032438783295", }, "lusd_rewards": { "asset": "eip155:1/erc20:0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D", "amount": "94477.70111867384658505", "value": "94477.70111867384658505", }, "eth_rewards": { "asset": "eip155:1/erc20:0x5f98805A4E8be255a32880FDeC7F6728C6568bA0", "amount": "10211401.723115634393264567", "value": "10211401.723115634393264567", } } } }, "message": "" }
- Response JSON Object:
optional[balances] (object) – A mapping of the category to the amount & value of assets staked in the protocol.
optional[proxies] (object) – A mapping of proxy addresses to the amount and value of assets staked in the protocol.
- Status Codes:
200 OK – Liquity staking information successfully queried.
401 Unauthorized – User is not logged in.
409 Conflict – Liquity module is not activated.
500 Internal Server Error – Internal rotki error.
502 Bad Gateway – An external service used in the query such as etherscan could not be reached or returned unexpected response.
Getting Liquity stability pool information
- GET /api/(version)/blockchains/eth/modules/liquity/pool
Doing a GET on the liquity stability pool resource will return the balances deposited in it and the rewards accrued.
Note
This endpoint can also be queried asynchronously by using
"async_query": trueNote
This endpoint requires a premium account.
Example Request:
http
GET /api/1/blockchains/eth/modules/liquity/pool HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/blockchains/eth/modules/liquity/pool
wget
wget -S -O- http://localhost:5042/api/1/blockchains/eth/modules/liquity/pool
httpie
http http://localhost:5042/api/1/blockchains/eth/modules/liquity/poolpython-requests
requests.get('http://localhost:5042/api/1/blockchains/eth/modules/liquity/pool')
- Request JSON Object:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "0x063c26fF1592688B73d8e2A18BA4C23654e2792E": { "balances": { "gains": { "asset": "ETH", "amount": "43.180853032438783295", "value": "43.180853032438783295", }, "rewards": { "asset": "eip155:1/erc20:0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D", "amount": "94477.70111867384658505", "value": "94477.70111867384658505", }, "deposited": { "asset": "eip155:1/erc20:0x5f98805A4E8be255a32880FDeC7F6728C6568bA0", "amount": "10211401.723115634393264567", "value": "10211401.723115634393264567", } }, "proxies": { "0x063c26fF1592688B73d8e2A18BA4C23654e2792E": { "gains": { "asset": "ETH", "amount": "43.180853032438783295", "value": "43.180853032438783295", }, "rewards": { "asset": "eip155:1/erc20:0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D", "amount": "94477.70111867384658505", "value": "94477.70111867384658505", }, "deposited": { "asset": "eip155:1/erc20:0x5f98805A4E8be255a32880FDeC7F6728C6568bA0", "amount": "10211401.723115634393264567", "value": "10211401.723115634393264567", } } } }, "message": "" }
- Response JSON Object:
balances (object) – A mapping of the category to the amount & value of assets staked in the protocol.
proxies (object) – A mapping of proxy addresses to the amount and value of assets staked in the protocol.
deposited (object) – Information about the amount and usd value of the LUSD deposited.
gains (object) – Information about the amount and usd value of the ETH gained as reward for liquidations.
rewards (object) – Information about the amount and usd value of the LQTY rewards gained.
- Status Codes:
200 OK – Liquity information successfully queried.
401 Unauthorized – User is not logged in.
409 Conflict – Liquity module is not activated.
500 Internal Server Error – Internal rotki error.
Getting Liquity staking information
- GET /api/(version)/blockchains/eth/modules/liquity/stats
Doing a GET on the liquity stats resource will return the statistics for staking in the stability pool and the LQTY staking service.
Note
This endpoint can also be queried asynchronously by using
"async_query": trueNote
This endpoint requires a premium account.
Example Request:
http
GET /api/1/blockchains/eth/modules/liquity/stats HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/blockchains/eth/modules/liquity/stats
wget
wget -S -O- http://localhost:5042/api/1/blockchains/eth/modules/liquity/stats
httpie
http http://localhost:5042/api/1/blockchains/eth/modules/liquity/statspython-requests
requests.get('http://localhost:5042/api/1/blockchains/eth/modules/liquity/stats')
- Request JSON Object:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "global_stats": { "total_value_gains_stability_pool": "41902.74041824219", "total_value_gains_staking": "190.09104568340678", "total_deposited_stability_pool": "1915600.7290263602", "total_withdrawn_stability_pool": "914454.5094041774", "total_deposited_stability_pool_value": "0.0", "total_withdrawn_stability_pool_value": "0.0", "staking_gains": [ { "asset": "ETH", "amount": "0.19015022103888912", "value": "23.001055387590114" }, { "asset": "eip155:1/erc20:0x5f98805A4E8be255a32880FDeC7F6728C6568bA0", "amount": "168.7710091203543", "value": "167.08999029581668" }, { "asset": "eip155:1/erc20:0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D", "amount": "1445.7823568041297", "value": "0.0" } ], "stability_pool_gains": [ { "asset": "ETH", "amount": "14.0767134582469", "value": "31051.389153894255" }, { "asset": "eip155:1/erc20:0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D", "amount": "11887.091269011284", "value": "10851.35126434794" } ] }, "by_address": { "0xF662f831361c8Ab48d807f7753eb3d641be25d24": { "total_value_gains_stability_pool": "0.0", "total_value_gains_staking": "0.0", "total_deposited_stability_pool": "1519146.7290263602", "total_withdrawn_stability_pool": "914454.5094041774", "total_deposited_stability_pool_value": "0.0", "total_withdrawn_stability_pool_value": "0.0", "staking_gains": [ { "asset": "ETH", "amount": "0.18236022449762773", "value": "0.0" }, { "asset": "eip155:1/erc20:0x5f98805A4E8be255a32880FDeC7F6728C6568bA0", "amount": "2.23017071973649", "value": "0.0" }, { "asset": "eip155:1/erc20:0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D", "amount": "1445.7823568041297", "value": "0.0" } ], "stability_pool_gains": [ { "asset": "ETH", "amount": "1.7820064710306824", "value": "0.0" }, { "asset": "eip155:1/erc20:0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D", "amount": "7646.741845927703", "value": "0.0" } ] }, "0xbB8311c7bAD518f0D8f907Cad26c5CcC85a06dC4": { "total_value_gains_stability_pool": "41902.74041824219", "total_value_gains_staking": "190.09104568340678", "total_deposited_stability_pool": "396454.0", "total_withdrawn_stability_pool": "0", "total_deposited_stability_pool_value": "0.0", "total_withdrawn_stability_pool_value": "0", "staking_gains": [ { "asset": "ETH", "amount": "0.007789996541261418", "value": "23.001055387590114" }, { "asset": "eip155:1/erc20:0x5f98805A4E8be255a32880FDeC7F6728C6568bA0", "amount": "166.54083840061782", "value": "167.08999029581668" } ], "stability_pool_gains": [ { "asset": "ETH", "amount": "12.294706987216218", "value": "31051.389153894255" }, { "asset": "eip155:1/erc20:0x6DEA81C8171D0bA574754EF6F8b412F2Ed88c54D", "amount": "4240.34942308358", "value": "10851.35126434794" } ] } } }, "message": "" }
- Response JSON Object:
result (object) – A mapping with the keys
global_statsandby_address.global_stats (object) – Stats aggregating the information for all the addresses tracked in the liquity module.
global_stats – Breakdown by tracked address of the stats.
total_value_gains_stability_pool (string) – Sum of all the gains valued at the moment of the event for the stability pool in the user’s main currency.
total_value_gains_staking (string) – Sum of all the gains valued at the moment of the event for liquity staking in the user’s main currency.
total_deposited_stability_pool (string) – Total amount of LUSD deposited in the stability pool.
total_withdrawn_stability_pool (string) – Total amount of LUSD withdrawn from the stability pool.
total_deposited_stability_pool_value (string) – Sum of the value deposited in the stability pool at the time of the events in the user’s main currency.
total_withdrawn_stability_pool_value (string) – Sum of the value withdrawn from the stability pool at the time of the events in the user’s main currency.
staking_gains (list[object]) – Breakdown by asset of the gains claimed by staking.
stability_pool_gains (list[object]) – Breakdown by asset of the gains claimed by depositing in the stability pool.
- Status Codes:
200 OK – Liquity staking stats successfully queried.
400 Bad Request – Requested module is not allowed to query statistics.
401 Unauthorized – User is not logged in.
409 Conflict – Liquity module is not activated.
500 Internal Server Error – Internal rotki error.
Getting Uniswap balances
- GET /api/(version)/blockchains/eth/modules/uniswap/v2/balances
Doing a GET on the uniswap balances resource will return the balances locked in Uniswap Liquidity Pools (LPs or pools).
Note
This endpoint can also be queried asynchronously by using
"async_query": trueExample Request:
http
GET /api/1/blockchains/eth/modules/uniswap/v2/balances HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/blockchains/eth/modules/uniswap/v2/balances
wget
wget -S -O- http://localhost:5042/api/1/blockchains/eth/modules/uniswap/v2/balances
httpie
http http://localhost:5042/api/1/blockchains/eth/modules/uniswap/v2/balancespython-requests
requests.get('http://localhost:5042/api/1/blockchains/eth/modules/uniswap/v2/balances')
- Request JSON Object:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "0xcf2B8EeC2A9cE682822b252a1e9B78EedebEFB02": [ { "address": "0x318BE2AA088FFb991e3F6E61AFb276744e36F4Ae", "assets": [ { "asset": { "ethereum_address": "0x364A7381A5b378CeD7AB33d1CDf6ff1bf162Bfd6", "name": "DeFi-X Token", "symbol": "TGX" }, "total_amount": "9588317.030426553444567747", "usd_price": "0.3015901111469715543448531276626107", "user_balance": { "amount": "4424094.631122964837017895643", "value": "1334263.191525095084350185834" } }, { "asset": "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7", "total_amount": "2897321.681999", "usd_price": "1.001", "user_balance": { "amount": "1336837.868136041506994516873", "value": "1338174.706004177548501511390" } } ], "total_supply": "5.255427314262137581", "user_balance": { "amount": "2.424878911648769806", "value": "2672437.897529272632851697224" } } ], }, "message": "", }
- Response JSON Object:
result (object) – A mapping between accounts and their Uniswap balances (represented by a list where each item is a LP).
address (string) – The LP contract address.
assets (list[object]) – A list with the LP underlying tokens data. Per item, when
"asset"is an object, it means the token is unknown to rotki."total_amount"is the total amount of this token the pool has."total_amount"is only available to premium users. For free usersnullis returned."usd_price"is the token USD price."user_balance"contains the user token balance and its estimated USD value.total_supply (optional[string]) – The total amount of liquidity tokens the LP has. Only available for premium users via the graph query. For free users
nullis returned.user_balance (object) – The liquidity token user balance and its USD value.
- Status Codes:
200 OK – Uniswap balances successfully queried.
401 Unauthorized – User is not logged in.
409 Conflict – Uniswap module is not activated.
500 Internal Server Error – Internal rotki error.
502 Bad Gateway – An external service used in the query such as etherscan or the graph node could not be reached or returned unexpected response.
Getting Loopring balances
- GET /api/(version)/blockchains/eth/modules/loopring/balances
Doing a GET on the loopring balances resource will return the balances in loopring L2 that the user has deposited from any of the L1 addresses that are set to track loopring.
Note
This endpoint can also be queried asynchronously by using
"async_query": trueExample Request:
http
GET /api/1/blockchains/eth/modules/loopring/balances HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/blockchains/eth/modules/loopring/balances
wget
wget -S -O- http://localhost:5042/api/1/blockchains/eth/modules/loopring/balances
httpie
http http://localhost:5042/api/1/blockchains/eth/modules/loopring/balancespython-requests
requests.get('http://localhost:5042/api/1/blockchains/eth/modules/loopring/balances')
- Request JSON Object:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "0xE74ad5437C6CFB0cCD6bADda1F6b57b6E542E75e": [{ "ETH": { "amount": "1050", "value": "950" }, "eip155:1/erc20:0x6810e776880C02933D47DB1b9fc05908e5386b96": { "amount": "1", "value": "5" } }] }, "message": "" }
- Response JSON Object:
result (object) – A mapping between accounts and their balances
- Status Codes:
200 OK – Loopring balances successfully queried.
401 Unauthorized – User is not logged in.
409 Conflict – Loopring module is not activated.
500 Internal Server Error – Internal rotki error.
502 Bad Gateway – An external service used in the query such as loopring returned an unexpected result.
Getting eth2 staking performance
- PUT /api/(version)/blockchains/eth2/stake/performance
Doing a PUT on the ETH2 stake performance endpoint will return the performance for all validators (or the filtered ones) in a paginated manner.
Note
This endpoint is only available for premium users
Note
This endpoint can also be queried asynchronously by using
"async_query": trueExample Request:
http
PUT /api/1/blockchains/eth2/stake/performance HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"from_timestamp": 1451606400, "to_timestamp": 1571663098, "validator_indices": [0, 15, 23542], "only_cache": false, "status": "all", "limit": 10, "offset": 10}
curl
curl -i -X PUT http://localhost:5042/api/1/blockchains/eth2/stake/performance -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_timestamp": 1451606400, "limit": 10, "offset": 10, "only_cache": false, "status": "all", "to_timestamp": 1571663098, "validator_indices": [0, 15, 23542]}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/blockchains/eth2/stake/performance --header="Content-Type: application/json;charset=UTF-8" --body-data='{"from_timestamp": 1451606400, "limit": 10, "offset": 10, "only_cache": false, "status": "all", "to_timestamp": 1571663098, "validator_indices": [0, 15, 23542]}'
httpie
echo '{ "from_timestamp": 1451606400, "limit": 10, "offset": 10, "only_cache": false, "status": "all", "to_timestamp": 1571663098, "validator_indices": [ 0, 15, 23542 ] }' | http PUT http://localhost:5042/api/1/blockchains/eth2/stake/performance Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/blockchains/eth2/stake/performance', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_timestamp': 1451606400, 'limit': 10, 'offset': 10, 'only_cache': False, 'status': 'all', 'to_timestamp': 1571663098, 'validator_indices': [0, 15, 23542]})
- Request JSON Object:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
only_cache (bool) – If false then we skip any cached values
limit (int) – Optional. This signifies the limit of records to return as per the sql spec.
offset (int) – This signifies the offset from which to start the return of records per the sql spec.
from_timestamp (int[optional]) – The timestamp from which to query. Can be missing in which case we query from 0.
to_timestamp (int[optional]) – The timestamp until which to query. Can be missing in which case we query until now.
validator_indices (list[optional]) – The indices of the validators to filter for
addresses (list[optional]) – The associated addresses for which to filter the results. These will associate with a validator if the address is a depositor, a withdrawal address or a fee recipient.
status (string[optional]) – The status by which to filter. By default and if missing it’s
"all"validators. Can also filter by"active"or"exited".
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "sums": { "apr": "0.0597652039949379861158979362586657031468575710584143257025001370766265371913491", "execution_blocks": "0.451964836013963505", "execution_mev": "0.31964836013963505", "exits": "0.0014143880000005993", "outstanding_consensus_pnl": "0.000829238", "sum": "3.2351487110139639043", "withdrawals": "2.2809402489999998" }, "validators": { "432840": { "apr": "0.0466762036714707128052091929912369373004480648295118244406922158753010413605874", "execution_blocks": "0.63361811418473", "execution_mev": "0.361811418473", "exits": "0.0014143880000005993", "sum": "2.5266283731847305993", "withdrawals": "1.591595871" }, "624729": { "apr": "0.0130890003234672733106887432674287658464095062289025012618079212013254958307617", "execution_blocks": "0.016346721829233505", "execution_mev": "0.012346721829233505", "outstanding_consensus_pnl": "0.000829238", "sum": "0.708520337829233305", "withdrawals": "0.6893443779999998" } }, "entries_found": 2, "entries_total": 402 }, "message": "" }
- Response JSON Object:
sums (object) – Sums of all the pages of the results
validator (object) – Mapping of validator index to performance for the current page
apr (string) – The APR of returns for the given timerange for the validator.
execution_blocks (string) – The sum of the block rewards of the validator sent to the fee recipient if that recipient is tracked.
execution_mev (string) – The sum of MEV rewards for blocks proposed by the validator if the MEV fee recipient is tracked.
withdrawals (string) – The sum of consensus layer withdrawals ETH pnl for the validator
exits (string) – The sum of the exit ETH PnL for the validator
outstanding_consensus_pnl (string) – If a recent timerange is queried we also take into account not yet withdrawn ETH gathering in the consensus layer.
entries_found (int) – The validators found for the current filter
entries_total (int) – The total number of validators found
- Status Codes:
200 OK – Eth2 validator performance successfully returned.
401 Unauthorized – User is not logged in.
403 Forbidden – Eth staking limit reached. Response should contain the keys
current_stakedandstaking_limit.409 Conflict – eth2 module is not activated.
500 Internal Server Error – Internal rotki error.
502 Bad Gateway – Error connecting to a remote to query data.
Adding an Eth2 validator
- PUT /api/(version)/blockchains/eth2/validators
Doing a PUT on the eth2 validators endpoint will input information and track an ETH2 validator.
Note
This endpoint can also be queried asynchronously by using
"async_query": trueExample Request:
http
PUT /api/1/blockchains/eth2/validators HTTP/1.1 Host: localhost:5042
curl
curl -i -X PUT http://localhost:5042/api/1/blockchains/eth2/validators
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/blockchains/eth2/validators
httpie
http PUT http://localhost:5042/api/1/blockchains/eth2/validators
python-requests
requests.put('http://localhost:5042/api/1/blockchains/eth2/validators')
- Request JSON Object:
int (validator_index) – An optional integer representing the validator index of the validator to track. If this is not given then the public key of the validator has to be given!
str (public_key) – An optional string representing the hexadecimal string of the public key of the validator to track. If this is not given the validator index has to be given!
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
- Response JSON Object:
ownership_percentage – An optional string representing the amount of the validator owned by the user in the range of 0 to 100. If not provided a default value of 100 is assigned.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true "message": "", }
- Status Codes:
200 OK – Eth2 validator successfully added.
403 Forbidden – Can’t add the validator since adding it would go over their premium staking limit. Response should contain the keys
current_stakedandstaking_limit.401 Unauthorized – User is not logged in.
409 Conflict – eth2 module is not activated.
500 Internal Server Error – Internal rotki error.
502 Bad Gateway – An external service used in the query such as beaconcha.in could not be reached or returned unexpected response.
Deleting Eth2 validators
- DELETE /api/(version)/blockchains/eth2/validators
Doing a DELETE on the eth2 validators endpoint will delete information and stop tracking a number of ETH2 validator/s.
Example Request:
http
DELETE /api/1/blockchains/eth2/validators HTTP/1.1 Host: localhost:5042 Content-Type: application/json { "validators": [1, 23423, 3233] }
curl
curl -i -X DELETE http://localhost:5042/api/1/blockchains/eth2/validators -H "Content-Type: application/json" --data-raw '{"validators": [1, 23423, 3233]}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/blockchains/eth2/validators --header="Content-Type: application/json" --body-data='{"validators": [1, 23423, 3233]}'
httpie
echo '{ "validators": [ 1, 23423, 3233 ] }' | http DELETE http://localhost:5042/api/1/blockchains/eth2/validators Content-Type:application/json
python-requests
requests.delete('http://localhost:5042/api/1/blockchains/eth2/validators', headers={'Content-Type': 'application/json'}, json={'validators': [1, 23423, 3233]})
- Request JSON Object:
validators (list[int]) – A list of indices of eth2 validators to delete
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Status Codes:
200 OK – Eth2 validator/s successfully delete.
401 Unauthorized – User is not logged in.
409 Conflict – eth2 module is not activated.
500 Internal Server Error – Internal rotki error.
Editing an Eth2 validator
- PATCH /api/(version)/blockchains/eth2/validators
Doing a PATCH on the eth2 validators endpoint will allow to edit the ownership percentage of a validator identified by its index.
Example Request:
http
PUT /api/1/blockchains/eth2/validators HTTP/1.1 Host: localhost:5042
curl
curl -i -X PUT http://localhost:5042/api/1/blockchains/eth2/validators
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/blockchains/eth2/validators
httpie
http PUT http://localhost:5042/api/1/blockchains/eth2/validators
python-requests
requests.put('http://localhost:5042/api/1/blockchains/eth2/validators')
- Request JSON Object:
int (validator_index) – An integer representing the validator index of the validator to edit.
- Response JSON Object:
ownership_percentage – A float representing the amount of the validator owned by the user in the range of 0 to 100. If not provided a default value of 100 is assigned.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true "message": "", }
- Status Codes:
200 OK – Eth2 validator successfully edited.
401 Unauthorized – User is not logged in.
403 Forbidden – editing the validator exceeded the eth staking limit. Response should contain the keys
current_stakedandstaking_limit.409 Conflict – eth2 module is not activated or validator doesn’t exist.
500 Internal Server Error – Internal rotki error.
Getting tracked Eth2 validators
- GET /api/(version)/blockchains/eth2/validators
Doing a GET on the ETH2 validators endpoint will get information on the tracked ETH2 validators. If the user is not premium they will see up to a certain limit of validators. If ignore cache is false, only DB data is return. If it’s true then all validator data will be refreshed and new validators will be detected.
Note
This endpoint can also be queried asynchronously by using
"async_query": trueExample Request:
http
GET /api/1/blockchains/eth2/validators HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"ignore_cache": true, "async_query": true}
curl
curl -i -X GET http://localhost:5042/api/1/blockchains/eth2/validators -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": true, "ignore_cache": true}'
wget
wget -S -O- http://localhost:5042/api/1/blockchains/eth2/validators --header="Content-Type: application/json;charset=UTF-8" --body-data='{"async_query": true, "ignore_cache": true}'
httpie
echo '{ "async_query": true, "ignore_cache": true }' | http http://localhost:5042/api/1/blockchains/eth2/validators Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/blockchains/eth2/validators', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': True, 'ignore_cache': True})
- Request JSON Object:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
ignore_cache (bool) – Boolean denoting whether to ignore the DB cache and refresh all validator data.
validator_indices (list(string)[optional]) – Optionally filter entries validator indices. If missing data for all validators are returned.
addresses (list(string)[optional]) – The associated addresses for which to filter the results. These will associate with a validator if the address is a depositor, a withdrawal address or a fee recipient.
status (string[optional]) – The status by which to filter. By default and if missing it’s
"all"validators. Can also filter by"active"or"exited".
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result":{ "entries":[ { "index":1, "public_key":"0xa1d1ad0714035353258038e964ae9675dc0252ee22cea896825c01458e1807bfad2f9969338798548d9858a571f7425c", "withdrawal_address": "0x23a3283f9f538a54d49139cd35c2fe0443cad3db", "status": "pending", }, { "index":1532, "public_key":"0xa509dec619e5b3484bf4bc1c33baa4c2cdd5ac791876f4add6117f7eded966198ab77862ec2913bb226bdf855cc6d6ed", "ownership_percentage": "50", "activation_timestamp": 1701971000, "status": "active" }, { "index":5421, "public_key":"0xa64722f93f37c7da8da67ee36fd2a763103897efc274e3accb4cd172382f7a170f064b81552ae77cdbe440208a1b897e", "ownership_percentage": "25.75", "withdrawal_address": "0xfa13283f9e538a84d49139cd35c2fe0443caa34f", "activation_timestamp": 1701972000, "withdrawable_timestamp": 1702572000, "exited_timestamp": 1702584000, "status": "exited" } ], "entries_found":3, "entries_limit":4 }, "message":"" }
- Response JSON Object:
entries (object) – The resulting entries list
index (integer) – The index of the validator
public_key (string) – The public key of the validator
status (string) – The status of the validator. Can be one of
"pending","active","exiting","consolidated"and"exited".ownership_percentage (string[optional]) – The ownership percentage of the validator. If missing assume 100%.
withdrawal_address (string[optional]) – The withdrawal address for the validator if set.
activation_timestamp (integer[optional]) – If existing this is the timestamp the validator will (or has been) activate/d. If not then this is a pending validator not yet fully deposited or not yet processed by the consensus layer.
withdrawable_timestamp (integer[optional]) – If existing this is the timestamp the validator will (or has been) able to be completely withdrawn. In other words from which point on a full exit will happen next time it’s skimmed by withdrawals. If this key exists this mean we are dealing with a validator that is exiting or has exited.
exited_timestamp (integer[optional]) – If existing this is the timestamp the validator has exited the beaconchain.
consolidated_into (integer[optional]) – The validator index in which it was consolidated into. Only present if the validator is
"consolidated"
- Status Codes:
200 OK – Eth2 validator defaults successfully returned.
401 Unauthorized – User is not logged in.
409 Conflict – eth2 module is not activated.
500 Internal Server Error – Internal rotki error.
502 Bad Gateway – Error contacting to a remote to query data.
Querying ethereum airdrops
- GET /api/(version)/blockchains/eth/airdrops
Doing a GET on the ethereum airdrops endpoint will return how much and of which token any of the tracked ethereum addresses are entitled to.
Example Request
http
GET /api/1/blockchains/eth/airdrops HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/blockchains/eth/airdrops
wget
wget -S -O- http://localhost:5042/api/1/blockchains/eth/airdrops
httpie
http http://localhost:5042/api/1/blockchains/eth/airdropspython-requests
requests.get('http://localhost:5042/api/1/blockchains/eth/airdrops')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "0xe5B3330A43CeC5A01A80E75ebaB2d3bc17e70819": { "1inch": { "amount": "675.55", "asset": "eip155:1/erc20:0x111111111117dC0aa78b770fA6A738034120C302", "link": "https://app.uniswap.org/", "claimed": false, "cutoff_time": 1719697503, "has_decoder": true } }, "0x0B89f648eEcCc574a9B7449B5242103789CCD9D7": { "1inch": { "amount": "1823.23", "asset": "eip155:1/erc20:0x111111111117dC0aa78b770fA6A738034120C302", "link": "https://1inch.exchange/", "claimed": false, "has_decoder": false }, "uniswap": { "amount": "400", "asset": "eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", "link": "https://app.uniswap.org/", "claimed": true, "icon_url": "https://raw.githubusercontent.com/rotki/data/main/airdrops/icons/uniswap.svg", "has_decoder": true } }, "message": "" } }
- Request JSON Object:
result (object) – A mapping of addresses to protocols for which claimable airdrops exist
- Status Codes:
200 OK – Tags successfully queried.
401 Unauthorized – User is not logged in.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Could not query an airdrop file
507 Insufficient Storage – Failed to store CSV files for airdrops.
Get addresses to query per protocol
- GET /api/(version)/queried_addresses/
Doing a GET on this endpoint will return a mapping of which addresses are set for querying for each protocol. If a protocol is not returned or has no addresses then all addresses are queried
Example Request:
http
GET /api/1/queried_addresses HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/queried_addresses
wget
wget -S -O- http://localhost:5042/api/1/queried_addresses
httpie
http http://localhost:5042/api/1/queried_addressespython-requests
requests.get('http://localhost:5042/api/1/queried_addresses')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "aave": ["0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b"], "makerdao_dsr": ["0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b"], }, "message": "" }
- Response JSON Object:
result (list) – A mapping of modules/protocols for which an entry exists to the list of addresses to query.
- Status Codes:
200 OK – The addresses have been queried successfully
401 Unauthorized – No user is logged in.
500 Internal Server Error – Internal rotki error
Add address to query per protocol
- PUT /api/(version)/queried_addresses/
Doing a PUT on this endpoint will add a new address for querying by a protocol/module. Returns all the queried addresses per module after the addition.
Example Request:
http
PUT /api/1/queried_addresses HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "module": "aave", "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b" }
curl
curl -i -X PUT http://localhost:5042/api/1/queried_addresses -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b", "module": "aave"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/queried_addresses --header="Content-Type: application/json;charset=UTF-8" --body-data='{"address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b", "module": "aave"}'
httpie
echo '{ "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b", "module": "aave" }' | http PUT http://localhost:5042/api/1/queried_addresses Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/queried_addresses', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'address': '0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b', 'module': 'aave'})
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "aave": ["0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b"], "makerdao_dsr": ["0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b"], }, "message": "" }
- Response JSON Object:
result (list) – A mapping of modules/protocols for which an entry exists to the list of addresses to query.
- Status Codes:
200 OK – The address has been added successfully.
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is logged in.
409 Conflict – The address already exists in the addresses to query for that protocol.
500 Internal Server Error – Internal rotki error
Remove an address to query per protocol
- DELETE /api/(version)/queried_addresses/
Doing a DELETE on this endpoint will remove an address for querying by a protocol/module. Returns all the queried addresses per module after the deletion.
Example Request:
http
DELETE /api/1/queried_addresses HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "module": "aave", "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b" }
curl
curl -i -X DELETE http://localhost:5042/api/1/queried_addresses -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b", "module": "aave"}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/queried_addresses --header="Content-Type: application/json;charset=UTF-8" --body-data='{"address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b", "module": "aave"}'
httpie
echo '{ "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b", "module": "aave" }' | http DELETE http://localhost:5042/api/1/queried_addresses Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/1/queried_addresses', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'address': '0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b', 'module': 'aave'})
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "aave": ["0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B"], "makerdao_dsr": ["0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b"], }, "message": "" }
- Response JSON Object:
result (list) – A mapping of modules/protocols for which an entry exists to the list of addresses to query.
- Status Codes:
200 OK – The address has been removed successfully.
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is logged in.
409 Conflict – The address is not in the addresses to query for that protocol.
500 Internal Server Error – Internal rotki error
Adding EVM accounts to all EVM chains
- PUT /api/(version)/blockchains/evm/accounts
Doing a PUT on the EVM accounts endpoint functions just like the add blockchain accounts endpoint but adds the addresses for all evm chains. It will follow the following logic. Take ethereum mainnet as the parent chain. If it’s a contract there, it will only add it to the mainnet. If it’s an EoA it will try all chains one by one and see if they have any transactions/activity and add it to the ones that do.
Note
This endpoint can also be queried asynchronously by using
"async_query": trueExample Request:
http
PUT /api/1/blockchains/evm/accounts HTTP/1.1 Host: localhost:5042 { "accounts": [{ "address": "0x9008D19f58AAbD9eD0D60971565AA8510560ab41", "label": "my new metamask", "tags": ["public", "metamask"] }, { "address": "0x9531C059098e3d194fF87FebB587aB07B30B1306" }, { "address": "0x106B62Fdd27B748CF2Da3BacAB91a2CaBaeE6dCa" }, { "address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65" }, { "address": "0x7277F7849966426d345D8F6B9AFD1d3d89183083" }] } For request details check `here <blockchain_account_addition_section_>`__
curl
curl -i -X PUT http://localhost:5042/api/1/blockchains/evm/accounts --data-raw '{ "accounts": [{ "address": "0x9008D19f58AAbD9eD0D60971565AA8510560ab41", "label": "my new metamask", "tags": ["public", "metamask"] }, { "address": "0x9531C059098e3d194fF87FebB587aB07B30B1306" }, { "address": "0x106B62Fdd27B748CF2Da3BacAB91a2CaBaeE6dCa" }, { "address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65" }, { "address": "0x7277F7849966426d345D8F6B9AFD1d3d89183083" }] } For request details check `here <blockchain_account_addition_section_>`__'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/blockchains/evm/accounts --body-data='{ "accounts": [{ "address": "0x9008D19f58AAbD9eD0D60971565AA8510560ab41", "label": "my new metamask", "tags": ["public", "metamask"] }, { "address": "0x9531C059098e3d194fF87FebB587aB07B30B1306" }, { "address": "0x106B62Fdd27B748CF2Da3BacAB91a2CaBaeE6dCa" }, { "address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65" }, { "address": "0x7277F7849966426d345D8F6B9AFD1d3d89183083" }] } For request details check `here <blockchain_account_addition_section_>`__'
httpie
echo '{ "accounts": [{ "address": "0x9008D19f58AAbD9eD0D60971565AA8510560ab41", "label": "my new metamask", "tags": ["public", "metamask"] }, { "address": "0x9531C059098e3d194fF87FebB587aB07B30B1306" }, { "address": "0x106B62Fdd27B748CF2Da3BacAB91a2CaBaeE6dCa" }, { "address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65" }, { "address": "0x7277F7849966426d345D8F6B9AFD1d3d89183083" }] } For request details check `here <blockchain_account_addition_section_>`__' | http PUT http://localhost:5042/api/1/blockchains/evm/accounts
python-requests
requests.put('http://localhost:5042/api/1/blockchains/evm/accounts', data='{\r\n\n "accounts": [{\r\n\n "address": "0x9008D19f58AAbD9eD0D60971565AA8510560ab41",\r\n\n "label": "my new metamask",\r\n\n "tags": ["public", "metamask"]\r\n\n }, {\r\n\n "address": "0x9531C059098e3d194fF87FebB587aB07B30B1306"\r\n\n }, {\r\n\n "address": "0x106B62Fdd27B748CF2Da3BacAB91a2CaBaeE6dCa"\r\n\n }, {\r\n\n "address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65"\r\n\n }, {\r\n\n "address": "0x7277F7849966426d345D8F6B9AFD1d3d89183083"\r\n\n }]\r\n\n}\r\n\n\r\n\nFor request details check `here <blockchain_account_addition_section_>`__')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "added":{ "0x9531C059098e3d194fF87FebB587aB07B30B1306": ["all"], "0x9008D19f58AAbD9eD0D60971565AA8510560ab41": ["eth"] }, "failed":{ "0xc37b40ABdB939635068d3c5f13E7faF686F03B65": [ "polygon_pos", "arbitrum_one", "base", "gnosis" ] }, "existed":{ "0x7277F7849966426d345D8F6B9AFD1d3d89183083": ["gnosis"] }, "no_activity":{ "0x106B62Fdd27B748CF2Da3BacAB91a2CaBaeE6dCa": ["all"], "0x7277F7849966426d345D8F6B9AFD1d3d89183083": [ "eth", "optimism", "avax", "polygon_pos", "arbitrum_one", "base" ] } }, "message": "" }
Note
When a result includes all the chains instead of listing them all we use the special symbol
all- Response JSON Object:
added (object) – A mapping containing addresses and what chains they were added to.
existed (object) – A mapping containing addresses and in what chains they were already tracked before the api call so no action was taken on them.
failed (object) – A mapping containing which chains failed to get added for each address due to some error contacting remote APIs.
no_activity (object) – A mapping containing addresses and in which chains they had no activity so no action was taken for them.
- Status Codes:
200 OK – Accounts successfully added
400 Bad Request – Provided JSON or data is in some way malformed. The accounts to add contained invalid addresses or were an empty list.
401 Unauthorized – User is not logged in.
409 Conflict – Provided tags do not exist. Check message for details.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Remote error occurred when attempted to connect to an Avalanche or Polkadot node and only if it’s the first account added. Check message for details.
- POST /api/(version)/blockchains/evm/accounts
Doing a POST on the EVM accounts endpoint will re-detect evm accounts on all supported chains. Rotki will go through already added addresses and for each address, if it is an EOA (not a smart contract) and has activity on some chain, will add it to that chain.
Note
This endpoint can also be queried asynchronously by using
"async_query": trueExample Request:
http
POST /api/1/blockchains/evm/accounts HTTP/1.1 Host: localhost:5042 {}
curl
curl -i -X POST http://localhost:5042/api/1/blockchains/evm/accounts --data-raw '{}'
wget
wget -S -O- http://localhost:5042/api/1/blockchains/evm/accounts --post-data='{}'
httpie
echo '{}' | http POST http://localhost:5042/api/1/blockchains/evm/accounts
python-requests
requests.post('http://localhost:5042/api/1/blockchains/evm/accounts', data='{}')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – true in case of success, null otherwise.
- Status Codes:
200 OK – Accounts successfully added
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – User is not logged in.
409 Conflict – Node that was queried is not synchronized.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Remote error occurred.
Adding blockchain accounts
- PUT /api/(version)/blockchains/(blockchain)/accounts
Note
Supported blockchains:
"BTC", "BCH", "KSM", "DOT", "SOLANA"and all supported EVM chains.Supported blockchains with ENS domains:
"BTC", "BCH", "ETH", "KSM", "DOT"This endpoint can also be queried asynchronously by using
"async_query": trueDoing a PUT on the blockchains endpoint with a specific blockchain URL and a list of account data in the json data will add these accounts to the tracked accounts for the given blockchain and the current user. A list of accounts’ addresses that were added during a request is returned. This data is returned so that if you add an ens name, you get its name’s resolved address for the further usage. If one of the given accounts to add is invalid the entire request will fail.
Example Request:
http
PUT /api/1/blockchains/eth/accounts HTTP/1.1 Host: localhost:5042 { "accounts": [{ "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "label": "my new metamask", "tags": ["public", "metamask"] }, { "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b" }] }curl
curl -i -X PUT http://localhost:5042/api/1/blockchains/eth/accounts --data-raw '{ "accounts": [{ "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "label": "my new metamask", "tags": ["public", "metamask"] }, { "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b" }] }'wget
wget -S -O- --method=PUT http://localhost:5042/api/1/blockchains/eth/accounts --body-data='{ "accounts": [{ "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "label": "my new metamask", "tags": ["public", "metamask"] }, { "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b" }] }'httpie
echo '{ "accounts": [{ "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "label": "my new metamask", "tags": ["public", "metamask"] }, { "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b" }] }' | http PUT http://localhost:5042/api/1/blockchains/eth/accountspython-requests
requests.put('http://localhost:5042/api/1/blockchains/eth/accounts', data='{\r\n\n "accounts": [{\r\n\n "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B",\r\n\n "label": "my new metamask",\r\n\n "tags": ["public", "metamask"]\r\n\n }, {\r\n\n "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b"\r\n\n }]\r\n\n}')
- reqjson list[object] accounts:
A list of account data to add for the given blockchain
- reqjsonarr string address:
The address of the account to add. Can either be a hexadecimal address or an ENS name.
- reqjsonarr string[optional] label:
An optional label to describe the new account. Cannot be empty string.
- reqjsonarr list[optional] tags:
An optional list of tags to attach to the new account. Can be null. Should never be an empty list.
- reqjson bool async_query:
Boolean denoting whether this is an asynchronous query or not
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": [ "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b" ], "message": "" }
- resjson list result:
A list containing accounts’ addresses that were added during a request.
- statuscode 200:
Accounts successfully added
- statuscode 400:
Provided JSON or data is in some way malformed. The accounts to add contained invalid addresses or were an empty list.
- statuscode 401:
User is not logged in.
- statuscode 409:
Provided tags do not exist. Check message for details.
- statuscode 500:
Internal rotki error
- statuscode 502:
Remote error occurred when attempted to connect to an Avalanche or Polkadot node and only if it’s the first account added. Check message for details.
Adding BTC/BCH xpubs
- PUT /api/(version)/blockchains/(blockchain)/xpub
Note
This endpoint can also be queried asynchronously by using
"async_query": trueNote
Only
"BCH"and"BTC"are the supported blockchain values for Xpubs.Doing a PUT on the xpubs endpoint will add an extended public key for bitcoin/bitcoin cash mainnet. All derived addresses that have ever had a transaction from this xpub and derivation path will be found and added for tracking in rotki.
Example Request:
http
PUT /api/1/blockchains/BTC/xpub HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk", "xpub_type": "p2sh_p2wpkh", "derivation_path": "m/0/0", "label": "my electrum xpub", "tags": ["public", "old"] }
curl
curl -i -X PUT http://localhost:5042/api/1/blockchains/BTC/xpub -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"derivation_path": "m/0/0", "label": "my electrum xpub", "tags": ["public", "old"], "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk", "xpub_type": "p2sh_p2wpkh"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/blockchains/BTC/xpub --header="Content-Type: application/json;charset=UTF-8" --body-data='{"derivation_path": "m/0/0", "label": "my electrum xpub", "tags": ["public", "old"], "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk", "xpub_type": "p2sh_p2wpkh"}'
httpie
echo '{ "derivation_path": "m/0/0", "label": "my electrum xpub", "tags": [ "public", "old" ], "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk", "xpub_type": "p2sh_p2wpkh" }' | http PUT http://localhost:5042/api/1/blockchains/BTC/xpub Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/blockchains/BTC/xpub', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'derivation_path': 'm/0/0', 'label': 'my electrum xpub', 'tags': ['public', 'old'], 'xpub': 'xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk', 'xpub_type': 'p2sh_p2wpkh'})
- Request JSON Object:
xpub (string) – The extended public key to add
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
- Request JSON Array of Objects:
derivation_path (string) – The derivation path from which to start deriving addresses relative to the xpub.
xpub_type (string[optional]) – An optional type to denote the type of the given xpub. If omitted the prefix xpub/ypub/zpub is used to determine the type. The valid xpub types are:
"p2pkh","p2sh_p2wpkh","wpkh"and"p2tr".label (string[optional]) – An optional label to describe the new extended public key
tags (list[optional]) – An optional list of tags to attach to the xpub. Can be null. Should never be an empty list.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Status Codes:
200 OK – Xpub successfully added
400 Bad Request – Provided JSON or data is in some way malformed. The accounts to add contained invalid addresses or were an empty list.
401 Unauthorized – User is not logged in.
409 Conflict – Some error occurred when re-querying the balances after addition. Provided tags do not exist. Check message for details.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Error occurred with some external service query such as blockstream or haskoin. Check message for details.
Editing BTC/BCH xpubs
- PATCH /api/(version)/blockchains/(blockchain)/xpub
Note
Only
"BCH"and"BTC"are the supported blockchain values for Xpubs.Doing a PATCH on the xpubs endpoint will edit the label and tag of an extended public key for bitcoin/bitcoin cash mainnet.
Example Request:
http
PATCH /api/1/blockchains/BTC/xpub HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk", "derivation_path": "m/0/0", "label": "my electrum xpub", "tags": ["public", "old"] }
curl
curl -i -X PATCH http://localhost:5042/api/1/blockchains/BTC/xpub -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"derivation_path": "m/0/0", "label": "my electrum xpub", "tags": ["public", "old"], "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk"}'
wget
wget -S -O- --method=PATCH http://localhost:5042/api/1/blockchains/BTC/xpub --header="Content-Type: application/json;charset=UTF-8" --body-data='{"derivation_path": "m/0/0", "label": "my electrum xpub", "tags": ["public", "old"], "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk"}'
httpie
echo '{ "derivation_path": "m/0/0", "label": "my electrum xpub", "tags": [ "public", "old" ], "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk" }' | http PATCH http://localhost:5042/api/1/blockchains/BTC/xpub Content-Type:"application/json;charset=UTF-8"
python-requests
requests.patch('http://localhost:5042/api/1/blockchains/BTC/xpub', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'derivation_path': 'm/0/0', 'label': 'my electrum xpub', 'tags': ['public', 'old'], 'xpub': 'xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk'})
- Request JSON Object:
xpub (string) – The extended public key to edit
- Request JSON Array of Objects:
derivation_path (string) – The derivation path from which to start deriving addresses relative to the xpub.
label (string[optional]) – An optional label to describe the new extended public key
tags (list[optional]) – An optional list of tags to attach to the xpub. Can be null. Should never be an empty list.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "per_account": { "BTC": { "standalone": { "3Kb9QPcTUJKspzjQFBppfXRcWew6hyDAPb": { "amount": "0.5", "usd_value": "3770.075" }, "33hjmoU9XjEz8aLxf44FNGB8TdrLkAVBBo": { "amount": "0.5", "usd_value": "3770.075" }}, "xpubs": [{ "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk", "derivation_path": "m/0/0", "addresses": { "1LZypJUwJJRdfdndwvDmtAjrVYaHko136r": { "amount": "0.5", "usd_value": "3770.075" }, "1AMrsvqsJzDq25QnaJzX5BzEvdqQ8T6MkT": { "amount": "0.5", "usd_value": "3770.075" } }}, { "xpub": "zpub6quTRdxqWmerHdiWVKZdLMp9FY641F1F171gfT2RS4D1FyHnutwFSMiab58Nbsdu4fXBaFwpy5xyGnKZ8d6xn2j4r4yNmQ3Yp3yDDxQUo3q", "derivation_path": "m", "addresses": { "bc1qc3qcxs025ka9l6qn0q5cyvmnpwrqw2z49qwrx5": { "amount": "0.5", "usd_value": "3770.075" }, "bc1qr4r8vryfzexvhjrx5fh5uj0s2ead8awpqspqra": { "amount": "0.5", "usd_value": "3770.075" } }}] }, "ETH": { "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B": { "assets": { "ETH": {"amount": "10", "usd_value": "1755.53"}, "GNO": {"amount": "1", "usd_value": "50"}, "RDN": {"amount": "1", "usd_value": "1.5"} }, "total_usd_value": "1807.03", }} }, "totals": { "BTC": {"amount": "1", "usd_value": "7540.15"}, "ETH": {"amount": "10", "usd_value": "1650.53"}, "RDN": {"amount": "1", "usd_value": "1.5"}, "GNO": {"amount": "1", "usd_value": "50"} }, "message": "" }
- Response JSON Object:
result (object) – An object containing the
"per_account"and"totals"keys as also defined here.
- Status Codes:
200 OK – Xpub successfully edited
400 Bad Request – Provided JSON or data is in some way malformed. The accounts to add contained invalid addresses or were an empty list.
401 Unauthorized – User is not logged in.
409 Conflict – Some error occurred when re-querying the balances after addition. Provided tags do not exist. Check message for details.
500 Internal Server Error – Internal rotki error
Deleting BTC/BCH xpubs
- DELETE /api/(version)/blockchains/(blockchain)/xpub
Note
This endpoint can also be queried asynchronously by using
"async_query": trueNote
Only
"BCH"and"BTC"are the supported blockchain values for Xpubs.Doing a DELETE on the xpubs endpoint will remove an extended public key for bitcoin/bitcoin cash mainnet. All derived addresses from the xpub will also be deleted.
Example Request:
http
DELETE /api/1/blockchains/BTC/xpub HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk", "derivation_path": "m/0/0" }
curl
curl -i -X DELETE http://localhost:5042/api/1/blockchains/BTC/xpub -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"derivation_path": "m/0/0", "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk"}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/blockchains/BTC/xpub --header="Content-Type: application/json;charset=UTF-8" --body-data='{"derivation_path": "m/0/0", "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk"}'
httpie
echo '{ "derivation_path": "m/0/0", "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk" }' | http DELETE http://localhost:5042/api/1/blockchains/BTC/xpub Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/1/blockchains/BTC/xpub', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'derivation_path': 'm/0/0', 'xpub': 'xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk'})
- Request JSON Object:
xpub (string) – The extended public key to remove
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
- Request JSON Array of Objects:
derivation_path (string) – The derivation path from which addresses were derived.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "per_account": { "BTC": { "standalone": { "3Kb9QPcTUJKspzjQFBppfXRcWew6hyDAPb": { "amount": "0.5", "usd_value": "3770.075" }, "33hjmoU9XjEz8aLxf44FNGB8TdrLkAVBBo": { "amount": "0.5", "usd_value": "3770.075" }}, "xpubs": [{ "xpub": "zpub6quTRdxqWmerHdiWVKZdLMp9FY641F1F171gfT2RS4D1FyHnutwFSMiab58Nbsdu4fXBaFwpy5xyGnKZ8d6xn2j4r4yNmQ3Yp3yDDxQUo3q", "derivation_path": "m", "addresses": { "bc1qc3qcxs025ka9l6qn0q5cyvmnpwrqw2z49qwrx5": { "amount": "0.5", "usd_value": "3770.075" }, "bc1qr4r8vryfzexvhjrx5fh5uj0s2ead8awpqspqra": { "amount": "0.5", "usd_value": "3770.075" } }}] }, "ETH": { "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B": { "assets": { "ETH": {"amount": "10", "usd_value": "1755.53"}, "GNO": {"amount": "1", "usd_value": "50"}, "RDN": {"amount": "1", "usd_value": "1.5"} }, "liabilities": {} }} }, "totals": { "assets": { "BTC": {"amount": "1", "usd_value": "7540.15"}, "ETH": {"amount": "10", "usd_value": "1650.53"}, "RDN": {"amount": "1", "usd_value": "1.5"}, "GNO": {"amount": "1", "usd_value": "50"} }, "liabilities": {} }, "message": "" }
- Response JSON Object:
result (object) – An object containing the
"per_account"and"totals"keys as also defined here.
- Status Codes:
200 OK – Xpub successfully removed
400 Bad Request – Provided JSON or data is in some way malformed. The accounts to add contained invalid addresses or were an empty list.
401 Unauthorized – User is not logged in.
409 Conflict – Some error occurred when re-querying the balances after addition. Check message for details.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Error occurred with some external service query such as blockstream/haskoin. Check message for details.
Querying BTC/BCH xpub balances
- GET /api/(version)/blockchains/(blockchain)/xpub
Note
This endpoint can also be queried asynchronously by using
"async_query": trueNote
Only
"BCH"and"BTC"are the supported blockchain values for Xpubs.Doing a GET on the xpub endpoint will query balances for all addresses derived from the specified extended public key.
When
ignore_cacheis true, the endpoint will first check for newly derived addresses from the xpub and include them in the balance query. When false, it uses only existing derived addresses stored in the database.Example Request:
http
GET /api/1/blockchains/BTC/xpub?xpub=xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk&derivation_path=m%2F0%2F0&ignore_cache=true&async_query=false HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8
curl
curl -i -X GET 'http://localhost:5042/api/1/blockchains/BTC/xpub?xpub=xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk&derivation_path=m%2F0%2F0&ignore_cache=true&async_query=false' -H "Content-Type: application/json;charset=UTF-8"
wget
wget -S -O- 'http://localhost:5042/api/1/blockchains/BTC/xpub?xpub=xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk&derivation_path=m%2F0%2F0&ignore_cache=true&async_query=false' --header="Content-Type: application/json;charset=UTF-8"
httpie
http 'http://localhost:5042/api/1/blockchains/BTC/xpub?xpub=xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk&derivation_path=m%2F0%2F0&ignore_cache=true&async_query=false' Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/blockchains/BTC/xpub?xpub=xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk&derivation_path=m%2F0%2F0&ignore_cache=true&async_query=false', headers={'Content-Type': 'application/json;charset=UTF-8'})
- Query Parameters:
xpub (string) – The extended public key to query balances for
derivation_path (string) – [Optional] The derivation path used with the xpub
ignore_cache (bool) – [Optional] Whether to check for new derived addresses. Defaults to false
async_query (bool) – [Optional] Boolean denoting whether this is an asynchronous query or not
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "per_account": { "BTC": { "1LZypJUwJJRdfdndwvDmtAjrVYaHko136r": { "amount": "0.5", "usd_value": "3770.075" }, "1AMrsvqsJzDq25QnaJzX5BzEvdqQ8T6MkN": { "amount": "0.0005", "usd_value": "3.77" } } }, "totals": { "assets": { "BTC": {"amount": "0.5005", "usd_value": "3773.845"} }, "liabilities": {} } }, "message": "" }
- Response JSON Object:
result (object) – An object containing balance information for all addresses derived from the xpub. Uses the same format as blockchain balance queries with
"per_account"and"totals"keys as defined here.
- Status Codes:
200 OK – Xpub balances successfully queried
400 Bad Request – Provided parameters are malformed or the xpub is invalid
401 Unauthorized – User is not logged in
502 Bad Gateway – Error occurred with some external service query such as blockstream/haskoin. Check message for details.
Editing blockchain account data
- PATCH /api/(version)/blockchains/(blockchain)/accounts
Note
Supported blockchains:
"BTC", "BCH", "KSM", "DOT", "SOLANA"and all supported EVM chains.Supported blockchains with ENS domains:
"BTC", "BCH", "ETH", "KSM", "DOT"Doing a PATCH on the blockchains endpoint with a specific blockchain URL and a list of accounts to edit will edit the label and tags for those accounts.
Example Request:
http
PATCH /api/1/blockchains/eth/accounts HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "accounts": [ { "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "label": "my new metamask", "tags": [ "public", "metamask" ] }, { "address": "johndoe.eth", "label": "my hardware wallet" } ] }
curl
curl -i -X PATCH http://localhost:5042/api/1/blockchains/eth/accounts -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"accounts": [{"address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "label": "my new metamask", "tags": ["public", "metamask"]}, {"address": "johndoe.eth", "label": "my hardware wallet"}]}'
wget
wget -S -O- --method=PATCH http://localhost:5042/api/1/blockchains/eth/accounts --header="Content-Type: application/json;charset=UTF-8" --body-data='{"accounts": [{"address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "label": "my new metamask", "tags": ["public", "metamask"]}, {"address": "johndoe.eth", "label": "my hardware wallet"}]}'
httpie
echo '{ "accounts": [ { "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "label": "my new metamask", "tags": [ "public", "metamask" ] }, { "address": "johndoe.eth", "label": "my hardware wallet" } ] }' | http PATCH http://localhost:5042/api/1/blockchains/eth/accounts Content-Type:"application/json;charset=UTF-8"
python-requests
requests.patch('http://localhost:5042/api/1/blockchains/eth/accounts', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'accounts': [{'address': '0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B', 'label': 'my new metamask', 'tags': ['public', 'metamask']}, {'address': 'johndoe.eth', 'label': 'my hardware wallet'}]})
- Request JSON Object:
accounts (list[object]) – A list of account data to edit for the given blockchain
- Request JSON Array of Objects:
address (string) – The address of the account to edit. Can either be a hexadecimal address or an ENS name.
label (string[optional]) – An optional label to edit for the account. Cannot be empty string.
tags (list[optional]) – An optional list of tags to attach to the account. Can be null. Should never be an empty list.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result" : [{ "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "label": "my new metamask", "tags": ["public", "metamask"] }, { "address": "0x19b0AD50E768D2376C6BA7de32F426ecE4e03e0b", "label": "my hardware wallet", "tags": null }], "message": "", }
- Response JSON Object:
result (list) – A list containing the blockchain account data as also defined here. Result is different depending on the blockchain type.
- Status Codes:
200 OK – Accounts successfully edited
400 Bad Request – Provided JSON or data is in some way malformed. Given list to edit is empty.
401 Unauthorized – User is not logged in.
409 Conflict – An account given to edit does not exist or a given tag does not exist.
500 Internal Server Error – Internal rotki error
Account operations by chain type
- PATCH /api/(version)/blockchains/type/(chain_type)/accounts
Note
Supported blockchains types:
EVM, BITCOIN, SUBSTRATE, SOLANANote
This endpoint doesn’t support ENS resolution
This endpoint can also be queried asynchronously by using
"async_query": trueDoing a PATCH on this endpoint with a list of accounts to edit will edit the label and tags for those accounts in all the chains of the same type where they are tracked.
Example Request:
http
PATCH /api/1/blockchains/type/evm/accounts HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "accounts": [ { "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "label": "my new metamask", "tags": [ "public", "metamask" ] }, { "address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "label": "my hardware wallet" } ] }
curl
curl -i -X PATCH http://localhost:5042/api/1/blockchains/type/evm/accounts -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"accounts": [{"address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "label": "my new metamask", "tags": ["public", "metamask"]}, {"address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "label": "my hardware wallet"}]}'
wget
wget -S -O- --method=PATCH http://localhost:5042/api/1/blockchains/type/evm/accounts --header="Content-Type: application/json;charset=UTF-8" --body-data='{"accounts": [{"address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "label": "my new metamask", "tags": ["public", "metamask"]}, {"address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "label": "my hardware wallet"}]}'
httpie
echo '{ "accounts": [ { "address": "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B", "label": "my new metamask", "tags": [ "public", "metamask" ] }, { "address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "label": "my hardware wallet" } ] }' | http PATCH http://localhost:5042/api/1/blockchains/type/evm/accounts Content-Type:"application/json;charset=UTF-8"
python-requests
requests.patch('http://localhost:5042/api/1/blockchains/type/evm/accounts', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'accounts': [{'address': '0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B', 'label': 'my new metamask', 'tags': ['public', 'metamask']}, {'address': '0xc37b40ABdB939635068d3c5f13E7faF686F03B65', 'label': 'my hardware wallet'}]})
- Request JSON Object:
chain_type (string) – The type of blockchain where the address was added.
EVM,BITCOINorSUBSTRATEaccounts (list[object]) – A list of account data to edit.
- Request JSON Array of Objects:
address (string) – The address of the account to edit. It doesn’t allow ENS names.
label (string[optional]) – An optional label to edit for the account. Cannot be empty string.
tags (list[optional]) – An optional list of tags to attach to the account. Can be null. Should never be an empty list.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result" : True, "message": "", }
- Response JSON Object:
result (list) – Okay result if all the accounts were edited correctly.
- Status Codes:
200 OK – Accounts successfully edited
400 Bad Request – Provided JSON or data is in some way malformed. Given list to edit is empty.
401 Unauthorized – User is not logged in.
409 Conflict – An account given to edit does not exist or a given tag does not exist.
500 Internal Server Error – Internal rotki error
- DELETE /api/(version)/blockchains/type/(chain_type)/accounts
Note
Supported blockchains types:
EVM, BITCOIN, SUBSTRATE, SOLANANote
This endpoint doesn’t support ENS resolution
This endpoint can also be queried asynchronously by using
"async_query": trueDoing a DELETE on this endpoint with a list of accounts in the json data will remove these accounts from the tracked accounts for the all the chains of the
chain_typeprovided. If one of the given accounts to add is invalid the entire request will fail.Example Request:
http
DELETE /api/1/blockchains/type/evm/accounts HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"accounts": ["0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B"]}
curl
curl -i -X DELETE http://localhost:5042/api/1/blockchains/type/evm/accounts -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"accounts": ["0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B"]}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/blockchains/type/evm/accounts --header="Content-Type: application/json;charset=UTF-8" --body-data='{"accounts": ["0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B"]}'
httpie
echo '{ "accounts": [ "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B" ] }' | http DELETE http://localhost:5042/api/1/blockchains/type/evm/accounts Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/1/blockchains/type/evm/accounts', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'accounts': ['0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B']})
- Request JSON Object:
chain_type (string) – The type of blockchain where the address was added.
EVM,BITCOINorSUBSTRATEaccounts (list[string]) – A list of accounts to delete for the given blockchain. Each account Can only an address. ENS is not supported.
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 (list) – Okey result if all the accounts were deleted correctly.
- Status Codes:
200 OK – Accounts successfully deleted
400 Bad Request – Provided JSON or data is in some way malformed. Given list to delete is empty.
401 Unauthorized – User is not logged in.
409 Conflict – An account given to be deleted does not exist.
500 Internal Server Error – Internal rotki error
Removing blockchain accounts
- DELETE /api/(version)/blockchains/(blockchain)/accounts
Note
Supported blockchains:
"BTC", "BCH", "KSM", "DOT", "SOLANA"and all supported EVM chains.Supported blockchains with ENS domains:
"BTC", "BCH", "ETH", "KSM", "DOT"This endpoint can also be queried asynchronously by using
"async_query": true- Doing a DELETE on the blockchains endpoint with a specific blockchain URL and a list of accounts in the json data will remove these accounts from the tracked accounts for the given blockchain and the current user. The updated balances after the account deletions are returned.
If one of the given accounts to add is invalid the entire request will fail.
Example Request:
http
DELETE /api/1/blockchains/eth/accounts HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"accounts": ["0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B"]}
curl
curl -i -X DELETE http://localhost:5042/api/1/blockchains/eth/accounts -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"accounts": ["0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B"]}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/blockchains/eth/accounts --header="Content-Type: application/json;charset=UTF-8" --body-data='{"accounts": ["0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B"]}'
httpie
echo '{ "accounts": [ "0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B" ] }' | http DELETE http://localhost:5042/api/1/blockchains/eth/accounts Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/1/blockchains/eth/accounts', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'accounts': ['0x78b0AD50E768D2376C6BA7de33F426ecE4e03e0B']})
- Request JSON Object:
accounts (list[string]) – A list of accounts to delete for the given blockchain. Each account Can either be a hexadecimal address or an ENS name.
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "per_account": { "BTC": { "standalone": { "3Kb9QPcTUJKspzjQFBppfXRcWew6hyDAPb": { "amount": "0.5", "usd_value": "3770.075" }, "33hjmoU9XjEz8aLxf44FNGB8TdrLkAVBBo": { "amount": "0.5", "usd_value": "3770.075" }}, "xpubs": [{ "xpub": "xpub68V4ZQQ62mea7ZUKn2urQu47Bdn2Wr7SxrBxBDDwE3kjytj361YBGSKDT4WoBrE5htrSB8eAMe59NPnKrcAbiv2veN5GQUmfdjRddD1Hxrk", "derivation_path": "m/0/0", "addresses": { "1LZypJUwJJRdfdndwvDmtAjrVYaHko136r": { "amount": "0.5", "usd_value": "3770.075" }, "1AMrsvqsJzDq25QnaJzX5BzEvdqQ8T6MkT": { "amount": "0.5", "usd_value": "3770.075" } }}, { "xpub": "zpub6quTRdxqWmerHdiWVKZdLMp9FY641F1F171gfT2RS4D1FyHnutwFSMiab58Nbsdu4fXBaFwpy5xyGnKZ8d6xn2j4r4yNmQ3Yp3yDDxQUo3q", "derivation_path": "m", "addresses": { "bc1qc3qcxs025ka9l6qn0q5cyvmnpwrqw2z49qwrx5": { "amount": "0.5", "usd_value": "3770.075" }, "bc1qr4r8vryfzexvhjrx5fh5uj0s2ead8awpqspqra": { "amount": "0.5", "usd_value": "3770.075" } }}] }}, "totals": { "assets": {"BTC": {"amount": "1", "usd_value": "7540.15"}}, "liabilities": {} } }, "message": "" }
- Response JSON Object:
result (object) – An object containing the
"per_account"and"totals"keys as also defined here.
- Status Codes:
200 OK – Accounts successfully deleted
400 Bad Request – Provided JSON or data is in some way malformed. The accounts to remove contained invalid addresses or were an empty list.
401 Unauthorized – User is not logged in.
409 Conflict – Some error occurred when re-querying the balances after addition. Check message for details.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Error occurred with some external service query such as Etherscan. Check message for details.
Getting manually tracked balances
- GET /api/(version)/balances/manual/
Note
This endpoint can also be queried asynchronously by using
"async_query": trueDoing a GET on the manually tracked balances endpoint will return all the manually tracked balance accounts from the database. If a value threshold is provided, only balances with value greater than the threshold are returned (in user’s main currency).
Example Request:
http
GET /api/1/balances/manual?value_threshold=1000 HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET 'http://localhost:5042/api/1/balances/manual?value_threshold=1000'
wget
wget -S -O- 'http://localhost:5042/api/1/balances/manual?value_threshold=1000'
httpie
http 'http://localhost:5042/api/1/balances/manual?value_threshold=1000'
python-requests
requests.get('http://localhost:5042/api/1/balances/manual?value_threshold=1000')
- Query Parameters:
value_threshold (decimal) – Optional. If provided, only returns balances with value greater than this threshold (in user’s main currency).
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "balances": [{ "identifier": 1, "asset": "XMR", "label": "My monero wallet", "amount": "50.315", "value": "2370.13839", "tags": ["public"], "location": "blockchain" }, { "identifier": 2, "asset": "BTC", "label": "My XPUB BTC wallet", "amount": "1.425", "value": "9087.22", "location": "blockchain" }, { "identifier": 3, "asset": "ZEC", "label" "My favorite wallet", "amount": "76.2" "value": "6067.77", "tags": ["private", "inheritance"], "location": "blockchain" }] "message": "" }
- Response JSON Object:
result (object) – An object containing all the manually tracked balances as defined here with additionally a current value in user’s main currency per account.
- Status Codes:
200 OK – Balances successfully queried
401 Unauthorized – User is not logged in.
500 Internal Server Error – Internal rotki error
Adding manually tracked balances
- PUT /api/(version)/balances/manual/
Note
This endpoint can also be queried asynchronously by using
"async_query": trueDoing a PUT on the manually tracked balances endpoint you can add a balance for an asset that rotki can’t automatically detect, along with a label identifying it for you and any number of tags.
Example Request:
http
PUT /api/1/balances/manual/ HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "balances": [{ "asset": "XMR", "label": "My monero wallet", "amount": "50.315", "tags": ["public"], "location": "blockchain", "balance_type": "asset" }, { "asset": "BTC", "label": "My XPUB BTC wallet", "amount": "1.425", "location": "blockchain", "balance_type": "liability" }] }
curl
curl -i -X PUT http://localhost:5042/api/1/balances/manual/ -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"balances": [{"asset": "XMR", "label": "My monero wallet", "amount": "50.315", "tags": ["public"], "location": "blockchain", "balance_type": "asset"}, {"asset": "BTC", "label": "My XPUB BTC wallet", "amount": "1.425", "location": "blockchain", "balance_type": "liability"}]}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/balances/manual/ --header="Content-Type: application/json;charset=UTF-8" --body-data='{"balances": [{"asset": "XMR", "label": "My monero wallet", "amount": "50.315", "tags": ["public"], "location": "blockchain", "balance_type": "asset"}, {"asset": "BTC", "label": "My XPUB BTC wallet", "amount": "1.425", "location": "blockchain", "balance_type": "liability"}]}'
httpie
echo '{ "balances": [ { "amount": "50.315", "asset": "XMR", "balance_type": "asset", "label": "My monero wallet", "location": "blockchain", "tags": [ "public" ] }, { "amount": "1.425", "asset": "BTC", "balance_type": "liability", "label": "My XPUB BTC wallet", "location": "blockchain" } ] }' | http PUT http://localhost:5042/api/1/balances/manual/ Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/balances/manual/', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'balances': [{'asset': 'XMR', 'label': 'My monero wallet', 'amount': '50.315', 'tags': ['public'], 'location': 'blockchain', 'balance_type': 'asset'}, {'asset': 'BTC', 'label': 'My XPUB BTC wallet', 'amount': '1.425', 'location': 'blockchain', 'balance_type': 'liability'}]})
- Request JSON Object:
balances (list[object]) – A list of manually tracked balances to add to rotki
- Request JSON Array of Objects:
asset (string) – The asset that is being tracked
label (string) – A label to describe where is this balance stored. Must be unique between all manually tracked balance labels.
amount (string) – The amount of asset that is stored.
tags (list[optional]) – An optional list of tags to attach to the this manually tracked balance. Can be null. Should never be an empty list.
location (string) – The location where the balance is saved. Can be one of: [“external”, “kraken”, “poloniex”, “bittrex”, “binance”, “bitmex”, “coinbase”, “banks”, “blockchain”, “coinbasepro”, “gemini”, “ftx”, “ftxus”, “independentreserve”]
balance_type (string[optional]) – The type of the balance. Either “asset” or “liability”. By default it’s an asset.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "balances": [{ "identifier": 1, "asset": "XMR", "label": "My monero wallet", "amount": "50.315", "value": "2370.13839", "tags": ["public"], "location": "blockchain", "balance_type": "asset" }, { "identifier" :2, "asset": "BTC", "label": "My XPUB BTC wallet", "amount": "1.425", "value": "9087.22", "location": "blockchain", "balance_type": "asset" }, { "identifier": 3 "asset": "ZEC", "label" "My favorite wallet", "amount": "76.2" "value": "6067.77", "tags": ["private", "inheritance"] "location": "blockchain", "balance_type": "asset" }] "message": "" }
- Response JSON Object:
result (object) – An object containing all the manually tracked balances as defined here with additionally a current usd equivalent value per account.
- Status Codes:
200 OK – Balances successfully added
400 Bad Request – Provided JSON or data is in some way malformed. The balances to add contained invalid assets or were an empty list. One of the balance labels already exist.
401 Unauthorized – User is not logged in.
409 Conflict – Provided tags do not exist. Check message for details.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Error occurred with some external service query such as Cryptocompare. Check message for details.
Editing manually tracked balances
- PATCH /api/(version)/balances/manual
Note
This endpoint can also be queried asynchronously by using
"async_query": trueDoing a PATCH on the manual balances endpoint allows you to edit a number of manually tracked balances by identifier.
Example Request:
http
PATCH /api/1/balances/manual/ HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "balances": [{ "identifier": 1, "asset": "XMR", "label": "My monero wallet", "amount": "4.5", "location": "blockchain", "balance_type": "asset" },{ "identifier": 3, "asset": "ETH" , "label": "My favorite wallet", "amount": "10", "tags": [], "location": "kraken", "balance_type": "liability" }] }
curl
curl -i -X PATCH http://localhost:5042/api/1/balances/manual/ -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"balances": [{"identifier": 1, "asset": "XMR", "label": "My monero wallet", "amount": "4.5", "location": "blockchain", "balance_type": "asset"}, {"identifier": 3, "asset": "ETH", "label": "My favorite wallet", "amount": "10", "tags": [], "location": "kraken", "balance_type": "liability"}]}'
wget
wget -S -O- --method=PATCH http://localhost:5042/api/1/balances/manual/ --header="Content-Type: application/json;charset=UTF-8" --body-data='{"balances": [{"identifier": 1, "asset": "XMR", "label": "My monero wallet", "amount": "4.5", "location": "blockchain", "balance_type": "asset"}, {"identifier": 3, "asset": "ETH", "label": "My favorite wallet", "amount": "10", "tags": [], "location": "kraken", "balance_type": "liability"}]}'
httpie
echo '{ "balances": [ { "amount": "4.5", "asset": "XMR", "balance_type": "asset", "identifier": 1, "label": "My monero wallet", "location": "blockchain" }, { "amount": "10", "asset": "ETH", "balance_type": "liability", "identifier": 3, "label": "My favorite wallet", "location": "kraken", "tags": [] } ] }' | http PATCH http://localhost:5042/api/1/balances/manual/ Content-Type:"application/json;charset=UTF-8"
python-requests
requests.patch('http://localhost:5042/api/1/balances/manual/', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'balances': [{'identifier': 1, 'asset': 'XMR', 'label': 'My monero wallet', 'amount': '4.5', 'location': 'blockchain', 'balance_type': 'asset'}, {'identifier': 3, 'asset': 'ETH', 'label': 'My favorite wallet', 'amount': '10', 'tags': [], 'location': 'kraken', 'balance_type': 'liability'}]})
- Request JSON Object:
accounts (list[object]) – A list of manual balances to edit. As defined here.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "balances": [{ "identifier" 1, "asset": "XMR", "label": "My monero wallet", "amount": "4.5", "value": "210.548", "tags": ["public"], "location": "blockchain", "balance_type": "asset" }, { "identifier": 2, "asset": "BTC", "label": "My XPUB BTC wallet", "amount": "1.425", "value": "9087.22", "location": "blockchain", "balance_type": "asset" }, { "identifier": 3, "asset": "ZEC", "label" "My favorite wallet", "amount": "10" "value": "1330.85" "location": "kraken", "balance_type": "asset" }] "message": "" }
- Response JSON Object:
result (object) – An object containing all the manually tracked balances as defined here with additionally a current usd equivalent value per account.
- Status Codes:
200 OK – Balances successfully edited
400 Bad Request – Provided JSON or data is in some way malformed. The balances to add contained invalid assets or were an empty list.
401 Unauthorized – User is not logged in.
409 Conflict – Provided tags do not exist. Check message for details.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Error occurred with some external service query such as Cryptocompare. Check message for details.
Deleting manually tracked balances
- DELETE /api/(version)/balances/manual/
Note
This endpoint can also be queried asynchronously by using
"async_query": true- Doing a DELETE on the manual balances endpoint with a list of identifiers of manually tracked balances will remove these balances from the database for the current user.
If one of the given ids to remove is invalid the entire request will fail.
Example Request:
http
DELETE /api/1/balances/manual HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"ids": [1, 3]}
curl
curl -i -X DELETE http://localhost:5042/api/1/balances/manual -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"ids": [1, 3]}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/balances/manual --header="Content-Type: application/json;charset=UTF-8" --body-data='{"ids": [1, 3]}'
httpie
echo '{ "ids": [ 1, 3 ] }' | http DELETE http://localhost:5042/api/1/balances/manual Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/1/balances/manual', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'ids': [1, 3]})
- Request JSON Object:
balances (list[string]) – A list of labels of manually tracked balances to delete
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "balances": [{ "identifier": 2, "asset": "BTC", "label": "My XPUB BTC wallet", "amount": "1.425", "value": "9087.22", "location": "blockchain", "balance_type": "asset" }] "message": "" }
- Response JSON Object:
result (object) – An object containing all the manually tracked balances as defined here with additionally a current usd equivalent value per account.
- Status Codes:
200 OK – Balances successfully delete
400 Bad Request – Provided JSON or data is in some way malformed. One of the labels to remove did not exist.
401 Unauthorized – User is not logged in.
409 Conflict – Check message for details.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Error occurred with some external service query such as Cryptocompare. Check message for details.
Getting watchers
- GET /api/(version)/watchers
Note
This endpoint is only available for premium users
Doing a GET on the watchers endpoint, will return the currently installed watchers from the rotki server.
Example Request:
http
GET /api/1/watchers HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/watchers
wget
wget -S -O- http://localhost:5042/api/1/watchers
httpie
http http://localhost:5042/api/1/watcherspython-requests
requests.get('http://localhost:5042/api/1/watchers')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": [{ "identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=", "type": "makervault_collateralization_ratio", "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"} }, { "identifier": "7a4m7vRrLLOipwNmzhAVdo6FaGgr0XKGYLyjHqWa2KQ=", "type": "makervault_collateralization_ratio", "args": {"ratio": "185.55", "op": "lt","vault_id": "456"} }], "message": "" }
- Response JSON Object:
result (object) – An list containing all the watcher results.
- Request JSON Object:
identifier (string) – The identifier with which to identify this vault. It’s unique per user and vault args + watcher combination. The client needs to keep this identifier. If the entry is edited, the identifier changes.
type (string) – The type of the watcher. Valid types are: “makervault_collateralization_ratio”.
args (object) – An object containing the args for the vault. Depending on the vault type different args are possible. Check here to see the different options.
- Status Codes:
200 OK – Watchers successfully queried
401 Unauthorized – No user is currently logged in.
403 Forbidden – Logged in user does not have premium.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Could not connect to or got unexpected response format from rotki server
- For makervault ratio the possible arguments are:
vault_id: The id of the vault to watcher
ratio: The target ratio to watch for
- op: The comparison operator:
lt: less than the given ratio
le: less than or equal to the given ratio
gt: greater than the given ratio
ge: greater than or equal to the given ratio
Adding new watcher
- PUT /api/(version)/watchers/
Note
This endpoint is only available for premium users
Doing a PUT on the watchers endpoint you can install new watchers for watching to the server.
Example Request:
http
PUT /api/1/watchers/ HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "watchers": [{ "type": "makervault_collateralization_ratio", "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"} }, { "type": "makervault_collateralization_ratio", "args": {"ratio": "185.55", "op": "lt","vault_id": "456"} }] }
curl
curl -i -X PUT http://localhost:5042/api/1/watchers/ -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"watchers": [{"type": "makervault_collateralization_ratio", "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}}, {"type": "makervault_collateralization_ratio", "args": {"ratio": "185.55", "op": "lt", "vault_id": "456"}}]}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/watchers/ --header="Content-Type: application/json;charset=UTF-8" --body-data='{"watchers": [{"type": "makervault_collateralization_ratio", "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}}, {"type": "makervault_collateralization_ratio", "args": {"ratio": "185.55", "op": "lt", "vault_id": "456"}}]}'
httpie
echo '{ "watchers": [ { "args": { "op": "gt", "ratio": "200.5", "vault_id": "24" }, "type": "makervault_collateralization_ratio" }, { "args": { "op": "lt", "ratio": "185.55", "vault_id": "456" }, "type": "makervault_collateralization_ratio" } ] }' | http PUT http://localhost:5042/api/1/watchers/ Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/watchers/', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'watchers': [{'type': 'makervault_collateralization_ratio', 'args': {'ratio': '200.5', 'op': 'gt', 'vault_id': '24'}}, {'type': 'makervault_collateralization_ratio', 'args': {'ratio': '185.55', 'op': 'lt', 'vault_id': '456'}}]})
- Request JSON Object:
watchers (list[object]) – A list of watchers to add as defined in the above section but without an identifier. The identifier is created server-side and returned in the response.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": [{ "identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=", "type": "makervault_collateralization_ratio", "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"} }, { "identifier": "7a4m7vRrLLOipwNmzhAVdo6FaGgr0XKGYLyjHqWa2KQ=", "type": "makervault_collateralization_ratio", "args": {"ratio": "185.55", "op": "lt","vault_id": "456"} }], "message": "" }
- Response JSON Object:
result (object) – An object containing all the watchers, including the ones that were added. The watchers follow the schema defined above.
- Status Codes:
200 OK – Watchers successfully added
400 Bad Request – Provided JSON or data is in some way malformed. Or the same watcher already exists for this user in the DB.
401 Unauthorized – No user is currently logged in.
403 Forbidden – Logged in user does not have premium.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Could not connect to or got unexpected response format from rotki server
Editing watchers
- PATCH /api/(version)/watchers
Note
This endpoint is only available for premium users
Doing a PATCH on the watchers endpoint allows you to edit a number of watchers by identifier. If one of the identifier is not found, the whole method fails.
Example Request:
http
PATCH /api/1/watchers/ HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "watchers": [{ "identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=", "type": "makervault_collateralization_ratio", "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"} }, { "identifier": "7a4m7vRrLLOipwNmzhAVdo6FaGgr0XKGYLyjHqWa2KQ=", "type": "makervault_collateralization_ratio", "args": {"ratio": "185.55", "op": "lt","vault_id": "456"} }] }
curl
curl -i -X PATCH http://localhost:5042/api/1/watchers/ -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"watchers": [{"identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=", "type": "makervault_collateralization_ratio", "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}}, {"identifier": "7a4m7vRrLLOipwNmzhAVdo6FaGgr0XKGYLyjHqWa2KQ=", "type": "makervault_collateralization_ratio", "args": {"ratio": "185.55", "op": "lt", "vault_id": "456"}}]}'
wget
wget -S -O- --method=PATCH http://localhost:5042/api/1/watchers/ --header="Content-Type: application/json;charset=UTF-8" --body-data='{"watchers": [{"identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=", "type": "makervault_collateralization_ratio", "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"}}, {"identifier": "7a4m7vRrLLOipwNmzhAVdo6FaGgr0XKGYLyjHqWa2KQ=", "type": "makervault_collateralization_ratio", "args": {"ratio": "185.55", "op": "lt", "vault_id": "456"}}]}'
httpie
echo '{ "watchers": [ { "args": { "op": "gt", "ratio": "200.5", "vault_id": "24" }, "identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=", "type": "makervault_collateralization_ratio" }, { "args": { "op": "lt", "ratio": "185.55", "vault_id": "456" }, "identifier": "7a4m7vRrLLOipwNmzhAVdo6FaGgr0XKGYLyjHqWa2KQ=", "type": "makervault_collateralization_ratio" } ] }' | http PATCH http://localhost:5042/api/1/watchers/ Content-Type:"application/json;charset=UTF-8"
python-requests
requests.patch('http://localhost:5042/api/1/watchers/', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'watchers': [{'identifier': '6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=', 'type': 'makervault_collateralization_ratio', 'args': {'ratio': '200.5', 'op': 'gt', 'vault_id': '24'}}, {'identifier': '7a4m7vRrLLOipwNmzhAVdo6FaGgr0XKGYLyjHqWa2KQ=', 'type': 'makervault_collateralization_ratio', 'args': {'ratio': '185.55', 'op': 'lt', 'vault_id': '456'}}]})
- Request JSON Object:
watchers (list[object]) – A list of watcher to edit. As defined here.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": [{ "identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=", "type": "makervault_collateralization_ratio", "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"} }, { "identifier": "7a4m7vRrLLOipwNmzhAVdo6FaGgr0XKGYLyjHqWa2KQ=", "type": "makervault_collateralization_ratio", "args": {"ratio": "185.55", "op": "lt","vault_id": "456"} }], "message": "" }
- Response JSON Object:
result (object) – An object containing all the watchers as defined here
- Status Codes:
200 OK – Watchers successfully edited
400 Bad Request – Provided JSON or data is in some way malformed. Or a given identifier does not exist in the DB.
401 Unauthorized – No user is currently logged in.
403 Forbidden – Logged in user does not have premium.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Could not connect to or got unexpected response format from rotki server
Deleting watchers
- DELETE /api/(version)/watchers/
Note
This endpoint is only available for premium users
Doing a DELETE on the watchers endpoint with a list of identifiers will delete either all or none of them.
Example Request:
http
DELETE /api/1/watchers HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"watchers": ["6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ", "92Jm7vRrLLOipwNXzhAVdo6XaGAr0XKGYLyjHqWa2KA"]}
curl
curl -i -X DELETE http://localhost:5042/api/1/watchers -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"watchers": ["6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ", "92Jm7vRrLLOipwNXzhAVdo6XaGAr0XKGYLyjHqWa2KA"]}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/watchers --header="Content-Type: application/json;charset=UTF-8" --body-data='{"watchers": ["6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ", "92Jm7vRrLLOipwNXzhAVdo6XaGAr0XKGYLyjHqWa2KA"]}'
httpie
echo '{ "watchers": [ "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ", "92Jm7vRrLLOipwNXzhAVdo6XaGAr0XKGYLyjHqWa2KA" ] }' | http DELETE http://localhost:5042/api/1/watchers Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/1/watchers', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'watchers': ['6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ', '92Jm7vRrLLOipwNXzhAVdo6XaGAr0XKGYLyjHqWa2KA']})
- Request JSON Object:
watchers (list[string]) – A list of identifier of watchers to delete
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": [{ "identifier": "6h3m7vRrLLOipwNmzhAVdo6FaGlr0XKGYLyjHqWa2KQ=", "type": "makervault_collateralization_ratio", "args": {"ratio": "200.5", "op": "gt", "vault_id": "24"} }], "message": "" }
- Response JSON Object:
result (object) – An object containing all the watchers after deletion. The watchers follow the schema defined above.
- Status Codes:
200 OK – Watchers successfully delete
400 Bad Request – Provided JSON or data is in some way malformed. One of the identifiers to remove did not exist.
401 Unauthorized – No user is currently logged in.
403 Forbidden – Logged in user does not have premium.
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Could not connect to or got unexpected response format from rotki server
Dealing with ignored assets
- GET /api/(version)/assets/ignored/
Doing a GET on the ignored assets endpoint will return a list of all assets that the user has set to have ignored.
Example Request:
http
GET /api/1/assets/ignored HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/assets/ignored
wget
wget -S -O- http://localhost:5042/api/1/assets/ignored
httpie
http http://localhost:5042/api/1/assets/ignoredpython-requests
requests.get('http://localhost:5042/api/1/assets/ignored')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": ["eip155:1/erc20:0xAf30D2a7E90d7DC361c8C4585e9BB7D2F6f15bc7", "eip155:1/erc20:0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413"] "message": "" }
- Response JSON Object:
result (list) – A list of asset names that are currently ignored.
- Status Codes:
200 OK – Assets successfully queried
400 Bad Request – Provided JSON or data is in some way malformed.
401 Unauthorized – User is not logged in.
500 Internal Server Error – Internal rotki error
- PUT /api/(version)/assets/ignored/
Doing a PUT on the ignored assets endpoint will add new assets to the ignored assets list. Returns the new list with the added assets in the response.
Example Request:
http
PUT /api/1/assets/ignored HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"assets": ["eip155:1/erc20:0x6810e776880C02933D47DB1b9fc05908e5386b96"]}
curl
curl -i -X PUT http://localhost:5042/api/1/assets/ignored -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"assets": ["eip155:1/erc20:0x6810e776880C02933D47DB1b9fc05908e5386b96"]}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/assets/ignored --header="Content-Type: application/json;charset=UTF-8" --body-data='{"assets": ["eip155:1/erc20:0x6810e776880C02933D47DB1b9fc05908e5386b96"]}'
httpie
echo '{ "assets": [ "eip155:1/erc20:0x6810e776880C02933D47DB1b9fc05908e5386b96" ] }' | http PUT http://localhost:5042/api/1/assets/ignored Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/assets/ignored', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'assets': ['eip155:1/erc20:0x6810e776880C02933D47DB1b9fc05908e5386b96']})
- Request JSON Object:
assets (list) – A list of asset symbols to add to the ignored assets.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": {"successful":[],"no_action":["eip155:1/erc20:0x255Aa6DF07540Cb5d3d297f0D0D4D84cb52bc8e6"]}, "message": "" }
- Response JSON Object:
successful (list) – A list of asset identifiers that were added to the list of ignored assets.
no_action (list) – A list of assets that were already ignored and no action was taken on them.
- Status Codes:
200 OK – Assets successfully added
400 Bad Request – Provided JSON or data is in some way malformed.
401 Unauthorized – User is not logged in.
500 Internal Server Error – Internal rotki error
- DELETE /api/(version)/assets/ignored/
Doing a DELETE on the ignored assets endpoint will remove the given assets from the ignored assets list. Returns the new list without the removed assets in the response.
Example Request:
http
DELETE /api/1/assets/ignored HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"assets": ["eip155:1/erc20:0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413"]}
curl
curl -i -X DELETE http://localhost:5042/api/1/assets/ignored -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"assets": ["eip155:1/erc20:0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413"]}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/assets/ignored --header="Content-Type: application/json;charset=UTF-8" --body-data='{"assets": ["eip155:1/erc20:0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413"]}'
httpie
echo '{ "assets": [ "eip155:1/erc20:0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413" ] }' | http DELETE http://localhost:5042/api/1/assets/ignored Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/1/assets/ignored', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'assets': ['eip155:1/erc20:0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413']})
- Request JSON Object:
assets (list) – A list of asset symbols to remove from the ignored assets.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": {"successful":[],"no_action":["ETH"]}, "message": "" }
- Response JSON Object:
successful (list) – A list of asset identifiers that were removed from the list of ignored assets.
no_action (list) – A list of assets that weren’t ignored and no action was taken on them.
- Status Codes:
200 OK – Assets successfully removed
400 Bad Request – Provided JSON or data is in some way malformed.
401 Unauthorized – User is not logged in.
500 Internal Server Error – Internal rotki error
False positive in spam assets
- POST /api/(version)/assets/ignored/whitelist
Doing a POST on this endpoint will mark the provided token as a false positive spam asset. This will remove it from the list of ignored assets, remove the spam value from the protocol field and add it to the list of false positives.
Example Request
http
PATH /api/1/assets/ignored/whitelist HTTP/1.1 Host: localhost:5042 {"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}
curl
curl -i -X PATH http://localhost:5042/api/1/assets/ignored/whitelist --data-raw '{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}'
wget
wget -S -O- --method=PATH http://localhost:5042/api/1/assets/ignored/whitelist --body-data='{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}'
httpie
echo '{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}' | http PATH http://localhost:5042/api/1/assets/ignored/whitelist
python-requests
requests.path('http://localhost:5042/api/1/assets/ignored/whitelist', data='{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}')
- Request JSON Array of Objects:
token (string) – The identifier of the evm token that will be marked as false positive
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – Boolean denoting success or failure.
- Status Codes:
200 OK – Asset added to spam whitelist successfully.
401 Unauthorized – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
- GET /api/(version)/assets/ignored/whitelist
Doing a GET on this endpoint will return a list of the assets that are whitelisted.
Example Request
http
GET /api/1/assets/ignored/whitelist HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/assets/ignored/whitelist
wget
wget -S -O- http://localhost:5042/api/1/assets/ignored/whitelist
httpie
http http://localhost:5042/api/1/assets/ignored/whitelistpython-requests
requests.get('http://localhost:5042/api/1/assets/ignored/whitelist')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": ["eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F"], "message": "" }
- Response JSON Object:
result (bool) – list of the assets whitelisted.
- Status Codes:
200 OK – Assets listed successfully.
409 Conflict – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
- DELETE /api/(version)/assets/ignored/whitelist
Doing a DELETE on this endpoint will remove the provided token from the list of false positives.
Example Request
http
DELETE /api/1/assets/ignored/whitelist HTTP/1.1 Host: localhost:5042 {"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}
curl
curl -i -X DELETE http://localhost:5042/api/1/assets/ignored/whitelist --data-raw '{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/assets/ignored/whitelist --body-data='{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}'
httpie
echo '{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}' | http DELETE http://localhost:5042/api/1/assets/ignored/whitelist
python-requests
requests.delete('http://localhost:5042/api/1/assets/ignored/whitelist', data='{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}')
- Request JSON Array of Objects:
token (string) – The identifier of the evm token that will be removed from the false positive whitelist
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – Boolean denoting success or failure.
- Status Codes:
200 OK – Asset removed from spam whitelist successfully.
409 Conflict – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
Toggle spam status of tokens
- POST /api/(version)/assets/spam/
Doing a POST on this endpoint will mark the provided tokens as spam. It will move each token to the list of ignored assets and remove it from the list of whitelisted tokens. Any protocol value that the token might have will be overwritten. Supports both EVM and Solana tokens.
Example Request
http
PATH /api/1/assets/spam HTTP/1.1 Host: localhost:5042 {"tokens": ["eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"]}
curl
curl -i -X PATH http://localhost:5042/api/1/assets/spam --data-raw '{"tokens": ["eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"]}'
wget
wget -S -O- --method=PATH http://localhost:5042/api/1/assets/spam --body-data='{"tokens": ["eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"]}'
httpie
echo '{"tokens": ["eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"]}' | http PATH http://localhost:5042/api/1/assets/spam
python-requests
requests.path('http://localhost:5042/api/1/assets/spam', data='{"tokens": ["eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"]}')
- Request JSON Array of Objects:
tokens (list[string]) – The identifiers of the tokens that will be marked as spam. Accepts EVM token and Solana token identifiers.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – Boolean denoting success or failure.
- Status Codes:
200 OK – Assets marked as spam successfully.
401 Unauthorized – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
- DELETE /api/(version)/assets/spam/
Doing a DELETE on this endpoint will remove the spam protocol from the token setting it to null. It will also remove the token from the list of ignored assets. Supports both EVM and Solana tokens.
Example Request
http
DELETE /api/1/assets/spam HTTP/1.1 Host: localhost:5042 {"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}
curl
curl -i -X DELETE http://localhost:5042/api/1/assets/spam --data-raw '{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/assets/spam --body-data='{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}'
httpie
echo '{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}' | http DELETE http://localhost:5042/api/1/assets/spam
python-requests
requests.delete('http://localhost:5042/api/1/assets/spam', data='{"token": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2"}')
- Request JSON Array of Objects:
token (string) – The identifier of the token that will be updated removing the protocol value of spam. Accepts EVM token and Solana token identifiers.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – Boolean denoting success or failure.
- Status Codes:
200 OK – Asset updated correctly.
401 Unauthorized – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
Dealing with ignored actions
- PUT /api/(version)/actions/ignored
Doing a PUT on the ignored actions endpoint will add action identifiers for ignoring of history event type during accounting. Returns the list of all ignored action identifiers of history events after the addition.
Example Request:
http
PUT /api/1/actions/ignored HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"data": ["Z231-XH23K"]}
curl
curl -i -X PUT http://localhost:5042/api/1/actions/ignored -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"data": ["Z231-XH23K"]}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/actions/ignored --header="Content-Type: application/json;charset=UTF-8" --body-data='{"data": ["Z231-XH23K"]}'
httpie
echo '{ "data": [ "Z231-XH23K" ] }' | http PUT http://localhost:5042/api/1/actions/ignored Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/actions/ignored', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'data': ['Z231-XH23K']})
- Request JSON Object:
data (list) – The data to ignore. For type “evm_transaction” it’s an object with the following keys:
"evm_chain"with the name of the evm chain the transaction happened in and"tx_hash"the string of the transaction hash to ignore. For all other types it’s a list of strings representing the identifier of the action to ignore.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – The result field in this response is a simple boolean value indicating success or failure.
- Status Codes:
200 OK – Action ids successfully added
400 Bad Request – Provided JSON or data is in some way malformed.
401 Unauthorized – User is not logged in.
409 Conflict – One of the action ids provided is already on the list.
500 Internal Server Error – Internal rotki error
- DELETE /api/(version)/actions/ignored/
Doing a DELETE on the ignored actions endpoint removes action ids from the list of actions of history event to be ignored during accounting.
Example Request:
http
DELETE /api/1/actions/ignored HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "data": ["ethereum-0x34d9887286d8c427e5bf18004c464d150190780e83e89a47906cc63a07267780", "jwonowifewe"] }
curl
curl -i -X DELETE http://localhost:5042/api/1/actions/ignored -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"data": ["ethereum-0x34d9887286d8c427e5bf18004c464d150190780e83e89a47906cc63a07267780", "jwonowifewe"]}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/actions/ignored --header="Content-Type: application/json;charset=UTF-8" --body-data='{"data": ["ethereum-0x34d9887286d8c427e5bf18004c464d150190780e83e89a47906cc63a07267780", "jwonowifewe"]}'
httpie
echo '{ "data": [ "ethereum-0x34d9887286d8c427e5bf18004c464d150190780e83e89a47906cc63a07267780", "jwonowifewe" ] }' | http DELETE http://localhost:5042/api/1/actions/ignored Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/1/actions/ignored', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'data': ['ethereum-0x34d9887286d8c427e5bf18004c464d150190780e83e89a47906cc63a07267780', 'jwonowifewe']})
- Request JSON Object:
data (list) – As defined in
PUTabove.
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 – Action ids successfully removed
400 Bad Request – Provided JSON or data is in some way malformed.
401 Unauthorized – User is not logged in.
409 Conflict – One of the action ids provided is not on the list.
500 Internal Server Error – Internal rotki error
Querying general information
- GET /api/(version)/info
Doing a GET on the info endpoint will return general information about rotki. Under the version key we get info on the current version of rotki. When
check_for_updatesistrueif there is a newer version then"download_url"will be populated. If not then only"our_version"and"latest_version"will be. There is a possibility that latest version may not be populated due to github not being reachable. Also we return the data directory and other information.Note
This endpoint also accepts parameters as query arguments.
Example Request:
http
GET /api/1/info HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"check_for_updates": true}
curl
curl -i -X GET http://localhost:5042/api/1/info -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"check_for_updates": true}'
wget
wget -S -O- http://localhost:5042/api/1/info --header="Content-Type: application/json;charset=UTF-8" --body-data='{"check_for_updates": true}'
httpie
echo '{ "check_for_updates": true }' | http http://localhost:5042/api/1/info Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/info', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'check_for_updates': True})
- Request JSON Object:
check_for_updates (bool) – If true will perform an external query to check the latest version available and get the download link.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "version": { "our_version": "1.0.3", "latest_version": "1.0.4", "download_url": "https://github.com/rotki/rotki/releases/tag/v1.0.4" }, "data_directory": "/home/username/.local/share/rotki/data", "log_level": "DEBUG", "accept_docker_risk": false, "backend_default_arguments": { "max_logfiles_num": 3, "max_size_in_mb_all_logs": 300, "sqlite_instructions": 5000 } }, "message": "" }
- Response JSON Object:
our_version (str) – The version of rotki present in the system
latest_version (str) – The latest version of rotki available
download_url (str) – URL link to download the latest version
data_directory (str) – The rotki data directory
log_level (str) – The log level used in the backend. Can be
DEBUG,INFO,WARN,ERRORorCRITICAL.accept_docker_risk (bool) – A boolean indicating if the user has passed an environment variable to the backend process acknowledging the security issues with the docker setup: https://github.com/rotki/rotki/issues/5176
backend_default_arguments (object) – A mapping of backend arguments to their default values so that the frontend can know about them.
- Status Codes:
200 OK – Information queried successfully
500 Internal Server Error – Internal rotki error
Sending a Ping
- GET /api/(version)/ping
Doing a GET on the ping endpoint will return true. It serves as a very fast way to check the connection to the API and that everything necessary for other calls has initialized.
Example Request:
http
GET /api/1/ping HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/ping
wget
wget -S -O- http://localhost:5042/api/1/ping
httpie
http http://localhost:5042/api/1/pingpython-requests
requests.get('http://localhost:5042/api/1/ping')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – The result field in this response is a simple boolean value indicating success or failure.
- Status Codes:
200 OK – Ping successful
500 Internal Server Error – Internal rotki error
Data imports
- PUT /api/(version)/import
Doing a PUT on the data import endpoint will facilitate importing data from external sources. The arguments are the source of data import and the filepath to the data for importing.
Note
This endpoint can also be queried asynchronously by using
"async_query": true.Note
If you want to provide a stream of data instead of a path, you can call POST on this endpoint and provide the stream in filepath variable.
Example Request:
http
PUT /api/1/import HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"source": "cointracking", "filepath": "/path/to/data/file", "timestamp_format": "%d/%m/%Y %H:%M:%S", "timezone": "Europe/Madrid"}
curl
curl -i -X PUT http://localhost:5042/api/1/import -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"filepath": "/path/to/data/file", "source": "cointracking", "timestamp_format": "%d/%m/%Y %H:%M:%S", "timezone": "Europe/Madrid"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/import --header="Content-Type: application/json;charset=UTF-8" --body-data='{"filepath": "/path/to/data/file", "source": "cointracking", "timestamp_format": "%d/%m/%Y %H:%M:%S", "timezone": "Europe/Madrid"}'
httpie
echo '{ "filepath": "/path/to/data/file", "source": "cointracking", "timestamp_format": "%d/%m/%Y %H:%M:%S", "timezone": "Europe/Madrid" }' | http PUT http://localhost:5042/api/1/import Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/import', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'filepath': '/path/to/data/file', 'source': 'cointracking', 'timestamp_format': '%d/%m/%Y %H:%M:%S', 'timezone': 'Europe/Madrid'})
- Request JSON Object:
source (str) – The source of the data to import. Valid values are
"cointracking","cryptocom","blockfi_transactions","blockfi_trades","nexo","shapeshift_trades","uphold_transactions","bitmex_wallet_history","bisq_trades","binance","rotki_events","rotki_trades","bitcoin_tax","bitstamp","bittrex","kucoin","blockpit".filepath (str) – The filepath to the data for importing
timestamp_format (str) – Optional. Custom format to use for dates in the CSV file. Should follow rules at Datetime docs.
timezone (str) – Optional. IANA timezone name to use for dates in the CSV file that do not include timezone information. Defaults to
"UTC". Example:"Europe/Madrid".
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 – Data imported. Check user messages for warnings.
400 Bad Request – Provided JSON or data is in some way malformed.
409 Conflict – User is not logged in.
500 Internal Server Error – Internal rotki error
ERC20 token info
- GET /api/(version)/blockchains/evm/erc20details
Doing a GET to this endpoint will return basic information about a token by calling the
decimals/name/symbolmethods.Note
This endpoint can also be queried asynchronously by using
"async_query": true.Example Request:
http
GET /api/1/blockchains/eth/erc20details HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"address": "0x6B175474E89094C44Da98b954EedeAC495271d0F", "evm_chain": "optimism"}
curl
curl -i -X GET http://localhost:5042/api/1/blockchains/eth/erc20details -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0x6B175474E89094C44Da98b954EedeAC495271d0F", "evm_chain": "optimism"}'
wget
wget -S -O- http://localhost:5042/api/1/blockchains/eth/erc20details --header="Content-Type: application/json;charset=UTF-8" --body-data='{"address": "0x6B175474E89094C44Da98b954EedeAC495271d0F", "evm_chain": "optimism"}'
httpie
echo '{ "address": "0x6B175474E89094C44Da98b954EedeAC495271d0F", "evm_chain": "optimism" }' | http http://localhost:5042/api/1/blockchains/eth/erc20details Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/blockchains/eth/erc20details', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'address': '0x6B175474E89094C44Da98b954EedeAC495271d0F', 'evm_chain': 'optimism'})
- Request JSON Object:
address (str) – The checksummed address of a contract
evm_chain (str) – The name of the evm chain to check for token info e.g.
"ethereum","optimism"etc.async_query (bool) – A boolean denoting whether the query should be made asynchronously or not. Missing defaults to false.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "decimals": 18, "symbol": "DAI", "name": "Dai Stablecoin" }, "message": "" }
- Response JSON Object:
result (object) – The result field in this response is a object with a minimum of one attribute.
decimals (int) – Number of decimals for the requested contract.
nullif this information is not available on chain.symbol (str) – Symbol for the requested contract.
nullif this information is not available on chain.name (str) – Name for the requested contract.
nullif this information is not available on chain.message (str) – Empty string if there is no issues with the contract, for example, it not existing on the chain.
- Status Codes:
200 OK – No critical error found.
409 Conflict – There is an error with the address.
500 Internal Server Error – Internal rotki error.
All Binance markets
- GET /api/(version)/exchanges/binance/pairs
Doing a GET to this endpoint will return all the market pairs available at binance.
Note
This endpoint will only return information if either Binance or Binance US are configured
Example Request:
http
GET /api/1/exchanges/binance/pairs?location=binance HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET 'http://localhost:5042/api/1/exchanges/binance/pairs?location=binance'
wget
wget -S -O- 'http://localhost:5042/api/1/exchanges/binance/pairs?location=binance'
httpie
http 'http://localhost:5042/api/1/exchanges/binance/pairs?location=binance'
python-requests
requests.get('http://localhost:5042/api/1/exchanges/binance/pairs?location=binance')
- Query Parameters:
location (string) – Either
binanceorbinanceuslocations. This argument will filter the result based on the exchange type.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": ["BTCUSD", "ETHUSD", "XRPUSD"], "message": "" }
- Status Codes:
200 OK – Pairs successfully queried
502 Bad Gateway – Failed to query pairs from the binance API and the database.
User selected Binance markets
- GET /api/(version)/exchanges/binance/pairs/(exchange account name)
Doing a GET to this endpoint will return the market pairs that the user has selected to be queried at binance.
Example Request:
http
GET /api/1/exchanges/binance/pairs/testExchange HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/exchanges/binance/pairs/testExchange
wget
wget -S -O- http://localhost:5042/api/1/exchanges/binance/pairs/testExchange
httpie
http http://localhost:5042/api/1/exchanges/binance/pairs/testExchangepython-requests
requests.get('http://localhost:5042/api/1/exchanges/binance/pairs/testExchange')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": ["BTCUSD", "ETHUSD"], "message": "" }
Querying NFTs
- GET /api/(version)/nfts
Note
This endpoint also accepts parameters as query arguments.
Note
This endpoint can also be queried asynchronously by using
"async_query": trueDoing a GET on the NFTs endpoint will query all NFTs for all user tracked addresses.
Example Request:
http
GET /api/1/nfts HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"async_query": false, "ignore_cache": true}
curl
curl -i -X GET http://localhost:5042/api/1/nfts -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": false, "ignore_cache": true}'
wget
wget -S -O- http://localhost:5042/api/1/nfts --header="Content-Type: application/json;charset=UTF-8" --body-data='{"async_query": false, "ignore_cache": true}'
httpie
echo '{ "async_query": false, "ignore_cache": true }' | http http://localhost:5042/api/1/nfts Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/nfts', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': False, 'ignore_cache': True})
- Request JSON Object:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
- Parameters:
ignore_cache (bool) – Boolean denoting whether to ignore the cache for this query or not.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "addresses": { "0xeE3766e4F996DC0e0F8c929954EAAFef3441de87": [ { "token_identifier": "8636", "name": "BASTARD GAN PUNK V2 #8636", "background_color": null, "image_url": "https://lh3.googleusercontent.com/kwF-39qZlluEalQnNv-yMxbntzNdc3g00pK2xALkpoir9ooWttVUO2hVFWOgPtOkJOHufYRajfn-nNFdjruRQ4YaMgOYHEB8E4CdjBk", "external_link": "https://www.bastardganpunks.club/v2/8636", "price_in_asset": "0.025", "price_asset": "ETH", "price": "250", "collection": { "name": "BASTARD GAN PUNKS V2", "banner_image": "https://lh3.googleusercontent.com/InX38GA4YmuR2ukDhN0hjf8-Qj2U3Tdw3wD24IsbjuXNtrTZXNwWiIeWR9bJ_-rEUOnQgkpLbj71TDKrzNzHLHkOSRdLo8Yd2tE3_jg=s2500", "description": "VERSION 2 OF BASTARD GAN PUNKS ARE COOLER, BETTER AND GOOFIER THAN BOTH BOOMER CRYPTOPUNKS & VERSION 1 BASTARD GAN PUNKS. THIS TIME, ALL CRYPTOPUNK ATTRIBUTES ARE EXTRACTED AND A NEW DATASET OF ALL COMBINATIONS OF THEM ARE TRAINED WITH GAN TO GIVE BIRTH TO EVEN MORE BADASS ONES. ALSO EACH ONE HAS A UNIQUE STORY GENERATED FROM MORE THAN 10K PUNK & EMO SONG LYRICS VIA GPT-2 LANGUAGE PROCESSING ALGORITHM. \r\n\r\nBASTARDS ARE SLOWLY DEGENERATING THE WORLD. ADOPT ONE TO KICK EVERYONE'S ASSES!\r\n\r\nDISCLAIMER: THIS PROJECT IS NOT AFFILIATED WITH LARVA LABS", "large_image": "https://lh3.googleusercontent.com/vF8johTucYy6yycIOJTM94LH-wcDQIPTn9-eKLMbxajrm7GZfJJWqxdX6uX59pA4n4n0QNEn3bh1RXcAFLeLzJmq79aZmIXVoazmVw=s300" } } ] }, "entries_found": 95, "entries_limit": 500 }, "message": "" }
- Response JSON Object:
addresses (object) – A mapping of ethereum addresses to list of owned NFTs.
entries_found (int) – The number of NFT entries found. If non-premium and the free limit has been hit this will be equal to the limit, since we stop searching after the limit.
entries_limit (int) – The free limit for NFTs.
token_identifier (string) – The identifier of the specific NFT token for the given contract type. This is not a unique id across all NFTs.
background_color (string) – [Optional]. A color for the background of the image of the NFT. Can be Null.
image_url (string) – [Optional]. Link to the image of the NFT. Can be Null.
name (string) – [ Optional] The name of the NFT. Can be Null.
external_link (string) – [Optional]. A link to the page of the creator of the NFT. Can be Null.
permalink (string) – [Optional]. A link to the NFT in opensea.
price_in_asset (string) – The last known price of the NFT in price_asset. Can be zero.
price_asset (string) – The identifier of the asset used for price_in_asset.
price (string) – The last known price of the NFT in the user’s preferred currency. Can be zero.
- Status Codes:
200 OK – NFTs successfully queried
400 Bad Request – Provided JSON is in some way malformed
401 Unauthorized – User is not logged in.
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 opensea could not be reached or returned unexpected response.
Show NFT Balances
- GET /api/(version)/nfts/balances
Note
This endpoint also accepts parameters as query arguments.
Note
This endpoint can also be queried asynchronously by using
"async_query": trueDoing a GET on the NFTs balances endpoint will query all NFTs for all user tracked addresses and return those whose price can be detected.
Example Request:
http
GET /api/1/nfts/balances HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"async_query": false, "ignore_cache": false, "offset": 3, "limit": 1}
curl
curl -i -X GET http://localhost:5042/api/1/nfts/balances -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": false, "ignore_cache": false, "limit": 1, "offset": 3}'
wget
wget -S -O- http://localhost:5042/api/1/nfts/balances --header="Content-Type: application/json;charset=UTF-8" --body-data='{"async_query": false, "ignore_cache": false, "limit": 1, "offset": 3}'
httpie
echo '{ "async_query": false, "ignore_cache": false, "limit": 1, "offset": 3 }' | http http://localhost:5042/api/1/nfts/balances Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/nfts/balances', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': False, 'ignore_cache': False, 'limit': 1, 'offset': 3})
- Request JSON Object:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not
owner_addresses (list[string][optional]) – A list of evm addresses. If provided, only nfts owned by these addresses will be returned.
name (string[optional]) – Optional nfts name to filter by.
collection_name (string[optional]) – Optional nfts collection_name to filter by.
ignored_assets_handling (string[optional]) – A flag to specify how to handle ignored assets. Possible values are ‘none’, ‘exclude’ and ‘show_only’. You can write ‘none’ in order to not handle them in any special way (meaning to show them too). This is the default. You can write ‘exclude’ if you want to exclude them from the result. And you can write ‘show_only’ if you want to only see the ignored assets in the result.
limit (int) – This signifies the limit of records to return as per the sql spec.
offset (int) – This signifies the offset from which to start the return of records per the sql spec.
order_by_attributes (list[string][optional]) – This is the list of attributes of the nft by which to order the results. By default we sort using
name.ascending (list[bool][optional]) – Should the order be ascending? This is the default. If set to false, it will be on descending order.
lps_handling (string[optional]) – A flag to specify how to handle LP NFTs. Possible values are ‘all_nfts’ (default), ‘only_lps’ and ‘exclude_lps’. You can use ‘only_lps’ if you want to only include LPs NFTs in the result or you can use ‘exclude_lps’ if you want NFTs not marked as LP positions.
- Parameters:
ignore_cache (bool) – Boolean denoting whether to ignore the cache for this query or not.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "entries": [ { "id": "unique id", "name": "a name", "collection_name": "A collection name", "manually_input": true, "price_asset": "ETH", "price_in_asset": "1", "price": "2501.15" "image_url": "https://storage.opensea.io/files/305952feb5321a50d5d4f6ab6c16da1f.mov", "is_lp": false }, { "id": "unique id 2", "name": null, "collection_name": "A collection name", "manually_input": false, "price_asset": "USD", "price_in_asset": "150.55", "price": "150.55" "image_url": "https://lh3.googleusercontent.com/xJpOAw7P96jdPgs91w7ZQMTq91tvcCva4J2RYHh7LjFufod_UP9FE0bVjhp1cYpbx2p1qFFj2NDFf3oS0eEcNI3L5w", "is_lp": true }, ], "entries_found": 2, "entries_total": 10, "total_value": "2651.70" }, "message": "" }
- Response JSON Object:
entries (object) – A list of nfts balances.
namecan also be null.collection_namecan be null if nft does not have a collection.entries_found (int) – The number of entries found for the current filter. Ignores pagination.
entries_total (int) – The number of total entries ignoring all filters.
total_value (int) – Total value (in user’s preferred currency) of the nfts in the filter.
- Status Codes:
200 OK – NFT balances successfully queried
400 Bad Request – Provided JSON is in some way malformed
401 Unauthorized – User is not logged in.
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 opensea could not be reached or returned unexpected response.
Querying database information
- GET /api/(version)/database/info
Doing a GET on the database information will query information about the global database. If a user is logged in it will also query info on the user’s DB and potential backups.
Example Request:
http
GET /api/1/history/database/info HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/history/database/info
wget
wget -S -O- http://localhost:5042/api/1/history/database/info
httpie
http http://localhost:5042/api/1/history/database/infopython-requests
requests.get('http://localhost:5042/api/1/history/database/info')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "globaldb": {"globaldb_assets_version": 10, "globaldb_schema_version": 2}, "userdb": { "info": { "filepath": "/home/username/.local/share/rotki/data/user/rotkehlchen.db", "size": 5590482, "version": 30 }, "backups": [{ "size": 323441, "time": 1626382287, "version": 27 }, { "size": 623441, "time": 1623384287, "version": 24 }] } "message": "" }
- Response JSON Object:
globaldb (object) – An object with information on the global DB
globaldb_assets_version (int) – The version of the global database’s assets.
globaldb_schema_version (int) – The version of the global database’s schema.
userdb (object) – An object with information on the currently logged in user’s DB. If there is no currently logged in user this is an empty object.
info (object) – Under the userdb this contains the info of the currently logged in user. It has the path to the DB file, the size in bytes and the DB version.
backups (list) – Under the userdb this contains the list of detected backups (if any) for the user db. Each list entry is an object with the size in bytes of the backup, the unix timestamp in which it was taken and the user DB version.
- Status Codes:
200 OK – Data were queried successfully.
401 Unauthorized – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
Creating a database backup
- PUT /api/(version)/database/backups
Doing a PUT on the database backups endpoint will immediately create a backup of the current user’s database.
Example Request:
http
PUT /api/1/history/database/backups HTTP/1.1 Host: localhost:5042
curl
curl -i -X PUT http://localhost:5042/api/1/history/database/backups
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/history/database/backups
httpie
http PUT http://localhost:5042/api/1/history/database/backups
python-requests
requests.put('http://localhost:5042/api/1/history/database/backups')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": "/path/to/created/1633042045_rotkehlchen_db_v28.backup", "message": "" }
- Response JSON Object:
result (string) – The full path of the newly created database backup
- Status Codes:
200 OK – Backup was created successfully.
401 Unauthorized – No user is currently logged in.
409 Conflict – Failure to create the DB backup.
500 Internal Server Error – Internal rotki error.
Deleting a database backup
- DELETE /api/(version)/database/backups
Doing a DELETE on the database backups endpoint with the backup filepath will delete it.
Example Request:
http
DELETE /api/1/history/database/backups HTTP/1.1 Host: localhost:5042 {"file": "/path/to/created/1633042045_rotkehlchen_db_v28.backup"}
curl
curl -i -X DELETE http://localhost:5042/api/1/history/database/backups --data-raw '{"file": "/path/to/created/1633042045_rotkehlchen_db_v28.backup"}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/history/database/backups --body-data='{"file": "/path/to/created/1633042045_rotkehlchen_db_v28.backup"}'
httpie
echo '{"file": "/path/to/created/1633042045_rotkehlchen_db_v28.backup"}' | http DELETE http://localhost:5042/api/1/history/database/backups
python-requests
requests.delete('http://localhost:5042/api/1/history/database/backups', data='{"file": "/path/to/created/1633042045_rotkehlchen_db_v28.backup"}')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – True for success
- Status Codes:
200 OK – Backup was deleted successfully.
400 Bad Request – The given filepath does not exist
401 Unauthorized – No user is currently logged in.
409 Conflict – Failure to delete the backup or the requested file to delete is not in the user’s data directory.
500 Internal Server Error – Internal rotki error.
Downloading a database backup
- GET /api/(version)/database/backups
Doing a GET on the database backups endpoint with the backup filepath will download it.
Example Request:
http
GET /api/1/history/database/backups HTTP/1.1 Host: localhost:5042 {"file": "/path/to/created/1633042045_rotkehlchen_db_v28.backup"}
curl
curl -i -X GET http://localhost:5042/api/1/history/database/backups --data-raw '{"file": "/path/to/created/1633042045_rotkehlchen_db_v28.backup"}'
wget
wget -S -O- http://localhost:5042/api/1/history/database/backups --body-data='{"file": "/path/to/created/1633042045_rotkehlchen_db_v28.backup"}'
httpie
echo '{"file": "/path/to/created/1633042045_rotkehlchen_db_v28.backup"}' | http http://localhost:5042/api/1/history/database/backups
python-requests
requests.get('http://localhost:5042/api/1/history/database/backups', data='{"file": "/path/to/created/1633042045_rotkehlchen_db_v28.backup"}')
Example Response:
HTTP/1.1 200 OK Content-Type: application/octet-stream
- Status Codes:
200 OK – Backup was downloaded successfully.
400 Bad Request – The given filepath does not exist
401 Unauthorized – No user is currently logged in.
409 Conflict – Failure to download the backup or the requested file to download is not in the user’s data directory.
500 Internal Server Error – Internal rotki error.
Get associated locations
- GET /api/(version)/locations/associated
Doing a GET on this endpoint will return a list of locations where the user has information. It contains locations imported in CSV, exchanges and DeFi locations.
Example Request:
http
GET /api/1/locations/associated HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/locations/associated
wget
wget -S -O- http://localhost:5042/api/1/locations/associated
httpie
http http://localhost:5042/api/1/locations/associatedpython-requests
requests.get('http://localhost:5042/api/1/locations/associated')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": ["nexo", "kraken", "uniswap"], "message": "" }
- Status Codes:
200 OK – Locations successfully queried.
401 Unauthorized – User is not logged in.
409 Conflict – Other error. Check error message for details.
500 Internal Server Error – Internal Rotki error
Get location labels
- GET /api/(version)/locations/labels
Doing a GET on this endpoint will return a list of all unique location labels with their corresponding locations from the user’s history events. Results are ordered with the most frequently occurring labels first.
Example Request:
http
GET /api/1/locations/labels HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/locations/labels
wget
wget -S -O- http://localhost:5042/api/1/locations/labels
httpie
http http://localhost:5042/api/1/locations/labelspython-requests
requests.get('http://localhost:5042/api/1/locations/labels')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": [ { "location_label": "0x616B71067BE19BdbdBea3600Db0626859Ff25A75", "location": "ethereum" }, { "location_label": "Kraken 1", "location": "kraken" }, { "location_label": "Binance Account", "location": "binance" } ], "message": "" }
- resjsonarr string location_label:
A unique location label from the history events. An account address, exchange name, etc.
- resjsonarr string location:
The location of events with this label.
- statuscode 200:
Location labels successfully queried.
- statuscode 401:
User is not logged in.
- statuscode 409:
Other error. Check error message for details.
- statuscode 500:
Internal Rotki error
Lido CSM staking
- GET /api/(version)/lido-csm/node-operators
Return the list of tracked Lido Community Staking Module (CSM) node operators.
Example Request:
http
GET /api/1/lido-csm/node-operators HTTP/1.1 Host: localhost:5042 Accept: application/json, text/javascript
curl
curl -i -X GET http://localhost:5042/api/1/lido-csm/node-operators -H "Accept: application/json, text/javascript"
wget
wget -S -O- http://localhost:5042/api/1/lido-csm/node-operators --header="Accept: application/json, text/javascript"
httpie
http http://localhost:5042/api/1/lido-csm/node-operators Accept:"application/json, text/javascript"
python-requests
requests.get('http://localhost:5042/api/1/lido-csm/node-operators', headers={'Accept': 'application/json, text/javascript'})
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": [ { "address": "0xbB8311c7bAD518f0D8f907Cad26c5CcC85a06dC4", "node_operator_id": 7, "metrics": { "operatorType": {"id": 1, "label": "Permissionless"}, "bond": {"current": "1.5", "required": "2.0", "claimable": "0.2"}, "keys": {"totalDeposited": 64}, "rewards": {"pending": "0.15"} } } ], "message": "" }
- Response JSON Object:
result (list) – Tracked node operator entries.
result[].address (string) – Checksummed Ethereum address.
result[].node_operator_id (int) – Node operator identifier.
result[].metrics (object) – Cached metrics for the node operator (may be
null).
- Status Codes:
200 OK – Query succeeded.
- PUT /api/(version)/lido-csm/node-operators
Add a new tracked Lido CSM node operator. The backend persists the association and attempts to compute metrics immediately. The provided address must already be registered as an Ethereum blockchain account in
/api/(version)/blockchains/accounts.Example Request:
http
PUT /api/1/lido-csm/node-operators HTTP/1.1 Host: localhost:5042 Accept: application/json, text/javascript Content-Type: application/json;charset=UTF-8 { "address": "0xbB8311c7bAD518f0D8f907Cad26c5CcC85a06dC4", "node_operator_id": 7 }
curl
curl -i -X PUT http://localhost:5042/api/1/lido-csm/node-operators -H "Accept: application/json, text/javascript" -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0xbB8311c7bAD518f0D8f907Cad26c5CcC85a06dC4", "node_operator_id": 7}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/lido-csm/node-operators --header="Accept: application/json, text/javascript" --header="Content-Type: application/json;charset=UTF-8" --body-data='{"address": "0xbB8311c7bAD518f0D8f907Cad26c5CcC85a06dC4", "node_operator_id": 7}'
httpie
echo '{ "address": "0xbB8311c7bAD518f0D8f907Cad26c5CcC85a06dC4", "node_operator_id": 7 }' | http PUT http://localhost:5042/api/1/lido-csm/node-operators Accept:"application/json, text/javascript" Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/lido-csm/node-operators', headers={'Accept': 'application/json, text/javascript', 'Content-Type': 'application/json;charset=UTF-8'}, json={'address': '0xbB8311c7bAD518f0D8f907Cad26c5CcC85a06dC4', 'node_operator_id': 7})
- Request JSON Object:
address (string) – Checksummed Ethereum address that owns the node operator. It must be registered as an Ethereum EVM account.
node_operator_id (int) – Non-negative node operator identifier.
- Status Codes:
200 OK – Node operator stored and metrics computed when possible.
400 Bad Request – Malformed payload.
409 Conflict – Address is not registered as an Ethereum EVM account or node operator already tracked.
502 Bad Gateway – Operator stored but metrics could not be fetched from the blockchain.
- DELETE /api/(version)/lido-csm/node-operators
Remove a tracked node operator.
Example Request:
http
DELETE /api/1/lido-csm/node-operators HTTP/1.1 Host: localhost:5042 Accept: application/json, text/javascript Content-Type: application/json;charset=UTF-8 { "address": "0xbB8311c7bAD518f0D8f907Cad26c5CcC85a06dC4", "node_operator_id": 7 }
curl
curl -i -X DELETE http://localhost:5042/api/1/lido-csm/node-operators -H "Accept: application/json, text/javascript" -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0xbB8311c7bAD518f0D8f907Cad26c5CcC85a06dC4", "node_operator_id": 7}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/lido-csm/node-operators --header="Accept: application/json, text/javascript" --header="Content-Type: application/json;charset=UTF-8" --body-data='{"address": "0xbB8311c7bAD518f0D8f907Cad26c5CcC85a06dC4", "node_operator_id": 7}'
httpie
echo '{ "address": "0xbB8311c7bAD518f0D8f907Cad26c5CcC85a06dC4", "node_operator_id": 7 }' | http DELETE http://localhost:5042/api/1/lido-csm/node-operators Accept:"application/json, text/javascript" Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/1/lido-csm/node-operators', headers={'Accept': 'application/json, text/javascript', 'Content-Type': 'application/json;charset=UTF-8'}, json={'address': '0xbB8311c7bAD518f0D8f907Cad26c5CcC85a06dC4', 'node_operator_id': 7})
- Request JSON Object:
address (string) – Address that owns the node operator.
node_operator_id (int) – Identifier to remove.
- Status Codes:
200 OK – Node operator removed.
400 Bad Request – Malformed payload.
409 Conflict – Node operator not found.
- POST /api/(version)/lido-csm/metrics
Recompute metrics for all tracked node operators and return the refreshed entries.
Example Request:
http
POST /api/1/lido-csm/metrics HTTP/1.1 Host: localhost:5042 Accept: application/json, text/javascript
curl
curl -i -X POST http://localhost:5042/api/1/lido-csm/metrics -H "Accept: application/json, text/javascript"
wget
wget -S -O- http://localhost:5042/api/1/lido-csm/metrics --header="Accept: application/json, text/javascript"
httpie
http POST http://localhost:5042/api/1/lido-csm/metrics Accept:"application/json, text/javascript"
python-requests
requests.post('http://localhost:5042/api/1/lido-csm/metrics', headers={'Accept': 'application/json, text/javascript'})
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": [ { "address": "0xbB8311c7bAD518f0D8f907Cad26c5CcC85a06dC4", "node_operator_id": 7, "metrics": { "operatorType": {"id": 1, "label": "Permissionless"}, "bond": {"current": "1.6", "required": "2.0", "claimable": "0.2"}, "keys": {"totalDeposited": 64}, "rewards": {"pending": "0.05"} } } ], "message": "" }
- Response JSON Object:
result (list) – Updated node operator entries.
- Status Codes:
200 OK – Metrics refreshed successfully.
500 Internal Server Error – Refresh failed; see message for details.
502 Bad Gateway – Refresh partially succeeded but at least one operator’s metrics failed to update.
Staking events
- GET /api/(version)/staking/kraken
Note
This endpoint can also be queried asynchronously by using
"async_query": trueNote
This endpoint also accepts parameters as query arguments.
Doing a GET on this endpoint will return all staking events for the desired location. At the moment the only valid location is kraken. If the retrieval of new information fails the information at the database will be returned
Example Request:
http
GET /api/1/staking/kraken HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"from_timestamp": 1451606400, "to_timestamp": 1571663098, "only_cache": false}
curl
curl -i -X GET http://localhost:5042/api/1/staking/kraken -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_timestamp": 1451606400, "only_cache": false, "to_timestamp": 1571663098}'
wget
wget -S -O- http://localhost:5042/api/1/staking/kraken --header="Content-Type: application/json;charset=UTF-8" --body-data='{"from_timestamp": 1451606400, "only_cache": false, "to_timestamp": 1571663098}'
httpie
echo '{ "from_timestamp": 1451606400, "only_cache": false, "to_timestamp": 1571663098 }' | http http://localhost:5042/api/1/staking/kraken Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/staking/kraken', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_timestamp': 1451606400, 'only_cache': False, 'to_timestamp': 1571663098})
- Request JSON Object:
limit (int) – Optional. This signifies the limit of records to return as per the sql spec.
offset (int) – This signifies the offset from which to start the return of records per the sql spec.
order_by_attributes (list[string]) – Optional. This is the list of attributes of the history by which to order the results. If none is given ‘timestamp’ is assumed. Valid values are: [‘timestamp’, ‘location’, ‘amount’].
ascending (list[bool]) – Optional. False by default. Defines the order by which results are returned depending on the chosen order by attribute.
from_timestamp (int) – The timestamp from which to query. Can be missing in which case we query from 0.
to_timestamp (int) – The timestamp until which to query. Can be missing in which case we query until now.
only_cache (bool) – Optional.If this is true then the equivalent exchange/location is not queried, but only what is already in the DB is returned.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "entries": [ { "event_type": "unstake asset", "asset": "ETH2", "timestamp": 1636740198, "location": "kraken", "amount": "0.0600000000", "value": "278.7345000000000" }, { "event_type": "get reward", "asset": "ETH2", "timestamp": 1636864588, "location": "kraken", "amount": "0.0000103220", "value": "0.0478582110500" }, { "event_type": "stake asset", "asset": "ETH", "timestamp": 1636738550, "location": "kraken", "amount": "0.0600000000", "value": "278.7345000000000" } ], "entries_found": 3, "entries_total": 3, "entries_limit": -1, "total_usd_value": "0.02", "assets": ["ETH2", "ETH"], "received": [ { "asset": "ETH2", "amount": "0.0000103220", "value": "0.21935353362" } ] }, "message": "" }
- Response JSON Array of Objects:
timestamp (int) – The timestamp at which the event occurred
location (string) – A valid location at which the event happened
amount (string) – The amount related to the event
asset (string) – Asset involved in the event
event_type (string) – Type of event. Can be reward, deposit asset or remove asset.
message (string) – It won’t be empty if the query to external services fails for some reason.
total_value (string) – Sum of the value for the assets received computed at the time of acquisition of each event in the user’s main currency.
- Response JSON Object:
entries_found (int) – The number of entries found for the current filter. Ignores pagination.
entries_limit (int) – The limit of entries if free version. -1 for premium.
entries_total (int) – The number of total entries ignoring all filters.
assets (list[string]) – Assets involved in events ignoring all filters.
received (list[object]) – Assets received with the total amount received for each asset and the aggregated value at time of acquisition in the user’s main currency.
- Status Codes:
200 OK – Events are successfully returned
400 Bad Request – Provided JSON is in some way malformed
401 Unauthorized – No user is logged in.
409 Conflict – Kraken is not active or some parameter for filters is not valid.
500 Internal Server Error – Internal rotki error
Export assets added by the user
- PUT /api/(version)/assets/user
Note
This endpoint can also be queried asynchronously by using
"async_query": trueCalling this endpoint with PUT and action download will create a zip file with the assets that are not included by default with vanilla rotki. If a destination folder is provided, the file is saved there and the result is
true. If no destination folder is provided, the result contains afile_paththat can be used to download the file via the/assets/user/downloadendpoint.Example Request:
http
PUT /api/1/assets/user HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"action": "download", "destination": "/home/user/Downloads", "async_query": true}
curl
curl -i -X PUT http://localhost:5042/api/1/assets/user -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"action": "download", "async_query": true, "destination": "/home/user/Downloads"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/assets/user --header="Content-Type: application/json;charset=UTF-8" --body-data='{"action": "download", "async_query": true, "destination": "/home/user/Downloads"}'
httpie
echo '{ "action": "download", "async_query": true, "destination": "/home/user/Downloads" }' | http PUT http://localhost:5042/api/1/assets/user Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/assets/user', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'action': 'download', 'async_query': True, 'destination': '/home/user/Downloads'})
Example Response (with destination):
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
Example Response (without destination):
HTTP/1.1 200 OK Content-Type: application/json { "result": { "file_path": "/tmp/tmpxxxxxx/assets.zip" }, "message": "" }
- Response JSON Array of Objects:
action (string) – Action performed on the endpoint
destination (string) – Optional folder where the generated files will be saved
- Status Codes:
200 OK – Response file is correctly generated
401 Unauthorized – No user is logged in.
507 Insufficient Storage – Failed to create the file.
Downloading Exported User Assets
- GET /api/(version)/assets/user/download
Doing a GET on this endpoint will download the zip file exported in a previous call to the export endpoint and specified here with file_path.
Example Request:
http
GET /api/1/assets/user/download HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "file_path": "/tmp/tmpxxxxxx/assets.zip" }
curl
curl -i -X GET http://localhost:5042/api/1/assets/user/download -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"file_path": "/tmp/tmpxxxxxx/assets.zip"}'
wget
wget -S -O- http://localhost:5042/api/1/assets/user/download --header="Content-Type: application/json;charset=UTF-8" --body-data='{"file_path": "/tmp/tmpxxxxxx/assets.zip"}'
httpie
echo '{ "file_path": "/tmp/tmpxxxxxx/assets.zip" }' | http http://localhost:5042/api/1/assets/user/download Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/assets/user/download', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'file_path': '/tmp/tmpxxxxxx/assets.zip'})
- Request JSON Object:
file_path (string) – The zip file to be downloaded.
Example Response:
HTTP/1.1 200 OK Content-Type: application/zip
- Status Codes:
200 OK – Zip file successfully downloaded
400 Bad Request – Provided JSON is in some way malformed
401 Unauthorized – No user is logged in.
500 Internal Server Error – Internal rotki error
Import assets added by the user
- PUT /api/(version)/assets/user
- POST /api/(version)/assets/user
Doing a put or a post to this endpoint will import the assets in the json file provided. The file has to follow the rotki expected format and will be verified.
Note
If doing a POST the action field is not required.
Note
This endpoint can be called asynchronously.
Example Request:
http
POST /api/1/assets/user HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"action": "upload", "file": "/tmp/assets.zip"}
curl
curl -i -X POST http://localhost:5042/api/1/assets/user -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"action": "upload", "file": "/tmp/assets.zip"}'
wget
wget -S -O- http://localhost:5042/api/1/assets/user --header="Content-Type: application/json;charset=UTF-8" --post-data='{"action": "upload", "file": "/tmp/assets.zip"}'
httpie
echo '{ "action": "upload", "file": "/tmp/assets.zip" }' | http POST http://localhost:5042/api/1/assets/user Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/assets/user', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'action': 'upload', 'file': '/tmp/assets.zip'})
- Response JSON Array of Objects:
action (string) – Action performed on the endpoint
file (string) – The path to the file to upload for PUT. The file itself for POST.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Status Codes:
200 OK – Assets correctly imported
401 Unauthorized – No user is logged in.
409 Conflict – Imported file is for an older version of the schema or file can’t be loaded or format is not valid.
500 Internal Server Error – Internal rotki error
507 Insufficient Storage – Filesystem error, probably related to size.
Handling snapshot manipulation
- GET /api/(version)/snapshots/(timestamp)
Doing a GET on this endpoint without any action query parameter will return the database snapshot for the specified timestamp in JSON.
Example Request:
http
GET /api/1/snapshots/149095883 HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8
curl
curl -i -X GET http://localhost:5042/api/1/snapshots/149095883 -H "Content-Type: application/json;charset=UTF-8"
wget
wget -S -O- http://localhost:5042/api/1/snapshots/149095883 --header="Content-Type: application/json;charset=UTF-8"
httpie
http http://localhost:5042/api/1/snapshots/149095883 Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/snapshots/149095883', headers={'Content-Type': 'application/json;charset=UTF-8'})
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "balances_snapshot": [ { "timestamp": 149095883, "category": "asset", "asset_identifier": "AVAX", "amount": "1000.00", "value": "12929.00", } ], "location_data_snapshot": [ { "timestamp": 149095883, "location": "external", "value": "12929.00" }, { "timestamp": 149095883, "location": "total", "value": "12929.00" } ] }, "message": "" }
- Response JSON Object:
result (object) – A dictionary representing the snapshot at the specified timestamp.
- Status Codes:
200 OK – Snapshot was retrieved successfully.
401 Unauthorized – No user is currently logged in.
404 Not Found – No snapshot data found for the given timestamp.
500 Internal Server Error – Internal rotki error.
- GET /api/(version)/snapshots/(timestamp)
Doing a GET on this endpoint with action
'export'will export the database snapshot for the specified timestamp to CSV files and save them in the given directory.Example Request:
http
GET /api/1/snapshots/149095883?action=export&path=%2Fhome%2Fuser%2Fdocuments HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8
curl
curl -i -X GET 'http://localhost:5042/api/1/snapshots/149095883?action=export&path=%2Fhome%2Fuser%2Fdocuments' -H "Content-Type: application/json;charset=UTF-8"
wget
wget -S -O- 'http://localhost:5042/api/1/snapshots/149095883?action=export&path=%2Fhome%2Fuser%2Fdocuments' --header="Content-Type: application/json;charset=UTF-8"
httpie
http 'http://localhost:5042/api/1/snapshots/149095883?action=export&path=%2Fhome%2Fuser%2Fdocuments' Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/snapshots/149095883?action=export&path=%2Fhome%2Fuser%2Fdocuments', headers={'Content-Type': 'application/json;charset=UTF-8'})
- Reqquery str path:
The directory in which to write the exported CSV files.
- Reqquery str action:
The action to be performed by the endpoint. Can be one of
'export','download'.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true "message": "" }
- Response JSON Object:
result (bool) – Boolean denoting success or failure of the query.
- Status Codes:
200 OK – Files were exported successfully.
400 Bad Request – Provided query parameter(s) is in some way malformed or given path is not a directory.
401 Unauthorized – No user is currently logged in.
409 Conflict – No snapshot data found for the given timestamp. No permissions to write in the given directory. Check error message.
500 Internal Server Error – Internal rotki error.
- GET /api/(version)/snapshots/(timestamp)
Doing a GET on this endpoint with action
'download'will download database snapshot for the specified timestamp as a zip file.Example Request:
http
GET /api/1/snapshots/149095883?action=download HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8
curl
curl -i -X GET 'http://localhost:5042/api/1/snapshots/149095883?action=download' -H "Content-Type: application/json;charset=UTF-8"
wget
wget -S -O- 'http://localhost:5042/api/1/snapshots/149095883?action=download' --header="Content-Type: application/json;charset=UTF-8"
httpie
http 'http://localhost:5042/api/1/snapshots/149095883?action=download' Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/snapshots/149095883?action=download', headers={'Content-Type': 'application/json;charset=UTF-8'})
- Reqquery str action:
The action to be performed by the endpoint. Can be one of
'export','download'.
Example Response:
HTTP/1.1 200 OK Content-Type: application/zip
- Status Codes:
200 OK – Snapshot was downloaded successfully.
400 Bad Request – Provided query parameter(s) is in some way malformed.
401 Unauthorized – No user is currently logged in.
409 Conflict – No snapshot data found for the given timestamp. No permissions to write in the given directory. Check error message.
500 Internal Server Error – Internal rotki error.
- DELETE /api/(version)/snapshots
Doing a DELETE on this endpoint will delete the snapshot for the specified timestamp.
Example Request:
http
DELETE /api/1/snapshots HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"timestamp": 149095883}
curl
curl -i -X DELETE http://localhost:5042/api/1/snapshots -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"timestamp": 149095883}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/snapshots --header="Content-Type: application/json;charset=UTF-8" --body-data='{"timestamp": 149095883}'
httpie
echo '{ "timestamp": 149095883 }' | http DELETE http://localhost:5042/api/1/snapshots Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/1/snapshots', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'timestamp': 149095883})
- Request JSON Object:
timestamp (int) – The epoch timestamp representing the time of the snapshot to be deleted.
Example Response:
HTTP/1.1 200 OK Content-Type: application/zip
- Status Codes:
200 OK – Snapshot was deleted successfully.
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is currently logged in.
409 Conflict – No snapshot found for the specified timestamp.Check error message.
500 Internal Server Error – Internal rotki error.
- PATCH /api/(version)/snapshots/(timestamp)
Doing a PATCH on this endpoint will replace the snapshot at the specified timestamp with the provided payload.
Example Request:
http
PATCH /api/1/snapshots/ HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "balances_snapshot": [ { "timestamp": 149095883, "category": "asset", "asset_identifier": "AVAX", "amount": "1000.00", "value": "12929.00" } ], "location_data_snapshot": [ { "timestamp": 149095883, "location": "external", "value": "12929.00" }, { "timestamp": 149095883, "location": "total", "value": "12929.00" } ] }
curl
curl -i -X PATCH http://localhost:5042/api/1/snapshots/ -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"balances_snapshot": [{"timestamp": 149095883, "category": "asset", "asset_identifier": "AVAX", "amount": "1000.00", "value": "12929.00"}], "location_data_snapshot": [{"timestamp": 149095883, "location": "external", "value": "12929.00"}, {"timestamp": 149095883, "location": "total", "value": "12929.00"}]}'
wget
wget -S -O- --method=PATCH http://localhost:5042/api/1/snapshots/ --header="Content-Type: application/json;charset=UTF-8" --body-data='{"balances_snapshot": [{"timestamp": 149095883, "category": "asset", "asset_identifier": "AVAX", "amount": "1000.00", "value": "12929.00"}], "location_data_snapshot": [{"timestamp": 149095883, "location": "external", "value": "12929.00"}, {"timestamp": 149095883, "location": "total", "value": "12929.00"}]}'
httpie
echo '{ "balances_snapshot": [ { "amount": "1000.00", "asset_identifier": "AVAX", "category": "asset", "timestamp": 149095883, "value": "12929.00" } ], "location_data_snapshot": [ { "location": "external", "timestamp": 149095883, "value": "12929.00" }, { "location": "total", "timestamp": 149095883, "value": "12929.00" } ] }' | http PATCH http://localhost:5042/api/1/snapshots/ Content-Type:"application/json;charset=UTF-8"
python-requests
requests.patch('http://localhost:5042/api/1/snapshots/', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'balances_snapshot': [{'timestamp': 149095883, 'category': 'asset', 'asset_identifier': 'AVAX', 'amount': '1000.00', 'value': '12929.00'}], 'location_data_snapshot': [{'timestamp': 149095883, 'location': 'external', 'value': '12929.00'}, {'timestamp': 149095883, 'location': 'total', 'value': '12929.00'}]})
- Request JSON Object:
balances_snapshot (list) – The list of objects representing the balances of an account to be updated. All fields are required i.e
"timestamp","category","asset_identifier","amount","usd_value".location_data_snapshot (list) – The list of objects representing the location data to be updated. All fields are required i.e
"timestamp","location","usd_value".
Example Response:
HTTP/1.1 200 OK Content-Type: application/zip
- Status Codes:
200 OK – Snapshot was updated successfully.
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is currently logged in.
409 Conflict – JSON has different timestamps. Snapshot contains an unknown asset. JSON has invalid headers. Check error message.
500 Internal Server Error – Internal rotki error.
- PUT /api/(version)/snapshots
- POST /api/(version)/snapshots
Doing either a PUT or a POST on this import endpoint will import database snapshot from the specified paths in the request body. PUT expect paths to the files to be imported. POST expects the files to be uploaded as multipart/form-data.
Example Request:
http
PUT /api/1/snapshots HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "balances_snapshot_file": "/path/to/balances_snapshot_import.csv", "location_data_snapshot_file": "/path/to/location_data_snapshot.csv" }
curl
curl -i -X PUT http://localhost:5042/api/1/snapshots -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"balances_snapshot_file": "/path/to/balances_snapshot_import.csv", "location_data_snapshot_file": "/path/to/location_data_snapshot.csv"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/snapshots --header="Content-Type: application/json;charset=UTF-8" --body-data='{"balances_snapshot_file": "/path/to/balances_snapshot_import.csv", "location_data_snapshot_file": "/path/to/location_data_snapshot.csv"}'
httpie
echo '{ "balances_snapshot_file": "/path/to/balances_snapshot_import.csv", "location_data_snapshot_file": "/path/to/location_data_snapshot.csv" }' | http PUT http://localhost:5042/api/1/snapshots Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/snapshots', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'balances_snapshot_file': '/path/to/balances_snapshot_import.csv', 'location_data_snapshot_file': '/path/to/location_data_snapshot.csv'})
- Request JSON Object:
balances_snapshot_file (str) – The path to a balances_snapshot_import.csv file that was previously exported.
location_data_snapshot_file (str) – The path to a location_data_snapshot.csv file that was previously exported.
Example Response:
HTTP/1.1 200 OK Content-Type: application/zip
- Status Codes:
200 OK – Snapshot was imported successfully.
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is currently logged in.
409 Conflict – CSV file has different timestamps. Snapshot contains an unknown asset. Csv file has invalid headers. Check error message.
500 Internal Server Error – Internal rotki error.
Get ENS names
- POST /api/(version)/names/ens/reverse
Doing a POST on the ENS reverse endpoint will return the ENS names for the given ethereum addresses from cache if found and from blockchain otherwise. If ignore_cache is true, then the entire cache will be recreated
Note
This endpoint can also be queried asynchronously by using
"async_query": true.Example Request:
http
POST /api/1/names/ens/reverse HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "ethereum_addresses": ["0x1", "0x2"] } .. http:example:: curl wget httpie python-requests POST /api/1/naminens/reverse HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "ethereum_addresses": ["0x1", "0x2"], "ignore_cache": true }
curl
curl -i -X POST http://nohost/api/1/names/ens/reverse --data-raw '{ "ethereum_addresses": ["0x1", "0x2"] } .. http:example:: curl wget httpie python-requests POST /api/1/naminens/reverse HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "ethereum_addresses": ["0x1", "0x2"], "ignore_cache": true }'
wget
wget -S -O- http://nohost/api/1/names/ens/reverse --post-data='{ "ethereum_addresses": ["0x1", "0x2"] } .. http:example:: curl wget httpie python-requests POST /api/1/naminens/reverse HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "ethereum_addresses": ["0x1", "0x2"], "ignore_cache": true }'
httpie
echo '{ "ethereum_addresses": ["0x1", "0x2"] } .. http:example:: curl wget httpie python-requests POST /api/1/naminens/reverse HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "ethereum_addresses": ["0x1", "0x2"], "ignore_cache": true }' | http POST http://nohost/api/1/names/ens/reverse
python-requests
requests.post('http://nohost/api/1/names/ens/reverse', data='{\r\n\n "ethereum_addresses": ["0x1", "0x2"]\r\n\n }\r\n\n\r\n\n.. http:example:: curl wget httpie python-requests\r\n\n\r\n\n POST /api/1/naminens/reverse HTTP/1.1\r\n\n Host: localhost:5042\r\n\n Content-Type: application/json;charset=UTF-8\r\n\n\r\n\n {\r\n\n "ethereum_addresses": ["0x1", "0x2"],\r\n\n "ignore_cache": true\r\n\n }')
- Request JSON Object:
ethereum_addresses (list) – A list of ethereum addresses to get names for.
ignore_cache (bool) – If true, the entire cache will be updated.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "0x1": "name1", "0x2": "name2" }, "message": "", }
- Response JSON Object:
result (object) – A dictionary of ethereum address to ENS name.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – Names were returned successfully.
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is currently logged in.
409 Conflict – Failed to query names or addresses have incorrect format.
500 Internal Server Error – Internal rotki error.
Get address from ENS name
- POST /api/(version)/names/ens/resolve
Doing a POST on the ENS resolution endpoint will return the address for the given ENS name if it exists. And null if it does not.
Note
This endpoint can also be queried asynchronously by using
"async_query": true.Example Request:
http
POST /api/1/naminens/reverse HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "name": "lefteris.eth", "ignore_cache": true }
curl
curl -i -X POST http://localhost:5042/api/1/naminens/reverse -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"ignore_cache": true, "name": "lefteris.eth"}'
wget
wget -S -O- http://localhost:5042/api/1/naminens/reverse --header="Content-Type: application/json;charset=UTF-8" --post-data='{"ignore_cache": true, "name": "lefteris.eth"}'
httpie
echo '{ "ignore_cache": true, "name": "lefteris.eth" }' | http POST http://localhost:5042/api/1/naminens/reverse Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/naminens/reverse', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'ignore_cache': True, 'name': 'lefteris.eth'})
- Request JSON Object:
name (str) – The name to resolve to an address
ignore_cache (bool[optional]) – If true, then cache checking will be skipped. Off by default.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12", "message": "", }
- Response JSON Object:
result (str) – An evm address if resolution succeeds or null if not.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – Name was resolved successfully
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is currently logged in.
404 Not Found – Name not found.
409 Conflict – Failed to resolve name or addresses have incorrect format.
500 Internal Server Error – Internal rotki error.
Get mappings from addressbook
- POST /api/(version)/names/addressbook
Doing a POST on the addressbook endpoint with either /global or /private postfix with a list of addresses will return found address mappings with the specified filter arguments. If no filter argument is specified, all known mappings are returned.
Example Request
http
POST /api/1/names/addressbook/global HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "offset": 0, "limit": 1, "blockchain": "eth", "name_substring": "neighbour", "addresses": [ {"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth"}, {"address": "bc1qamhqfr5z2ypehv0sqq784hzgd6ws2rjf6v46w8", "blockchain": "btc"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"} ] }
curl
curl -i -X POST http://localhost:5042/api/1/names/addressbook/global -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"addresses": [{"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth"}, {"address": "bc1qamhqfr5z2ypehv0sqq784hzgd6ws2rjf6v46w8", "blockchain": "btc"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"}], "blockchain": "eth", "limit": 1, "name_substring": "neighbour", "offset": 0}'
wget
wget -S -O- http://localhost:5042/api/1/names/addressbook/global --header="Content-Type: application/json;charset=UTF-8" --post-data='{"addresses": [{"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth"}, {"address": "bc1qamhqfr5z2ypehv0sqq784hzgd6ws2rjf6v46w8", "blockchain": "btc"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"}], "blockchain": "eth", "limit": 1, "name_substring": "neighbour", "offset": 0}'
httpie
echo '{ "addresses": [ { "address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth" }, { "address": "bc1qamhqfr5z2ypehv0sqq784hzgd6ws2rjf6v46w8", "blockchain": "btc" }, { "address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD" } ], "blockchain": "eth", "limit": 1, "name_substring": "neighbour", "offset": 0 }' | http POST http://localhost:5042/api/1/names/addressbook/global Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/names/addressbook/global', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'addresses': [{'address': '0x9531c059098e3d194ff87febb587ab07b30b1306', 'blockchain': 'eth'}, {'address': 'bc1qamhqfr5z2ypehv0sqq784hzgd6ws2rjf6v46w8', 'blockchain': 'btc'}, {'address': '0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD'}], 'blockchain': 'eth', 'limit': 1, 'name_substring': 'neighbour', 'offset': 0})
- Request JSON Object:
limit (int[optional]) – This signifies the limit of records to return as per the sql spec.
offset (int[optional]) – This signifies the offset from which to start the return of records per the sql spec.
order_by_attributes (list[string]) – This is the list of attributes of the addressbook entries 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.
name_substring (str[optional]) – The substring to use as filter for the name to be found in the addressbook.
blockchain (str[optional]) – The blockchain in which to use the provided name.
strict_blockchain (bool[optional]) – Defaults to true. When true, the provided
blockchainmust match exactly. When false, include all blockchains where the address format is valid for the same chain family (e.g., any EVM-based chain whenblockchainis an EVM chain).addresses (object[optional]) – List of addresses that the backend should find names for.
Example Response
HTTP/1.1 200 OK Content-Type: application/zip { "result": { "entries": [ { "address": "bc1qamhqfr5z2ypehv0sqq784hzgd6ws2rjf6v46w8", "name": "mtgox", "blockchain": "btc" }, { "address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "name": "My dear friend Tom", "blockchain": "eth" }, { "address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD", "name": "Neighbour Frank", "blockchain": "eth" } ], "entries_found": 1, "entries_total": 3 }, "message": "" }
- Response JSON Object:
entries (object) – An array of address objects. Each entry is composed of the address under the
"address"key and other metadata like"name"and"blockchain"for each address.entries_found (int) – The number of entries found for the current filter. Ignores pagination.
entries_total (int) – The number of total entries ignoring all filters.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – Mappings were returned successfully.
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is currently logged in.
409 Conflict – Addresses have incorrect format.
500 Internal Server Error – Internal rotki error.
Insert mappings into addressbook
- PUT /api/(version)/names/addressbook
Doing a PUT on the addressbook endpoint with either /global or /private postfix with a list of entries, each entry containing address and a name will add these entries to the addressbook.
Example Request
http
PUT /api/1/names/addressbook/private HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "entries": [ {"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth", "name": "Dude ABC"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD", "name": "Dude XYZ"} ] }
curl
curl -i -X PUT http://localhost:5042/api/1/names/addressbook/private -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"entries": [{"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth", "name": "Dude ABC"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD", "name": "Dude XYZ"}]}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/names/addressbook/private --header="Content-Type: application/json;charset=UTF-8" --body-data='{"entries": [{"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth", "name": "Dude ABC"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD", "name": "Dude XYZ"}]}'
httpie
echo '{ "entries": [ { "address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth", "name": "Dude ABC" }, { "address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD", "name": "Dude XYZ" } ] }' | http PUT http://localhost:5042/api/1/names/addressbook/private Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/names/addressbook/private', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'entries': [{'address': '0x9531c059098e3d194ff87febb587ab07b30b1306', 'blockchain': 'eth', 'name': 'Dude ABC'}, {'address': '0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD', 'name': 'Dude XYZ'}]})
- Request JSON Object:
entries (object) – A list of entries to be added to the addressbook
Example Response
HTTP/1.1 200 OK Content-Type: application/zip { "result": true, "message": "" }
- Response JSON Object:
result (bool) – A boolean which is true in the case that entries were added successfully.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – Entries were added successfully.
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is currently logged in.
409 Conflict – Some of the provided entries’ addresses have incorrect format.
500 Internal Server Error – Internal rotki error.
Update mappings in the addressbook
- PATCH /api/(version)/names/addressbook
Doing a PATCH on the addressbook endpoint with either /global or /private postfix with a list of entries, each entry containing address and a name will update these entries’ names in the addressbook, or add them if they do not already exist. Setting a blank name will delete the entry.
Example Request
http
PATCH /api/1/names/addressbook/private HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "entries": [ {"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "name": "Dude ABC"}, {"address": "13EcxFSXEFmJfxGXSQYLfgEXXGZBSF1P753MyHauw5NV4tAV", "name": "Polkacomma"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD", "name": "Dude XYZ"} ] }
curl
curl -i -X PATCH http://localhost:5042/api/1/names/addressbook/private -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"entries": [{"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "name": "Dude ABC"}, {"address": "13EcxFSXEFmJfxGXSQYLfgEXXGZBSF1P753MyHauw5NV4tAV", "name": "Polkacomma"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD", "name": "Dude XYZ"}]}'
wget
wget -S -O- --method=PATCH http://localhost:5042/api/1/names/addressbook/private --header="Content-Type: application/json;charset=UTF-8" --body-data='{"entries": [{"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "name": "Dude ABC"}, {"address": "13EcxFSXEFmJfxGXSQYLfgEXXGZBSF1P753MyHauw5NV4tAV", "name": "Polkacomma"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD", "name": "Dude XYZ"}]}'
httpie
echo '{ "entries": [ { "address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "name": "Dude ABC" }, { "address": "13EcxFSXEFmJfxGXSQYLfgEXXGZBSF1P753MyHauw5NV4tAV", "name": "Polkacomma" }, { "address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD", "name": "Dude XYZ" } ] }' | http PATCH http://localhost:5042/api/1/names/addressbook/private Content-Type:"application/json;charset=UTF-8"
python-requests
requests.patch('http://localhost:5042/api/1/names/addressbook/private', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'entries': [{'address': '0x9531c059098e3d194ff87febb587ab07b30b1306', 'name': 'Dude ABC'}, {'address': '13EcxFSXEFmJfxGXSQYLfgEXXGZBSF1P753MyHauw5NV4tAV', 'name': 'Polkacomma'}, {'address': '0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD', 'name': 'Dude XYZ'}]})
- Request JSON Object:
entries (object) – A list of entries to be updated in the addressbook.
address (str) – The address that will be tracked in the addressbook.
blockchain (str[optional]) – The blockchain in which to use the provided name.
name (str) – Name to be used.
Example Response
HTTP/1.1 200 OK Content-Type: application/zip { "result": true, "message": "" }
- Response JSON Object:
result (bool) – A boolean which is true in case if entries were updated successfully.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – Entries were updated successfully.
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is currently logged in.
409 Conflict – Some of the provided entries don’t exist in the addressbook or addresses have incorrect format.
500 Internal Server Error – Internal rotki error.
Delete mappings in the addressbook
- DELETE /api/(version)/names/addressbook
Doing a DELETE on the addressbook endpoint with either /global or /private postfix with a list of addresses will delete mappings in the addressbook of the specified addresses
Example Request
http
DELETE /api/1/names/addressbook/global HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "addresses": [ {"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"} ] }
curl
curl -i -X DELETE http://localhost:5042/api/1/names/addressbook/global -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"addresses": [{"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"}]}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/names/addressbook/global --header="Content-Type: application/json;charset=UTF-8" --body-data='{"addresses": [{"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"}]}'
httpie
echo '{ "addresses": [ { "address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth" }, { "address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD" } ] }' | http DELETE http://localhost:5042/api/1/names/addressbook/global Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/1/names/addressbook/global', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'addresses': [{'address': '0x9531c059098e3d194ff87febb587ab07b30b1306', 'blockchain': 'eth'}, {'address': '0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD'}]})
- Request JSON Object:
entries (object) – A list of addresses to be deleted from the addressbook
address (str) – The address that will be deleted in the addressbook.
blockchain (str[optional]) – The blockchain for which to delete the name mapping. If is not provided the names for all the chains will be deleted.
Example Response
HTTP/1.1 200 OK Content-Type: application/zip { "result": true, "message": "" }
- Response JSON Object:
result (bool) – A boolean which is true in case if entries were deleted successfully.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – Entries were deleted successfully.
400 Bad Request – Provided JSON is in some way malformed.
409 Conflict – No user is currently logged in.
409 Conflict – Some of the provided entries don’t exist in the addressbook or addresses have incorrect format.
500 Internal Server Error – Internal rotki error.
Search for all known names of an address
- POST /api/(version)/names
Doing a POST on all names endpoint with a list of addresses will search for names of these addresses in all places and return a name for each address if found. Only one name is returned. The priority of the returned names adheres to the following order: private addressbook > blockchain account labels > global addressbook > ethereum tokens > hardcoded mappings > ENS names.
Example Request
http
POST /api/1/names HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "addresses": [ {"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"} ] }
curl
curl -i -X POST http://localhost:5042/api/1/names -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"addresses": [{"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"}]}'
wget
wget -S -O- http://localhost:5042/api/1/names --header="Content-Type: application/json;charset=UTF-8" --post-data='{"addresses": [{"address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth"}, {"address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD"}]}'
httpie
echo '{ "addresses": [ { "address": "0x9531c059098e3d194ff87febb587ab07b30b1306", "blockchain": "eth" }, { "address": "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD" } ] }' | http POST http://localhost:5042/api/1/names Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/names', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'addresses': [{'address': '0x9531c059098e3d194ff87febb587ab07b30b1306', 'blockchain': 'eth'}, {'address': '0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD'}]})
- Request JSON Object:
addresses (object) – List of addresses that the backend should find names for
address (str) – The address that will be queried in the addressbook.
blockchain (str[optional]) – The chain for which to find names. If is not provided the names are searched for all chains.
Example Response
HTTP/1.1 200 OK Content-Type: application/zip { "result": { "0x9531c059098e3d194ff87febb587ab07b30b1306": "My blockchain account 1", "0x8A4973ABBCEd48596D6D79ac6B53Ceda65e342CD": "Neighbour Frank", }, "message": "" }
- Response JSON Object:
result (object) – A dictionary of mappings. Address -> name.
message (str) – Error message if any errors occurred.
- Status Codes:
200 OK – Mappings were returned successfully.
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is currently logged in.
409 Conflict – Addresses have incorrect format.
500 Internal Server Error – Internal rotki error.
Handling user notes
- POST /api/(version)/notes
Doing a POST on this endpoint will return all the user notes present in the database.
Example Request:
http
POST /api/1/notes HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"from_timestamp": 12345677, "to_timestamp": 12345679, "title_substring": "#"}
curl
curl -i -X POST http://localhost:5042/api/1/notes -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_timestamp": 12345677, "title_substring": "#", "to_timestamp": 12345679}'
wget
wget -S -O- http://localhost:5042/api/1/notes --header="Content-Type: application/json;charset=UTF-8" --post-data='{"from_timestamp": 12345677, "title_substring": "#", "to_timestamp": 12345679}'
httpie
echo '{ "from_timestamp": 12345677, "title_substring": "#", "to_timestamp": 12345679 }' | http POST http://localhost:5042/api/1/notes Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/notes', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_timestamp': 12345677, 'title_substring': '#', 'to_timestamp': 12345679})
- Request JSON Object:
location (str[optional]) – A string filtering the note location. Possible values are hardcoded here: https://github.com/rotki/rotki/blob/develop/frontend/app/src/types/notes.ts
limit (int) – This signifies the limit of records to return as per the sql spec.
offset (int) – This signifies the offset from which to start the return of records per the sql spec.
order_by_attributes (list[string]) – This is the list of attributes of the note by which to order the results. By default we sort using
last_update_timestamp.ascending (list[bool]) – Should the order be ascending? This is the default. If set to false, it will be on descending order.
from_timestamp (int) – The timestamp after which to return transactions. If not given zero is considered as the start.
to_timestamp (int) – The timestamp until which to return transactions. If not given all transactions from
from_timestampuntil now are returned.title_substring (string) – The substring to use as filter for the title of the notes.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "entries": [{ "identifier": 1, "title": "#1", "content": "Hello, World!", "location": "manual balances", "last_update_timestamp": 12345678, "is_pinned": true }, { "identifier": 2, "title": "#2", "content": "Hi", "location": "manual balances", "last_update_timestamp": 12345699, "is_pinned": false }], "entries_found": 2, "entries_total": 2, "entries_limit": -1 }, "message": "" }
- Response JSON Object:
result (object) – An array of objects representing user note entries.
identifier (int) – The unique identifier of the user note.
title (str) – The title of the note.
content (str) – The content of the note.
location (str) – The location inside the application the note was taken.
last_update_timestamp (int) – The timestamp the note was last updated.
is_pinned (bool) – Whether the note has been pinned by the user or not.
entries_found (int) – The number of entries found for the current filter. Ignores pagination.
entries_limit (int) – The limit of entries if free version. -1 for premium.
entries_total (int) – The number of total entries ignoring all filters.
- Status Codes:
200 OK – User notes were retrieved successfully.
401 Unauthorized – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
- DELETE /api/(version)/notes
Doing a DELETE on this endpoint will delete a user note for the specified identifier.
Example Request:
http
DELETE /api/1/notes HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"identifier": 149095883}
curl
curl -i -X DELETE http://localhost:5042/api/1/notes -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"identifier": 149095883}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/notes --header="Content-Type: application/json;charset=UTF-8" --body-data='{"identifier": 149095883}'
httpie
echo '{ "identifier": 149095883 }' | http DELETE http://localhost:5042/api/1/notes Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/1/notes', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'identifier': 149095883})
- Request JSON Object:
identifier (int) – The identifier of the user note you’re trying to delete.
Example Response:
HTTP/1.1 200 OK Content-Type: application/zip {"result": true, "message": ""}
- Status Codes:
200 OK – User note was deleted successfully.
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is currently logged in.
409 Conflict – No user note found. Check error message.
500 Internal Server Error – Internal rotki error.
- PATCH /api/(version)/notes
Doing a PATCH on this endpoint will update the content of an already existing user note.
Example Request:
http
PATCH /api/1/notes HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "identifier": 2, "title": "#2", "content": "Go to bed", "location": "manual balances", "last_update_timestamp": 12345699, "is_pinned": false }
curl
curl -i -X PATCH http://localhost:5042/api/1/notes -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"content": "Go to bed", "identifier": 2, "is_pinned": false, "last_update_timestamp": 12345699, "location": "manual balances", "title": "#2"}'
wget
wget -S -O- --method=PATCH http://localhost:5042/api/1/notes --header="Content-Type: application/json;charset=UTF-8" --body-data='{"content": "Go to bed", "identifier": 2, "is_pinned": false, "last_update_timestamp": 12345699, "location": "manual balances", "title": "#2"}'
httpie
echo '{ "content": "Go to bed", "identifier": 2, "is_pinned": false, "last_update_timestamp": 12345699, "location": "manual balances", "title": "#2" }' | http PATCH http://localhost:5042/api/1/notes Content-Type:"application/json;charset=UTF-8"
python-requests
requests.patch('http://localhost:5042/api/1/notes', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'content': 'Go to bed', 'identifier': 2, 'is_pinned': False, 'last_update_timestamp': 12345699, 'location': 'manual balances', 'title': '#2'})
- Request JSON Object:
identifier (int) – The unique identifier of the user note.
title (str) – The title of the note.
content (str) – The content of the note.
location (str) – The location inside the application the note was taken.
last_update_timestamp (int) – The timestamp the note was last updated.
- Response JSON Object:
is_pinned (bool) – Whether the note has been pinned by the user or not.
Example Response:
HTTP/1.1 200 OK Content-Type: application/zip {"result": true, "message": ""}
- Status Codes:
200 OK – User note was updated successfully.
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is currently logged in.
409 Conflict – User note does not exist.
500 Internal Server Error – Internal rotki error.
- PUT /api/(version)/notes
Doing a PUT on this endpoint will add a new user note to the DB.
Example Request:
http
PUT /api/1/notes HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "title": "#5", "content": "Go to bed now", "location": "history events" }
curl
curl -i -X PUT http://localhost:5042/api/1/notes -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"content": "Go to bed now", "location": "history events", "title": "#5"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/notes --header="Content-Type: application/json;charset=UTF-8" --body-data='{"content": "Go to bed now", "location": "history events", "title": "#5"}'
httpie
echo '{ "content": "Go to bed now", "location": "history events", "title": "#5" }' | http PUT http://localhost:5042/api/1/notes Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/notes', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'content': 'Go to bed now', 'location': 'history events', 'title': '#5'})
- Request JSON Object:
title (str) – The title of the note to be created.
content (str) – The content of the note to be created.
location (str) – The location inside the application the note was taken.
Example Response:
HTTP/1.1 201 OK Content-Type: application/zip {"result": 1, "message": ""}
- Response JSON Object:
result (int) – The unique identifier of the note created.
- Status Codes:
200 OK – User note was added successfully.
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is currently logged in.
409 Conflict – User note with the given title already exists. User has reached the limit of available notes. Check error message.
500 Internal Server Error – Internal rotki error.
Custom Assets
- POST /api/(version)/assets/custom
Doing a POST on this endpoint will return all the custom assets present in the database using the filter parameters.
Example Request:
http
POST /api/1/assets/custom HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"name": "land", "custom_asset_type": "real estate"}
curl
curl -i -X POST http://localhost:5042/api/1/assets/custom -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"custom_asset_type": "real estate", "name": "land"}'
wget
wget -S -O- http://localhost:5042/api/1/assets/custom --header="Content-Type: application/json;charset=UTF-8" --post-data='{"custom_asset_type": "real estate", "name": "land"}'
httpie
echo '{ "custom_asset_type": "real estate", "name": "land" }' | http POST http://localhost:5042/api/1/assets/custom Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/assets/custom', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'custom_asset_type': 'real estate', 'name': 'land'})
- Request JSON Object:
limit (int[optional]) – This signifies the limit of records to return as per the sql spec.
offset (int[optional]) – This signifies the offset from which to start the return of records per the sql spec.
name (string[optional]) – The name of the custom asset to be used as a filter.
identifier (string[optional]) – The identifier of the custom asset to be used as a filter.
custom_asset_type (string[optional]) – The type of the custom asset to be used as a filter.
order_by_attributes (list[string][optional]) – This is the list of attributes of the custom asset by which to order the results. By default we sort using
name.ascending (list[bool][optional]) – Should the order be ascending? This is the default. If set to false, it will be on descending order.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "entries": [{ "identifier": "00fe5f97-882b-42e5-b0e0-39ebd3a99156'", "name": "House", "notes": "Apartment purchase", "custom_asset_type": "real estate" }, { "identifier": "333c248f-7c64-41f4-833b-2fad96c4ea6b", "name": "Ferrari", "notes": "Exotic car inheritance from lineage", "custom_asset_types": "vehicles" }], "entries_found": 2, "entries_total": 2, }, "message": "" }
- Response JSON Object:
result (object) – An array of objects representing custom assets entries.
identifier (str) – The unique identifier of the custom asset.
name (str) – The name of the custom asset.
notes (str) – The notes used as a description of the custom asset. This field can be null.
custom_asset_type (str) – The type/category of the custom asset.
entries_found (int) – The number of entries found for the current filter. Ignores pagination.
entries_total (int) – The number of total entries ignoring all filters.
- Status Codes:
200 OK – Custom assets were retrieved successfully.
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
- DELETE /api/(version)/assets/custom
Doing a DELETE on this endpoint will delete a custom asset for the specified identifier.
Example Request:
http
DELETE /api/1/assets/custom HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"identifier": "aca42c5d-36f1-4a8b-af28-5aeb322748b5"}
curl
curl -i -X DELETE http://localhost:5042/api/1/assets/custom -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"identifier": "aca42c5d-36f1-4a8b-af28-5aeb322748b5"}'
wget
wget -S -O- --method=DELETE http://localhost:5042/api/1/assets/custom --header="Content-Type: application/json;charset=UTF-8" --body-data='{"identifier": "aca42c5d-36f1-4a8b-af28-5aeb322748b5"}'
httpie
echo '{ "identifier": "aca42c5d-36f1-4a8b-af28-5aeb322748b5" }' | http DELETE http://localhost:5042/api/1/assets/custom Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/1/assets/custom', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'identifier': 'aca42c5d-36f1-4a8b-af28-5aeb322748b5'})
- Request JSON Object:
identifier (str) – The identifier of the custom asset you’re trying to delete.
Example Response:
HTTP/1.1 200 OK Content-Type: application/zip {"result": true, "message": ""}
- Status Codes:
200 OK – Custom asset was deleted successfully.
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is currently logged in.
409 Conflict – No custom asset found. Check error message.
500 Internal Server Error – Internal rotki error.
- PATCH /api/(version)/assets/custom
Doing a PATCH on this endpoint will update the content of an already existing custom asset.
Example Request:
http
PATCH /api/1/assets/custom HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "identifier": "de0b49aa-65e1-4b4e-94b5-d1cd3e4baee1", "name": "Hotel", "notes": "Hotel from ma", "custom_asset_type": "real estate" }
curl
curl -i -X PATCH http://localhost:5042/api/1/assets/custom -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"custom_asset_type": "real estate", "identifier": "de0b49aa-65e1-4b4e-94b5-d1cd3e4baee1", "name": "Hotel", "notes": "Hotel from ma"}'
wget
wget -S -O- --method=PATCH http://localhost:5042/api/1/assets/custom --header="Content-Type: application/json;charset=UTF-8" --body-data='{"custom_asset_type": "real estate", "identifier": "de0b49aa-65e1-4b4e-94b5-d1cd3e4baee1", "name": "Hotel", "notes": "Hotel from ma"}'
httpie
echo '{ "custom_asset_type": "real estate", "identifier": "de0b49aa-65e1-4b4e-94b5-d1cd3e4baee1", "name": "Hotel", "notes": "Hotel from ma" }' | http PATCH http://localhost:5042/api/1/assets/custom Content-Type:"application/json;charset=UTF-8"
python-requests
requests.patch('http://localhost:5042/api/1/assets/custom', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'custom_asset_type': 'real estate', 'identifier': 'de0b49aa-65e1-4b4e-94b5-d1cd3e4baee1', 'name': 'Hotel', 'notes': 'Hotel from ma'})
- Request JSON Object:
identifier (str) – The unique identifier of the custom asset to update.
name (str) – The name of the custom asset.
custom_asset_type (str) – The type/category of the custom asset.
notes (str[optional]) – The notes that serve as a description of the custom asset. This is optional.
Example Response:
HTTP/1.1 200 OK Content-Type: application/zip {"result": true, "message": ""}
- Status Codes:
200 OK – Custom asset was updated successfully.
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is currently logged in.
409 Conflict – Custom asset name and type is already being used. Custom asset does not exist. Check error message.
500 Internal Server Error – Internal rotki error.
- PUT /api/(version)/assets/custom
Doing a PUT on this endpoint will add a new custom asset to the DB.
Example Request:
http
PUT /api/1/assets/custom HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "name": "Yacht", "custom_asset_type": "flex" }
curl
curl -i -X PUT http://localhost:5042/api/1/assets/custom -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"custom_asset_type": "flex", "name": "Yacht"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/assets/custom --header="Content-Type: application/json;charset=UTF-8" --body-data='{"custom_asset_type": "flex", "name": "Yacht"}'
httpie
echo '{ "custom_asset_type": "flex", "name": "Yacht" }' | http PUT http://localhost:5042/api/1/assets/custom Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/assets/custom', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'custom_asset_type': 'flex', 'name': 'Yacht'})
- Request JSON Object:
name (str) – The name of the custom asset to be created.
custom_asset_type (str) – The type/category of the custom asset.
notes (str[optional]) – The notes of the custom asset to be created. This is optional.
Example Response:
HTTP/1.1 201 OK Content-Type: application/zip {"result": "c0c991f0-6511-4b0d-83fc-40fde8495874", "message": ""}
- Response JSON Object:
result (str) – The unique identifier of the custom asset created.
- Status Codes:
200 OK – Custom asset was created successfully.
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is currently logged in.
409 Conflict – Custom asset with the given name and type already exists. Check error message.
500 Internal Server Error – Internal rotki error.
- GET /api/(version)/assets/custom/types
Doing a GET on this endpoint will return all the custom asset types in the DB sorted in ascending order.
Example Request:
http
GET /api/1/assets/custom/types HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8
curl
curl -i -X GET http://localhost:5042/api/1/assets/custom/types -H "Content-Type: application/json;charset=UTF-8"
wget
wget -S -O- http://localhost:5042/api/1/assets/custom/types --header="Content-Type: application/json;charset=UTF-8"
httpie
http http://localhost:5042/api/1/assets/custom/types Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/assets/custom/types', headers={'Content-Type': 'application/json;charset=UTF-8'})
Example Response:
HTTP/1.1 201 OK Content-Type: application/zip {"result": ["medals", "real estate", "stocks"], "message": ""}
- Response JSON Object:
result (list[str]) – The list of custom asset types in the DB.
- Status Codes:
200 OK – Custom asset types retrieved successfully.
401 Unauthorized – No user is currently logged in.
409 Conflict – Other error. Check error message.
500 Internal Server Error – Internal rotki error.
Events Details
- GET /api/(version)/history/events/details
Doing a GET on this endpoint will return the details of a history event.
Example Request:
http
GET /api/1/history/events/details HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"identifier": 137}
curl
curl -i -X GET http://localhost:5042/api/1/history/events/details -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"identifier": 137}'
wget
wget -S -O- http://localhost:5042/api/1/history/events/details --header="Content-Type: application/json;charset=UTF-8" --body-data='{"identifier": 137}'
httpie
echo '{ "identifier": 137 }' | http http://localhost:5042/api/1/history/events/details Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/history/events/details', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'identifier': 137})
- Request JSON Object:
identifier (int) – The identifier of the event to be queried.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "sub_swaps": [ {"from_amount": "100.0", "to_amount": "0.084", "from_asset": "eip155:1/erc20:0x6B3595068778DD592e39A122f4f5a5cF09C90fE2", "to_asset": "ETH"}, {"from_amount": "0.084", "to_amount": "98.2", "from_asset": "ETH", "to_asset": "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7"} ] }, "message": "" }
- Response JSON Object:
result (object) – A dictionary with the details. It may contain one of the following amount of details.
sub_swaps (list) – A list with the details of each sub-swap. Each entry contains the following keys: from_amount, to_amount, from_asset, to_asset.
liquity_staking (dict) – Information about assets that were staked in liquity in this event.
- Status Codes:
200 OK – The details were returned successfully.
400 Bad Request – Provided JSON is in some way malformed.
404 Not Found – There is no event with the provided identifier or the event has no details to be returned.
401 Unauthorized – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
Event Group Position
- GET /api/(version)/history/events/position
Doing a GET on this endpoint will return the 0-based position of a history event group in the filtered and sorted list of groups. This is useful for navigating to a specific event in paginated views.
Example Request:
http
GET /api/1/history/events/position HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"group_identifier": "10x1234567890abcdef"}
curl
curl -i -X GET http://localhost:5042/api/1/history/events/position -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"group_identifier": "10x1234567890abcdef"}'
wget
wget -S -O- http://localhost:5042/api/1/history/events/position --header="Content-Type: application/json;charset=UTF-8" --body-data='{"group_identifier": "10x1234567890abcdef"}'
httpie
echo '{ "group_identifier": "10x1234567890abcdef" }' | http http://localhost:5042/api/1/history/events/position Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/history/events/position', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'group_identifier': '10x1234567890abcdef'})
- Request JSON Object:
group_identifier (string) – The group identifier of the event group to find the position of.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": 42, "message": "" }
- Response JSON Object:
result (int) – The 0-based position of the group in the filtered and sorted list of groups. Returns null if the group is not found.
- Status Codes:
200 OK – The position was returned successfully.
400 Bad Request – Provided JSON is in some way malformed.
401 Unauthorized – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
Get Binance Savings Interests History
- POST /api/(version)/exchanges/(location)/savings
Doing a POST on this endpoint will return all history events relating to interest payments for the specified location. .. note:
This endpoint can also be queried asynchronously by using ``"async_query": true``.
Example Request:
http
POST /api/1/exchanges/binance/savings HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"from_timestamp": 1451606400, "to_timestamp": 1571663098, "only_cache": false}
curl
curl -i -X POST http://localhost:5042/api/1/exchanges/binance/savings -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_timestamp": 1451606400, "only_cache": false, "to_timestamp": 1571663098}'
wget
wget -S -O- http://localhost:5042/api/1/exchanges/binance/savings --header="Content-Type: application/json;charset=UTF-8" --post-data='{"from_timestamp": 1451606400, "only_cache": false, "to_timestamp": 1571663098}'
httpie
echo '{ "from_timestamp": 1451606400, "only_cache": false, "to_timestamp": 1571663098 }' | http POST http://localhost:5042/api/1/exchanges/binance/savings Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/exchanges/binance/savings', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_timestamp': 1451606400, 'only_cache': False, 'to_timestamp': 1571663098})
- Request JSON Object:
async_query (bool) – Boolean denoting whether this is an asynchronous query or not.
limit (int) – Optional. This signifies the limit of records to return as per the sql spec.
offset (int) – This signifies the offset from which to start the return of records per the sql spec.
order_by_attributes (list[string]) – Optional. This is the list of attributes of the history by which to order the results. If none is given ‘timestamp’ is assumed. Valid values are: [‘timestamp’, ‘location’, ‘amount’].
ascending (list[bool]) – Optional. False by default. Defines the order by which results are returned depending on the chosen order by attribute.
from_timestamp (int) – The timestamp from which to query. Can be missing in which case we query from 0.
to_timestamp (int) – The timestamp until which to query. Can be missing in which case we query until now.
only_cache (bool) – Optional.If this is true then the equivalent exchange/location is not queried, but only what is already in the DB is returned.
location (string) – This represents the exchange’s name. Can only be one of “binance” or “binanceus”.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "entries": [ { "timestamp": 1587233562, "location": "binance", "asset": "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F", "amount": "0.00987654", "usd_value": "0.05432097" }, { "timestamp": 1577233578, "location": "binance", "asset": "eip155:1/erc20:0x4Fabb145d64652a948d72533023f6E7A623C7C53", "amount": "0.00006408", "usd_value": "0.00070488" } ], "entries_found": 2, "entries_limit": 100, "entries_total": 2, "total_usd_value": "0.05502585", "assets": [ "eip155:1/erc20:0x4Fabb145d64652a948d72533023f6E7A623C7C53", "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F" ], "received": [ { "asset": "eip155:1/erc20:0x4Fabb145d64652a948d72533023f6E7A623C7C53", "amount": "0.00006408", "usd_value": "0.00070488" }, { "asset": "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F", "amount": "0.00987654", "usd_value": "0.05432097" } ] }, "message": "" }
- Response JSON Array of Objects:
timestamp (int) – The timestamp at which the event occurred.
location (string) – A valid location at which the event happened.
amount (string) – The amount related to the event.
asset (string) – Asset involved in the event.
message (string) – It won’t be empty if the query to external services fails for some reason.
- Response JSON Object:
entries_found (int) – The number of entries found for the current filter. Ignores pagination.
entries_limit (int) – The limit of entries if free version. -1 for premium.
entries_total (int) – The number of total entries ignoring all filters.
total_value (string) – Sum of the value for the assets received computed at the time of acquisition of each event in the user’s main currency.
assets (list[string]) – Assets involved in events ignoring all filters.
received (list[object]) – Assets received with the total amount received for each asset and the aggregated value at time of acquisition in the user’s main currency.
- Status Codes:
200 OK – The balances were returned successfully.
400 Bad Request – Invalid location provided.
401 Unauthorized – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
502 Bad Gateway – An external service used in the query such as binance could not be reached or returned unexpected response.
Get all EVM Chains
- GET /api/(version)/blockchains/evm/all
Doing a GET request on this endpoint will return a list of all EVM chain IDs and their names and labels.
Example Request
http
GET /api/(version)/blockchains/evm/all HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8
{}
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": [ {"id": 1, "name": "ethereum", "label": "Ethereum"}, {"id": 10, "name": "optimism", "label": "Optimism"}, {"id": 56, "name": "binance", "label": "Binance Smart Chain"}, {"id": 100, "name": "gnosis", "label": "Gnosis"}, {"id": 137, "name": "polygon_pos", "label": "Polygon POS"}, {"id": 250, "name": "fantom", "label": "Fantom"}, {"id": 42161, "name": "arbitrum_one", "label": "Arbitrum One"}, {"id": 8453, "name": "base", "label": "Base"}, {"id": 43114, "name": "avalanche", "label": "Avalanche"}, {"id": 42220, "name": "celo", "label": "Celo"} ], "message": "" }
- Response JSON Array of Objects:
result – Returns a list of all EVM chains IDs, their names and labels.
nameis what is used to describe the chain when dealing from/to the API.labelis the label to use in the frontend to display the chain.
- Status Codes:
200 OK – Success
500 Internal Server Error – Internal rotki error
Get avatar for an ens name
- GET /api/(version)/avatars/ens/<ens_name>
Doing a GET on this endpoint will return the avatar that is currently set for the provided ens name. If successful, responses include an ETag header for caching.
Example Request
http
GET /api/1/avatars/ens/rotki.eth HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {}
curl
curl -i -X GET http://localhost:5042/api/1/avatars/ens/rotki.eth -H "Content-Type: application/json;charset=UTF-8"
wget
wget -S -O- http://localhost:5042/api/1/avatars/ens/rotki.eth --header="Content-Type: application/json;charset=UTF-8"
httpie
http http://localhost:5042/api/1/avatars/ens/rotki.eth Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/avatars/ens/rotki.eth', headers={'Content-Type': 'application/json;charset=UTF-8'})
- Request JSON Object:
ens_name (string) – The ens name to check avatar for. It should have .eth postfix.
Example Response:
HTTP/1.1 200 OK Content-Type: image/png
- Status Codes:
200 OK – The avatar was successfully found and returned.
304 Not Modified – Avatar image has not changed. Should be cached on the client. This is returned if the given If-Match or If-None-Match header match the ETag of the previous response.
400 Bad Request – Invalid ens name provided (it doesn’t end with .eth).
404 Not Found – There is no avatar set for the given ens name.
409 Conflict – Avatar was requested for an ens name that is not currently in the database or we couldn’t query the blockchain.
Clear Icons/Avatars Cache
- POST /api/(version)/cache/<cache_type>/clear
Doing a POST on this endpoint will clear the cache of avatars/icons depending on the
cache_type. Valid options ofcache_typeareicons&avatars.Example Request
http
POST /api/1/cache/icons/clear HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "entries": ["ETH", "BTC"] }
curl
curl -i -X POST http://localhost:5042/api/1/cache/icons/clear -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"entries": ["ETH", "BTC"]}'
wget
wget -S -O- http://localhost:5042/api/1/cache/icons/clear --header="Content-Type: application/json;charset=UTF-8" --post-data='{"entries": ["ETH", "BTC"]}'
httpie
echo '{ "entries": [ "ETH", "BTC" ] }' | http POST http://localhost:5042/api/1/cache/icons/clear Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/cache/icons/clear', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'entries': ['ETH', 'BTC']})
http
POST /api/1/cache/avatars/clear HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "entries": ["rotki.eth", "nebolax.eth"] }
curl
curl -i -X POST http://localhost:5042/api/1/cache/avatars/clear -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"entries": ["rotki.eth", "nebolax.eth"]}'
wget
wget -S -O- http://localhost:5042/api/1/cache/avatars/clear --header="Content-Type: application/json;charset=UTF-8" --post-data='{"entries": ["rotki.eth", "nebolax.eth"]}'
httpie
echo '{ "entries": [ "rotki.eth", "nebolax.eth" ] }' | http POST http://localhost:5042/api/1/cache/avatars/clear Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/cache/avatars/clear', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'entries': ['rotki.eth', 'nebolax.eth']})
- Request JSON Array of Objects:
entries (optional[string]) – An array of the icons/avatars to be cleared from the cache. All icons/avatars are deleted in the cache if
null.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json
- Status Codes:
200 OK – The cache items were cleared successfully.
400 Bad Request – Entries provided do not match the
cache_typespecified. Invalidcache_typeprovided.500 Internal Server Error – Internal rotki error
Event Mappings
- GET /api/(version)/history/events/type_mappings
Doing a GET on this endpoint will return a mapping of history events types and subtypes to a mapping of
EventCategoryrepresentations. We also return properties suchicon,labelandcolorfor event types.Example Request
http
GET /history/events/type_mappings HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/history/events/type_mappings
wget
wget -S -O- http://localhost:5042/history/events/type_mappings
httpie
http http://localhost:5042/history/events/type_mappingspython-requests
requests.get('http://localhost:5042/history/events/type_mappings')
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result":{ "global_mappings":{ "spend":{ "fee": {"default": "gas"}, "return wrapped": {"default": "send"}, "donate": {"default": "donate"}, "none":"{"default": send"}, }, "deposit":{ "deposit asset": { "default": "deposit", "exchange": "exchange deposit" }, "bridge": {"default": "bridge deposit"} } }, "entry_type_mappings":{ "eth withdrawal event":{ "staking":{ "remove asset":{ "is_exit":"stake exit", "not_exit":"withdraw" } } } }, "per_protocol_mappings":{ "ethereum":{ "aave":{ "spend":{ "payback debt":"repay", "liquidate":"liquidate" } } }, "optimism":{ "aave":{ "spend":{ "payback debt":"repay", "liquidate":"liquidate" } } }, "polygon pos":{ "aave":{ "spend":{ "payback debt":"repay", "liquidate":"liquidate" } } }, }, "event_category_details":{ "send":{ "direction": "out", "counterparty_mappings": { "default": { "label":"send", "icon":"mdi-arrow-up", }}}, "receive":{ "direction": "in", "counterparty_mappings": { "default": { "label":"receive", "icon":"mdi-arrow-down", "color":"green" }}}, "fee":{ "direction": "out", "counterparty_mappings": { "default": { "label":"fee", "icon":"mdi-account-cash", }, "gas": { "label":"gas fee", "icon":"mdi-fire", }}}, "gas":{ "label":"gas_fee", "icon":"mdi-fire", }, "receive":{ "label":"receive", "icon":"mdi-arrow-down", "color":"green" } } } }
- Response JSON Object:
global_mappings (object) – keys of this object are the history event types names and values are mappings of subtypes’ names to the
EventCategorymapping. Each mapping is either a simple {“default”: “send”}, or a different one depending on specific string values. Such as “exchange”. At the moment the only such possible values are “default” and “exchange”.type_mappings (object) – the keys of this mapping are entry types and it contains the combinations of event type and subtype that would overwrite the information in
global_mappingsonly for that entry type.per_protocol_mappings (object) – same as global_mappings but contains specific mappings per chain and protocol.
event_category_details (object) – This is a mapping of
EventCategoryto its direction and mapping of counterparty to details. For all theEventCategoryDetailsmapping there is a"default"key mapping to the default details. For some exceptions there is also other keys which are counterparties. Such as for spend/fee and counterparty gas.label (string) – Label to show in the frontend for the event type.
icon (string) – Icon to be used by the frontend for this event type.
color[optional] (string) – Optional color to apply to the icon
- Resjon object accounting_events_icons:
Mapping of accounting event type to its corresponding icon name.
- Status Codes:
200 OK – Information was correctly generated
500 Internal Server Error – Internal rotki error
Getting all available counterparties
- GET /api/(version)/history/events/counterparties
Doing a GET on this endpoint will return information for all the counterparties used for decoding events in the backend.
Example Request
http
GET /history/events/counterparties HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/history/events/counterparties
wget
wget -S -O- http://localhost:5042/history/events/counterparties
httpie
http http://localhost:5042/history/events/counterpartiespython-requests
requests.get('http://localhost:5042/history/events/counterparties')
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result":[ { "identifier":"1inch-v1", "label":"1inch", "image":"1inch.svg" }, { "identifier":"1inch-v2", "label":"1inch", "image":"1inch.svg" }, { "identifier":"gas", "label":"gas", "icon":"lu-flame" }, { "identifier":"hedgey", "label":"Hedgey", "image":"hedgey_dark.svg", "darkmode_image":"hedgey_light.svg" } ] }
- Response JSON Object:
identifier (string) – value used by the backend to represent the counterparty.
label (string) – Name displayed in the frontend.
image (string) – Optional. Relative path to the counterparty image. To be used mainly in light mode
darkmode_image (string) – Optional. Relative path to the counterparty image to be used for dark mode.
icon (string) – Optional. If given then this means the counterparty has no image but uses an icon from the icon set.
- Status Codes:
200 OK – Information was correctly generated
500 Internal Server Error – Internal rotki error
Get all valid locations
- GET /api/(version)/locations/all
Doing a GET on this endpoint will return all the possible location values.
Example Request
http
GET /locations/all HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/locations/all
wget
wget -S -O- http://localhost:5042/locations/all
httpie
http http://localhost:5042/locations/allpython-requests
requests.get('http://localhost:5042/locations/all')
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result":{ "locations": { "ethereum": {"image": "ethereum.svg"}, "optimism": {"image": "optimism.svg"}, "ftx": {"image": "ftx.svg", "is_exchange": true}, "kraken": { "image": "kraken.svg", "exchange_detail": { "is_exchange_with_key": true } }, "kucoin": { "image": "kucoin.svg", "exchange_detail": { "is_exchange_with_key": true, "is_exchange_with_passphrase": true } }, "bitpanda": { "image": "bitpanda.svg", "exchange_detail": { "is_exchange_with_key": true, "is_exchange_without_api_secret": true } "cryptocom": { "image": "crypto_com.svg", "exchange_detail": { "is_exchange_with_key": true, "experimental": true } }, "external": {"icon": "mdi-book"} } }
- Response JSON Object:
locations (list[string]) – A mapping of locations to their details. Can contain image or icon depending on whether a known image should be used or an icon from the icon set. Additionally, it can contain a display_name if a special name needs to be used. If the location is an exchange, it may also include an is_exchange key, or an exchange_details object if the location has more details for the exchange data. The exchange_details object can contain is_exchange_with_key for exchanges requiring an API key, is_exchange_with_passphrase for exchanges needing an API key and passphrase, and is_exchange_without_api_secret for exchanges that do not require an API secret key, all within the exchange_detail object. If the exchange implementation is experimenta then the experimental key will exist and be set to true.
- Status Codes:
200 OK – Information was correctly returned
500 Internal Server Error – Internal rotki error
Refresh protocol data
- GET /api/(version)/protocols/data/refresh
Doing a GET on this endpoint will return the list of protocols that have caches and can be used by this endpoint.
Example Request
http
GET /protocols/data/refresh HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/protocols/data/refresh
wget
wget -S -O- http://localhost:5042/protocols/data/refresh
httpie
http http://localhost:5042/protocols/data/refreshpython-requests
requests.get('http://localhost:5042/protocols/data/refresh')
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": ["curve", "velodrome", "aerodrome", "yearn", "maker", "aave", "convex", "gearbox", "spark", "balancer_v1", "balancer_v2", "balancer_v3", "eth_withdrawals", "eth_blocks", "eth_validators_data", "merkl", "beefy_finance", "customized_events"], "message": "" }
- Response JSON Object:
result (list[string]) – Values that can be used in this endpoint.
- Status Codes:
200 OK – List queried correctly.
500 Internal Server Error – Internal rotki error
- POST /api/(version)/protocols/data/refresh
Doing a POST on this endpoint will refresh the data for the selected protocol.
Note
This endpoint can also be queried asynchronously by using
"async_query": true.Example Request
http
POST /protocols/data/refresh HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "cache_protocol": "curve" }
curl
curl -i -X POST http://localhost:5042/protocols/data/refresh --data-raw 'Content-Type: application/json;charset=UTF-8 { "cache_protocol": "curve" }'
wget
wget -S -O- http://localhost:5042/protocols/data/refresh --post-data='Content-Type: application/json;charset=UTF-8 { "cache_protocol": "curve" }'
httpie
echo 'Content-Type: application/json;charset=UTF-8 { "cache_protocol": "curve" }' | http POST http://localhost:5042/protocols/data/refresh
python-requests
requests.post('http://localhost:5042/protocols/data/refresh', data='Content-Type: application/json;charset=UTF-8\r\n\n\r\n\n{\r\n\n "cache_protocol": "curve"\r\n\n}')
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – Is true if the cache was refreshed successfully.
- Status Codes:
200 OK – Protocol data was correctly refreshed
409 Conflict – An issue during refreshing protocol data occurred
500 Internal Server Error – Internal rotki error
Getting Metadata For Airdrops
- GET /api/(version)/airdrops/metadata
Doing a GET on this endpoint will return metadata for all the airdrops that are supported by rotki.
Example Request
http
GET /airdrops/metadata HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/airdrops/metadata
wget
wget -S -O- http://localhost:5042/airdrops/metadata
httpie
http http://localhost:5042/airdrops/metadatapython-requests
requests.get('http://localhost:5042/airdrops/metadata')
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result":[ { "identifier": "uniswap", "name": "Uniswap", "icon": "uniswap.svg", "icon_url": "https://raw.githubusercontent.com/rotki/data/main/airdrops/icons/uniswap.svg" }, { "identifier": "1inch", "name": "1inch", "icon": "1inch.svg" } ], "message": "", }
- Response JSON Object:
identifier (string) – The identifier of the airdrop.
name (string) – The name of the airdrop.
icon (string) – The icon of the airdrop.
- Status Codes:
200 OK – Information was correctly returned
500 Internal Server Error – Internal rotki error
502 Bad Gateway – Failed to fetch airdrop metadata from rotki’s data repository.
Getting Metadata For Defi Protocols
- GET /api/(version)/defi/metadata
Doing a GET on this endpoint will return metadata for all the defi protocols that are supported by rotki.
Example Request
http
GET /defi/metadata HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/defi/metadata
wget
wget -S -O- http://localhost:5042/defi/metadata
httpie
http http://localhost:5042/defi/metadatapython-requests
requests.get('http://localhost:5042/defi/metadata')
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result":[ { "identifier": "uniswapv1", "name": "Uniswap V1", "icon": "uniswap.svg" }, { "identifier": "oneinch_liquidity", "name": "1inch Liquidity Protocol", "icon": "1inch.svg" } ], "message": "" }
- Response JSON Object:
identifier (string) – The identifier of the defi protocol.
name (string) – The name of the defi protocol.
icon (string) – The icon of the defi protocol.
- Status Codes:
200 OK – Information was correctly returned
500 Internal Server Error – Internal rotki error
Dealing with skipped external events
- GET /api/(version)/history/skipped_external_events
Doing a GET on this endpoint will return a summary of skipped external events in the DB.
Example Request
http
GET /api/1/history/skipped_external_events HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/history/skipped_external_events
wget
wget -S -O- http://localhost:5042/api/1/history/skipped_external_events
httpie
http http://localhost:5042/api/1/history/skipped_external_eventspython-requests
requests.get('http://localhost:5042/api/1/history/skipped_external_events')
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": { "locations": { "kraken": 5, "binance": 3 }, "total": 8 }, "message": "" }
- Response JSON Object:
result (bool) – The mapping of skipped event locations to the number of skipped events per location.
- Status Codes:
200 OK – All okay
500 Internal Server Error – Internal rotki error
- PUT /api/(version)/history/skipped_external_events
- PATCH /api/(version)/history/skipped_external_events
Doing a PUT on this endpoint with a filepath path as argument will export all skipped external events in a csv to that directory. Doing a PATCH on this endpoint will download all skipped external events in a csv file.
Example Request:
http
PUT /api/1/history/skipped_external_events HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"directory_path": "/home/username/path/to/csvdir"}
curl
curl -i -X PUT http://localhost:5042/api/1/history/skipped_external_events -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"directory_path": "/home/username/path/to/csvdir"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/history/skipped_external_events --header="Content-Type: application/json;charset=UTF-8" --body-data='{"directory_path": "/home/username/path/to/csvdir"}'
httpie
echo '{ "directory_path": "/home/username/path/to/csvdir" }' | http PUT http://localhost:5042/api/1/history/skipped_external_events Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/history/skipped_external_events', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'directory_path': '/home/username/path/to/csvdir'})
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – Boolean denoting success or failure.
- Status Codes:
200 OK – File were exported successfully
400 Bad Request – Provided JSON is in some way malformed or given string is not a directory.
404 Not Found – No file was found when trying to export the events in CSV.
401 Unauthorized – No user is currently logged in.
409 Conflict – No permissions to write in the given directory. Check error message.
500 Internal Server Error – Internal rotki error.
- POST /api/(version)/history/skipped_external_events
Doing a POST on this endpoint will try to reprocess all skipped external events saved in the DB.
Example Request
http
POST /api/1/history/skipped_external_events HTTP/1.1 Host: localhost:5042
curl
curl -i -X POST http://localhost:5042/api/1/history/skipped_external_events
wget
wget -S -O- http://localhost:5042/api/1/history/skipped_external_events
httpie
http POST http://localhost:5042/api/1/history/skipped_external_events
python-requests
requests.post('http://localhost:5042/api/1/history/skipped_external_events')
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": {"total": 10, "successful": 5}, "message": "" }
- Response JSON Object:
total (int) – The total number of skipped events that we tried to reprocess
successful (int) – The number of skipped events that we reprocessed successfully and were thus deleted from the skipped events table.
- Status Codes:
200 OK – Reprocessing went fine.
409 Conflict – An issue occurred during reprocessing
500 Internal Server Error – Internal rotki error
Managing custom accounting rules
- POST /api/(version)/accounting/rules
Doing a POST on this endpoint will allow querying the accounting rules by a list of possible values. This endpoint allows pagination.
Example Request
http
POST /api/1/accounting/rules HTTP/1.1 Host: localhost:5042 { "event_types":["deposit", "withdrawal"], "counterparties":["uniswap", "compound"] }
curl
curl -i -X POST http://localhost:5042/api/1/accounting/rules --data-raw '{ "event_types":["deposit", "withdrawal"], "counterparties":["uniswap", "compound"] }'
wget
wget -S -O- http://localhost:5042/api/1/accounting/rules --post-data='{ "event_types":["deposit", "withdrawal"], "counterparties":["uniswap", "compound"] }'
httpie
echo '{ "event_types":["deposit", "withdrawal"], "counterparties":["uniswap", "compound"] }' | http POST http://localhost:5042/api/1/accounting/rules
python-requests
requests.post('http://localhost:5042/api/1/accounting/rules', data='{\r\n\n "event_types":["deposit", "withdrawal"],\r\n\n "counterparties":["uniswap", "compound"]\r\n\n}')
- Request JSON Array of Objects:
event_types (optional[array[string]]) – List of possible event types to use while filtering.
event_subtypes (optional[array[string]]) – List of possible event subtypes to use while filtering.
counterparties (optional[array[string]]) – List of possible counterparties to use while filtering. Instead of a string a null value can also be given to mean counterparty being None.
identifiers (optional[array[int]]) – List of rule identifiers to filter by. Only rules with these identifiers will be returned.
custom_rule_handling (optional[string]) – Controls filtering of rules by event ID association. Possible values: ‘all’ (default - no filtering), ‘only’ (only rules with event IDs), ‘exclude’ (only rules without event IDs). Cannot be used together with event_ids when set to ‘only’ or ‘exclude’.
event_ids (optional[array[int]]) – List of specific group identifiers to filter accounting rules by. Only rules that apply to these specific events will be returned. Cannot be used together with custom_rule_handling when it’s set to ‘only’ or ‘exclude’.
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result":{ "entries":[{ "taxable":false, "count_cost_basis_pnl": {"value": true}, "count_entire_amount_spend":{"value": false}, "accounting_treatment":null, "identifier":2, "event_ids": [3234554], "event_type":"staking", "event_subtype":"spend", "counterparty":"compound" }], "entries_found":1, "entries_total":1, "entries_limit":-1 }, "message":"" }
- Response JSON Object:
entries (array) – List of all the rules with their identifier. For the meaning of each field refer to Request JSON Array of Objects
entries_found (int) – The number of entries found for the current filter. Ignores pagination.
entries_limit (int) – The limit of entries if free version. Always -1 for this endpoint.
entries_total (int) – The number of total entries ignoring all filters.
- Status Codes:
200 OK – All okay
409 Conflict – Bad set of filters provided
500 Internal Server Error – Internal rotki error
- PUT /api/(version)/accounting/rules
Doing a PUT request on this endpoint will allow to create a new accounting rule.
Note
If
event_idsid provided, those event IDs are first removed from any existing rules. They are then either added to an existing event-specific rule with matching settings or a new event-specific rule is created.Example Request
http
PUT /api/1/accounting/rules HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "taxable": {"value": true}, "count_entire_amount_spend":{"value": false, "linked_setting": "include_crypto2crypto"}, "count_cost_basis_pnl":{"value": true}, "event_type":"staking", "event_subtype":"spend", "event_ids": [12345], "counterparty": "compound", "accounting_treatment":"swap" }
curl
curl -i -X PUT http://localhost:5042/api/1/accounting/rules -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"accounting_treatment": "swap", "count_cost_basis_pnl": {"value": true}, "count_entire_amount_spend": {"linked_setting": "include_crypto2crypto", "value": false}, "counterparty": "compound", "event_ids": [12345], "event_subtype": "spend", "event_type": "staking", "taxable": {"value": true}}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/accounting/rules --header="Content-Type: application/json;charset=UTF-8" --body-data='{"accounting_treatment": "swap", "count_cost_basis_pnl": {"value": true}, "count_entire_amount_spend": {"linked_setting": "include_crypto2crypto", "value": false}, "counterparty": "compound", "event_ids": [12345], "event_subtype": "spend", "event_type": "staking", "taxable": {"value": true}}'
httpie
echo '{ "accounting_treatment": "swap", "count_cost_basis_pnl": { "value": true }, "count_entire_amount_spend": { "linked_setting": "include_crypto2crypto", "value": false }, "counterparty": "compound", "event_ids": [ 12345 ], "event_subtype": "spend", "event_type": "staking", "taxable": { "value": true } }' | http PUT http://localhost:5042/api/1/accounting/rules Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/accounting/rules', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'accounting_treatment': 'swap', 'count_cost_basis_pnl': {'value': True}, 'count_entire_amount_spend': {'linked_setting': 'include_crypto2crypto', 'value': False}, 'counterparty': 'compound', 'event_ids': [12345], 'event_subtype': 'spend', 'event_type': 'staking', 'taxable': {'value': True}})
- Request JSON Array of Objects:
taxable (object) – If
valueis set totrueif the event should be considered as taxable. Allows to link the property to an accounting setting.count_entire_amount_spend (object) – If
valueis set totruethen the entire amount is counted as a spend. Which means an expense (negative pnl). Allows to link the property to an accounting setting.count_cost_basis_pnl (object) – If
valueis set totruethen we also count any profit/loss the asset may have had compared to when it was acquired. Allows to link the property to an accounting setting.linked_setting (string) – If it takes any value this property will take the value of the provided setting. Can be either include_gas_costs or include_crypto2crypto.
event_type (string) – The event type that the rule targets.
event_subtype (string) – The event subtype that the rule targets.
counterparty (optional[string]) – The counterparty that the rule targets.
accounting_treatment – Special rule to handle pairs of events. Can be
swaporswap with feeevent_ids (optional[list[int]]) – The identifiers (integer IDs) for a specified group of events. Only required when the rule should apply to certain events.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – Boolean denoting success or failure.
- Status Codes:
200 OK – Entry correctly stored.
401 Unauthorized – No user is currently logged in.
409 Conflict – Failed to validate the data. Combination of type, subtype and counterparty already exists.
500 Internal Server Error – Internal rotki error.
- PATCH /api/(version)/accounting/rules
Doing a PATCH on this endpoint allows to edit an accounting rule. Takes the same parameters as the PUT verb plus the identifier of the entry being updated.
Example Request:
http
PATCH /api/1/accounting/rules HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "identifier": 1, "taxable": true, "count_entire_amount_spend": {"value": false}, "count_cost_basis_pnl":{"value": true}, "event_type": "staking", "event_subtype": "spend", "counterparty": "uniswap", "accounting_treatment": "swap" }
curl
curl -i -X PATCH http://localhost:5042/api/1/accounting/rules -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"accounting_treatment": "swap", "count_cost_basis_pnl": {"value": true}, "count_entire_amount_spend": {"value": false}, "counterparty": "uniswap", "event_subtype": "spend", "event_type": "staking", "identifier": 1, "taxable": true}'
wget
wget -S -O- --method=PATCH http://localhost:5042/api/1/accounting/rules --header="Content-Type: application/json;charset=UTF-8" --body-data='{"accounting_treatment": "swap", "count_cost_basis_pnl": {"value": true}, "count_entire_amount_spend": {"value": false}, "counterparty": "uniswap", "event_subtype": "spend", "event_type": "staking", "identifier": 1, "taxable": true}'
httpie
echo '{ "accounting_treatment": "swap", "count_cost_basis_pnl": { "value": true }, "count_entire_amount_spend": { "value": false }, "counterparty": "uniswap", "event_subtype": "spend", "event_type": "staking", "identifier": 1, "taxable": true }' | http PATCH http://localhost:5042/api/1/accounting/rules Content-Type:"application/json;charset=UTF-8"
python-requests
requests.patch('http://localhost:5042/api/1/accounting/rules', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'accounting_treatment': 'swap', 'count_cost_basis_pnl': {'value': True}, 'count_entire_amount_spend': {'value': False}, 'counterparty': 'uniswap', 'event_subtype': 'spend', 'event_type': 'staking', 'identifier': 1, 'taxable': True})
- Request JSON Array of Objects:
identifier (integer) – The id of the rule being updated.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – Boolean denoting success or failure.
- Status Codes:
200 OK – Entry correctly updated.
401 Unauthorized – No user is currently logged in.
409 Conflict – Failed to validate the data. Entry doesn’t exist. Combination of type, subtype and counterparty already exists.
500 Internal Server Error – Internal rotki error.
- DELETE /api/(version)/accounting/rules
Doing a DELETE on this endpoint allows deleting a rule by their identifier.
Example Request:
http
PATCH /api/1/accounting/rules HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "identifier": 2 }
curl
curl -i -X PATCH http://localhost:5042/api/1/accounting/rules -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"identifier": 2}'
wget
wget -S -O- --method=PATCH http://localhost:5042/api/1/accounting/rules --header="Content-Type: application/json;charset=UTF-8" --body-data='{"identifier": 2}'
httpie
echo '{ "identifier": 2 }' | http PATCH http://localhost:5042/api/1/accounting/rules Content-Type:"application/json;charset=UTF-8"
python-requests
requests.patch('http://localhost:5042/api/1/accounting/rules', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'identifier': 2})
- Request JSON Array of Objects:
identifier (integer) – The identifier of the rule that will be deleted
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – Boolean denoting success or failure.
- Status Codes:
200 OK – Entry correctly deleted.
401 Unauthorized – No user is currently logged in.
409 Conflict – Failed to validate the data. Or entry doesn’t exist.
500 Internal Server Error – Internal rotki error.
Accounting rules linkable properties
- GET /api/(version)/accounting/rules/info
Doing a GET on this endpoint will return a mapping of the properties that can be linked for accounting rules.
Example Request
http
GET /api/1/accounting/rules/info HTTP/1.1 Host: localhost:5042
curl
curl -i -X GET http://localhost:5042/api/1/accounting/rules/info
wget
wget -S -O- http://localhost:5042/api/1/accounting/rules/info
httpie
http http://localhost:5042/api/1/accounting/rules/infopython-requests
requests.get('http://localhost:5042/api/1/accounting/rules/info')
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": { "count_entire_amount_spend":["include_gas_costs", "include_crypto2crypto"], "count_cost_basis_pnl":["include_gas_costs", "include_crypto2crypto"] }, "message": "" }
- Response JSON Object:
result (object) – A mapping of the properties that can be linked to the list of settings configurations that can be used for that field.
- Status Codes:
200 OK – All okay
500 Internal Server Error – Internal rotki error
Solving conflicts in accounting rules
- POST /api/(version)/accounting/rules/conflicts
Doing a POST on this endpoint will return the list of conflicts for accounting rules providing the local version and remote version to compare them. It allows pagination by
limitandoffset.Example Request
http
POST /api/1/accounting/rules/conflicts HTTP/1.1 Host: localhost:5042
curl
curl -i -X POST http://localhost:5042/api/1/accounting/rules/conflicts
wget
wget -S -O- http://localhost:5042/api/1/accounting/rules/conflicts
httpie
http POST http://localhost:5042/api/1/accounting/rules/conflicts
python-requests
requests.post('http://localhost:5042/api/1/accounting/rules/conflicts')
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result":{ "entries":[ { "local_id": 1, "local_data":{ "taxable":{ "value":true, "linked_setting":"include_crypto2crypto" }, "count_cost_basis_pnl":{ "value":true }, "count_entire_amount_spend":{ "value":false, "linked_setting":"include_crypto2crypto" }, "accounting_treatment":"None", "event_type":"spend", "event_subtype":"return wrapped", "counterparty":"compound" }, "remote_data":{ "taxable":{ "value":false }, "count_cost_basis_pnl":{ "value":false }, "count_entire_amount_spend":{ "value":false }, "accounting_treatment":"swap", "event_type":"spend", "event_subtype":"return wrapped", "counterparty":"compound" } } ], "entries_found":1, "entries_total":1, "entries_limit":-1 }, "message":"" }
- Response JSON Object:
result (object) – An object, mapping identifiers to the local and remote version of the conflict.
- Status Codes:
200 OK – All okay
401 Unauthorized – No user is currently logged in
500 Internal Server Error – Internal rotki error
- PATCH /api/(version)/accounting/rules/conflicts
Doing a PATCH on this endpoint will apply a conflict resolution method for the selected accounting rules.
Example Request
Note
Either
conflictsorsolve_all_usingneed to be provided but not both together.http
PATH /api/1/accounting/rules/conflicts HTTP/1.1 Host: localhost:5042 {"conflicts": [{"local_id": "1", "solve_using": "remote"}]}
curl
curl -i -X PATH http://localhost:5042/api/1/accounting/rules/conflicts --data-raw '{"conflicts": [{"local_id": "1", "solve_using": "remote"}]}'
wget
wget -S -O- --method=PATH http://localhost:5042/api/1/accounting/rules/conflicts --body-data='{"conflicts": [{"local_id": "1", "solve_using": "remote"}]}'
httpie
echo '{"conflicts": [{"local_id": "1", "solve_using": "remote"}]}' | http PATH http://localhost:5042/api/1/accounting/rules/conflicts
python-requests
requests.path('http://localhost:5042/api/1/accounting/rules/conflicts', data='{"conflicts": [{"local_id": "1", "solve_using": "remote"}]}')
- Request JSON Array of Objects:
local_id (string) – The identifier of the rule that will be updated.
solve_using (string) – Either
remoteorlocal.solve_all_using (string) – Either
remoteorlocal. If this is given it should be the only key in the request.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – Boolean denoting success or failure.
- Status Codes:
200 OK – Conflicts resolved successfully.
401 Unauthorized – No user is currently logged in.
409 Conflict – Couldn’t find the rule locally.
500 Internal Server Error – Internal rotki error.
Managing calendar entries
- POST /api/(version)/calendar
Doing a POST on this endpoint will allow querying the calendar entries by some of their attributes.
Example Request
http
POST /api/(version)/calendar HTTP/1.1 Host: localhost:5042 { "from_timestamp": 1977652400, "to_timestamp": 1977652511, "accounts": [{"address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12"}, {"address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "blockchain": "gnosis"}] "counterparty": 'ens' }
curl
curl -i -X POST 'http://localhost:5042/api/(version)/calendar' --data-raw '{ "from_timestamp": 1977652400, "to_timestamp": 1977652511, "accounts": [{"address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12"}, {"address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "blockchain": "gnosis"}] "counterparty": 'ens' }'
wget
wget -S -O- 'http://localhost:5042/api/(version)/calendar' --post-data='{ "from_timestamp": 1977652400, "to_timestamp": 1977652511, "accounts": [{"address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12"}, {"address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "blockchain": "gnosis"}] "counterparty": 'ens' }'
httpie
echo '{ "from_timestamp": 1977652400, "to_timestamp": 1977652511, "accounts": [{"address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12"}, {"address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "blockchain": "gnosis"}] "counterparty": '"'"'ens'"'"' }' | http POST 'http://localhost:5042/api/(version)/calendar'
python-requests
requests.post('http://localhost:5042/api/(version)/calendar', data='{\r\n\n "from_timestamp": 1977652400,\r\n\n "to_timestamp": 1977652511,\r\n\n "accounts": [{"address": "0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12"}, {"address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "blockchain": "gnosis"}]\r\n\n "counterparty": \'ens\'\r\n\n}')
- Request JSON Array of Objects:
accounts (optional[list[object]]) – List of addresses + their chain linked to the calendar events. The blockchain part can be omitted and it will return information for the address in all the chains.
identifiers (optional[integer]) – List of identifiers linked to the calendar events.
- Request JSON Object:
counterparty (optional[string]) – Counterparty used to filter the events.
name (optional[string]) – Substring used to filter for in the
nameattribute when querying calendar events.description (optional[string]) – Substring used to filter for in the
descriptionattribute when querying calendar events.
- Response JSON Object:
from_timestamp (int) – The earliest timestamp of the events queried.
to_timestamp (int) – The latest timestamp of the events queried.
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result":{ "entries":[ { "identifier":1, "name":"ENS renewal", "description":"Renew yabir.eth extended", "counterparty":"ENS", "timestamp":1977652411, "address":"0xc37b40ABdB939635068d3c5f13E7faF686F03B65" }, { "identifier":2, "name":"CRV unlock", "description":"Unlock date for CRV", "counterparty":"CURVE", "timestamp":1851422011, "address":"0x2B888954421b424C5D3D9Ce9bB67c9bD47537d12" } ], "entries_found":2, "entries_total":2, "entries_limit":-1 } }
- Response JSON Object:
entries (array) – List of all the calendar events with their identifier.
entries_found (int) – The number of entries found for the current filter. Ignores pagination.
entries_limit (int) – The limit of entries if free version. Always -1 for this endpoint.
entries_total (int) – The number of total entries ignoring all filters.
- Status Codes:
200 OK – All okay
401 Unauthorized – No user is currently logged in.
500 Internal Server Error – Internal rotki error
- PUT /api/(version)/calendar
Doing a PUT request on this endpoint will allow to create a new calendar entry.
Example Request
http
PUT /api/(version)/calendar HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "timestamp":1869737344, "name":"ENS renewal", "description":"Renew yabir.eth", "counterparty":"ENS", "address":"0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "color": "ffffff" }
curl
curl -i -X PUT 'http://localhost:5042/api/(version)/calendar' -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "color": "ffffff", "counterparty": "ENS", "description": "Renew yabir.eth", "name": "ENS renewal", "timestamp": 1869737344}'
wget
wget -S -O- --method=PUT 'http://localhost:5042/api/(version)/calendar' --header="Content-Type: application/json;charset=UTF-8" --body-data='{"address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "color": "ffffff", "counterparty": "ENS", "description": "Renew yabir.eth", "name": "ENS renewal", "timestamp": 1869737344}'
httpie
echo '{ "address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "color": "ffffff", "counterparty": "ENS", "description": "Renew yabir.eth", "name": "ENS renewal", "timestamp": 1869737344 }' | http PUT 'http://localhost:5042/api/(version)/calendar' Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/(version)/calendar', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'address': '0xc37b40ABdB939635068d3c5f13E7faF686F03B65', 'color': 'ffffff', 'counterparty': 'ENS', 'description': 'Renew yabir.eth', 'name': 'ENS renewal', 'timestamp': 1869737344})
- Response JSON Object:
timestamp (integer) – Timestamp of the event in the calendar.
name (string) – Name of the event.
description (optional[string]) – Longer description given to the event.
counterparty (string) – A protocol counterparty given to the calendar event. Missing if it doesn’t have a value.
address (string) – Address linked to the calendar event. Missing if it doesn’t have a value.
color (string) – The color to render the event in the frontend with. Missing if it doesn’t have a value.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": {"entry_id": 1}, "message": "" }
- Response JSON Object:
result (object) – object with the identifier of the calendar entry created.
- Status Codes:
200 OK – Entry correctly stored.
401 Unauthorized – No user is currently logged in.
409 Conflict – Failed to validate the data.
500 Internal Server Error – Internal rotki error.
- PATCH /api/(version)/calendar
Doing a PATCH on this endpoint allows to edit a calendar entry. Takes the same parameters as the PUT verb plus the identifier of the entry being updated.
Example Request:
http
PATCH /api/(version)/calendar HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "identifier": 1, "timestamp":1869737344, "name":"ENS renewal", "description":"Renew yabir.eth", "counterparty":"ENS", "address":"0xc37b40ABdB939635068d3c5f13E7faF686F03B65" }
curl
curl -i -X PATCH 'http://localhost:5042/api/(version)/calendar' -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "counterparty": "ENS", "description": "Renew yabir.eth", "identifier": 1, "name": "ENS renewal", "timestamp": 1869737344}'
wget
wget -S -O- --method=PATCH 'http://localhost:5042/api/(version)/calendar' --header="Content-Type: application/json;charset=UTF-8" --body-data='{"address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "counterparty": "ENS", "description": "Renew yabir.eth", "identifier": 1, "name": "ENS renewal", "timestamp": 1869737344}'
httpie
echo '{ "address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "counterparty": "ENS", "description": "Renew yabir.eth", "identifier": 1, "name": "ENS renewal", "timestamp": 1869737344 }' | http PATCH 'http://localhost:5042/api/(version)/calendar' Content-Type:"application/json;charset=UTF-8"
python-requests
requests.patch('http://localhost:5042/api/(version)/calendar', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'address': '0xc37b40ABdB939635068d3c5f13E7faF686F03B65', 'counterparty': 'ENS', 'description': 'Renew yabir.eth', 'identifier': 1, 'name': 'ENS renewal', 'timestamp': 1869737344})
- Request JSON Array of Objects:
identifier (integer) – The id of the event being updated.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": {"entry_id": 1}, "message": "" }
- Response JSON Object:
result (object) – object with the identifier of the calendar entry updated.
- Status Codes:
200 OK – Entry correctly updated.
401 Unauthorized – No user is currently logged in.
409 Conflict – Failed to validate the data. Event not found.
500 Internal Server Error – Internal rotki error.
- DELETE /api/(version)/calendar
Doing a DELETE on this endpoint allows deleting a calendar event by their identifier.
Example Request:
http
PATCH /api/(version)/calendar HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "identifier": 2 }
curl
curl -i -X PATCH 'http://localhost:5042/api/(version)/calendar' -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"identifier": 2}'
wget
wget -S -O- --method=PATCH 'http://localhost:5042/api/(version)/calendar' --header="Content-Type: application/json;charset=UTF-8" --body-data='{"identifier": 2}'
httpie
echo '{ "identifier": 2 }' | http PATCH 'http://localhost:5042/api/(version)/calendar' Content-Type:"application/json;charset=UTF-8"
python-requests
requests.patch('http://localhost:5042/api/(version)/calendar', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'identifier': 2})
- Request JSON Array of Objects:
identifier (integer) – The identifier of the event that will be deleted
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – Boolean denoting success or failure.
- Status Codes:
200 OK – Entry correctly deleted.
401 Unauthorized – No user is currently logged in.
409 Conflict – Failed to validate the data. Entry doesn’t exist.
500 Internal Server Error – Internal rotki error.
Managing calendar reminders
- POST /api/(version)/calendar/reminders
Doing a POST on this endpoint will allow querying the calendar reminders using the identifier of the associated calendar entry.
Example Request
http
POST /api/(version)/calendar/reminders HTTP/1.1 Host: localhost:5042 {"identifier": 1}
curl
curl -i -X POST 'http://localhost:5042/api/(version)/calendar/reminders' --data-raw '{"identifier": 1}'
wget
wget -S -O- 'http://localhost:5042/api/(version)/calendar/reminders' --post-data='{"identifier": 1}'
httpie
echo '{"identifier": 1}' | http POST 'http://localhost:5042/api/(version)/calendar/reminders'
python-requests
requests.post('http://localhost:5042/api/(version)/calendar/reminders', data='{"identifier": 1}')
- Response JSON Object:
identifier (int) – Identifier of the calendar entry linked to the reminder.
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result":{ "entries":[ { "identifier":1, "event_id": 1, "secs_before": 213234124, "acknowledged": true }, { "identifier":2, "event_id": 1, "secs_before": 2132341253, "acknowledged": false }, ] } }
- Response JSON Object:
entries (array) – List of all the calendar reminders linked to the provided calendar event.
- Status Codes:
200 OK – All okay
401 Unauthorized – No user is currently logged in.
500 Internal Server Error – Internal rotki error
- PUT /api/(version)/calendar/reminders
Doing a PUT request on this endpoint will allow to create new calendar reminder entries. If any of the entries fails to get added the key
failedwill be populated in the response.Example Request
http
PUT /api/(version)/calendar/reminders HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "reminders": [ {"secs_before": 1869737344, "event_id": 1}, {"secs_before": 1869737344, "event_id": 100} ] }
curl
curl -i -X PUT 'http://localhost:5042/api/(version)/calendar/reminders' -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"reminders": [{"secs_before": 1869737344, "event_id": 1}, {"secs_before": 1869737344, "event_id": 100}]}'
wget
wget -S -O- --method=PUT 'http://localhost:5042/api/(version)/calendar/reminders' --header="Content-Type: application/json;charset=UTF-8" --body-data='{"reminders": [{"secs_before": 1869737344, "event_id": 1}, {"secs_before": 1869737344, "event_id": 100}]}'
httpie
echo '{ "reminders": [ { "event_id": 1, "secs_before": 1869737344 }, { "event_id": 100, "secs_before": 1869737344 } ] }' | http PUT 'http://localhost:5042/api/(version)/calendar/reminders' Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/(version)/calendar/reminders', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'reminders': [{'secs_before': 1869737344, 'event_id': 1}, {'secs_before': 1869737344, 'event_id': 100}]})
- Response JSON Object:
secs_before (integer) – Seconds before the event timestamp to trigger a notification.
event_id (integer) – Identifier of a valid calendar entry.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": {"success": [1], "failed": [100]}, "message": "" }
- Response JSON Object:
result (object) – object with the ids of the events for which the reminders were created successfully and for which it failed. If none failed the failed key is not returned.
- Status Codes:
200 OK – Entry correctly stored.
401 Unauthorized – No user is currently logged in.
409 Conflict – Failed to validate the data.
500 Internal Server Error – Internal rotki error.
- PATCH /api/(version)/calendar/reminders
Doing a PATCH on this endpoint allows to edit a calendar reminder. Takes the same parameters as the PUT verb plus the identifier of the entry being updated.
Example Request:
http
PATCH /api/(version)/calendar HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "identifier": 1, "secs_before": 1869737344, "event_id": 1, "acknowledged": true }
curl
curl -i -X PATCH 'http://localhost:5042/api/(version)/calendar' -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"acknowledged": true, "event_id": 1, "identifier": 1, "secs_before": 1869737344}'
wget
wget -S -O- --method=PATCH 'http://localhost:5042/api/(version)/calendar' --header="Content-Type: application/json;charset=UTF-8" --body-data='{"acknowledged": true, "event_id": 1, "identifier": 1, "secs_before": 1869737344}'
httpie
echo '{ "acknowledged": true, "event_id": 1, "identifier": 1, "secs_before": 1869737344 }' | http PATCH 'http://localhost:5042/api/(version)/calendar' Content-Type:"application/json;charset=UTF-8"
python-requests
requests.patch('http://localhost:5042/api/(version)/calendar', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'acknowledged': True, 'event_id': 1, 'identifier': 1, 'secs_before': 1869737344})
- Request JSON Array of Objects:
identifier (integer) – The id of the event being updated.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": {"entry_id": 1}, "message": "" }
- Response JSON Object:
result (object) – object with the identifier of the calendar reminder updated.
- Status Codes:
200 OK – Entry correctly updated.
401 Unauthorized – No user is currently logged in.
409 Conflict – Failed to validate the data. Event not found.
500 Internal Server Error – Internal rotki error.
- DELETE /api/(version)/calendar/reminders
Doing a DELETE on this endpoint allows deleting a calendar reminder by their identifier.
Example Request:
http
PATCH /api/(version)/calendar/reminders HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "identifier": 2 }
curl
curl -i -X PATCH 'http://localhost:5042/api/(version)/calendar/reminders' -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"identifier": 2}'
wget
wget -S -O- --method=PATCH 'http://localhost:5042/api/(version)/calendar/reminders' --header="Content-Type: application/json;charset=UTF-8" --body-data='{"identifier": 2}'
httpie
echo '{ "identifier": 2 }' | http PATCH 'http://localhost:5042/api/(version)/calendar/reminders' Content-Type:"application/json;charset=UTF-8"
python-requests
requests.patch('http://localhost:5042/api/(version)/calendar/reminders', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'identifier': 2})
- Request JSON Array of Objects:
identifier (integer) – The identifier of the reminder that will be deleted
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (bool) – Boolean denoting success or failure.
- Status Codes:
200 OK – Entry correctly deleted.
401 Unauthorized – No user is currently logged in.
409 Conflict – Failed to validate the data. Entry doesn’t exist.
500 Internal Server Error – Internal rotki error.
- POST /api/(version)/statistics/events
Doing a POST on this endpoint will query basic events statistics from the user DB.
Example Request:
http
POST /api/(version)/statistics/events HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "from_timestamp": 1704067200, "to_timestamp": 1735689599 }
curl
curl -i -X POST 'http://localhost:5042/api/(version)/statistics/events' -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_timestamp": 1704067200, "to_timestamp": 1735689599}'
wget
wget -S -O- 'http://localhost:5042/api/(version)/statistics/events' --header="Content-Type: application/json;charset=UTF-8" --post-data='{"from_timestamp": 1704067200, "to_timestamp": 1735689599}'
httpie
echo '{ "from_timestamp": 1704067200, "to_timestamp": 1735689599 }' | http POST 'http://localhost:5042/api/(version)/statistics/events' Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/(version)/statistics/events', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_timestamp': 1704067200, 'to_timestamp': 1735689599})
- Request JSON Array of Objects:
from_timestamp (integer) – Start of the range used to query statistics. Defaults to 0.
to_timestamp (integer) – End of the range used to query statistics. Defaults to now.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "message": "", "result": { "eth_on_gas": "0.21760082633497774", "eth_on_gas_per_address": { "0x01471dB828Cfb96Dcf215c57a7a6493702031EC1": "0.21760082633497774", } "gnosis_max_payments_by_currency": { "AED": "36.0", "EUR": "120.17", "THB": "13615.25", "USD": "85.0" }, "top_days_by_number_of_transactions": [ { "amount": 5, "timestamp": 1716715671 } ], "trades_by_exchange": { "bybit": 4, "coinbase": 21, "kraken": 35 }, "transactions_per_protocol": [ { "protocol": "ens", "transactions": 1 } ], "transactions_per_chain": { "ARBITRUM_ONE": 1284, "BASE": 463, "ETHEREUM": 144, "GNOSIS": 1067, "OPTIMISM": 283, "POLYGON_POS": 186, "SCROLL": 17 }, "score": 1631 }, "status_code": 200 }
- Response JSON Object:
eth_on_gas (string) – Amount of ETH spent on gas.
eth_on_gas_per_address (object) – Amount of ETH spent on gas per address.
gnosis_max_payments_by_currency (object) – Object that maps currency symbol to the max amount paid in a single payments using that currency.
top_days_by_number_of_transactions (list) – list with the top 10 days with more EVM transactions. Sorted in descending order.
transactions_per_protocol (list) – Sorted list of per protocol interactions by number of transactions.
trades_by_exchange (object) – number of trades executed on every tracked exchange.
transactions_per_chain (object) – number of transactions that rotki tracks by chain for the user.
score (int) – Score assigned to the stats.
- Status Codes:
200 OK – Data queried correctly.
401 Unauthorized – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
Historical Balance Queries
- POST /api/(version)/balances/historical
Gets historical balance data at a specific timestamp, calculated from processing of historical events. If asset is provided, returns balance for that specific asset. Otherwise returns balances for all assets.
The response includes a
processing_requiredflag that indicates whether historical events exist but haven’t been processed yet. Ifprocessing_requiredis true, callPOST /tasks/triggerto trigger processing, then retry this endpoint.Filtering by
asset,location,location_labelandprotocolis applied before grouping. Whengroup_by_accountis true, the response returns separate records per matchinglocation,location_label,protocolandassetbucket. The entries order is not guaranteed and clients should not rely on it.Note
This endpoint can also be queried asynchronously by using
"async_query": true.Example Request (All Assets):
http
POST /api/(version)/balances/historical HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "timestamp": 1672531200 }curl
curl -i -X POST 'http://localhost:5042/api/(version)/balances/historical' -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"timestamp": 1672531200}'wget
wget -S -O- 'http://localhost:5042/api/(version)/balances/historical' --header="Content-Type: application/json;charset=UTF-8" --post-data='{"timestamp": 1672531200}'httpie
echo '{ "timestamp": 1672531200 }' | http POST 'http://localhost:5042/api/(version)/balances/historical' Content-Type:"application/json;charset=UTF-8"python-requests
requests.post('http://localhost:5042/api/(version)/balances/historical', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'timestamp': 1672531200})Example Request (Grouped by Account):
http
POST /api/(version)/balances/historical HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8
- {
“timestamp”: 1672531200, “group_by_account”: true
}
Example Request (Single Asset):
http
POST /api/(version)/balances/historical HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8
- {
“timestamp”: 1672531200, “asset”: “BTC”
}
Example Request (Filtered by Location):
http
POST /api/(version)/balances/historical HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8
- {
“timestamp”: 1672531200, “location”: “ethereum”
}
Example Request (Filtered by Location Label):
http
POST /api/(version)/balances/historical HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8
- {
“timestamp”: 1672531200, “location_label”: “0x1234567890AbcdEF1234567890aBcdef12345678”
}
Example Request (Filtered by Protocol):
http
POST /api/(version)/balances/historical HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8
- {
“timestamp”: 1672531200, “protocol”: “aave”
}
- reqjsonarr integer timestamp:
The timestamp to query the balance for
- reqjsonarr string asset:
(Optional) The asset identifier to query balance for. If not provided, returns balances for all assets.
- reqjsonarr string location:
(Optional) Filter balances by location (e.g., “ethereum”, “kraken”, “binance”). If not provided, returns balances across all locations.
- reqjsonarr string location_label:
(Optional) Filter balances by location label (e.g., a specific wallet address). If not provided, returns balances across all location labels.
- reqjsonarr string protocol:
(Optional) Filter balances by protocol (e.g., “aave”, “uniswap-v2”). If not provided, returns balances across all protocols.
- reqjsonarr boolean group_by_account:
(Optional, default false) If true, returns one record per location, location label, protocol and asset bucket instead of aggregating by asset.
Example Response (All Assets - data available):
HTTP/1.1 200 OK Content-Type: application/json { "message": "", "result": { "processing_required": false, "entries": { "BTC": "2.0", "ETH": "10.0" } }, "status_code": 200 }Example Response (Single Asset - data available):
HTTP/1.1 200 OK Content-Type: application/json
- {
“message”: “”, “result”: {
“processing_required”: false, “entries”: {
“BTC”: “2.0”
}
}, “status_code”: 200
}
Example Response (Grouped by Account - data available):
HTTP/1.1 200 OK Content-Type: application/json
- {
“message”: “”, “result”: {
“processing_required”: false, “entries”: [
- {
“location”: “ethereum”, “location_label”: “0x52908400098527886E0F7030069857D2E4169EE7”, “protocol”: null, “asset”: “ETH”, “amount”: “1.2”
}, {
“location”: “ethereum”, “location_label”: “0x8617E340B3D01FA5F11F306F4090FD50E238070D”, “protocol”: null, “asset”: “ETH”, “amount”: “0.8”
}, {
“location”: “ethereum”, “location_label”: “0x52908400098527886E0F7030069857D2E4169EE7”, “protocol”: “aave_v3”, “asset”: “eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48”, “amount”: “250.12”
}
]
}, “status_code”: 200
}
Example Response (processing required):
HTTP/1.1 200 OK Content-Type: application/json
- {
“message”: “”, “result”: {
“processing_required”: true
}, “status_code”: 200
}
- resjson bool processing_required:
Whether historical events exist but need processing. If true, call the processing endpoint and retry.
- resjson object entries:
(Only present when data is available and
group_by_accountis false) A mapping of asset identifiers to their amount as string.- resjson list entries:
(Only present when data is available and
group_by_accountis true) Records withlocation,location_label,protocol,assetandamount.- statuscode 200:
Historical balances returned
- statuscode 400:
Malformed query
- statuscode 403:
User does not have premium access
- statuscode 404:
No historical data found when
group_by_accountis true- statuscode 409:
User is not logged in
- statuscode 500:
Internal Rotki error
- POST /api/(version)/balances/historical/current
Gets current balances derived from processed historical events. This is equivalent to querying
/balances/historicalwith the current timestamp andgroup_by_accountset to true. Optionalasset,location,location_labelandprotocolfilters are applied before grouping, and omitted filters include all matching buckets. The entries order is not guaranteed and clients should not rely on it.Note
This endpoint can also be queried asynchronously by using
"async_query": true.Example Request:
http
POST /api/(version)/balances/historical/current HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8
- {
“asset”: “ETH”, “location”: “ethereum”
}
- reqjsonarr string asset:
(Optional) The asset identifier to query balance for.
- reqjsonarr string location:
(Optional) Filter balances by location.
- reqjsonarr string location_label:
(Optional) Filter balances by location label.
- reqjsonarr string protocol:
(Optional) Filter balances by protocol.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json
- {
“message”: “”, “result”: {
“processing_required”: false, “entries”: [
- {
“location”: “ethereum”, “location_label”: “0x1234567890AbcdEF1234567890aBcdef12345678”, “protocol”: null, “asset”: “ETH”, “amount”: “1.25”
}
]
}, “status_code”: 200
}
- resjson bool processing_required:
Whether historical events exist but need processing.
- resjson list entries:
(Only present when data is available) Records with
location,location_label,protocol,assetandamount.- statuscode 200:
Current derived historical balances returned
- statuscode 400:
Malformed query
- statuscode 403:
User does not have premium access
- statuscode 404:
No historical data found
- statuscode 409:
User is not logged in
- statuscode 500:
Internal Rotki error
- POST /api/(version)/balances/historical/asset/series
Gets historical balance series for one account and asset, grouped by matching location and protocol buckets. Each point is the bucket balance after the event at that timestamp. The entries order is not guaranteed and clients should not rely on it. The required selector is
location_labelandasset. Optionallocationandprotocolfilters only narrow that selector; if omitted, matching locations and protocols are returned as separate series records.Note
This endpoint can also be queried asynchronously by using
"async_query": true.Example Request:
http
POST /api/(version)/balances/historical/asset/series HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8
- {
“asset”: “ETH”, “location_label”: “0x1234567890AbcdEF1234567890aBcdef12345678”, “from_timestamp”: 1714521600, “to_timestamp”: 1714608000
}
- reqjsonarr string asset:
The asset identifier to query balance series for.
- reqjsonarr string location_label:
The account/address label to query.
- reqjsonarr integer from_timestamp:
(Optional, default 0) Inclusive start timestamp.
- reqjsonarr integer to_timestamp:
(Optional, default now) Inclusive end timestamp.
- reqjsonarr string location:
(Optional) Filter balances by location.
- reqjsonarr string protocol:
(Optional) Filter balances by protocol.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json
- {
“message”: “”, “result”: {
“processing_required”: false, “entries”: [
- {
“location”: “ethereum”, “location_label”: “0x1234567890AbcdEF1234567890aBcdef12345678”, “protocol”: null, “asset”: “ETH”, “times”: [1714521600, 1714608000], “values”: [“1.0”, “1.25”]
}
]
}, “status_code”: 200
}
- resjson bool processing_required:
Whether historical events exist but need processing.
- resjson list entries:
(Only present when data is available) Series records with
location,location_label,protocol,asset,timesandvalues.- statuscode 200:
Historical balance series returned
- statuscode 400:
Malformed query
- statuscode 403:
User does not have premium access
- statuscode 404:
No historical data found
- statuscode 409:
User is not logged in
- statuscode 500:
Internal Rotki error
- POST /api/(version)/balances/historical/asset
Gets historical balance amounts for a specific asset within a given time range, calculated from processing of historical events. It’s the total amount of asset held at each timestamp where a change occurred.
Note
If processing reveals a negative total balance amount at any point, the response will include amounts up to the event that caused the negative balance. No amounts after this point are returned.
Example Request:
http
POST /api/(version)/balances/historical/asset HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "asset": "BTC", "from_timestamp": 1672531200, "to_timestamp": 1675209600 }curl
curl -i -X POST 'http://localhost:5042/api/(version)/balances/historical/asset' -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"asset": "BTC", "from_timestamp": 1672531200, "to_timestamp": 1675209600}'wget
wget -S -O- 'http://localhost:5042/api/(version)/balances/historical/asset' --header="Content-Type: application/json;charset=UTF-8" --post-data='{"asset": "BTC", "from_timestamp": 1672531200, "to_timestamp": 1675209600}'httpie
echo '{ "asset": "BTC", "from_timestamp": 1672531200, "to_timestamp": 1675209600 }' | http POST 'http://localhost:5042/api/(version)/balances/historical/asset' Content-Type:"application/json;charset=UTF-8"python-requests
requests.post('http://localhost:5042/api/(version)/balances/historical/asset', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'asset': 'BTC', 'from_timestamp': 1672531200, 'to_timestamp': 1675209600})
- reqjsonarr string asset:
The asset identifier to query balance amounts for. This is mutually exclusive with the collection id
- reqjson integer collection_id:
Collection id to query balance amounts. This is mutually exclusive with the asset
- reqjsonarr integer from_timestamp:
The start timestamp of the query range
- reqjsonarr integer to_timestamp:
The end timestamp of the query range
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "message": "", "result": { "times": [1672531200, 1673308800, 1674518400], "values": ["1.5", "2.0", "1.8"] }, "status_code": 200 } :resjson list[integer] times: Timestamps of balance changes. :resjson list last_group_identifier: (Optional) A list containing [identifier, group_identifier] of the event that caused the negative balance amount. :resjson list[string] values: Net asset balance amount at each corresponding timestamp. :statuscode 200: Historical balances returned :statuscode 400: Malformed query :statuscode 401: User is not logged in :statuscode 403: User does not have premium access :statuscode 500: Internal Rotki error
- POST /api/(version)/balances/historical/netvalue
Retrieves daily asset balances within a specified time range.
Balances are aggregated per day, with timestamps normalized to midnight UTC. For queries within a single day, one entry is returned for that day.
Note
Returns raw asset balances. Price conversion and net value calculation are handled by the frontend.
Example Request:
http
POST /api/(version)/balances/historical/netvalue HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "from_timestamp": 1672531200, "to_timestamp": 1675209600 }curl
curl -i -X POST 'http://localhost:5042/api/(version)/balances/historical/netvalue' -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_timestamp": 1672531200, "to_timestamp": 1675209600}'wget
wget -S -O- 'http://localhost:5042/api/(version)/balances/historical/netvalue' --header="Content-Type: application/json;charset=UTF-8" --post-data='{"from_timestamp": 1672531200, "to_timestamp": 1675209600}'httpie
echo '{ "from_timestamp": 1672531200, "to_timestamp": 1675209600 }' | http POST 'http://localhost:5042/api/(version)/balances/historical/netvalue' Content-Type:"application/json;charset=UTF-8"python-requests
requests.post('http://localhost:5042/api/(version)/balances/historical/netvalue', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_timestamp': 1672531200, 'to_timestamp': 1675209600})
- reqjsonarr integer from_timestamp:
The start timestamp of the query range
- reqjsonarr integer to_timestamp:
The end timestamp of the query range
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "message": "", "result": { "processing_required": false, "times": [1672531200, 1673308800, 1674518400], "values": [ {"BTC": "2.0", "ETH": "10.0", "EUR": "20000"}, {"BTC": "2.2", "ETH": "10.0", "EUR": "16800"}, {"BTC": "1.7", "ETH": "9.8", "EUR": "17040"} ] }, "status_code": 200 }
- resjson bool processing_required:
True if events exist but haven’t been processed yet. False otherwise.
- resjson list[integer] times:
Timestamps (day start) at which balances were calculated. Only present when data is available.
- resjson list[object] values:
Asset balances at each corresponding timestamp. Each object maps asset identifiers to their balance amounts. Only present when data is available.
- statuscode 200:
Historical balances returned
- statuscode 400:
Malformed query
- statuscode 401:
User is not logged in
- statuscode 403:
User does not have premium access
- statuscode 500:
Internal Rotki error
- POST /api/(version)/balances/historical/asset/prices
- POST Gets historical price data for a specific asset within a given time range at specified intervals.
- POST Returns both the available prices and timestamps where price data is missing.
If
only_cache_periodis provided, the endpoint will only return prices found in cache within the specified time period around each timestamp. This is useful for scenarios requiring immediate responses, such as graph rendering.Note
This endpoint can also be queried asynchronously by using
"async_query": true.Example Request:
http
POST /api/(version)/balances/historical/asset/prices HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "asset": "BTC", "interval": 86400, "from_timestamp": 1672531200, "to_timestamp": 1675209600, "async_query": false }curl
curl -i -X POST 'http://localhost:5042/api/(version)/balances/historical/asset/prices' -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"asset": "BTC", "async_query": false, "from_timestamp": 1672531200, "interval": 86400, "to_timestamp": 1675209600}'wget
wget -S -O- 'http://localhost:5042/api/(version)/balances/historical/asset/prices' --header="Content-Type: application/json;charset=UTF-8" --post-data='{"asset": "BTC", "async_query": false, "from_timestamp": 1672531200, "interval": 86400, "to_timestamp": 1675209600}'httpie
echo '{ "asset": "BTC", "async_query": false, "from_timestamp": 1672531200, "interval": 86400, "to_timestamp": 1675209600 }' | http POST 'http://localhost:5042/api/(version)/balances/historical/asset/prices' Content-Type:"application/json;charset=UTF-8"python-requests
requests.post('http://localhost:5042/api/(version)/balances/historical/asset/prices', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'asset': 'BTC', 'async_query': False, 'from_timestamp': 1672531200, 'interval': 86400, 'to_timestamp': 1675209600})
- Request JSON Array of Objects:
asset (string) – The asset identifier to query prices for
interval (integer) – The time interval between price queries in seconds
from_timestamp (integer) – The start timestamp of the query range
to_timestamp (integer) – The end timestamp of the query range
exclude_timestamps (integer) – (Optional) List of timestamps to exclude from price queries.
async_query (boolean) – (Optional) Whether to process the request asynchronously
- Request JSON Object:
only_cache_period (integer) – (Optional) Time period in seconds around each timestamp to search for cached prices. If omitted, falls back to querying historical prices
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "message": "", "result": { "prices": { "1672531200": "20000", "1672617600": "19500", "1672704000": "19800" }, "no_prices_timestamps": [1672790400, 1672876800], "rate_limited_prices_timestamps": [1672790400, 1672876800] }, "status_code": 200 }
- resjson object prices:
Mapping of timestamps to price values in user’s profit currency
- resjson list[integer] no_prices_timestamps:
List of timestamps where price data was not available
- resjson list[integer] rate_limited_prices_timestamps:
List of timestamps where price queries were rate-limited by the data provider
- statuscode 200:
Historical prices returned
- statuscode 400:
Malformed query
- statuscode 401:
User is not logged in
- statuscode 500:
Internal Rotki error
- POST /api/(version)/balances/historical/onchain
Query the historical on-chain balance of an asset at a specific timestamp using archive nodes. Supports native tokens and ERC20 tokens on EVM chains.
Note
This endpoint requires an archive node to be available for the specified chain. This endpoint can also be queried asynchronously by using
"async_query": true.Example Request (Native Token):
http
POST /api/1/balances/historical/onchain HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "timestamp": 1609459200, "evm_chain": "ethereum", "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "asset": "ETH" }curl
curl -i -X POST http://localhost:5042/api/1/balances/historical/onchain -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "asset": "ETH", "evm_chain": "ethereum", "timestamp": 1609459200}'wget
wget -S -O- http://localhost:5042/api/1/balances/historical/onchain --header="Content-Type: application/json;charset=UTF-8" --post-data='{"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "asset": "ETH", "evm_chain": "ethereum", "timestamp": 1609459200}'httpie
echo '{ "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "asset": "ETH", "evm_chain": "ethereum", "timestamp": 1609459200 }' | http POST http://localhost:5042/api/1/balances/historical/onchain Content-Type:"application/json;charset=UTF-8"python-requests
requests.post('http://localhost:5042/api/1/balances/historical/onchain', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'address': '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', 'asset': 'ETH', 'evm_chain': 'ethereum', 'timestamp': 1609459200})Example Request (ERC20 Token):
http
POST /api/1/balances/historical/onchain HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "timestamp": 1609459200, "evm_chain": "ethereum", "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "asset": "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F" }curl
curl -i -X POST http://localhost:5042/api/1/balances/historical/onchain -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "asset": "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F", "evm_chain": "ethereum", "timestamp": 1609459200}'wget
wget -S -O- http://localhost:5042/api/1/balances/historical/onchain --header="Content-Type: application/json;charset=UTF-8" --post-data='{"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "asset": "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F", "evm_chain": "ethereum", "timestamp": 1609459200}'httpie
echo '{ "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "asset": "eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F", "evm_chain": "ethereum", "timestamp": 1609459200 }' | http POST http://localhost:5042/api/1/balances/historical/onchain Content-Type:"application/json;charset=UTF-8"python-requests
requests.post('http://localhost:5042/api/1/balances/historical/onchain', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'address': '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', 'asset': 'eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F', 'evm_chain': 'ethereum', 'timestamp': 1609459200})
- Request JSON Object:
timestamp (integer) – The Unix timestamp at which to query the balance
evm_chain (string) – The EVM chain name (e.g., “ethereum”, “optimism”, “arbitrum_one”)
address (string) – The EVM address to query the balance for
asset (string) – The asset identifier (native token or ERC20 token on the specified chain)
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "ETH": "8.275127966894157145" }, "message": "" }
- Response JSON Object:
result (object) – Mapping of asset identifier to balance amount as string
- Status Codes:
200 OK – Historical on-chain balance returned successfully
400 Bad Request – Invalid request (future timestamp, wrong chain for asset, invalid chain)
401 Unauthorized – User is not logged in
403 Forbidden – User does not have premium access
409 Conflict – No archive node available for the specified chain
502 Bad Gateway – Failed to query balance from archive node
Refetch transactions for a specific time period
- POST /api/(version)/blockchains/transactions/refetch
Doing a POST on the transactions refetch endpoint will force a re-query of transactions for the specified time period. This is useful to recover potentially missed transactions due to API issues or other temporary failures. Unlike normal transaction queries, this ignores query range checks.
Note
This endpoint can also be queried asynchronously by using
"async_query": trueExample Request:
http
POST /api/1/blockchains/transactions/refetch HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "async_query": false, "from_timestamp": 1640995200, "to_timestamp": 1672531200, "chain": "eth", "address": "0xb8553D9ee35dd23BB96fbd679E651B929821969B" }
curl
curl -i -X POST http://localhost:5042/api/1/blockchains/transactions/refetch -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0xb8553D9ee35dd23BB96fbd679E651B929821969B", "async_query": false, "chain": "eth", "from_timestamp": 1640995200, "to_timestamp": 1672531200}'
wget
wget -S -O- http://localhost:5042/api/1/blockchains/transactions/refetch --header="Content-Type: application/json;charset=UTF-8" --post-data='{"address": "0xb8553D9ee35dd23BB96fbd679E651B929821969B", "async_query": false, "chain": "eth", "from_timestamp": 1640995200, "to_timestamp": 1672531200}'
httpie
echo '{ "address": "0xb8553D9ee35dd23BB96fbd679E651B929821969B", "async_query": false, "chain": "eth", "from_timestamp": 1640995200, "to_timestamp": 1672531200 }' | http POST http://localhost:5042/api/1/blockchains/transactions/refetch Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/blockchains/transactions/refetch', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'address': '0xb8553D9ee35dd23BB96fbd679E651B929821969B', 'async_query': False, 'chain': 'eth', 'from_timestamp': 1640995200, 'to_timestamp': 1672531200})
- Request JSON Object:
async_query (bool) – If true, the query will be processed asynchronously.
from_timestamp (int) – Start of the time period to refetch transactions for.
to_timestamp (int) – End of the time period to refetch transactions for.
chain (string) – The chain to query (e.g., “eth”, “optimism”, “solana”). Only supports Solana and EVM chains.
address (string) – Optional. The address to query transactions for. If not provided, all tracked addresses for the specified chain will be queried.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "new_transactions_count": 2, "new_transactions": { "eth": [ "0x1234...", "0xabcd..." ] } }, "message": "" }
- Response JSON Object:
new_transactions_count (int) – The number of new transactions found and added to the database.
new_transactions (dict) – Mapping of chain to list of new transaction hashes.
new_transactions[chain] (list) – New transaction hashes for the chain (Solana uses the transaction signature).
- Status Codes:
200 OK – Transactions successfully refetched.
401 Unauthorized – User is not logged in.
400 Bad Request – Invalid parameters such as from_timestamp > to_timestamp. Address not tracked by rotki.
500 Internal Server Error – Internal rotki error
Get history status summary
- POST /api/(version)/history/status/summary
Doing a GET on the transactions status endpoint will query status information about how recently all EVM chains and exchanges have been queried for transactions/events and how many transactions are waiting to be decoded.
Note
This endpoint can also be queried asynchronously by using
"async_query": trueExample Request:
http
GET /api/1/history/status/summary HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"async_query": false}
curl
curl -i -X GET http://localhost:5042/api/1/history/status/summary -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": false}'
wget
wget -S -O- http://localhost:5042/api/1/history/status/summary --header="Content-Type: application/json;charset=UTF-8" --body-data='{"async_query": false}'
httpie
echo '{ "async_query": false }' | http http://localhost:5042/api/1/history/status/summary Content-Type:"application/json;charset=UTF-8"
python-requests
requests.get('http://localhost:5042/api/1/history/status/summary', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': False})
Example Response:
HTTP/1.1 200 OK Content-Type: application/json {"result": {"evm_last_queried_ts": 1600000000, "exchanges_last_queried_ts": 1599999000, "undecoded_tx_count": 3, "has_evm_accounts": true, "has_exchanges_accounts": true}, "message": "" }
- Response JSON Object:
result (object) – An object containing the status data
evm_last_queried_ts (integer) – The last timestamp when transactions for all EVM chains have been queried.
exchanges_last_queried_ts (integer) – The last timestamp when history events for all exchanges have been queried.
undecoded_tx_count (integer) – The number of transactions waiting to be decoded.
has_evm_accounts (boolean) – Whether there are any EVM accounts added to rotki.
has_exchanges_accounts (boolean) – Whether there are any exchange accounts added to rotki.
- Status Codes:
200 OK – Status successfully queried.
401 Unauthorized – User is not logged in.
409 Conflict – Other error. Check error message for details.
500 Internal Server Error – Internal rotki error
Active management
- POST /api/(version)/wallet/transfer/token
Prepares a token transfer transaction without submitting it to the blockchain. This endpoint returns the transaction data needed to perform an ERC20 token transfer.
Example Request:
http
POST /api/1/wallet/transfer/token HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "from_address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "to_address": "0x9531C059098e3d194fF87FebB587aB07B30B1306", "token": "eip155:1/erc20:0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84", "amount": "0.000000000000000001" }curl
curl -i -X POST http://localhost:5042/api/1/wallet/transfer/token -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"amount": "0.000000000000000001", "from_address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "to_address": "0x9531C059098e3d194fF87FebB587aB07B30B1306", "token": "eip155:1/erc20:0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84"}'wget
wget -S -O- http://localhost:5042/api/1/wallet/transfer/token --header="Content-Type: application/json;charset=UTF-8" --post-data='{"amount": "0.000000000000000001", "from_address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "to_address": "0x9531C059098e3d194fF87FebB587aB07B30B1306", "token": "eip155:1/erc20:0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84"}'httpie
echo '{ "amount": "0.000000000000000001", "from_address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "to_address": "0x9531C059098e3d194fF87FebB587aB07B30B1306", "token": "eip155:1/erc20:0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84" }' | http POST http://localhost:5042/api/1/wallet/transfer/token Content-Type:"application/json;charset=UTF-8"python-requests
requests.post('http://localhost:5042/api/1/wallet/transfer/token', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'amount': '0.000000000000000001', 'from_address': '0xc37b40ABdB939635068d3c5f13E7faF686F03B65', 'to_address': '0x9531C059098e3d194fF87FebB587aB07B30B1306', 'token': 'eip155:1/erc20:0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84'})
- Request JSON Object:
from_address (string) – The address from which the tokens will be sent
to_address (string) – The address to which the tokens will be sent
token (string) – The token identifier in the format eip155:{chain_id}/erc20:{contract_address}
amount (string) – The amount of tokens to transfer as a string
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "message": "", "result": { "chainId": 1, "from": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "to": "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84", "data": "0xa9059cbb0000000000000000000000009531c059098e3d194ff87febb587ab07b30b13060000000000000000000000000000000000000000000000000000000000000001" }, "status_code": 200 }
- Response JSON Object:
result (object) – The transaction data needed for the token transfer
chainId (integer) – The chain ID of the blockchain network
from (string) – The sender’s address
to (string) – The token contract address
data (string) – The encoded transaction data for the token transfer
- Status Codes:
200 OK – Transaction data successfully prepared
400 Bad Request – Malformed request
409 Conflict – Error preparing the payload
500 Internal Server Error – Internal Rotki error
- POST /api/(version)/wallet/transfer/native
Prepares a native cryptocurrency transfer transaction without submitting it to the blockchain. This endpoint returns the transaction data needed to perform a transfer of the blockchain’s native asset (e.g., ETH).
Example Request:
http
POST /api/1/wallet/transfer/native HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "from_address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "to_address": "0x9531C059098e3d194fF87FebB587aB07B30B1306", "amount": "0.0003", "chain": "ethereum" }curl
curl -i -X POST http://localhost:5042/api/1/wallet/transfer/native -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"amount": "0.0003", "chain": "ethereum", "from_address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "to_address": "0x9531C059098e3d194fF87FebB587aB07B30B1306"}'wget
wget -S -O- http://localhost:5042/api/1/wallet/transfer/native --header="Content-Type: application/json;charset=UTF-8" --post-data='{"amount": "0.0003", "chain": "ethereum", "from_address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "to_address": "0x9531C059098e3d194fF87FebB587aB07B30B1306"}'httpie
echo '{ "amount": "0.0003", "chain": "ethereum", "from_address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "to_address": "0x9531C059098e3d194fF87FebB587aB07B30B1306" }' | http POST http://localhost:5042/api/1/wallet/transfer/native Content-Type:"application/json;charset=UTF-8"python-requests
requests.post('http://localhost:5042/api/1/wallet/transfer/native', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'amount': '0.0003', 'chain': 'ethereum', 'from_address': '0xc37b40ABdB939635068d3c5f13E7faF686F03B65', 'to_address': '0x9531C059098e3d194fF87FebB587aB07B30B1306'})
- Request JSON Object:
from_address (string) – The address from which the native cryptocurrency will be sent
to_address (string) – The address to which the native cryptocurrency will be sent
amount (string) – The amount of native cryptocurrency to transfer as a string
chain (string) – The EVM chain name (e.g., “ethereum” for Ethereum)
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "message": "", "result": { "from": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "to": "0x9531C059098e3d194fF87FebB587aB07B30B1306", "value": 300000000000000, "nonce": 55 }, "status_code": 200 }
- Response JSON Object:
result (object) – The transaction data needed for the native transfer
from (string) – The sender’s address
to (string) – The recipient’s address
value (integer) – The amount to transfer in the smallest unit of the native cryptocurrency
nonce (integer) – The transaction nonce
- Status Codes:
200 OK – Transaction data successfully prepared
400 Bad Request – Malformed request
409 Conflict – Error preparing the payload
500 Internal Server Error – Internal Rotki error
- POST /api/(version)/wallet/interacted
Checks if the address in the from interacted with the address in the to. This interaction check is unidirectional, meaning it only verifies if from_address has interacted with to_address, not the other way around.
- Example Request:
http
POST /api/1/wallet/interacted HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "from_address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "to_address": "0x9531C059098e3d194fF87FebB587aB07B30B1306" }curl
curl -i -X POST http://localhost:5042/api/1/wallet/interacted -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"from_address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "to_address": "0x9531C059098e3d194fF87FebB587aB07B30B1306"}'wget
wget -S -O- http://localhost:5042/api/1/wallet/interacted --header="Content-Type: application/json;charset=UTF-8" --post-data='{"from_address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "to_address": "0x9531C059098e3d194fF87FebB587aB07B30B1306"}'httpie
echo '{ "from_address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "to_address": "0x9531C059098e3d194fF87FebB587aB07B30B1306" }' | http POST http://localhost:5042/api/1/wallet/interacted Content-Type:"application/json;charset=UTF-8"python-requests
requests.post('http://localhost:5042/api/1/wallet/interacted', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'from_address': '0xc37b40ABdB939635068d3c5f13E7faF686F03B65', 'to_address': '0x9531C059098e3d194fF87FebB587aB07B30B1306'})
- reqjson string from_address:
The address from which the interaction is being checked.
- reqjson string to_address:
The address with which the interaction is being checked.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": true }
- Response JSON Object:
result (boolean) – Indicates whether the from_address has interacted with the to_address.
- Status Codes:
200 OK – Interaction check successful.
400 Bad Request – Malformed request.
500 Internal Server Error – Internal Rotki error.
- POST /api/(version)/wallet/balance
Queries the token or native asset balance for a given EVM chain and address.
Note
This endpoint can also be queried asynchronously by using
"async_query": true.Example Request (Native Balance):
http
POST /api/1/wallet/balance HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "evm_chain": "ethereum", "address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "asset": "ETH", "async_query": false }curl
curl -i -X POST http://localhost:5042/api/1/wallet/balance -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "asset": "ETH", "async_query": false, "evm_chain": "ethereum"}'wget
wget -S -O- http://localhost:5042/api/1/wallet/balance --header="Content-Type: application/json;charset=UTF-8" --post-data='{"address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "asset": "ETH", "async_query": false, "evm_chain": "ethereum"}'httpie
echo '{ "address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "asset": "ETH", "async_query": false, "evm_chain": "ethereum" }' | http POST http://localhost:5042/api/1/wallet/balance Content-Type:"application/json;charset=UTF-8"python-requests
requests.post('http://localhost:5042/api/1/wallet/balance', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'address': '0xc37b40ABdB939635068d3c5f13E7faF686F03B65', 'asset': 'ETH', 'async_query': False, 'evm_chain': 'ethereum'})Example Request (ERC20 Balance):
http
POST /api/1/wallet/balance HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "evm_chain": "ethereum", "address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "asset": "eip155:1/erc20:0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84", "async_query": false }curl
curl -i -X POST http://localhost:5042/api/1/wallet/balance -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "asset": "eip155:1/erc20:0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84", "async_query": false, "evm_chain": "ethereum"}'wget
wget -S -O- http://localhost:5042/api/1/wallet/balance --header="Content-Type: application/json;charset=UTF-8" --post-data='{"address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "asset": "eip155:1/erc20:0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84", "async_query": false, "evm_chain": "ethereum"}'httpie
echo '{ "address": "0xc37b40ABdB939635068d3c5f13E7faF686F03B65", "asset": "eip155:1/erc20:0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84", "async_query": false, "evm_chain": "ethereum" }' | http POST http://localhost:5042/api/1/wallet/balance Content-Type:"application/json;charset=UTF-8"python-requests
requests.post('http://localhost:5042/api/1/wallet/balance', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'address': '0xc37b40ABdB939635068d3c5f13E7faF686F03B65', 'asset': 'eip155:1/erc20:0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84', 'async_query': False, 'evm_chain': 'ethereum'})
- reqjson string evm_chain:
The EVM chain to query (e.g., “ethereum”, “optimism”).
- reqjson string address:
The address whose balance should be queried.
- reqjson string asset:
The asset identifier. Use the native symbol (e.g., “ETH”) or an ERC20 format like “eip155:1/erc20:0x…”.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": "23.755147", "message": "" }
- resjson string result:
The balance with decimals already adjusted to the asset’s precision.
- statuscode 200:
Balance retrieved successfully.
- statuscode 400:
Malformed request.
- statuscode 409:
Error querying the RPC or mismatch between asset and chain provided.
- statuscode 500:
Internal Rotki error.
Ethereum staking events
- DELETE /api/(version)/blockchains/eth2/stake/events
Doing a DELETE on this endpoint will reset Ethereum staking events data by removing all stored events of the specified type and clearing associated cache entries to enable fresh data retrieval.
Example Request
http
DELETE /api/(version)/blockchains/eth2/stake/events HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"entry_type": "eth_withdrawal_event"}
curl
curl -i -X DELETE 'http://localhost:5042/api/(version)/blockchains/eth2/stake/events' -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"entry_type": "eth_withdrawal_event"}'
wget
wget -S -O- --method=DELETE 'http://localhost:5042/api/(version)/blockchains/eth2/stake/events' --header="Content-Type: application/json;charset=UTF-8" --body-data='{"entry_type": "eth_withdrawal_event"}'
httpie
echo '{ "entry_type": "eth_withdrawal_event" }' | http DELETE 'http://localhost:5042/api/(version)/blockchains/eth2/stake/events' Content-Type:"application/json;charset=UTF-8"
python-requests
requests.delete('http://localhost:5042/api/(version)/blockchains/eth2/stake/events', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'entry_type': 'eth_withdrawal_event'})
- Request JSON Object:
entry_type (string) – The type of staking events to reset. Must be either
eth_block_eventoreth_withdrawal_event.
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (boolean) – Returns
truewhen the reset operation completes successfully.
- Status Codes:
200 OK – Reset operation completed successfully.
400 Bad Request – Failed to validate the data or invalid entry type provided.
401 Unauthorized – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
- PUT /api/(version)/blockchains/eth2/stake/events
Doing a PUT on this endpoint will reprocess the Ethereum block production events in the db, updating the event type depending on whether the fee receiver address is tracked, and combining block events with evm tx events.
Example Request
http
PUT /api/(version)/blockchains/eth2/stake/events HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "block_numbers": [10001, 10002], "async_query": false }
curl
curl -i -X PUT 'http://localhost:5042/api/(version)/blockchains/eth2/stake/events' -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": false, "block_numbers": [10001, 10002]}'
wget
wget -S -O- --method=PUT 'http://localhost:5042/api/(version)/blockchains/eth2/stake/events' --header="Content-Type: application/json;charset=UTF-8" --body-data='{"async_query": false, "block_numbers": [10001, 10002]}'
httpie
echo '{ "async_query": false, "block_numbers": [ 10001, 10002 ] }' | http PUT 'http://localhost:5042/api/(version)/blockchains/eth2/stake/events' Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/(version)/blockchains/eth2/stake/events', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': False, 'block_numbers': [10001, 10002]})
- Request JSON Object:
block_numbers (list(integer)[optional]) – List of block numbers for which to redecode events. Redecodes all events when omitted.
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Response JSON Object:
result (boolean) – Returns
truewhen the redecode operation completes successfully.
- Status Codes:
200 OK – Redecode operation completed successfully.
400 Bad Request – Failed to validate the data or invalid entry type provided.
401 Unauthorized – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
Refetch ETH staking events
- POST /api/(version)/blockchains/eth2/events/refetch
Doing a POST on this endpoint will force a re-query of ETH staking events (block productions or withdrawals) for the specified validators or addresses. This is useful to recover potentially missed events due to indexer errors or other temporary failures.
For block production events, beaconcha.in does not support time range filtering, so all blocks for the targeted validators are re-queried regardless of the provided time range. This operation can be expensive in terms of API usage.
For withdrawal events, etherscan is queried for the specified time range.
Existing events are not deleted. Duplicates are handled automatically.
Note
This endpoint can also be queried asynchronously by using
"async_query": trueExample Request (block productions by validator indices):
http
POST /api/1/blockchains/eth2/events/refetch HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"async_query": false, "entry_type": "block productions", "validator_indices": [12345, 67890]}
curl
curl -i -X POST http://localhost:5042/api/1/blockchains/eth2/events/refetch -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": false, "entry_type": "block productions", "validator_indices": [12345, 67890]}'
wget
wget -S -O- http://localhost:5042/api/1/blockchains/eth2/events/refetch --header="Content-Type: application/json;charset=UTF-8" --post-data='{"async_query": false, "entry_type": "block productions", "validator_indices": [12345, 67890]}'
httpie
echo '{ "async_query": false, "entry_type": "block productions", "validator_indices": [ 12345, 67890 ] }' | http POST http://localhost:5042/api/1/blockchains/eth2/events/refetch Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/blockchains/eth2/events/refetch', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': False, 'entry_type': 'block productions', 'validator_indices': [12345, 67890]})
Example Request (withdrawals by addresses):
http
POST /api/1/blockchains/eth2/events/refetch HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"async_query": false, "entry_type": "eth withdrawals", "addresses": ["0x4c66C2055f6A7A01e102Bde8d8d71d1D36667e21"], "from_timestamp": 1640995200, "to_timestamp": 1672531200}
curl
curl -i -X POST http://localhost:5042/api/1/blockchains/eth2/events/refetch -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"addresses": ["0x4c66C2055f6A7A01e102Bde8d8d71d1D36667e21"], "async_query": false, "entry_type": "eth withdrawals", "from_timestamp": 1640995200, "to_timestamp": 1672531200}'
wget
wget -S -O- http://localhost:5042/api/1/blockchains/eth2/events/refetch --header="Content-Type: application/json;charset=UTF-8" --post-data='{"addresses": ["0x4c66C2055f6A7A01e102Bde8d8d71d1D36667e21"], "async_query": false, "entry_type": "eth withdrawals", "from_timestamp": 1640995200, "to_timestamp": 1672531200}'
httpie
echo '{ "addresses": [ "0x4c66C2055f6A7A01e102Bde8d8d71d1D36667e21" ], "async_query": false, "entry_type": "eth withdrawals", "from_timestamp": 1640995200, "to_timestamp": 1672531200 }' | http POST http://localhost:5042/api/1/blockchains/eth2/events/refetch Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/blockchains/eth2/events/refetch', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'addresses': ['0x4c66C2055f6A7A01e102Bde8d8d71d1D36667e21'], 'async_query': False, 'entry_type': 'eth withdrawals', 'from_timestamp': 1640995200, 'to_timestamp': 1672531200})
Example Request (all tracked validators):
http
POST /api/1/blockchains/eth2/events/refetch HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 {"async_query": false, "entry_type": "block productions"}
curl
curl -i -X POST http://localhost:5042/api/1/blockchains/eth2/events/refetch -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"async_query": false, "entry_type": "block productions"}'
wget
wget -S -O- http://localhost:5042/api/1/blockchains/eth2/events/refetch --header="Content-Type: application/json;charset=UTF-8" --post-data='{"async_query": false, "entry_type": "block productions"}'
httpie
echo '{ "async_query": false, "entry_type": "block productions" }' | http POST http://localhost:5042/api/1/blockchains/eth2/events/refetch Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/blockchains/eth2/events/refetch', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'async_query': False, 'entry_type': 'block productions'})
- Request JSON Object:
async_query (bool) – If true, the query will be processed asynchronously.
entry_type (string) – The type of staking events to refetch. Must be either
block productionsoreth withdrawals.validator_indices (list[int]) – Optional. A list of one or more validator indices to refetch events for. Can’t specify both
validator_indicesandaddressesin the same query.addresses (list[string]) – Optional. A list of one or more withdrawal addresses to refetch events for. Can’t specify both
validator_indicesandaddressesin the same query.from_timestamp (int) – Optional. Start of the time period. Defaults to 0. Only meaningful for withdrawal events since beaconcha.in does not support time range filtering.
to_timestamp (int) – Optional. End of the time period. Defaults to current time. Only meaningful for withdrawal events since beaconcha.in does not support time range filtering.
Note
If neither
validator_indicesnoraddressesis provided, events are refetched for all tracked validators.Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "result": { "total": 3, "per_validator": { 12345: 2, 67890: 1 }, "per_address": { "0x4c66C2055f6A7A01e102Bde8d8d71d1D36667e21": 2, "0xAbCdEf0123456789AbCdEf0123456789AbCdEf01": 1 } }, "message": "" }
- Response JSON Object:
result (object) – An object containing the breakdown of newly added events during the refetch operation.
result.total (int) – The total number of newly added events.
result.per_validator (object) – A mapping of validator index to the number of newly added events for that validator. Only validators with new events are included.
result.per_address (object) – A mapping of reward/withdrawal address to the number of newly added events for that address. For block productions this is the fee recipient address, for withdrawals this is the withdrawal address. Only addresses with new events are included.
- Status Codes:
200 OK – Refetch operation completed successfully.
400 Bad Request – Invalid parameters such as providing both validator_indices and addresses, validator indices not tracked by rotki, or no tracked validators found.
401 Unauthorized – No user is currently logged in.
409 Conflict – eth2 module is not active.
502 Bad Gateway – Could not reach external data sources (beaconcha.in or etherscan).
500 Internal Server Error – Internal rotki error.
Solana Token Migration
- POST /api/(version)/solana/tokens/migrate
Migrates a user-added Solana token to the proper token type. This endpoint creates a new Solana token with the provided address and metadata, replaces all references in the database, and cleans up the migration table if necessary. This is a temporary endpoint to correct custom user input solana tokens input before release 1.40.
Note
This endpoint can also be queried asynchronously by using
"async_query": true.Example Request
http
POST /api/1/solana/tokens/migrate HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "async_query": false, "old_asset": "RAYDIUMSOL", "address": "So11111111111111111111111111111111111112", "decimals": 9, "token_kind": "spl_token" }
curl
curl -i -X POST http://localhost:5042/api/1/solana/tokens/migrate -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"address": "So11111111111111111111111111111111111112", "async_query": false, "decimals": 9, "old_asset": "RAYDIUMSOL", "token_kind": "spl_token"}'
wget
wget -S -O- http://localhost:5042/api/1/solana/tokens/migrate --header="Content-Type: application/json;charset=UTF-8" --post-data='{"address": "So11111111111111111111111111111111111112", "async_query": false, "decimals": 9, "old_asset": "RAYDIUMSOL", "token_kind": "spl_token"}'
httpie
echo '{ "address": "So11111111111111111111111111111111111112", "async_query": false, "decimals": 9, "old_asset": "RAYDIUMSOL", "token_kind": "spl_token" }' | http POST http://localhost:5042/api/1/solana/tokens/migrate Content-Type:"application/json;charset=UTF-8"
python-requests
requests.post('http://localhost:5042/api/1/solana/tokens/migrate', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'address': 'So11111111111111111111111111111111111112', 'async_query': False, 'decimals': 9, 'old_asset': 'RAYDIUMSOL', 'token_kind': 'spl_token'})
- Request JSON Object:
async_query (bool) – Optional. Whether to process the request asynchronously. Defaults to false.
old_asset (string) – The old asset identifier to migrate from. Must exist in the user_added_solana_tokens table.
address (string) – The new Solana address (mint address) for the token
decimals (int) – The number of decimal places for the token
token_kind (string) – The type of Solana token. Must be either “spl_token” or “spl_nft”
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 migration operation.
- Status Codes:
200 OK – Token migration completed successfully.
400 Bad Request – Failed to validate the data or invalid parameters provided.
401 Unauthorized – No user is currently logged in.
409 Conflict – Token does not exist in user_added_solana_tokens table, or failed to create the new Solana token due to unknown asset or input error.
500 Internal Server Error – Internal rotki error.
Monerium OAuth
- GET /api/(version)/services/monerium
Doing a GET on this endpoint returns the Monerium authentication status.
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": { "authenticated": true, "user_email": "alice@example.com", "default_profile_id": "profile-123", "profiles": [], "expires_at": 1700000000, }, "message": "" }
- Response JSON Object:
result (object) – Status payload describing the saved Monerium OAuth credentials.
authenticated (bool) –
truewhen access tokens are stored,falseotherwise.user_email (str) – Email address of the connected Monerium account. Present only when authenticated.
default_profile_id (str) – Identifier of the default Monerium profile. Present only when authenticated.
profiles (list) – List of available Monerium profiles with metadata. Present only when authenticated.
expires_at (int) – Unix timestamp when the cached access token expires. Present only when authenticated.
- Status Codes:
200 OK – Status queried successfully.
401 Unauthorized – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
- PUT /api/(version)/services/monerium
Doing a PUT on this endpoint stores Monerium OAuth tokens obtained from the external OAuth flow and fetches the user context.
Example Request
http
PUT /api/1/services/monerium HTTP/1.1 Host: localhost:5042 Content-Type: application/json;charset=UTF-8 { "access_token": "access-token", "refresh_token": "refresh-token", "expires_in": 3600 }
curl
curl -i -X PUT http://localhost:5042/api/1/services/monerium -H "Content-Type: application/json;charset=UTF-8" --data-raw '{"access_token": "access-token", "expires_in": 3600, "refresh_token": "refresh-token"}'
wget
wget -S -O- --method=PUT http://localhost:5042/api/1/services/monerium --header="Content-Type: application/json;charset=UTF-8" --body-data='{"access_token": "access-token", "expires_in": 3600, "refresh_token": "refresh-token"}'
httpie
echo '{ "access_token": "access-token", "expires_in": 3600, "refresh_token": "refresh-token" }' | http PUT http://localhost:5042/api/1/services/monerium Content-Type:"application/json;charset=UTF-8"
python-requests
requests.put('http://localhost:5042/api/1/services/monerium', headers={'Content-Type': 'application/json;charset=UTF-8'}, json={'access_token': 'access-token', 'expires_in': 3600, 'refresh_token': 'refresh-token'})
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": { "success": true, "message": "Successfully authenticated with Monerium", "user_email": "alice@example.com", "default_profile_id": "profile-123", "profiles": [] }, "message": "" }
- Request JSON Object:
access_token (str) – Access token returned by the Monerium OAuth callback.
refresh_token (str) – Refresh token returned by the OAuth callback.
expires_in (int) – Lifetime of the access token in seconds.
- Response JSON Object:
result (object) – Confirmation payload containing the stored user context.
success (bool) –
truewhen the credentials were stored successfully.message (str) – Confirmation message returned by rotki.
user_email (str) – Email address retrieved from Monerium.
default_profile_id (str) – Default profile identifier fetched from Monerium.
profiles (list) – List of Monerium profiles associated with the account.
- Status Codes:
200 OK – Credentials stored successfully.
400 Bad Request – Failed to validate or store the credentials, or Monerium returned an error.
401 Unauthorized – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
- DELETE /api/(version)/services/monerium
Doing a DELETE on this endpoint removes stored Monerium OAuth credentials.
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Status Codes:
200 OK – Credentials removed successfully.
401 Unauthorized – No user is currently logged in.
500 Internal Server Error – Internal rotki error.
GnosisPay admins
- GET /api/(version)/services/gnosispay/admins
Retrieve tracked Gnosis addresses whose corresponding safe has at least one administrator reported by the Gnosis Pay contract.
Note
This endpoint can also be queried asynchronously by using
"async_query": true.Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": { "0xaCFEb570426e260Eb930971FE528c8014f1002a0": [ "0x37f18A82493cdF80675fF01e58c1A1b39637cf50", "0xc37b40ABdB939635068d3c5f13E7faF686F03B65" ] }, "message": "" }
- Response JSON Object:
result (object) – Mapping of tracked safe addresses to the list of admin addresses.
- Status Codes:
200 OK – The request was successful.
401 Unauthorized – No user is currently logged in.
409 Conflict – Error querying the on chain information.
502 Bad Gateway – Failed to query the external contract.
GnosisPay nonce
- GET /api/(version)/services/gnosispay/nonce
Retrieve a SIWE nonce from the Gnosis Pay public API. The nonce is returned as plain text.
Note
This endpoint can be queried asynchronously via
"async_query": true.Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": "e9d4b01d-8f3b-43d3-8d52-4d7e1c6fa4b1", "message": "" }
- Response JSON Object:
result (string) – SIWE nonce obtained from the Gnosis Pay API.
- Status Codes:
200 OK – The request was successful.
401 Unauthorized – No user is currently logged in.
409 Conflict – Failed to query the Gnosis Pay API.
GnosisPay SIWE token
- POST /api/(version)/services/gnosispay/token
Use the signed SIWE message to retrieve a Gnosis Pay session token and store it in rotki.
Example Request
POST /api/1/services/gnosispay/token HTTP/1.1 Content-Type: application/json { "message": "rotki wants you to sign in with your Ethereum account...", "signature": "0x4f4c1df6..." }
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "result": true, "message": "" }
- Request JSON Object:
message (string) – SIWE message that was signed.
signature (string) – Signature produced by the user’s wallet.
- Response JSON Object:
result (string) – true if it was saved successfully.
- Status Codes:
200 OK – The request was successful.
401 Unauthorized – No user is currently logged in.
409 Conflict – Failed to verify the SIWE signature with Gnosis Pay.