Skip to main content

What is ICP Rosetta?

Intermediate
Rosetta

ICP Rosetta allows for communication with the ICP ledger and the NNS governance canister through the Rosetta-API standard.

The Rosetta API is a standardized specification for blockchain integrations developed by Coinbase. ICP Rosetta provides a Rosetta-compliant interface that enables:

  • Custody platforms to integrate with the Internet Computer Protocol
  • Analytics and compliance tools to pull ledger and governance data
  • KYC (Know Your Customer) and AML (Anti-Money Laundering) compliance
  • Transaction preparation and submission to the ICP ledger and NNS governance

Supported operations​

ICP Rosetta supports various operations through its APIs:

Ledger operations​

  • Account balance queries
  • Transaction history retrieval
  • Transaction construction and submission
  • Transfer operations

Governance operations​

  • Neuron management (stake, dissolve, spawn)
  • Voting on governance proposals
  • Reward distribution queries
  • Network nervous system interactions

Supported endpoints​

ICP Rosetta implements the complete Rosetta specification including:

  • Data API: For querying blockchain data
  • Construction API: For creating and submitting transactions
  • Network API: For network information and status

Getting started​

To start using ICP Rosetta, you'll need to set up a Rosetta node. There are multiple deployment options available:

  • Docker deployment (recommended for most users)
  • Building from source (for development and customization)
  • Local cluster setup (for testing with monitoring tools)
  • Managed endpoints (no local setup required)

Test environment​

For testing and development, you can connect to the test ICP ledger (xafvr-biaaa-aaaai-aql5q-cai) that runs on mainnet but uses test tokens (TESTICP). Get free test tokens from Validation Cloud's faucet to start experimenting without using real ICP.

For detailed setup instructions, see the Running Rosetta guide.

Requirements and limitations​

The integration software provided has specific requirements and limitations.

Transaction timing requirement​

For transactions involving ICP tokens, the unsigned transaction must be created less than 24 hours before the network receives the signed transaction. This is due to the deduplication mechanism. Any submitted transaction that refers back to a transaction older than 24 hours is rejected to maintain operational efficiency.

Signature schemes​

The examples and documentation typically use:

  • Ed25519
  • SECP256k1

For the complete list of supported signature schemes, refer to the Rosetta specification.

Response format​

The integration software only replies with a subset of the potential responses that the specification supports. For example:

  • No UTXO features are implemented
  • No UTXO messages appear in any software responses

Compliance​

Other than the 24-hour transaction timing requirement, the Rosetta API integration software:

  • Fully complies with all standard Rosetta endpoints.
  • Passes all rosetta-cli tests.
  • Accepts any valid Rosetta request.

Frequently asked questions​

How do I run an instance of the Rosetta node?​

The easiest way is to use the dfinity/rosetta-api Docker image. See the Running Rosetta guide for detailed instructions on all deployment methods.

How do I connect the Rosetta node to the mainnet?​

Use the flags --mainnet and --not-whitelisted when starting your Rosetta node.

How do I know if the node has caught up with the network?​

Look for the log entry: You are all caught up to block XX in the startup logs after Starting Rosetta API server. This confirms synchronization with all blocks.

How do I persist synced block data?​

Mount the /data directory as a Docker volume:

docker volume create rosetta
docker run \
    --volume rosetta:/data \
    --publish 8081:8081 \
    --detach \
    dfinity/rosetta-api

Is the Rosetta node versioned?​

Yes, new versions are regularly published on DockerHub. It's recommended to use specific versions in production (e.g., dfinity/rosetta-api:v2.0.0).

You can query the version of a running node using the /network/options endpoint:

curl -H 'Content-Type: application/json' \
  -d '{"network_identifier": {"blockchain": "Internet Computer", "network": "00000000000000020101"}}' \
  -X POST http://localhost:8081/network/options | jq '.version.node_version'

What's the default port?​

The Rosetta node listens on port 8081 by default.

How do I get test tokens for development?​

Use Validation Cloud's free faucet to get TESTICP tokens from the test ICP ledger (xafvr-biaaa-aaaai-aql5q-cai). This allows you to test ICP Rosetta functionality without using real ICP tokens.