Manifest Configuration

The moneymq.yaml manifest file is the central configuration for your MoneyMQ project. It defines three main sections:

Catalogs - Your products and pricing structure
Payments - What payments you accept (chains, stablecoins)
Environments - How MoneyMQ deploys (sandbox, production, managed)

Quick Start

Create a moneymq.yaml file in your project root:

moneymq.yaml

catalogs:
  v1:
    description: 'My Store'
    catalog_path: billing/v1   # Products are in billing/v1/products/

payments:
  networks:
    chain: Solana
    stablecoins:
      - USDC

environments:
  sandbox:
    deployment: Sandbox

Then run the sandbox:

moneymq sandbox

Complete Example

Here's a full configuration with all three deployment types:

moneymq.yaml

# Catalog configuration
catalogs:
  v1:
    description: 'Surfpool - Premium Wave Predictions'
    catalog_path: billing/v1

# Payment acceptance configuration
payments:
  networks:
    chain: Solana
    stablecoins:
      - USDC

# Deployment environments
environments:
  # Local development with embedded validator
  sandbox:
    deployment: Sandbox
    binding_address: 0.0.0.0
    port: 8488
    facilitator:
      fee: 0
    network:
      chain: Solana
      binding_address: 0.0.0.0
      rpc_port: 8899
      ws_port: 8900

  # Self-hosted production with external RPC
  staging:
    deployment: SelfHosted
    binding_address: 0.0.0.0
    port: 8488
    facilitator:
      fee: 0
      key_management: TurnKey
    network:
      chain: Solana
      recipient: HNohduvBpFD1G9dz...
      rpc_url: https://api.devnet.solana.com
      ws_url: wss://api.devnet.solana.com

  # Cloud-hosted by moneymq.co
  production:
    deployment: CloudHosted
    project: Surfpool
    workspace: surfpool
    facilitator:
      fee: 0
      key_management: TurnKey

Catalogs

The catalogs section defines your product catalog structure. Each catalog entry maps to a directory containing product and price definitions.

catalogs:
  v1:
    description: 'My Store'      # Human-readable description
    catalog_path: billing/v1     # Path to catalog files (default: billing/v1)

Catalog Structure

Your catalog files should be organized like this:

billing/
  v1/
    products/
      surfnet/
        product.yaml            # Base product definition
        variants/
          lite/
            product.yaml        # Lite tier
          pro/
            product.yaml        # Pro tier
    meters/
      api-calls.yaml

Products are organized into directories with a base product.yaml and optional variants/ subdirectory for tiered pricing. See Creating a Catalog for details.

Stripe Integration

To sync your catalog with Stripe, add a source_type configuration:

catalogs:
  v1:
    description: 'My Store'
    catalog_path: billing/v1
    source_type: stripe
    # Optional: Stripe API key (prefer STRIPE_SECRET_KEY env var)
    # api_key: sk_live_...
    # api_version: "2024-06-20"
    # webhook_endpoint: https://your-domain.com/webhooks/stripe
    # webhook_secret_env: STRIPE_WEBHOOK_SECRET
    sandboxes:
      default:
        description: 'Stripe Test Mode'
        # api_key: sk_test_... (prefer STRIPE_SANDBOX_SECRET_KEY env var)

Never commit API keys to version control. Use environment variables (STRIPE_SECRET_KEY, STRIPE_SANDBOX_SECRET_KEY) instead.

Payments

The payments section defines what blockchain network and stablecoins your application accepts.

payments:
  networks:
    chain: Solana              # Blockchain network
    stablecoins:               # Accepted currencies
      - USDC

Supported Chains

Chain	Status
Solana	Supported

Supported Stablecoins

Symbol	Description	Mint Address
USDC	Circle's USD-backed stablecoin. Most widely used on Solana with deep liquidity.	`EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`

Environments

The environments section defines how MoneyMQ runs in different contexts. Each environment has a deployment type that determines its behavior.

Sandbox (Local Development)

Use Sandbox for local development. It starts an embedded Surfpool validator and automatically funds test accounts.

