### Install Masumi Node using Docker Compose

Source: https://context7.com/masumi-network/masumi-docs/llms.txt

Quickstart guide to install and run a Masumi Node using Docker Compose. Requires cloning the repository, configuring environment variables, and starting the services.

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

cp .env.example .env
# Edit .env with your Blockfrost API key, encryption key, and admin key

docker compose up -d

curl -X GET 'http://localhost:3001/api/v1/health/' -H 'accept: application/json'
# Expected:
# { "status": "success", "data": { "status": "ok" } }
```

--------------------------------

### Install and Start PostgreSQL

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/installing-postgresql-database.mdx

Use Homebrew to install PostgreSQL version 15 and start the service.

```bash
brew install postgresql@15
brew services start postgresql@15
```

--------------------------------

### Install and Configure PostgreSQL

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Installs PostgreSQL 15, starts and enables the service, and creates a dedicated database and user for Masumi.

```bash
apt install -y postgresql postgresql-contrib
systemctl start postgresql
systemctl enable postgresql
```

```sql
CREATE DATABASE masumi_payment;
CREATE USER masumi_user WITH ENCRYPTED PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE masumi_payment TO masumi_user;
\q
```

--------------------------------

### Install Masumi Payment Service Manually

Source: https://context7.com/masumi-network/masumi-docs/llms.txt

Manual setup guide for the Masumi Payment Service on production VPS deployments. Requires Node.js 18+, PostgreSQL 15+, cloning the repository, installing dependencies, configuring environment variables, and running migrations.

```bash
# Clone, check out latest stable tag, install deps
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

# Create PostgreSQL database
psql postgres -c "create database masumi_payment;"

# Configure environment
cp .env.example .env
# Minimum required variables in .env:
# DATABASE_URL="postgresql://username:password@localhost:5432/masumi_payment"
# ENCRYPTION_KEY="<openssl rand -hex 32>"
# ADMIN_KEY="<at-least-15-chars>"
# BLOCKFROST_API_KEY_PREPROD="<from blockfrost.io>"

# Run migrations and seed
npm run prisma:migrate
npm run prisma:seed

# Build frontend admin UI
cd frontend && npm install && npm run build && cd ..

# Build and start
npm run build && npm start

# Test
curl http://localhost:3001/api/v1/health
# { "status": "success", "data": { "status": "ok" } }
```

--------------------------------

### Clone Masumi Payment Service Repository

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/get-started/installation.mdx

Start the manual setup by cloning the Masumi Payment Service repository.

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

--------------------------------

### Run Development Server

Source: https://github.com/masumi-network/masumi-docs/blob/main/README.md

Use these commands to start the development server for the Masumi Docs project. Ensure you have Node.js installed.

```bash
npm run dev
# or
pnpm dev
# or
yarn dev
```

--------------------------------

### Clone Masumi Services Dev Quickstart Repo

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/get-started/installation.mdx

Clone the repository to start with the Docker Compose installation method.

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

--------------------------------

### Build and Start Masumi Node

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/get-started/installation.mdx

Build the project and start the Masumi Node application.

```bash
npm run build && npm start
```

--------------------------------

### Server Setup for Masumi Node on Ubuntu

Source: https://context7.com/masumi-network/masumi-docs/llms.txt

Installs necessary packages like Docker and Docker Compose on Ubuntu 22.04. Ensure you have root privileges or use sudo for these commands.

```bash
apt update && apt upgrade -y
apt install -y apt-transport-https ca-certificates curl software-properties-common git nginx
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | apt-key add -
add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
apt update && apt install -y docker-ce
curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" \
  -o /usr/local/bin/docker-compose && chmod +x /usr/local/bin/docker-compose
```

--------------------------------

### Install and Build Admin Interface

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/get-started/installation.mdx

Navigate to the frontend directory, install its requirements, build the interface, and return to the root directory.

```bash
cd frontend
npm install
npm run build
cd ..
```

--------------------------------

### Manually Install Masumi Skill

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/integrations/masumi-skills.mdx

Follow these steps to manually install the Masumi skill by cloning the repository and running the install script.

```bash
git clone https://github.com/masumi-network/masumi-skills
cd masumi-skills
./install.sh
```

--------------------------------

### Install and Configure PM2 for Process Management

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Installs PM2, a process manager, to keep the Masumi Node running in the background. Includes commands to start the service, save configuration, and set up auto-start on reboot.

```bash
npm install -g pm2
npm run build
pm2 start npm --name "masumi-node" -- start
pm2 save
pm2 startup
```

--------------------------------

### Get Demo Data

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/technical-documentation/agentic-service-api.mdx

Retrieves example input and output data for demonstration purposes without executing an actual job.

```APIDOC
## GET /demo

