Skip to content


Switch branches/tags

Latest commit

Signed-off-by: Jingfu Wang <>

Signed-off-by: Jingfu Wang <>

Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Rosetta CLI

CLI to validate the correctness of Rosetta API implementations

The rosetta-cli tool is used by developers to test the correctness of their Rosetta API implementations. The CLI also provides the ability to look up block contents and account balances.


To download a binary for the latest release, run:

curl -sSfL | sh -s

The binary will be installed inside the ./bin directory (relative to the directory where you ran the installation command).

Downloading binaries from the Github UI will cause permission errors on Mac.

Installing in a Custom Location

To download the binary into a specific directory, run:

curl -sSfL | sh -s -- -b <relative directory>

Run via Docker

Running the following command will start a Docker container and present CLI for the Rosetta API.

docker run -it [image-name] [command]

Example: To validate that the Data API implementation is correct, running the following command will start a Docker container with a data directory at <working directory>.

docker run -v "$(pwd):/data" -it [image-name] check:data --configuration-file /data/config.json

Updates and Releases

We recommend that you continually update your installation to the latest release as soon as possible. The latest release notes are available in our Community board under the Release category.

You can also view releases and change log information in the Releases section of this repository.


You can find the Rosetta API documentation at

For more information on the rosetta-cli tool, read our The rosetta-cli tool documentation.

For more information on how to test your implementation file with the rosetta-cli tool, read our How to Test Your Rosetta Implementation documentation.

Our documentation is divided into the following sections:


You may contribute to the rosetta-cli project in various ways:

Read our Contributing documentation for more information.

rosetta-cli Tool Development

While working on improvements to this repository, we recommend that you use these commands to check your code:

  • make deps to install dependencies
  • make test to run tests
  • make lint to lint the source code (included generated code)
  • make release to run one last check before opening a PR
  • make compile version=RELEASE_TAG to generate binaries

If you are developing on both the rosetta-cli and rosetta-sdk-go repositories, use go.mod replace to reference local changes:

replace "" v0.6.8 => "<PATH TO LOCAL rosetta-sdk-go>"


  • When we release a new rosetta-cli version, please update the version number to follow PR so that rosetta-cli version command can print the correct value.
  • Create binaries and upload all the binaries in the new release tag (e.g.
    • Ensure $GOPATH/bin is added to $PATH
    • Run make compile version=<New Version>
    • All the binaries will be created in the bin folder and should have extension as tar.gz and new version number


Many of the packages use a Helper/Handler interface pattern to acquire required information or to send events to some client implementation. An example of this is in the reconciler package where a Helper is used to get the account balance and the Handler is called to indicate whether the reconciliation of an account was successful.

Repo Structure

examples // examples of different config files
  logger // logic to write syncing information to stdout/files
  processor // Helper/Handler implementations for reconciler, storage, and syncer
  tester // test orchestrators


While running the check:data or check:construction option, if you get the following error:

dial tcp socket: too many open files: unable to sync to 1902533: unable to sync to 1902533

Please run the ulimit -n 10000 command to increase the max concurrent opened file limit.

Note: MacOS users, if you face ulimit: setrlimit failed: invalid argument error while setting ulimit, please run sudo launchctl limit maxfiles 10000 200000 before setting the ulimit.

Related Projects

Reference Implementations

To help you with examples, we developed complete Rosetta API reference implementations for Bitcoin and Ethereum. Developers of Bitcoin-like or Ethereum-like blockchains may find it easier to fork these reference implementations than to write an implementation from scratch.

You can also find community implementations for a variety of blockchains in the rosetta-ecosystem repository, and in the ecosystem category of our community site.


This project is available open source under the terms of the Apache 2.0 License. © 2022 Coinbase