What is ICRC Rosetta?
The ICRC Rosetta implementation allows for communication with the ICRC-1 compatible ledgers through the Rosetta-API standard. Examples include the ckBTC ledger and the ckETH ledger. This documentation covers the endpoints of the Data-API and the Construction-API.
Set up an ICRC Rosetta node
You can set up a Rosetta API-compliant node for ICRC to interact with the Internet Computer and your ICRC-1 ledgers of choice. For simplicity, these instructions will describe how to use a Docker image to create the integration with the Rosetta API. You can also build and run the binary using the source code.
If you don’t already have Docker in your environment, download and install the latest version.
Step 1: Install Docker and start the Docker daemon.
The Docker daemon (dockerd) should automatically start when you reboot your computer. If you start the Docker daemon manually, the instructions vary depending on the local operating system.
Step 2: Pull the latest dfinity/ic-icrc-rosetta-api image from the Docker Hub.
Run the following command:
docker pull dfinity/ic-icrc-rosetta-api
Step 3: Start the integration software.
From v2.1.0 - Multitoken tracking
Run the following command:
You can have a single ICRC Rosetta instance integrate with multiple tokens at the same time.
You will need to know the canister IDs of the ICRC-1 ledgers you are trying to connect to. For example, to connect the ckBTC ICRC-1 ledger with the canister ID mxzaz-hqaaa-aaaar-qaada-cai and ckETH ICRC-1 (ss2fx-dyaaa-aaaar-qacoq-cai) which are running on the mainnet, the following call could be used:
docker run \
--interactive \
--tty \
--publish 8082:8082 \
--rm \
dfinity/ic-icrc-rosetta-api \
--port 8082 \
--network-type mainnet \
--multi-tokens mxzaz-hqaaa-aaaar-qaada-cai,ss2fx-dyaaa-aaaar-qacoq-cai \
--multi-tokens-store-dir /data
In this case, each token will use a separate SQLite database in the specified directory, named /data/mxzaz-hqaaa-aaaar-qaada-cai.db and /data/ss2fx-dyaaa-aaaar-qacoq-cai.db respectively.
Before v2.1.0 - Single token tracking
Run the following command:
You will need to know the canister ID of the ICRC-1 ledger you are trying to connect to. For example, to connect the ckBTC ICRC-1 ledger with the canister ID mxzaz-hqaaa-aaaar-qaada-cai which is running on the mainnet, the following call could be used:
docker run \
--interactive \
--tty \
--publish 8082:8082 \
--rm \
dfinity/ic-icrc-rosetta-api \
--port 8082 \
--network-type mainnet \
--ledger-id mxzaz-hqaaa-aaaar-qaada-cai \
--store-file /data/db.sqlite
Initialization logs
In either case (Multi-token or legacy single token), the call specifies a port using --port which is used to publish through Docker.
The default port, if not specified, is 8080. The default network is the testnet.
This command starts the software on the local host and displays output similar to the following:
2025-04-04T11:15:25.840527Z INFO rs/rosetta-api/icrc1/src/main.rs:447: ICRC Rosetta is connected to the ICRC-1 ledger: mxzaz-hqaaa-aaaar-qaada-cai
2025-04-04T11:15:25.840649Z INFO rs/rosetta-api/icrc1/src/main.rs:451: The token symbol of the ICRC-1 ledger is: ckBTC
2025-04-04T11:15:30.467654Z INFO rs/rosetta-api/icrc1/src/main.rs:447: ICRC Rosetta is connected to the ICRC-1 ledger: ss2fx-dyaaa-aaaar-qacoq-cai
2025-04-04T11:15:30.467725Z INFO rs/rosetta-api/icrc1/src/main.rs:451: The token symbol of the ICRC-1 ledger is: ckETH
2025-04-04T11:15:30.468149Z INFO rs/rosetta-api/icrc1/src/main.rs:603: Starting Rosetta server
2025-04-04T11:15:30.468181Z INFO rs/rosetta-api/icrc1/src/main.rs:604: Rosetta server is listening at: 0.0.0.0:8080
2025-04-04T11:15:32.792226Z INFO sync{token=ckETH-ss2fx}: rs/rosetta-api/icrc1/src/ledger_blocks_synchronization/blocks_synchronizer.rs:288: Fully synched to block height: 801941
2025-04-04T11:15:37.490971Z INFO sync{token=ckBTC-mxzaz}: rs/rosetta-api/icrc1/src/ledger_blocks_synchronization/blocks_synchronizer.rs:276: Progress: 99.01% (fetching 23356 of 2365800), ETA: 0.6min (607.4 blocks/s)
2025-04-04T11:15:43.036138Z INFO sync{token=ckBTC-mxzaz}: rs/rosetta-api/icrc1/src/ledger_blocks_synchronization/blocks_synchronizer.rs:276: Progress: 99.18% (fetching 19354 of 2365800), ETA: 0.5min (659.7 blocks/s)
2025-04-04T11:15:48.416439Z INFO sync{token=ckBTC-mxzaz}: rs/rosetta-api/icrc1/src/ledger_blocks_synchronization/blocks_synchronizer.rs:276: Progress: 99.44% (fetching 13351 of 2365800), ETA: 0.3min (799.8 blocks/s)
2025-04-04T11:15:54.144698Z INFO sync{token=ckBTC-mxzaz}: rs/rosetta-api/icrc1/src/ledger_blocks_synchronization/blocks_synchronizer.rs:276: Progress: 99.77% (fetching 5347 of 2365800), ETA: 0.1min (947.0 blocks/s)
2025-04-04T11:16:00.456019Z INFO sync{token=ckBTC-mxzaz}: rs/rosetta-api/icrc1/src/ledger_blocks_synchronization/blocks_synchronizer.rs:276: Progress: 100.00% (fetching 1 of 2365800), ETA: 0.0min (925.7 blocks/s)
2025-04-04T11:16:00.456344Z INFO sync{token=ckBTC-mxzaz}: rs/rosetta-api/icrc1/src/ledger_blocks_synchronization/blocks_synchronizer.rs:288: Fully synched to block height: 2365800
Notice that most logs are labeled with a sync{token=...} prefix, which indicates which of the tracked tokens is generating those logs.
For further help on what the options for ICRC Rosetta are, you can run the following command:
docker run \
--interactive \
--tty \
--publish 8082:8082 \
--rm \
dfinity/ic-icrc-rosetta-api \
--help
By default, this software does not connect to any ICRC-1 ledger canister running on the Internet Computer blockchain mainnet.
Currently, there is no ICRC-1 ledger running on the testnet. However, there are several test tokens running on mainnet such as ckTestBTC (mc6ru-gyaaa-aaaar-qaaaq-cai) and ckTestETH (apia6-jaaaa-aaaar-qabma-cai).
The first time you run the command, it might take some time for the node to catch up to the current link of the chain. When the node is caught up, you should see output similar to the following:
Synced Up to block height: 1357644
After that, ICRC Rosetta will update the account balances. Please wait for any queries that include fetching account balances until this process is done. The corresponding message you will see is:
Account Balances have been updated successfully
After completing this step, the node continues to run as a passive node that does not participate in block making.
Step 4: Open a new terminal window or tab and run the ps command to verify the status of the service.
If you need to stop the service, press Ctrl-C. You might want to do this to change the canister identifier you are using, for example.
To test the integration after setting up the node, you will need to write a program to simulate a principal submitting a transaction or looking up an account balance.
Run the Rosetta node in production
When you are finished testing, you should run the Docker image in production mode without the --interactive, --tty, and --rm command-line options.
These command-line options are used to attach an interactive terminal session and remove the container and are primarily intended for testing purposes.
To run the software in a production environment, you can start the Docker image using the --detach option to run the container in the background and, optionally, specify the --volume command for storing blocks.
For more information about Docker command-line options, see the Docker reference documentation.
Requirements and limitations
The integration software provided in the Docker image has one requirement that is not part of the standard Rosetta API specification.
For transactions involving ICRC-1 tokens, the unsigned transaction must be created less than 24 hours before the network receives the signed transaction. The reason for this is the deduplication mechanism. Any submitted transaction that refers back to a too old transaction is rejected to maintain operational efficiency.
Other than this requirement, the Rosetta API integration software fully complies with all standard Rosetta endpoints and passes all of the rosetta-cli tests.
The software can accept any valid Rosetta request.
However, the integration software only prompts for transactions to be signed using Ed25519 and SECP256k1, rather than all the signature schemes listed, and only replies with a small subset of the potential responses that the specification supports.
For example, the software doesn’t implement any of the UTXO features of Rosetta, so you won’t see any UTXO messages in any of the software responses.
Frequently asked questions
The following questions come from the most commonly reported questions and blockers from the developer community regarding Rosetta integration with the Internet Computer.
How do I connect the Rosetta node to the mainnet?
Use flags --network-type mainnet
How do I know if the node has caught up with the testnet?
Search the Starting Rosetta API server startup log. There will be a log entry that says Synced Up to block height: XX.
This message confirms that you are caught up with all blocks.
How to persist synced blocks data?
Mount the /data directory as a volume.
docker volume create ic-icrc-rosetta
docker run \
--volume ic-icrc-rosetta:/data \
--interactive \
--tty \
--publish 8082:8082 \
--rm \
dfinity/ic-icrc-rosetta-api \
--network-type mainnet \
--port 8082 \
--ledger-id mxzaz-hqaaa-aaaar-qaada-cai \
--store-file /data/db.sqlite
Is the Rosetta node versioned?
Yes, new versions are regularly published on DockerHub.
It is recommended to use a specific version in production settings, e.g., dfinity/ic-icrc-rosetta-api:v1.0.0
You can query the version of a running Rosetta node using the /network/options endpoint.
$ curl -s -q -H 'Content-Type: application/json' -d '{
"network_identifier": {
"blockchain": "Internet Computer",
"network": "mxzaz-hqaaa-aaaar-qaada-cai"
},
"metadata": {}
}' --location '0.0.0.0:8082/network/options' | jq '.version.node_version'
"1.0.0"