### Description
Returns example input and output data for marketing purposes, without running an actual job.

### Method
GET

### Endpoint
/demo

### Response
#### Success Response (200)
- **input** (object) - Example input data for a job.
- **output** (object) - Example output data from a job.

#### Response Example
```json
{
  "input": {
    "full_name": "Alice Johnson",
    "email": "alice@example.com",
    "job_history": "Software Engineer at XYZ Corp, 2018–2023",
    "design_style": "Modern"
  },
  "output": {
    "result": "Resume generated successfully with modern design template."
  }
}
```

#### Error Responses
- `500 Internal Server Error`: If demo data cannot be retrieved.
```

--------------------------------

### Initial Server Setup: Update System

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Run these commands after SSHing into your new VPS instance to ensure the system is up-to-date.

```bash
ssh root@your_instance_ip
```

```bash
apt update && apt upgrade -y
```

--------------------------------

### Install Git

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Installs the Git version control system, which is required for cloning repositories.

```bash
apt install -y git
```

--------------------------------

### Start Generic Agent with PM2

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Starts a generic agent process using PM2. Adjust 'your-start-command' as needed.

```bash
pm2 start your-start-command --name "my-agent"
```

--------------------------------

### Install n8n-nodes-masumi-payment

Source: https://context7.com/masumi-network/masumi-docs/llms.txt

Install the Masumi payment community node for n8n. Restart n8n after manual installation to load the new nodes.

```bash
# Option 1: Via n8n Settings → Community Nodes → search "n8n-nodes-masumi-payment"

# Option 2: Manual install in your n8n directory
npm install n8n-nodes-masumi-payment
# Restart n8n to load the new nodes
```

--------------------------------

### Development Setup and Build Commands

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/n8n-node/index.mdx

Standard commands for setting up the development environment, building the project, and linting the code.

```bash
npm install && npm run build && npm run lint
```

--------------------------------

### Mint Example Registry Asset

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/technical-documentation/smart-contracts/registry-smart-contract.mdx

Execute this script to mint an example registry asset. The metadata for minting can be configured in the `mint-example.mjs` file. Requires Node.js and npm dependencies.

```bash
npm run mint
```

--------------------------------

### Install Node.js 18.x

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Installs Node.js version 18.x, which is a requirement for the Masumi Node. Verifies the installation.

```bash
curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
apt install -y nodejs
```

```bash
node --version  # Should show v18.x.x
npm --version
```

--------------------------------

### PostgreSQL Connection String Example

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/technical-documentation/environment-variables.mdx

Example of a PostgreSQL connection string for the Payment Service. Ensure the database has been migrated.

```sql
postgresql://user:password@localhost:5432/masumi?schema=public
```

--------------------------------

### Install Python Agent Dependencies

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Sets up a Python virtual environment and installs project dependencies from requirements.txt.

```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

--------------------------------

### Copy Environment File Template

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/get-started/installation.mdx

Copy the example environment file to create your own configuration.

```bash
cp .env.example .env
```

--------------------------------

### Install Docker Dependencies for Agent

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Installs Docker and Docker Compose, and starts/enables the Docker service.

```bash
apt install -y docker.io docker-compose git
systemctl start docker
systemctl enable docker
```

--------------------------------

### Run Development Server

Source: https://github.com/masumi-network/masumi-docs/blob/main/CURSOR-INSTRUCTIONS.md

Starts the development server to test navigation and content locally. Restart this server after making changes.

```bash
npm run dev
```

--------------------------------

### Start Node.js Agent with PM2

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Starts a Node.js agent using PM2, typically by running the 'start' script defined in package.json.

```bash
pm2 start npm --name "my-agent" -- start
```

--------------------------------

### Get Demo Data Response

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/technical-documentation/agentic-service-api.mdx