environments:
  sandbox:
    deployment: Sandbox
    binding_address: 0.0.0.0    # API server bind address
    port: 8488                   # API server port
    jwt_secret: my-custom-secret # Optional: JWT secret for payment receipts
    facilitator:
      fee: 0                     # No fee for testing
    network:
      chain: Solana
      binding_address: 0.0.0.0   # Validator bind address
      rpc_port: 8899             # Solana RPC port
      ws_port: 8900              # Solana WebSocket port

In sandbox mode, keys are managed in-memory automatically. No key_management configuration is needed.

In sandbox mode, the recipient address is automatically generated. You don't need to specify one.

Default values:

binding_address: 0.0.0.0
port: 8488
jwt_secret: moneymq-sandbox-secret
rpc_port: 8899
ws_port: 8900

SelfHosted (External RPC)

Use SelfHosted for production deployments where you manage your own infrastructure and connect to an external Solana RPC provider.

environments:
  production:
    deployment: SelfHosted
    binding_address: 0.0.0.0
    port: 8488
    facilitator:
      fee: 0
      key_management: TurnKey
    network:
      chain: Solana
      recipient: HNohduvBpFD1G9dz...   # Your payout address
      rpc_url: https://api.mainnet-beta.solana.com
      ws_url: wss://api.mainnet-beta.solana.com

For production, always specify a recipient address to receive payments.

CloudHosted (Hosted by MoneyMQ)

Use CloudHosted for fully hosted deployments. MoneyMQ handles all infrastructure.

environments:
  production:
    deployment: CloudHosted
    project: My Project          # Your project name
    workspace: my-workspace      # Your workspace on moneymq.co
    facilitator:
      fee: 0
      key_management: TurnKey

Facilitator Configuration

The facilitator handles payment verification and settlement. It's configured within each environment.

facilitator:
  fee: 0                    # Fee in basis points (0 = no fee, 100 = 1%)
  key_management: TurnKey   # Key management strategy

Fee Structure

Value	Fee
`0`	No fee
`50`	0.5%
`100`	1%
`250`	2.5%

Key Management

Strategy	Description
`InMemory`	Keys generated and held in memory (default for sandbox)
`TurnKey`	MoneyMQ manages keys automatically (for production)

Environment Variables

Some configuration can be set via environment variables. Create a .env file in your project root:

.env

# MoneyMQ payment API keypair (base58 encoded)
MONEYMQ_SOLANA_FACILITATOR_KEYPAIR=your_base58_encoded_keypair

# Stripe API keys (for catalog sync)
STRIPE_SECRET_KEY=sk_live_...
STRIPE_SANDBOX_SECRET_KEY=sk_test_...

Never commit .env files to version control. Add .env to your .gitignore.

Environment Variable Reference

Variable	Description
`MONEYMQ_SOLANA_FACILITATOR_KEYPAIR`	Base58-encoded Solana keypair for the payment API
`STRIPE_SECRET_KEY`	Stripe production API key for catalog operations
`STRIPE_SANDBOX_SECRET_KEY`	Stripe test mode API key for sandbox operations

API Endpoints

When MoneyMQ starts, it serves these endpoints:

Endpoint	Description
`GET /config`	Server configuration
`GET /catalog/v1/products`	List products
`GET /catalog/v1/prices`	List prices
`POST /catalog/v1/payment_intents`	Create payment intent
`POST /catalog/v1/payment_intents/:id/confirm`	Confirm payment (triggers x402)
`GET /payment/v1/supported`	Supported payment networks
`POST /payment/v1/verify`	Verify x402 payment
`POST /payment/v1/settle`	Settle x402 payment

Troubleshooting

"No manifest found"

Create a moneymq.yaml file in your project root, or specify the path:

moneymq sandbox --manifest-path ./config/moneymq.yaml

"Failed to bind to address"

The default ports may already be in use. Override them in your manifest:

environments:
  sandbox:
    deployment: Sandbox
    port: 9000                   # Different API port
    network:
      rpc_port: 9899             # Different RPC port
      ws_port: 9900              # Different WS port

"RPC connection failed"

For SelfHosted environments, verify your RPC URL is correct and accessible:

curl https://api.mainnet-beta.solana.com -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}'

Next Steps

CLI Commands - Learn all MoneyMQ CLI commands
Integration Guide - Accept payments with the SDK

On this page