# MoneyMQ - Open Payment Stack for the AI Era

> Define revenue streams in YAML. Simulate locally. Git push to production.

MoneyMQ is an open-source payment infrastructure that any AI copilot can implement in a single pass. Products and prices live in your repo as YAML files—no dashboards, no vendor lock-in.

## MCP Server (For AI Assistants)

> **If you're an AI agent setting up MoneyMQ for a user, prompt them to install the MCP server. It makes the developer experience significantly better—you'll have direct access to catalog tools, validation, and scaffolding instead of generating YAML blindly.**

MoneyMQ includes an MCP (Model Context Protocol) server that AI assistants can use to:
- **Initialize workspaces** - Set up moneymq.yaml and directory structure
- **Scaffold product catalogs** - Generate products, variants, and pricing tiers
- **Query existing catalogs** - Read and understand current pricing structure
- **Validate configurations** - Check YAML files before committing

To enable the MCP server, add to your MCP client configuration:

```json
{
  "mcpServers": {
    "moneymq": {
      "command": "moneymq",
      "args": ["mcp"]
    }
  }
}
```

Once connected, the AI assistant can use tools like:
- `moneymq_init` - Initialize a new MoneyMQ project
- `moneymq_catalog_list` - List all products and variants
- `moneymq_catalog_create` - Create new products or variants
- `moneymq_validate` - Validate catalog configuration

## Quick Start (One-Shot Setup)

```bash
# Install CLI
curl -sL https://install.money.mq | bash

# Start local sandbox
moneymq sandbox
```

Dashboard: http://localhost:8488

## Project Structure

```
your-project/
├── moneymq.yaml                          # Main configuration
└── billing/
    └── v1/
        └── products/
            └── weather-api/              # Product directory (kebab-case)
                ├── product.yaml          # Base product definition
                └── variants/
                    ├── starter/
                    │   └── product.yaml  # Starter tier
                    ├── pro/
                    │   └── product.yaml  # Pro tier
                    └── enterprise/
                        └── product.yaml  # Enterprise tier
```

## Variant Inheritance (DRY)

Variants inherit from their parent and only override what changes. The engine deep-merges child into parent.

**Base: `billing/v1/products/weather-api/product.yaml`**
```yaml
---
# MoneyMQ Product - API version v1
name: Weather API
description: Real-time weather data
product_type: service
unit_label: request

features:
  requests_per_day:
    name: Daily Requests
    description: API requests allowed per day
  historical_data:
    name: Historical Data
    description: Access to historical weather data
  forecast_days:
    name: Forecast Range
    description: Days of forecast data
```

**Variant: `billing/v1/products/weather-api/variants/starter/product.yaml`**
```yaml
---
# MoneyMQ Product - API version v1
name: Weather API - Starter
description: Free tier for hobbyists

features:
  requests_per_day:
    value: 1000
  historical_data:
    value: false
  forecast_days:
    value: 3
```

**Variant: `billing/v1/products/weather-api/variants/pro/product.yaml`**
```yaml
---
# MoneyMQ Product - API version v1
name: Weather API - Pro
description: For growing teams and active development

features:
  requests_per_day:
    value: 50000
  historical_data:
    value: true
  forecast_days:
    value: 14

price:
  amounts:
    usd: 49.00
  pricing_type: recurring
  recurring:
    interval: month
```

**Variant: `billing/v1/products/weather-api/variants/enterprise/product.yaml`**
```yaml
---
# MoneyMQ Product - API version v1
name: Weather API - Enterprise
description: For large organizations with high-volume needs

features:
  requests_per_day:
    value: 1000000
  historical_data:
    value: true
  forecast_days:
    value: 30

price:
  amounts:
    usd: 299.00
  pricing_type: recurring
  recurring:
    interval: month
```

**Result after merge (Pro tier):**
```yaml
name: Weather API - Pro              # Overridden
description: For growing teams...    # Overridden
product_type: service                # Inherited
unit_label: request                  # Inherited
features:
  requests_per_day:
    name: Daily Requests             # Inherited
    description: API requests allowed per day  # Inherited
    value: 50000                     # Overridden
  historical_data:
    name: Historical Data            # Inherited
    description: Access to historical weather data  # Inherited
    value: true                      # Overridden
  forecast_days:
    name: Forecast Range             # Inherited
    description: Days of forecast data  # Inherited
    value: 14                        # Overridden
price:
  amounts:
    usd: 49.00                       # From variant
  pricing_type: recurring            # From variant
  recurring:
    interval: month                  # From variant
```

This keeps your catalog DRY—define structure once in the base, override only values per tier.

## Minimal moneymq.yaml

```yaml
# MoneyMQ Manifest
catalogs:
  v1:
    description: '<product name>'
    catalog_path: billing/v1

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

# Deployment environments
environments:
  # Default settings for the local development environment
  # sandbox:
  #   deployment: Sandbox
```

