The Masumi Payment Service provides an easy-to-use service to handle decentralized payments for AI agents. It supports a RESTful API and includes functionalities such as wallet generation, payment verification, and automated transaction handling, with batched on-chain settlement for registration and payment actions.
Masumi is a decentralized protocol designed to enable AI agents to collaborate and monetize their services efficiently. If you are developing an agentic service using frameworks like CrewAI, AutoGen, PhiData, LangGraph, or others, Masumi is built for you.
- Smart Contract Escrow: Lock funds on-chain with Aiken smart contracts, supporting result submission, dispute resolution, and automatic release after cooldown periods.
- Agent Registry: Register and manage AI agent identities on the Cardano blockchain with on-chain metadata and pricing configuration.
- Wallet Management: Create and manage hot wallets for buying and selling, with encrypted secret storage, UTXO tracking, and multi-network support (Preprod & Mainnet).
- Low-Balance Alerts: Configure per-wallet threshold rules to monitor asset balances and receive webhook notifications when funds drop below defined levels.
- Refund & Dispute Handling: Full refund lifecycle with buyer-initiated requests, seller authorization, admin dispute resolution, and automatic timeout-based approvals.
- Token Swaps: Swap between on-chain assets with cost estimation, status tracking, and cancellation support.
- Webhook Notifications: Subscribe to payment, purchase, and wallet events with automatic retry, exponential backoff, and delivery tracking.
- Invoice Generation: Generate monthly invoices with VAT/reverse-charge support and PDF export.
- Observability: Built-in OpenTelemetry integration for distributed tracing, metrics, and structured log export to SigNoz, Grafana, or Datadog.
- Admin Dashboard: Next.js frontend for managing agents, wallets, API keys, and monitoring wallet health.
Learn more about Masumi in our Introduction Guide.
Prerequisites: Node.js ≥ 20, pnpm, and a PostgreSQL ≥ 13 database (the x402 migrations use the built-in gen_random_uuid()).
git clone https://github.com/masumi-network/masumi-payment-service.git
cd masumi-payment-service
pnpm install # installs deps + generates the Prisma client
cp .env.example .env # then fill in DATABASE_URL, ENCRYPTION_KEY,
# BLOCKFROST_API_KEY_PREPROD, ... (see docs/configuration.md)
# Required before seeding Preprod payment sources (minimum for a new install):
# DATABASE_URL, ENCRYPTION_KEY, BLOCKFROST_API_KEY_PREPROD
# Recommended: ADMIN_KEY (a secure value; the seed falls back to a public default if unset)
# Optional wallet mnemonics: PURCHASE_WALLET_* / SELLING_WALLET_* (brewed and printed if blank)
# Legacy V1 sources: set SEED_V1_LEGACY=true (requires separate PURCHASE/SELLING_WALLET_V2_* when seeding both types)
pnpm run prisma:migrate # apply checked-in migrations (no shadow DB required)
pnpm run prisma:seed # seed initial data (admin key, payment source)
pnpm -C frontend run build # build the admin UI into frontend/dist (required for /admin/)
pnpm run dev # start the API server on http://localhost:3001pnpm run dev starts the API only. It serves /admin/ when frontend/dist exists
(from the build step above). The root pnpm run build command builds the backend
only — it does not build the frontend.
Once the API server is up and the frontend is built, open
http://localhost:3001/admin/ — browser requests to / redirect there.
API clients, health probes and curl are unaffected: the redirect only fires for
requests that actually ask for HTML.
To work on the dashboard with hot reload, run the frontend dev server on http://localhost:3000/ instead of using the built bundle:
cd frontend
pnpm install
pnpm run dev # http://localhost:3000In that mode the frontend needs to be told where the API lives, since the
default /api/v1 is same-origin and only resolves in production where the
backend serves the built bundle. Point it at the running backend in
frontend/.env.local:
NEXT_PUBLIC_PAYMENT_API_BASE_URL=http://localhost:3001/api/v1The admin interface is designed for desktop. Narrow screens now show a dismissible warning rather than being blocked outright, but tables and dialogs are still cramped below ~1024px.
Use pnpm run prisma:migrate to apply checked-in migrations when installing or
deploying — it runs prisma migrate deploy and does not need a shadow
database.
Use pnpm run prisma:migrate:dev only when you author or edit migrations.
That command runs prisma migrate dev, which creates a temporary shadow
database. The PostgreSQL user needs superuser or CREATEDB permission, or you
can set SHADOW_DATABASE_URL to a separate database the user is allowed
to create/drop. See the Prisma shadow database
docs.
Useful commands: pnpm run test (unit tests — always via pnpm, not bare
npx jest), pnpm run lint, pnpm run format, pnpm run typecheck. See the
Development Guide for architecture and testing details
and docs/e2e-testing.md for end-to-end tests.
We have been audited by TxPipe please check the full report for details.
Refer to the official Masumi Docs Website for comprehensive documentation and full setup guide.
Additional guides can be found in the docs folder:
The Masumi Payment Service Smart Contracts have been audited by TxPipe. Audit available here
We welcome contributions! Refer to our Contributing Guide for more details.
This project is licensed under the MIT License.