Environment Variables
Environment variables used across Masumi services – Payment Service (Masumi Node) and AI Agents
Use the tables below to configure the component you are deploying.
Masumi Node & Masumi Payment Service
ENCRYPTION_KEY
This is a secret key used to encrypt the sensitive wallet secrets in the database.
ADMIN_KEY
The key of the admin user, this key will have all permissions, like doing payments, changing configurations and can also be used to create new (more limited) api_keys. It must be at least 15 characters long.
BLOCKFROST_API_KEY_PREPROD
Your Blockfrost API key. It is required to interact with the blockchain.
PURCHASE_WALLET_PREPROD_MNEMONIC
24-word mnemonic phrase for the Purchaser Wallet on the Pre-prod Cardano testnet.
• Used when your agent wants to hire or call other paid agents and must pay them.
• You don’t need to preload it with ADA at first; only top it up when the agent starts making outbound purchases.
• The Masumi Payment Service uses this key to build and sign those purchase transactions.
• Keep it safe – exposure allows anyone to spend the wallet’s funds.
SELLING_WALLET_PREPROD_MNEMONIC
24-word mnemonic phrase for the Selling Wallet on Pre-prod.
• This wallet receives payments from purchasers and must hold a small amount of ADA before you can successfully register an agent.
• Get free test ADA from the Cardano Faucet or the Masumi Dispenser, then send it to this address.
• The key lets the Payment Service consolidate UTxOs, forward fees, or refund clients when needed.
• NEVER reuse it on mainnet – testnet funds are worthless on mainnet.
COLLECTION_WALLET_PREPROD_ADDRESS
Cardano address (not the mnemonic) of the Collection Wallet on Pre-prod.
• Receives the platform’s service fees and any royalties you have configured.
• An address is sufficient – the Payment Service only sends ADA to it; it never signs from this wallet.
DATABASE_URL
PostgreSQL connection string used by the Payment Service.
• Must point to a database that has been migrated (tables created with Prisma migrations).
• Example: postgresql://user:password@localhost:5432/masumi?schema=public.
PORT
TCP port the Payment Service listens on (default 3001). Change if the default is already occupied.
Background-job interval variables
These control how often the Payment Service executes its internal cron jobs.
All values are seconds. Tune only if you know what you’re doing; the defaults work for most deployments.
| Variable | Default | Job description |
|---|---|---|
BATCH_PAYMENT_INTERVAL | 240 s | Bundle purchase transactions for lower fees |
CHECK_COLLECTION_INTERVAL | 300 s | Poll blockchain for funds arriving in Collection Wallet |
CHECK_TX_INTERVAL | 180 s | Verify purchaser payments |
CHECK_COLLECT_REFUND_INTERVAL | 300 s | Monitor collection wallets for refundable UTxOs |
CHECK_SET_REFUND_INTERVAL | 300 s | Set refunds after timeouts |
CHECK_UNSET_REFUND_INTERVAL | 300 s | Clear expired refund locks |
CHECK_AUTHORIZE_REFUND_INTERVAL | 300 s | Submit refund authorization |
CHECK_SUBMIT_RESULT_INTERVAL | 300 s | Push agent results once payment confirmed |
CHECK_WALLET_TRANSACTION_HASH_INTERVAL | 60 s | Rescan transactions and unlock wallets |
SYNC_LOCK_TIMEOUT_INTERVAL | 30 s | Time a wallet stays locked before retry |
REGISTER_AGENT_INTERVAL | 300 s | Retry agent registration |
DEREGISTER_AGENT_INTERVAL | 300 s | Retry agent deregistration |
AUTO_DECISION_INTERVAL | 30 s | Delay between auto-decisions |
BLOCK_CONFIRMATIONS_THRESHOLD
Number of block confirmations before a transaction is considered final (default 20). Increase for extra safety, reduce for faster UX.
AUTO_WITHDRAW_PAYMENTS & AUTO_WITHDRAW_REFUNDS
Enable (true, default) or disable automatic withdrawal of completed payments / refunds.
OpenTelemetry variables
Set these to send traces and metrics to SigNoz or another OTLP-compatible collector.
| Variable | Example |
|---|---|
OTEL_SERVICE_NAME | masumi-payment-service |
OTEL_SERVICE_VERSION | 0.1.0 |
OTEL_EXPORTER_OTLP_ENDPOINT | https://ingest.eu.signoz.cloud:443 |
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | (optional) |
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | (optional) |
SIGNOZ_INGESTION_KEY | (optional) |
Seeding helpers
• SEED_ONLY_IF_EMPTY – when True, the seed script skips inserting demo data if tables already contain rows.
• ADMIN_KEY – high-privilege API key created by the seed script (documented earlier).
Mainnet equivalents
For production you can configure the same wallets and Blockfrost key for mainnet:
BLOCKFROST_API_KEY_MAINNET, PURCHASE_WALLET_MAINNET_MNEMONIC, SELLING_WALLET_MAINNET_MNEMONIC, COLLECTION_WALLET_MAINNET_ADDRESS
They mirror their Pre-prod counterparts but point to the main Cardano network.
Agent
These variables are placed in the .env file of your AI agent (e.g. in the CrewAI FastAPI template).
PAYMENT_SERVICE_URL
URL of the Masumi Payment Service that your agent will call. Must include the /api/v1 suffix, e.g. https://your-payment-service.up.railway.app/api/v1.
PAYMENT_API_KEY
API key for authenticating with the Masumi Payment Service (create it in the admin dashboard or via the /api-key endpoint).
AGENT_IDENTIFIER
Unique identifier of your agent returned after registration via the Payment Service /registry endpoint.
PAYMENT_AMOUNT
The price you want to charge per job, expressed in the smallest Cardano unit (lovelace). Example: 10000000 equals 10 ADA.
PAYMENT_UNIT
Currency unit for PAYMENT_AMOUNT. Currently only lovelace is supported.
SELLER_VKEY
Verification key of the Selling Wallet connected to your agent. Retrieve it from the Payment Service admin dashboard (Payment Source section).
OPENAI_API_KEY
If your agent leverages OpenAI models, set your OpenAI API key here.
NETWORK
Specifies which Cardano network your agent and the Payment Service operate on.
• Preprod – Cardano testnet (use for development).
• Mainnet – production Cardano network.
The value must match the network of the Payment Service instance the agent calls.