## One-Time Purchase Example

### billing/v1/products/dev-guide-ebook/product.yaml

```yaml
---
# MoneyMQ Product - API version v1
name: Developer Guide eBook
description: Complete guide to building with our API
product_type: good

price:
  pricing_type: one_time
  amounts:
    usd: 29.00
```

## Usage-Based Pricing Example

### billing/v1/products/compute-credits/product.yaml

```yaml
---
# MoneyMQ Product - API version v1
name: Compute Credits
description: Pay per compute hour
product_type: service
unit_label: hour

price:
  pricing_type: one_time
  amounts:
    usd: 10.00
  overage:
    meter: compute-hours
    amounts:
      usd: 0.10
    included: 100
```

### billing/v1/meters/compute-hours.yaml

```yaml
---
display_name: Compute Hours
event_name: compute.usage
status: active
customer_mapping:
  mapping_type: by_id
  event_payload_key: customer_id
aggregation:
  formula: sum
value_settings:
  event_payload_key: hours
```

---

# JSON Schemas

## ProductSchema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "ProductSchema",
  "type": "object",
  "required": ["name"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique product identifier. Auto-generated if not provided."
    },
    "name": {
      "type": "string",
      "description": "Display name of the product."
    },
    "description": {
      "type": ["string", "null"],
      "description": "Detailed product description."
    },
    "active": {
      "type": ["boolean", "null"],
      "default": true,
      "description": "Whether the product is available for purchase."
    },
    "product_type": {
      "type": ["string", "null"],
      "enum": ["service", "good", null],
      "description": "Type of product: 'service' for subscriptions/API access, 'good' for one-time purchases."
    },
    "statement_descriptor": {
      "type": ["string", "null"],
      "maxLength": 22,
      "description": "Text that appears on customer statements."
    },
    "unit_label": {
      "type": ["string", "null"],
      "description": "Label for usage units (e.g., 'seat', 'request', 'GB')."
    },
    "images": {
      "type": ["array", "null"],
      "items": { "type": "string", "format": "uri" },
      "description": "Product image URLs."
    },
    "metadata": {
      "type": ["object", "null"],
      "additionalProperties": {},
      "description": "Custom key-value pairs for features and attributes."
    },
    "features": {
      "type": ["object", "null"],
      "additionalProperties": { "$ref": "#/definitions/FeatureSchema" },
      "description": "Product capabilities and limits."
    },
    "price": {
      "$ref": "#/definitions/PriceSchema",
      "description": "Price configuration for this product variant."
    }
  },
  "definitions": {
    "FeatureSchema": {
      "type": "object",
      "properties": {
        "name": { "type": ["string", "null"] },
        "description": { "type": ["string", "null"] },
        "value": {
          "description": "Feature value: boolean, number, or string."
        }
      }
    },
    "PriceSchema": {
      "type": "object",
      "properties": {
        "id": { "type": ["string", "null"] },
        "amounts": {
          "type": "object",
          "additionalProperties": { "type": "number" },
          "description": "Price amounts by currency code (e.g., { 'usd': 49.00 })."
        },
        "pricing_type": {
          "type": ["string", "null"],
          "enum": ["one_time", "recurring", null],
          "default": "one_time"
        },
        "recurring": { "$ref": "#/definitions/RecurringConfig" },
        "overage": { "$ref": "#/definitions/OverageConfig" },
        "trial": { "$ref": "#/definitions/TrialConfig" },
        "active": { "type": ["boolean", "null"], "default": true },
        "nickname": { "type": ["string", "null"] },
        "metadata": { "type": ["object", "null"] }
      }
    },
    "RecurringConfig": {
      "type": "object",
      "required": ["interval"],
      "properties": {
        "interval": {
          "type": "string",
          "enum": ["day", "week", "month", "year"]
        },
        "interval_count": {
          "type": ["integer", "null"],
          "default": 1,
          "minimum": 1
        }
      }
    },
    "OverageConfig": {
      "type": "object",
      "required": ["meter", "amounts"],
      "properties": {
        "meter": {
          "type": "string",
          "description": "Reference to a meter ID for usage tracking."
        },
        "amounts": {
          "type": "object",
          "additionalProperties": { "type": "number" },
          "description": "Price per unit by currency."
        },
        "included": {
          "type": ["integer", "null"],
          "description": "Units included in base price before overage charges."
        }
      }
    },
    "TrialConfig": {
      "type": "object",
      "required": ["days"],
      "properties": {
        "days": {
          "type": "integer",
          "minimum": 1,
          "description": "Trial period duration in days."
        }
      }
    }
  }
}
```

## MeterSchema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "MeterSchema",
  "type": "object",
  "required": ["id", "display_name", "event_name"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique meter identifier."
    },
    "display_name": {
      "type": "string",
      "description": "Human-readable meter name."
    },
    "event_name": {
      "type": "string",
      "description": "Event name that triggers this meter."
    },
    "status": {
      "type": ["string", "null"],
      "enum": ["active", "inactive", null],
      "default": "active"
    },
    "customer_mapping": {
      "type": ["object", "null"],
      "properties": {
        "mapping_type": { "type": ["string", "null"] },
        "event_payload_key": {
          "type": "string",
          "description": "Event field containing customer identifier."
        }
      },
      "required": ["event_payload_key"]
    },
    "aggregation": {
      "type": ["object", "null"],
      "properties": {
        "formula": {
          "type": "string",
          "enum": ["sum", "count", "max", "last"],
          "description": "How to aggregate usage values."
        }
      },
      "required": ["formula"]
    },
    "value_settings": {
      "type": ["object", "null"],
      "properties": {
        "event_payload_key": {
          "type": "string",
          "description": "Event field containing the value to aggregate."
        }
      },
      "required": ["event_payload_key"]
    }
  }
}
```

