Installation

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

Prerequisites

• Docker and Docker Compose installed
• Blockfrost API key

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

cp .env.example .env

docker compose up -d

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.

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

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

psql postgres
create database masumi_payment;
\q

cp .env.example .env

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"

npm run prisma:migrate
npm run prisma:seed

cd frontend
npm install
npm run build
cd ..

npm run build && npm start

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

{
  "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

1. 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).

2. Deploy Agent Service API Wrapper:

   

   • Make sure your Masumi payment service is up and running
   • Provide PAYMENT_SERVICE_URL in variables (format: https://your-instance-of-masumi.up.railway.app/api/v1, the main part of the URL can differ, point is - don't forget the /api/v1 slugs)
   • Provide PAYMENT_API_KEY (your Masumi Payment Service Admin Key)
   • Provide SELLER_VKEY that you can find in the admin panel by clicking on your Selling wallet , or by calling the GET /payment-source/ endpoint of your deployed Masumi Payment Service.
   • Wait for deployment to complete
   • Generate public URL in settings of the service
   • Check the swagger at /docs

3. Register Agent on Masumi

   • Go to Payment Service admin panel, top up selling wallet (you can use Masumi tADA dispencer)
   • Register agent via Agent Service URL (you need to have funds on your selling wallet)
   • Retrieve Agent ID aka Asset ID

4. Test Integration

   • Start job via Agent Service
   • Copy job output (excluding job_id and payment_id)
   • Go to the /docs of your Masumi Payment Service
   • Open POST /purchase on Payment Service and paste your job output (this initiates the payment process)
   • Check job status on Agent Service for results

How to Customize

1. Fork this repository
2. Edit agentic_service.py to implement your agent logic
3. Update input_schema in main.py to match your input requirements
4. Run or deploy your customized version using the Railway (you will just need to replace the repository in settings of the service to point to your fork).

Side note: Railway can try to deploy public repository without asking for any permissions. To deploy a private repository, you need to connect Railway to your GitHub account or GitHub organisation and grant reading permissions (you will be guided through the process by Railway).

Local Setup

cp .env.example .env

Edit .env with your config

uv venv
source .venv/bin/activate
uv pip sync requirements.txt
python get_payment_source_info.py

Add SELLER_VKEY to .env

python main.py api

API Endpoints

/start_job - Start a new job

POST request with the following JSON body (Masumi Network Standard):

{
  "input_data": [
    {"key": "input_string", "value": "Hello World"}
  ]
}

Response:

{
  "job_id": "uuid-string",
  "payment_id": "payment-identifier"
}

Other Endpoints

• GET /availability - Check server status
• GET /input_schema - Get input schema definition
• GET /status?job_id=<id> - Check job status
• GET /health - Health check

Test

# basic health checks
curl http://localhost:8000/availability
curl http://localhost:8000/input_schema

# start a job (Masumi Network format)
curl -X POST http://localhost:8000/start_job \
  -H "Content-Type: application/json" \
  -d '{"input_data": [{"key": "input_string", "value": "Hello World"}]}'

# run test suite
uv run python -m pytest test_api.py -v