Example JSON response from the /demo endpoint, providing sample input and output data for marketing purposes. This includes fields like 'full_name', 'email', and 'job_history'.

```json
{
  "input": {
    "full_name": "Alice Johnson",
    "email": "alice@example.com",
    "job_history": "Software Engineer at XYZ Corp, 2018–2023",
    "design_style": "Modern"
  },
  "output": {
    "result": "Resume generated successfully with modern design template."
  }
}
```

--------------------------------

### Install Nginx Web Server

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Installs the Nginx web server, commonly used for reverse proxying.

```bash
apt install -y nginx
```

--------------------------------

### Checkout Latest Stable Version and Install Dependencies

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/get-started/installation.mdx

Ensure you are using the latest stable release and install project dependencies.

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

--------------------------------

### GET /demo

Source: https://context7.com/masumi-network/masumi-docs/llms.txt

Returns sample input/output for display on Sokosumi marketplace without running an actual job.

```APIDOC
## GET /demo — Get Demo Data

### Description
Returns sample input/output for display on Sokosumi marketplace without running an actual job.

### Method
GET

### Endpoint
/demo

### Response
#### Success Response (200)
- **input** (object) - Sample input data.
- **output** (object) - Sample output data.

#### Response Example
```json
{
  "input": {
    "full_name": "Alice Johnson",
    "email": "alice@example.com",
    "design_style": "Modern"
  },
  "output": {
    "result": "Resume generated successfully with modern design template."
  }
}
```
```

--------------------------------

### Install Masumi SDK

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/human-in-the-loop.mdx

Install the Masumi Python SDK using pip. This is required to use Masumi's features, including HITL.

```bash
pip install masumi
```

--------------------------------

### Install Docker Compose

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Downloads and installs the latest version of Docker Compose. This command ensures the binary is executable.

```bash
curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose
```

--------------------------------

### Start Python Agent with PM2

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Starts a Python agent using PM2, specifying the interpreter and a name for the process.

```bash
pm2 start "python3 main.py api" --name "my-agent" --interpreter python3
```

--------------------------------

### Build Smart Contracts with Aiken

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/technical-documentation/smart-contracts/registry-smart-contract.mdx

Use this command to generate the smart contracts. Ensure Aiken is installed and in your PATH.

```bash
aiken build
```

--------------------------------

### Clone and Prepare Masumi Payment Service

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Installs Git, clones the Masumi Payment Service repository, checks out the latest stable version, and installs project dependencies.

```bash
apt install -y git
cd /opt
git clone https://github.com/masumi-network/masumi-payment-service.git
cd masumi-payment-service
git fetch --tags
git checkout $(git tag -l | sort -V | tail -n 1)
npm install
```

--------------------------------

### Provide Input Response

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/technical-documentation/agentic-service-api.mdx

Example JSON response after successfully providing input for a job.

```json
{
  "input_hash": "a87ff679a2f3e71d9181a67b7542122c",
  "signature": "8a5fd6602094407b7e5923aa0f2694f8cb5cf39f317a61059fdc572e24fc1c7660d23c04d46355aed78b5ec35ae8cad1433e7367bb874390dfe46ed155727a08"
}
```

--------------------------------

### Generate Aiken Documentation

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/technical-documentation/smart-contracts/registry-smart-contract.mdx

Use this command to generate HTML documentation for your Aiken library. Ensure Aiken is installed.

```bash
aiken docs
```

--------------------------------

### Complete Purchase Flow

Source: https://context7.com/masumi-network/masumi-docs/llms.txt

A step-by-step guide for the end-to-end buyer flow, including discovering agents, starting jobs, paying, and retrieving results.

```APIDOC
## End-to-End Buyer Flow

### Complete Purchase Flow — Discover, Start, Pay, Retrieve

Full walkthrough combining Registry Service, Agentic Service API, and Payment Service.

```bash
# ── Step 1: Discover agent ────────────────────────────────────────────────
curl 'http://localhost:3000/api/v1/payment-information?agentIdentifier=a1b2c3d4...'
  -H 'token: YOUR_API_KEY'
# Capture: sellerVkey, agentIdentifier, apiBaseUrl, pricing

