Skip to content

aspiers/ai-config / .agents/skills/rotki-api

rotki-api

Verified

Drives a running rotki desktop app through its local REST API and MCP server, and explains rotki's EVM indexer coverage (Etherscan, Blockscout, Routescan free and paid tiers), bridge-transaction matching, internal-transaction conflicts and zkSync Lite quirks. Use when querying or changing rotki data from an agent, when rotki warns that an indexer or paid API key is needed, when chains such as Base, BSC, Optimism, Polygon or zkSync Lite are missing transactions, when matching bridge legs, when resolving "Internal Transaction Conflicts", or when deciding whether to use rotki's MCP server.

FileKindSize
SKILL.mdskill md6.6 KB
references/api-recipes.mdmarkdown3.6 KB
references/indexers-and-gaps.mdmarkdown3.3 KB

references/api-recipes.md

View on GitHub
# rotki API recipes

Verified against rotki 1.44.1. Paths are relative to
`http://127.0.0.1:<core-port>/api/1`. The authoritative reference is
`docs/api.rst` in the rotki repository; search it by route rather than
reading it whole.

## Reads

| Purpose | Request |
|---|---|
| Tracked accounts on a chain | `GET /blockchains/<CHAIN>/accounts` (no body, no JSON header) |
| History events | `POST /history/events` with filters: `location`, `location_labels`, `identifiers`, `tx_refs`, `group_identifiers`, `event_subtypes`, `from_timestamp`, `to_timestamp`, `limit`, `offset`, `aggregate_by_group_ids: false` |
| Newest saved transaction per chain and address | `GET /blockchains/transactions/latest` |
| Undecoded transaction counts | `GET /blockchains/transactions/decode` with `{"async_query": false}` |
| Unmatched or ignored bridge legs | `GET /history/events/match/bridges?only_ignored=false\|true` |
| Candidate matches for a bridge leg (premium) | `POST /history/events/match/bridges` with `bridge_event`, `time_range` (seconds), `only_expected_assets`, `tolerance` |
| Internal-transaction conflicts | `GET /blockchains/transactions/internal/conflicts` with `failed`, `fixed`, `chain`, `limit`, `offset` |
| Premium tier and capabilities | `GET /premium/capabilities` |
| Manual balances | `GET /balances/manual` |

`POST /history/events` returns `result.entries`, each either an object or
a list of objects (grouped events), with the event under `.entry`.
Timestamps are milliseconds.

## Writes (each needs the user's approval)

| Purpose | Request | Undo |
|---|---|---|
| Add a transaction by hash, fetched from RPC nodes first | `GET /blockchains/evm/transactions/lookup` with `tx_hash`, `evm_chain`, `related_address` (a tracked address) | delete the transaction |
| Decode everything pending on a chain | `POST /blockchains/transactions/decode` with `chain` | n/a |
| Re-decode (and re-fetch) specific hashes | `PUT /blockchains/transactions/decode` with `chain`, `tx_refs`, `delete_custom: false` | re-decode again |
| Fetch transactions for chosen accounts | `POST /blockchains/transactions` with `accounts: [{address, blockchain}]`, time range | n/a |
| Add accounts | `PUT /blockchains/<CHAIN>/accounts` with `accounts: [{address, label}]` | `DELETE` same route |
| Match, ignore, mark external, or synthesise a bridge counterpart | `PUT /history/events/match/bridges` with `bridge_event` plus `matched_events`, nothing, `external: true` or `create_counterpart: true` | `DELETE` with `identifier` |
| Edit an event | `PATCH /history/events` with the full entry read back from `POST /history/events`, fields changed (e.g. `event_subtype: "donate"`, `user_notes`) | patch back |
| Add a manual balance | `PUT /balances/manual` with `balances: [{asset, label, amount, location, balance_type}]` | `DELETE` by identifier |

The lookup response's `was_fetched` is false when rotki already had the
transaction, which distinguishes new hashes from ones already present.
`delete_custom: false` keeps user-edited events when re-decoding.

To edit an event read back from `POST /history/events`, drop
`actual_group_identifier` before sending it to `PATCH /history/events`. If
the event shares a transaction with a matched asset movement, the read-back
`group_identifier` is the match's and the edit fails with "already exists";
use `actual_group_identifier` as `group_identifier` instead.

Spoof or poisoning addresses can be named in the private address book
(`PUT /names/addressbook/private` with `entries: [{address, blockchain,
name}]`) so rotki labels them wherever they appear; on-chain events from
them can be tagged with the `spam` subtype.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall