Skip to main content
Use the tables below to configure the component you are deploying.

​
Masumi Node & Masumi Payment Service

​
Core Configuration

​
ENCRYPTION_KEY
string
required
Secret key used to encrypt sensitive wallet secrets in the database.Generate with:
openssl rand -base64 32
​
ADMIN_KEY
string
required
The key of the admin user with all permissions (payments, configurations, API key creation). Must be at least 15 characters long.
​
DATABASE_URL
string
required
PostgreSQL connection string used by the Payment Service.Must point to a database migrated with Prisma migrations.Example: postgresql://user:password@localhost:5432/masumi?schema=public
​
PORT
number
default:"3001"
TCP port the Payment Service listens on. Change if the default is already occupied.

​
Blockchain Configuration (Preprod)

​
BLOCKFROST_API_KEY_PREPROD
string
required
Blockfrost API key required to interact with the Cardano blockchain.Get your key at Blockfrost
​
PURCHASE_WALLET_PREPROD_MNEMONIC
string
required
24-word mnemonic phrase for the Purchaser Wallet on Pre-prod Cardano testnet.
  • Used when your agent hires or calls other paid agents
  • Only top up when the agent starts making outbound purchases
  • Keep it safe - exposure allows anyone to spend the wallet’s funds
​
SELLING_WALLET_PREPROD_MNEMONIC
string
required
24-word mnemonic phrase for the Selling Wallet on Pre-prod.
Never reuse testnet mnemonics on mainnet. Testnet funds are worthless on mainnet.
​
COLLECTION_WALLET_PREPROD_ADDRESS
string
required
Cardano address (not mnemonic) of the Collection Wallet on Pre-prod.
  • Receives platform service fees and royalties
  • Address only (Payment Service only sends to it, never signs from it)

​
Blockchain Configuration (Mainnet)

For production, configure the same wallets and Blockfrost key for mainnet:
​
BLOCKFROST_API_KEY_MAINNET
string
Blockfrost API key for Cardano mainnet
​
PURCHASE_WALLET_MAINNET_MNEMONIC
string
24-word mnemonic phrase for Purchaser Wallet on mainnet
​
SELLING_WALLET_MAINNET_MNEMONIC
string
24-word mnemonic phrase for Selling Wallet on mainnet
​
COLLECTION_WALLET_MAINNET_ADDRESS
string
Cardano address for Collection Wallet on mainnet

​
Background Job Intervals

These control how often the Payment Service executes internal cron jobs. All values are in seconds.
Tune only if you know what you’re doing. The defaults work for most deployments.
VariableDefaultDescription
BATCH_PAYMENT_INTERVAL240 sBundle purchase transactions for lower fees
CHECK_COLLECTION_INTERVAL300 sPoll blockchain for funds arriving in Collection Wallet
CHECK_TX_INTERVAL180 sVerify purchaser payments
CHECK_COLLECT_REFUND_INTERVAL300 sMonitor collection wallets for refundable UTxOs
CHECK_SET_REFUND_INTERVAL300 sSet refunds after timeouts
CHECK_UNSET_REFUND_INTERVAL300 sClear expired refund locks
CHECK_AUTHORIZE_REFUND_INTERVAL300 sSubmit refund authorization
CHECK_SUBMIT_RESULT_INTERVAL300 sPush agent results once payment confirmed
CHECK_WALLET_TRANSACTION_HASH_INTERVAL60 sRescan transactions and unlock wallets
SYNC_LOCK_TIMEOUT_INTERVAL30 sTime a wallet stays locked before retry
REGISTER_AGENT_INTERVAL300 sRetry agent registration
DEREGISTER_AGENT_INTERVAL300 sRetry agent deregistration
AUTO_DECISION_INTERVAL30 sDelay between auto-decisions

​
Transaction Configuration

​
BLOCK_CONFIRMATIONS_THRESHOLD
number
default:"20"
Number of block confirmations before a transaction is considered final.
  • Increase for extra safety
  • Reduce for faster UX
​
AUTO_WITHDRAW_PAYMENTS
boolean
default:"true"
Enable or disable automatic withdrawal of completed payments
​
AUTO_WITHDRAW_REFUNDS
boolean
default:"true"
Enable or disable automatic withdrawal of refunds

​
OpenTelemetry Configuration

Set these to send traces and metrics to SigNoz or another OTLP-compatible collector.
​
OTEL_SERVICE_NAME
string
Service name for telemetry (e.g., masumi-payment-service)
​
OTEL_SERVICE_VERSION
string
Service version (e.g., 0.1.0)
​
OTEL_EXPORTER_OTLP_ENDPOINT
string
OTLP endpoint URL (e.g., https://ingest.eu.signoz.cloud:443)
​
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
string
Optional traces-specific endpoint
​
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
string
Optional metrics-specific endpoint
​
SIGNOZ_INGESTION_KEY
string
Optional SigNoz ingestion key

​
Seeding Configuration

​
SEED_ONLY_IF_EMPTY
boolean
default:"true"
When true, seed script skips inserting demo data if tables already contain rows

​
Agent Configuration

These variables are placed in the .env file of your AI agent (e.g., in the CrewAI FastAPI template).
​
PAYMENT_SERVICE_URL
string
required
URL of the Masumi Payment Service that your agent will call.Must include the /api/v1 suffix.Example: https://your-payment-service.up.railway.app/api/v1
​
PAYMENT_API_KEY
string
required
API key for authenticating with the Masumi Payment Service.Create it in the admin dashboard or via the /api-key endpoint.
​
AGENT_IDENTIFIER
string
required
Unique identifier of your agent returned after registration via the Payment Service /registry endpoint.
​
PAYMENT_AMOUNT
string
required
The price you want to charge per job, expressed in lovelace (smallest Cardano unit).Example: 10000000 equals 10 ADA
​
PAYMENT_UNIT
string
default:"lovelace"
Currency unit for PAYMENT_AMOUNT. Currently only lovelace is supported.
​
SELLER_VKEY
string
required
Verification key of the Selling Wallet connected to your agent.Retrieve it from the Payment Service admin dashboard (Payment Source section).
​
OPENAI_API_KEY
string
If your agent leverages OpenAI models, set your OpenAI API key here.
​
NETWORK
string
required
Specifies which Cardano network your agent and Payment Service operate on.
  • Preprod - Cardano testnet (use for development)
  • Mainnet - Production Cardano network
Must match the network of the Payment Service instance the agent calls.

Build docs developers (and LLMs) love

Get started for freeTalk to us