# ── Step 2: Start job on agent ────────────────────────────────────────────
curl -X POST 'https://my-agent.example.com/start_job'
  -H 'Content-Type: application/json'
  -d '{
    "identifier_from_purchaser": "a3f9bc12e4d78b",
    "input_data": { "prompt": "Summarize the Masumi whitepaper" }
  }'
# Capture: blockchainIdentifier, payByTime, submitResultTime, unlockTime, externalDisputeUnlockTime

# ── Step 3: Compute input hash ────────────────────────────────────────────
# SHA-256(hex) of the input_data object (canonical JSON)
# Python: hashlib.sha256(json.dumps(input_data, sort_keys=True, separators=(',',':')).encode()).hexdigest()
```
```

--------------------------------

### Copy and Configure Environment Variables

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/get-started/installation.mdx

Copy the example environment file and update it with your specific database credentials, encryption key, admin key, and Blockfrost API key.

```ini
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"
```

--------------------------------

### Install n8n-nodes-masumi-payment via npm

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/n8n-node/index.mdx

Use this command to manually install the n8n community node package in your n8n installation directory. Remember to restart n8n after installation.

```bash
# in your n8n installation directory
npm install n8n-nodes-masumi-payment

# Restart n8n
```

--------------------------------

### Wiring Masumi App with Storage Backend

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/technical-documentation/agent-state-persistence.mdx

Demonstrates how to instantiate a storage backend (SQLite or PostgreSQL) and pass it to `create_masumi_app`. This configures the Masumi application to use the specified storage for job management.

```python
from masumi import create_masumi_app, MasumiConfig

storage = SQLiteJobStorage("production_jobs.db")
# or: storage = PostgresJobStorage("postgresql://user:pass@localhost/agentdb")

app = create_masumi_app(
    config=MasumiConfig(),
    job_storage=storage,
    start_job_handler=process_job,
    input_schema_handler=get_schema,
)
```

--------------------------------

### Install Node.js Agent Dependencies

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Installs Node.js project dependencies using npm.

```bash
npm install
```

--------------------------------

### Configure Agent Environment Variables

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/technical-documentation/agent-identity-nft.mdx

Set up your agent's .env file with essential credentials and network settings for registration.

```bash
PAYMENT_SERVICE_URL=http://localhost:3001/api/v1
SELLER_VKEY=your_seller_vkey_here
PAYMENT_API_KEY=your_payment_api_key_here
NETWORK=Preprod
```

--------------------------------

### Common Workflow: Deploy at Scale

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/integrations/masumi-skills.mdx

This sequence outlines the steps for deploying agents at scale using Kodosumi and Masumi.

```text
Build Agent → Deploy on Kodosumi → List on Sokosumi → Payments via Masumi
```

--------------------------------

### Install Node.js Dependencies for Agent

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Installs Node.js version 18.x and git, required for Node.js-based agents.

```bash
curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
apt install -y nodejs git
```

--------------------------------

### POST /start_job

Source: https://context7.com/masumi-network/masumi-docs/llms.txt

Initiates a job with input data. The agent returns payment timing parameters needed for the escrow call.

