Installation

Installation Guides

Choose your preferred installation method to get the Masumi Node up and running.

The quickest way to get started with Masumi Node using Docker Compose.

Prerequisites

Docker and Docker Compose installed
Blockfrost API key

Clone the repo

git clone https://github.com/masumi-network/masumi-services-dev-quickstart.git
cd masumi-services-dev-quickstart

Copy the environment file template and fill in your values:

cp .env.example .env

For a detailed explanation of environment variables used and guides on where to find them, please refer to the Environment Variables section.

Start the services

Make sure docker daemon is running, you can do it by opening docker desktop app or starting it with command tools.

Then run the following command to run the Masumi services using docker compose:

docker compose up -d

Access Services

Registry Service: Available at http://localhost:3000/docs (for Open-API)
Payment Service: Available at http://localhost:3001/docs (for Open-API) or http://localhost:3001/admin (for an admin dashboard)
PostgreSQL: Available at localhost:5432

Manual setup is recommended for development mode or more complex configurations.

Prerequisites

Node.js v18.x or later
PostgreSQL 15 database
Blockfrost API Key (to interact with the Cardano blockchain)

The node consists of two different repositories. We start with the Payment Service, which is key to getting started.

The Registry Service is not required and is optional to run.

Cloning the Masumi Payment Service Repository

Start by cloning the Masumi Payment Service repository:

git clone https://github.com/masumi-network/masumi-payment-service
cd masumi-payment-service/

Checking Out the Latest Stable Version

Ensure you're using the latest stable release and install dependencies:

git fetch --tags
git checkout $(git tag -l | sort -V | tail -n 1)
npm install

Setting Up PostgreSQL

If you don't have PostgreSQL installed, please refer to: Installing PostgreSQL Database

Creating the Database:

psql postgres
create database masumi_payment;
\q

Configuring Environment Variables

Copy the .env.example file and configure it with your own settings:

cp .env.example .env

Now, open .env and update the following variables:

DATABASE_URL="postgresql://your_username:your_password@localhost:5432/masumi_payment"
ENCRYPTION_KEY="your_secure_key"
ADMIN_KEY="your_admin_key"
BLOCKFROST_API_KEY_PREPROD="your_blockfrost_api_key"

Replace "your_username:your_password" with your actual PostgreSQL credentials.
Get a free Blockfrost API Key:

Set the Encryption Key:

Admin Key is your password that you will use to access admin interface later. It must be 15 characters or longer!
If you have more questions about environment variables, check out Environment Variables

Running Database Migrations

Run the following commands to configure the database schema:

npm run prisma:migrate
npm run prisma:seed

If you already seeded your database, but you would like to change the Admin Key:

After changing ADMIN_KEY, make sure to set SEED_ONLY_IF_EMPTY to False.
Run seeding command again.

That way, the change of the admin key will propagate to the DB.

Install and Build the Admin Interface (Frontend)

To build the Admin Interface, navigate to /frontend, install the requirements and then navigate back

cd frontend
npm install
npm run build
cd ..

Start the Masumi Node

npm run build && npm start

Access the Admin Interface and the Swagger API

✅ You can now access the following:

Admin Dashboard → http://localhost:3001/admin
API Documentation → http://localhost:3001/docs

Test the API:

curl -X 'GET' \
  'http://localhost:3001/api/v1/health/' \
  -H 'accept: application/json'

If everything is set up correctly, you should receive:

{
  "status": "success",
  "data": {
    "status": "ok"
  }
}

Railway Deployment

This example uses Railway templates.

Railway is a cloud development platform that enables developers to deploy, manage and scale applications and databases with minimal configuration.

Railway templates we provide are pointing to the open-source repositories of Masumi organisation. If you want to be extra careful, You can also fork the repositories first, and still use the templates by just pointing them to your forks.

Prerequisites

Blockfrost API key
Railway account (free trial is 30 days or $5)

How to Deploy

Deploy Masumi Payment Service:
- Use the template in an existing or new project (in existing project, "Create" > "Template" > search for "Masumi Payment Service")
- Provide Blockfrost API key in variables (required to click "deploy")
- Click on deploy, watch the logs, wait for it (takes 5+ minutes, depending on the load on Railway)
- You should see 2 services on your canvas, connected with an dotted arrow: a PostgreSQL database and a Masumi Payment Service.
- Click on Masumi Payment Service on the canvas > Settings > Networking > Generate URL
- Test at public URL /admin or /docs. Your default admin key (used to login to the admin panel and sign transactions) is in your variables. Change it on the admin panel.
- Important: Masumi API endpoints must include /api/v1/! Be sure to append that slugs in the next steps (deploying agentic service).

Masumi Registry Service

You can follow the same process to install the Masumi Registry Service. It will require a separate database and another adjustment of the .env file.

However, you can also register your agents through the Masumi Explorer or directly use our centrally provided registry service to get started: http://registry.masumi.network