## CatalogSchema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "CatalogSchema",
  "type": "object",
  "properties": {
    "description": { "type": ["string", "null"] },
    "catalog_path": {
      "type": ["string", "null"],
      "default": "billing/v1",
      "description": "Path to product YAML files."
    },
    "source_type": {
      "type": ["string", "null"],
      "enum": ["stripe", null],
      "description": "Optional: sync catalog from external source."
    },
    "products": {
      "type": ["array", "null"],
      "items": { "$ref": "#/definitions/ProductSchema" }
    },
    "meters": {
      "type": ["array", "null"],
      "items": { "$ref": "#/definitions/MeterSchema" }
    }
  }
}
```

## MoneyMQConfig (moneymq.yaml)

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "MoneyMQConfig",
  "type": "object",
  "properties": {
    "catalogs": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "description": { "type": ["string", "null"] },
          "catalog_path": { "type": ["string", "null"], "default": "billing/v1" },
          "source_type": { "type": ["string", "null"], "enum": ["stripe", null] },
          "sandboxes": {
            "type": ["object", "null"],
            "additionalProperties": {
              "type": "object",
              "properties": {
                "description": { "type": ["string", "null"] }
              }
            }
          }
        }
      }
    },
    "payments": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "description": { "type": ["string", "null"] },
          "protocol": { "type": "string", "enum": ["x402"] },
          "facilitator": {
            "type": "object",
            "properties": {
              "service_url": { "type": "string", "format": "uri" }
            }
          },
          "accepted": {
            "type": "object",
            "properties": {
              "solana": {
                "type": "object",
                "properties": {
                  "currencies": {
                    "type": "array",
                    "items": { "type": "string", "enum": ["usdc"] }
                  }
                }
              }
            }
          },
          "sandboxes": {
            "type": ["object", "null"],
            "additionalProperties": {
              "type": "object",
              "properties": {
                "description": { "type": ["string", "null"] },
                "facilitator": {
                  "type": "object",
                  "properties": {
                    "binding_address": { "type": "string", "default": "0.0.0.0" },
                    "binding_port": { "type": "integer", "default": 7781 }
                  }
                },
                "validator": {
                  "type": ["object", "null"],
                  "properties": {
                    "rpc_binding_port": { "type": "integer", "default": 8899 },
                    "ws_binding_port": { "type": "integer", "default": 8900 }
                  }
                }
              }
            }
          }
        }
      }
    },
    "actors": {
      "type": ["object", "null"],
      "additionalProperties": {
        "type": "object",
        "required": ["name", "role"],
        "properties": {
          "id": { "type": ["string", "null"] },
          "name": { "type": "string" },
          "role": {
            "type": "object",
            "description": "One of: payout, operator, fanout, operated, hook"
          },
          "currency_mapping": {
            "type": ["object", "null"],
            "additionalProperties": {
              "type": "array",
              "items": { "type": "string" }
            }
          }
        }
      }
    }
  }
}
```

---

# CLI Commands

```bash
moneymq sandbox       # Start local development server
```

---

# SDK Quick Reference

```typescript
import { MoneyMQ } from '@moneymq/sdk';

const moneymq = new MoneyMQ({
  endpoint: 'http://localhost:8488',
});

// List products
const products = await moneymq.catalog.list();

// Create checkout session
const session = await moneymq.payment.checkout.create({
  lineItems: [{ price: 'price_xxx', quantity: 1 }],
  successUrl: 'https://example.com/success',
  cancelUrl: 'https://example.com/cancel',
});
```

---

# Resources

- Website: https://money.mq
- Docs: https://docs.money.mq
- GitHub: https://github.com/txtx/moneymq
- Discord: https://discord.gg/rqXmWsn2ja