# Rosetta API

> Install and run Mina's implementation of the Rosetta API for blockchain integration, historical data queries, and exchange support.

Canonical URL: https://docs.minaprotocol.com/node-operators/data-and-history/rosetta

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

[Rosetta API](https://www.rosetta-api.org/) (rebranded as [Mesh](https://docs.cdp.coinbase.com/mesh/docs/welcome/) 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](/node-operators/reference/mina-cli-reference) and [Archive Node](/node-operators/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:

| Component | Default Port | Description |
|---|---|---|
| **Mina Daemon** | 8302 (P2P), 3085 (GraphQL) | Syncs with the network, produces/validates blocks |
| **Archive Node** | 3086 | Stores historical block data in PostgreSQL |
| **PostgreSQL** | 5432 | Database backend for the archive node |
| **Rosetta API** | 3087 (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.

### Option 1: All-in-One Docker Image (Recommended for getting started)

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

```bash
docker run -it --rm --name rosetta \
  --entrypoint=./docker-start.sh \
  -p 8302:8302 -p 3085:3085 -p 127.0.0.1:3086:3086 -p 3087:3087 \
  minaprotocol/mina-rosetta:4.0.0-6850301-noble-mainnet
```

#### Devnet

```bash
docker run -it --rm --name rosetta \
  --entrypoint=./docker-start.sh \
  -p 8302:8302 -p 3085:3085 -p 127.0.0.1:3086:3086 -p 3087:3087 \
  -e MINA_NETWORK=devnet \
  -e PEER_LIST_URL=https://bootnodes.minaprotocol.com/networks/devnet.txt \
  minaprotocol/mina-rosetta:4.0.0-6965b50-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:

```bash
docker exec rosetta mina client status
```

#### Environment Variables

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

| Variable | Default | Description |
|---|---|---|
| `MINA_NETWORK` | `mainnet` | Network to connect to (`mainnet` or `devnet`) |
| `PEER_LIST_URL` | Network-specific seed list | URL for the peer list |
| `LOG_LEVEL` | `Debug` | Log level (`Info`, `Debug`, `Warn`, `Error`) |
| `MINA_GRAPHQL_PORT` | `3085` | GraphQL API port |
| `MINA_ARCHIVE_PORT` | `3086` | Archive node port |
| `MINA_ROSETTA_ONLINE_PORT` | `3087` | Rosetta online API port |
| `MINA_ROSETTA_OFFLINE_PORT` | `3088` | Rosetta offline API port |
| `POSTGRES_USERNAME` | `pguser` | PostgreSQL username |
| `POSTGRES_DBNAME` | `archive` | PostgreSQL database name |
| `POSTGRES_DATA_DIR` | `/data/postgresql` | PostgreSQL data directory |
| `MINA_ARCHIVE_DUMP_URL` | `https://storage.googleapis.com/mina-archive-dumps` | Base URL for archive database dumps |
| `MINA_CONFIG_DIR` | `/data/.mina-config` | Mina configuration directory |

### Option 2: Docker Compose (Recommended for production)

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](/node-operators/rosetta/docker-compose).

### 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.

```bash
# 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:

```bash
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](/node-operators/block-producer-node) and [archive node](/node-operators/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:

```bash
docker run -it --rm --name rosetta-offline \
  --entrypoint=./docker-standalone-start.sh \
  -p 3088:3088 \
  minaprotocol/mina-rosetta:4.0.0-6850301-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:

```bash
docker run -it --rm --name rosetta-demo \
  --entrypoint=./docker-demo-start.sh \
  -p 3085:3085 -p 3087:3087 \
  minaprotocol/mina-rosetta:4.0.0-6850301-noble-mainnet
```

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

## Available Images

| Network | Image | Notes |
|---|---|---|
| **Mainnet (noble)** | `minaprotocol/mina-rosetta:4.0.0-6850301-noble-mainnet` | amd64 |
| **Mainnet (bookworm)** | `minaprotocol/mina-rosetta:4.0.0-6850301-bookworm-mainnet` | Also available for arm64 |
| **Devnet (bookworm)** | `minaprotocol/mina-rosetta:4.0.0-6965b50-bookworm-devnet` | Latest devnet |

Images are published on [Docker Hub](https://hub.docker.com/r/minaprotocol/mina-rosetta/tags).

## Verifying the API

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

**List available networks:**

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

**Get network status:**

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

**Query an account balance:**

```bash
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 .
```

## Transaction metadata

In `/block` and `/search/transactions` responses, each payment, delegation, and zkApp command has a `metadata` object:

| Field | Description |
|--|--|
| `nonce` | Nonce of the fee payer. For a payment or a delegation, the fee payer is the sender. |
| `memo` | Memo of the transaction, as text. Not present when the memo is empty. |

```json
"metadata": { "nonce": 42, "memo": "deposit-7f3a" }
```

To match a deposit to a customer by memo, read `memo` from this object. Internal commands, such as coinbase and fee transfers, have no `metadata`.

## Building Your Own Image

For most users, the official images are sufficient. If you need to build a custom image, see the [Rosetta README](https://github.com/MinaProtocol/mina/blob/master/src/app/rosetta/README.md) in the Mina repository for build instructions.

## Questions and Support

- Post questions in [Mina GitHub Discussions](https://github.com/MinaProtocol/mina/discussions)
- Report bugs on [GitHub Issues](https://github.com/MinaProtocol/mina/issues)
- Join the [Mina Discord](https://discord.gg/minaprotocol) for community support