Skip to main content

Rosetta API

A standardized API for blockchain integration — query historical data, build transactions, and integrate with exchanges.

Rosetta API (rebranded as Mesh by Coinbase) is an open-source specification and set of tools that make deploying and interacting with blockchains quick and easy. Mina implements a subset of the Rosetta specification — not all endpoints defined in the spec are available. Mina's Rosetta implementation is primarily used by exchanges to integrate MINA deposits, withdrawals, and balance queries.

note

The Rosetta API is auxiliary to Mina's existing GraphQL API and Archive Node. While GraphQL provides access to current network state, historical and persistence data requires the Archive database. Rosetta bundles both data sources behind a standardized interface and exists primarily to satisfy exchange integration requirements.

Architecture​

The Rosetta stack consists of four components that work together:

ComponentDefault PortDescription
Mina Daemon8302 (P2P), 3085 (GraphQL)Syncs with the network, produces/validates blocks
Archive Node3086Stores historical block data in PostgreSQL
PostgreSQL5432Database backend for the archive node
Rosetta API3087 (online), 3088 (offline)Translates Mina data into the Rosetta specification

All ports listed above are defaults and can be overridden via configuration. When using Docker, these are the ports inside the container — map them to your desired host ports with -p.

Installation​

There are three ways to run Rosetta, depending on your needs.

The all-in-one image bundles the daemon, archive node, PostgreSQL, and Rosetta API into a single container. It automatically initializes the archive database from public o1Labs backups.

Requirements: Docker with at least 12 GB RAM allocated (16 GB recommended).

Mainnet​

docker run -it --rm --name rosetta \
  --entrypoint=./docker-start.sh \
  -p 8302:8302 -p 3085:3085 -p 3086:3086 -p 3087:3087 \
  minaprotocol/mina-rosetta:3.3.1-7b34378-noble-mainnet

Devnet​

docker run -it --rm --name rosetta \
  --entrypoint=./docker-start.sh \
  -p 8302:8302 -p 3085:3085 -p 3086:3086 -p 3087:3087 \
  -e MINA_NETWORK=devnet \
  -e PEER_LIST_URL=https://bootnodes.minaprotocol.com/networks/devnet.txt \
  minaprotocol/mina-rosetta:3.2.0-97ad487-bookworm-devnet

Initial sync typically takes between 20 minutes and 1 hour depending on your hardware and network connection. You can check sync status with:

docker exec rosetta mina client status

Environment Variables​

The all-in-one image supports the following environment variables for customization:

VariableDefaultDescription
MINA_NETWORKmainnetNetwork to connect to (mainnet or devnet)
PEER_LIST_URLNetwork-specific seed listURL for the peer list
LOG_LEVELDebugLog level (Info, Debug, Warn, Error)
MINA_GRAPHQL_PORT3085GraphQL API port
MINA_ARCHIVE_PORT3086Archive node port
MINA_ROSETTA_ONLINE_PORT3087Rosetta online API port
MINA_ROSETTA_OFFLINE_PORT3088Rosetta offline API port
POSTGRES_USERNAMEpguserPostgreSQL username
POSTGRES_DBNAMEarchivePostgreSQL database name
POSTGRES_DATA_DIR/data/postgresqlPostgreSQL data directory
MINA_ARCHIVE_DUMP_URLhttps://storage.googleapis.com/mina-archive-dumpsBase URL for archive database dumps
MINA_CONFIG_DIR/data/.mina-configMina configuration directory

For production deployments, use Docker Compose to run each component as a separate container. This gives you more control over resource allocation, logging, and restarts.

For production deployments, a complete Docker Compose configuration with all four services (PostgreSQL, archive node, Mina daemon, and Rosetta API) is available in the Rosetta Docker Compose guide.

Option 3: Debian Packages (Manual setup)​

You can install each component individually via Debian packages. This is useful if you already run a Mina daemon and archive node and only need to add the Rosetta API.

# Add the Mina repository (if not already configured)
echo "deb [trusted=yes] http://packages.o1test.net/ noble stable" | sudo tee /etc/apt/sources.list.d/mina.list
sudo apt-get update

# Install the Rosetta package for your network
sudo apt-get install mina-rosetta-mainnet
# or: sudo apt-get install mina-rosetta-devnet

Then run the Rosetta API pointing to your existing daemon and archive database:

mina-rosetta \
  --archive-uri postgres://<user>:<password>@<host>:<port>/<db> \
  --graphql-uri http://localhost:3085/graphql \
  --log-json \
  --port 3087

This requires a running Mina daemon and archive node with a populated PostgreSQL database.

Offline Mode​

The Rosetta Construction API requires an "offline" endpoint that can build and sign transactions without network access. Use the standalone entrypoint for this:

docker run -it --rm --name rosetta-offline \
  --entrypoint=./docker-standalone-start.sh \
  -p 3088:3088 \
  minaprotocol/mina-rosetta:3.3.1-7b34378-noble-mainnet

This starts only the Rosetta API process — no daemon, archive, or database. Point your Construction API calls to this endpoint for offline operations.

Demo Mode​

For development and testing, the demo mode launches a local sandbox with a simple genesis ledger and all components running inside a single container:

docker run -it --rm --name rosetta-demo \
  --entrypoint=./docker-demo-start.sh \
  -p 3085:3085 -p 3087:3087 \
  minaprotocol/mina-rosetta:3.3.1-7b34378-noble-mainnet

This creates an isolated network with no external connectivity — useful for developing integrations before connecting to mainnet or devnet.

Available Images​

NetworkImageNotes
Mainnet (noble)minaprotocol/mina-rosetta:3.3.1-7b34378-noble-mainnetamd64
Mainnet (bookworm)minaprotocol/mina-rosetta:3.3.1-7b34378-bookworm-mainnetAlso available for arm64
Devnet (bookworm)minaprotocol/mina-rosetta:3.2.0-97ad487-bookworm-devnetLatest devnet

Images are published on Docker Hub.

Verifying the API​

Once your node is synced, verify the Rosetta API is working.

List available networks:

curl -s http://localhost:3087/network/list \
  -H 'Content-Type: application/json' \
  -d '{"metadata":{}}' | jq .

Get network status:

curl -s http://localhost:3087/network/status \
  -H 'Content-Type: application/json' \
  -d '{"network_identifier": {"blockchain": "mina", "network": "mainnet"}}' | jq .

Query an account balance:

curl -s http://localhost:3087/account/balance \
  -H 'Content-Type: application/json' \
  -d '{
    "network_identifier": {"blockchain": "mina", "network": "mainnet"},
    "account_identifier": {"address": "<MINA_ADDRESS>"}
  }' | jq .

Building Your Own Image​

For most users, the official images are sufficient. If you need to build a custom image, see the Rosetta README in the Mina repository for build instructions.

Questions and Support​