```APIDOC
## POST /start_job — Start a Job on an Agent

### Description
Initiates a job with input data. The agent returns payment timing parameters needed for the escrow call.

### Method
POST

### Endpoint
/start_job

### Request Body
- **identifier_from_purchaser** (string) - Required - A unique identifier from the purchaser.
- **input_data** (object) - Required - The data required for the job.
  - **full_name** (string) - Required - The full name of the individual.
  - **email** (string) - Required - The email address.
  - **job_history** (string) - Optional - The job history details.
  - **design_style** (string) - Optional - The preferred design style.

### Request Example
```json
{
  "identifier_from_purchaser": "a3f9bc12e4d78b",
  "input_data": {
    "full_name": "Alice Johnson",
    "email": "alice@example.com",
    "job_history": "Software Engineer at XYZ Corp, 2018-2023",
    "design_style": "Modern"
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the job.
- **blockchainIdentifier** (string) - Identifier for the blockchain transaction.
- **payByTime** (integer) - Timestamp indicating when payment is due.
- **submitResultTime** (integer) - Timestamp for when the result was submitted.
- **unlockTime** (integer) - Timestamp for when the result will be unlocked.
- **externalDisputeUnlockTime** (integer) - Timestamp for when an external dispute can be unlocked.
- **agentIdentifier** (string) - The agent's unique identifier.
- **sellerVKey** (string) - The seller's verification key.
- **identifierFromPurchaser** (string) - The identifier from the purchaser.
- **input_hash** (string) - The hash of the input data.

#### Response Example
```json
{
  "id": "18d66eed-6af5-4589-b53a-d2e78af657b6",
  "blockchainIdentifier": "block_789def",
  "payByTime": 1721480200,
  "submitResultTime": 1717171717,
  "unlockTime": 1717172717,
  "externalDisputeUnlockTime": 1717173717,
  "agentIdentifier": "a1b2c3d4...",
  "sellerVKey": "addr1qxlkjl23k...",
  "identifierFromPurchaser": "a3f9bc12e4d78b",
  "input_hash": "a87ff679a2f3e71d9181a67b7542122c"
}
```
```

--------------------------------

### Agent Metadata Example

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/get-started/register-agent.mdx

An example of the JSON structure for agent metadata, following the Registry Metadata Standard.

```APIDOC
## Agent Metadata Example

This is an example of the JSON structure for agent metadata, following the Registry Metadata Standard.

```json
{
  "name": ["My AI Agent"],
  "description": ["An intelligent agent that processes natural language"],
  "api_url": ["https://my-agent.example.com"],
  "capability": {
    "name": ["text-processing"],
    "version": ["1.0.0"]
  },
  "requests_per_hour": ["100"],
  "author": {
    "name": ["John Doe"],
    "contact": ["john@example.com"],
    "organization": ["Example Corp"]
  },
  "tags": ["nlp", "text-processing", "ai"],
  "pricing": [
    {
      "quantity": 1,
      "unit": "c48cbb3d5e57ed56e276bc45f99ab39abe94e6cd7ac39fb402da47ad0014df105553444d"
    }
  ],
  "metadata_version": 1
}
```

**Note on Pricing Unit:**
- For Preprod (testnet) tUSDM: `16a55b2a349361ff88c03788f93e1e966e5d689605d044fef722ddde0014df10745553444d`
- For Mainnet USDM: `c48cbb3d5e57ed56e276bc45f99ab39abe94e6cd7ac39fb402da47ad0014df105553444d`
```

--------------------------------

### Configure Masumi Payment Service Environment

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Copies the example environment file and configures essential variables for database connection, security, API keys, and network settings.

```bash
cp .env.example .env
nano .env
```

```ini
# Database
DATABASE_URL="postgresql://masumi_user:your_secure_password@localhost:5432/masumi_payment?schema=public"

# Security
ENCRYPTION_KEY="your_secure_encryption_key_32_chars_min"
ADMIN_KEY="your_admin_password_15_chars_min"

# Blockfrost API
BLOCKFROST_API_KEY_PREPROD="your_blockfrost_api_key"
BLOCKFROST_API_KEY_MAINNET="your_mainnet_key_if_using"

# Network
NETWORK=Preprod

# Server Configuration
PORT=3001
HOST=0.0.0.0
```

--------------------------------

### Install Python Dependencies for Agent

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Installs Python 3, pip, and venv, which are common dependencies for Python-based agents.

```bash
apt install -y python3 python3-pip python3-venv git
```

--------------------------------

### Build Frontend and Run Database Migrations

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Builds the frontend admin interface and executes database migrations and seeding scripts.

```bash
cd frontend
npm install
npm run build
cd ..
npm run prisma:migrate
npm run prisma:seed
```

--------------------------------

### Verify Docker and Docker Compose Installation

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Checks if Docker and Docker Compose have been installed correctly by displaying their versions.

```bash
docker --version
docker-compose --version
```

--------------------------------

### Start a Job on an Agent

Source: https://context7.com/masumi-network/masumi-docs/llms.txt

Initiates a job with input data. The agent returns payment timing parameters needed for the escrow call. Ensure 'identifier_from_purchaser' and 'input_data' are correctly formatted.

```bash
curl -X POST 'https://my-agent.example.com/start_job' \
  -H 'Content-Type: application/json' \
  -d '{
    "identifier_from_purchaser": "a3f9bc12e4d78b",
    "input_data": {
      "full_name": "Alice Johnson",
      "email": "alice@example.com",
      "job_history": "Software Engineer at XYZ Corp, 2018-2023",
      "design_style": "Modern"
    }
  }'
```

--------------------------------

### View Differences Between Staging and Main

Source: https://github.com/masumi-network/masumi-docs/blob/main/STAGING_SETUP_GUIDE.md

Display the differences between the main and staging-docs branches.

```bash
git diff main..staging-docs
```

--------------------------------

### Meta.json with Icons and Root

Source: https://github.com/masumi-network/masumi-docs/blob/main/CURSOR-INSTRUCTIONS.md

Example of a meta.json file with an icon, root property, and a list of pages, including specific MIPs and attachments.

```json
{
  "title": "MIPs",
  "icon": "FileText",
  "root": true,
  "pages": [
    "index",
    "_mip-001",
    "_mip-002",
    "_mip-003",
    "mip-003-attachment-01",
    "_mip-004"
  ]
}
```

--------------------------------

### Install Docker CE on Ubuntu

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Installs Docker Community Edition and its dependencies on Ubuntu systems. Ensure you have the necessary prerequisites.

```bash
apt install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | apt-key add -
add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
apt update
apt install -y docker-ce
```

--------------------------------

### GET /registry/

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/get-started/register-agent.mdx

Check the status of your agent registration by calling the GET /registry/ endpoint. This will return your agentIdentifier once registration is complete.

```APIDOC
## GET /registry/

### Description
Check the status of your agent registration by calling the `GET /registry/` endpoint. This will return your `agentIdentifier` once registration is complete.

### Method
GET

### Endpoint
`/registry/`

### Response
#### Success Response (200)
- **agentIdentifier** (string) - The unique identifier for your registered agent.

#### Error Response (400, 401, 500)
- **error** (string) - Description of the error.
```

--------------------------------

### Install PM2 Process Manager

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Installs PM2 globally, a production process manager for Node.js applications with a built-in load balancer.

```bash
npm install -g pm2
```

--------------------------------

### Get Demo Data

Source: https://context7.com/masumi-network/masumi-docs/llms.txt

Returns sample input/output for display on Sokosumi marketplace without running an actual job. Useful for showcasing agent capabilities.

```bash
curl 'https://my-agent.example.com/demo'
```

--------------------------------

### Get Payment Details for a Specific Agent

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/core-concepts/identity.mdx

Once you have an agentIdentifier, use GET /payment-information to retrieve everything needed to initiate a payment to that agent.

```APIDOC
## GET /payment-information

### Description
Retrieves payment details for a specific agent using their agent identifier.

### Method
GET

### Endpoint
https://<your-registry-node>/api/v1/payment-information

### Parameters
#### Query Parameters
- **agentIdentifier** (string) - Required - The unique identifier of the agent.

### Request Example
```bash
curl "https://<your-registry-node>/api/v1/payment-information?agentIdentifier=a1b2c3d4..." \
  -H "token: <your-api-key>"
```

### Response
#### Success Response (200)
- **status** (string) - The status of the response (e.g., "success").
- **data** (object) - Contains the payment information for the agent.
  - **agentIdentifier** (string) - The unique identifier for the agent.
  - **name** (string) - The name of the agent service.
  - **status** (string) - The current status of the agent.
  - **sellerWallet** (object) - The agent's wallet information.
    - **address** (string) - The agent's wallet address.
    - **vkey** (string) - The agent's verification key.
  - **AgentPricing** (object) - Pricing information for the agent.
    - **pricingType** (string) - The type of pricing (e.g., "Fixed").
    - **Pricing** (array) - A list of pricing details.
      - **amount** (string) - The price amount.
      - **unit** (string) - The currency unit (e.g., "lovelace").
  - **apiBaseUrl** (string) - The base URL for the agent's API.

### Response Example
```json
{
  "status": "success",
  "data": {
    "agentIdentifier": "a1b2c3d4e5f6...",
    "name": "My Agentic Service",
    "status": "Online",
    "sellerWallet": {
      "address": "addr1...",
      "vkey": "..."
    },
    "AgentPricing": {
      "pricingType": "Fixed",
      "Pricing": [{ "amount": "1000000", "unit": "lovelace" }]
    },
    "apiBaseUrl": "https://my-agent.example.com"
  }
}
```
```

--------------------------------

### Save and Enable PM2 Startup

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/hosting-guide.mdx

Saves the current PM2 process list and configures PM2 to start automatically on system boot.

```bash
pm2 save
pm2 startup
```

--------------------------------

### GET /registry-entry/

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/get-started/register-agent.mdx

Verify your agent's registration by querying the registry using the GET /registry-entry/ endpoint. This endpoint retrieves a list of all online and health-checked agents.

```APIDOC
## GET /registry-entry/

### Description
Verify your agent's registration by querying the registry using the `GET /registry-entry/` endpoint. This endpoint retrieves a list of all online and health-checked agents. Your agent should appear in this list once the registration is confirmed.

### Method
GET

### Endpoint
`/registry-entry/`

### Response
#### Success Response (200)
- **agents** (array) - A list of registered agents, including their status and health information.

#### Error Response (400, 401, 500)
- **error** (string) - Description of the error.
```

--------------------------------

### Run Build Command

Source: https://github.com/masumi-network/masumi-docs/blob/main/CURSOR-INSTRUCTIONS.md

Builds the documentation site. This command is used to catch errors early and verify the production build.

```bash
npm run build
```

--------------------------------

### Start Job Endpoint Input

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/n8n-node/index.mdx

This JSON object represents the input required to start a job, including purchaser identification and input data for the agent. It is sent to the `/start_job` endpoint.

```json
{
  "identifier_from_purchaser": "user123",
  "input_data": [
    {"key": "prompt", "value": "analyze this text"}
  ]
}
```

--------------------------------

### Create Masumi Database

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/installing-postgresql-database.mdx

Connect to the default PostgreSQL database and create a new database named 'masumi_payment'.

```bash
psql postgres
create database masumi_payment
\q
```

--------------------------------

### Testing HITL Locally with Masumi CLI

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/documentation/how-to-guides/human-in-the-loop.mdx

A sequence of commands to test the HITL workflow locally. This includes starting the agent, starting a job, polling its status, providing input, and polling status again.

```bash
# 1. Start the agent
masumi run

# 2. Start a job (returns job_id)
curl -X POST http://localhost:8080/start_job \
  -H "Content-Type: application/json" \
  -d '{"input_data": {"text": "hello world"}, "identifier_from_purchaser": "test-123"}'

# 3. Poll status — should show awaiting_input
curl "http://localhost:8080/status?job_id=<JOB_ID>"

# 4. Provide the input
curl -X POST http://localhost:8080/provide_input \
  -H "Content-Type: application/json" \
  -d '{"job_id": "<JOB_ID>", "input_data": {"approve": true}}'

# 5. Poll status again — should show completed
curl "http://localhost:8080/status?job_id=<JOB_ID>"
```

--------------------------------

### Payment Information Response Example

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/core-concepts/identity.mdx

Example JSON response for payment information. It provides the agent's identifier, name, status, seller wallet details, pricing, and API base URL.

```json
{
  "status": "success",
  "data": {
    "agentIdentifier": "a1b2c3d4e5f6...",
    "name": "My Agentic Service",
    "status": "Online",
    "sellerWallet": {
      "address": "addr1...",
      "vkey": "..."
    },
    "AgentPricing": {
      "pricingType": "Fixed",
      "Pricing": [{ "amount": "1000000", "unit": "lovelace" }]
    },
    "apiBaseUrl": "https://my-agent.example.com"
  }
}
```

--------------------------------

### Registry Search Response Example

Source: https://github.com/masumi-network/masumi-docs/blob/main/content/docs/core-concepts/identity.mdx

Example JSON response from the Registry Service when searching for agents. It details agent information including agentIdentifier, name, status, API URL, and payment details.

```json
{
  "status": "success",
  "data": {
    "entries": [
      {
        "agentIdentifier": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
        "name": "My Agentic Service",
        "status": "Online",
        "apiBaseUrl": "https://my-agent.example.com",
        "paymentType": "Web3CardanoV1",
        "RegistrySource": {
          "policyId": "abc123...",
          "type": "Web3CardanoV1"
        },
        "Capability": { "name": "text-generation", "version": "1.0.0" },
        "AgentPricing": {
          "pricingType": "Fixed",
          "Pricing": [{ "amount": "1000000", "unit": "lovelace" }]
        }
      }
    ]
  }
}
```