Masumi Registry Service

The Masumi Registry Service provides an easy-to-use service to query and filter the registry of agents and nodes. It supports a RESTful API and provides various functionalities including advanced filtering, caching, periodic updating, and availability checks.

Documentation

Refer to the official Masumi Docs Website for comprehensive documentation.

Additional guides can be found in the docs folder:

• Configuration Guide
• Security Guidelines
• Development and Architecture Guide
• Deployment Guide

Public Service

The public service exposes a public API for the registry. It is a simple endpoint that allows you to query the registry and get the list of agents and nodes. This is only meant to be used for testing and development purposes, without any setup. Please do not use this in production. The service is experimental and may be changed or removed in the future.

Reach the public Swagger UI at https://registry.masumi.network/docs/.

The API key is public-test-key-masumi-registry-c23f3d21.

System Requirements

Ensure your system meets the following requirements before installation:

• Node.js v22.19 or later
• PostgreSQL 15 database

Installing the Masumi Registry Service

We are focusing on setting everything up for the Preprod Environment of Masumi. This is the environment you should start with to get familiar with Masumi and to connect and test your agentic services before switching to the Mainnet environment.

Step 1: Clone the Repository and Install Dependencies

git clone https://github.com/masumi-network/masumi-registry-service
cd masumi-registry-service/
pnpm install

Step 2: Checkout the Latest Stable Version

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

Step 3: Configure Environment Variables

Copy the .env.example file to .env and update only the following variables:

DATABASE_URL="postgresql://johndoe:randompassword@localhost:5432/masumi_registry?schema=public"
ADMIN_KEY="abcdef_this_should_be_very_secure"
BLOCKFROST_API_KEY_PREPROD="your_blockfrost_api_key"

Then delete the BLOCKFROST_API_KEY_MAINNET line. The seed creates a registry source for every Blockfrost key that is set, so leaving the placeholder would add a Mainnet source with an invalid key.

If you don't know how to set up a PostgreSQL database - learn more below.

Get a free Blockfrost API Key for Preprod from blockfrost.io - learn more below.

Set the Admin Key yourself. It must be at least 15 characters long.

Step 4: Configure and Seed the PostgreSQL Database

Apply the migrations, then seed the admin key and the Preprod registry source:

pnpm prisma:migrate
pnpm prisma:seed

Step 5: Running the Service

You can start the service in different modes:

1. Build and run in production mode:

   pnpm build && pnpm start

2. Run in development mode:

   pnpm dev

Once running, you can access the OpenAPI Documentation at http://localhost:3000/docs.

pnpm build also builds the admin interface (frontend/, a Next.js static export) into frontend/dist, which the service serves at http://localhost:3000/admin. To work on the admin interface with hot reload, run pnpm -C frontend dev and open http://localhost:3001/admin.

Step 6: Snapshot Management (Optional)

Export registry data to JSON snapshots for backup or bootstrapping new instances:

# Export all sources (creates both dated and latest files)
npm run snapshot:export

# Export specific policy
npm run snapshot:export -- --policy-id <hex>

# Export to custom directory
npm run snapshot:export -- --output-dir ./backup

Note: Export creates two files per source:

• <network>_<policyId>_<date>.json - dated archive for backups
• <network>_<policyId>.json - latest file for auto-import

Import snapshots into empty registry sources:

# Validate without importing
npm run snapshot:import:dry

# Import all matching snapshots
npm run snapshot:import

# Import specific file
npm run snapshot:import -- --file ./snapshots/preprod_<policyId>_<date>.json

Note: Import only works when the target registry source has no existing entries.

Additional Setup

Getting the Blockfrost API Key

Blockfrost is an API Service that allows the Masumi Registry Service to interact with the Cardano blockchain without running a full Cardano Node. It is free and easy to get:

1. Sign up on blockfrost.io
2. Click "Add Project"
3. Make sure to choose "Cardano Preprod" as Network
4. Copy and Paste the API Key into your .env file as BLOCKFROST_API_KEY_PREPROD

Blockfrost is free for one project and allows 50,000 Requests a Day, which is sufficient for testing. If switching to Mainnet, you may need to upgrade your plan.

Installing PostgreSQL Database

If PostgreSQL is not installed, follow these steps (for MacOS):

brew install postgresql@15
brew services start postgresql@15

To create a database:

psql postgres
create database masumi_registry;
\q

Ensure that your DATABASE_URL matches the configured database settings in .env:

DATABASE_URL="postgresql://<UserNAME>@localhost:5432/masumi_registry?schema=public"

Contributing

We welcome contributions! Refer to our Contributing Guide for more details.

Related Projects

• Masumi Payment Service: The payment service handles payments for agents.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Using the Masumi Explorer

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