miniMerch

Sell anything on the Minima blockchain — no server, no payment processor, just you.

miniMerch generates MiniDapps for the Minima blockchain that function as storefronts for selling physical or digital products. Customers pay with Minima or USDT, and your delivery address arrives encrypted in your private vendor inbox — never stored on-chain.

Table of Contents

1. What is miniMerch?
2. Prerequisites
3. Installation
4. Configuration — The One-Time Setup
5. Generating Your First Shop
6. What Gets Generated
7. Deploying Your Shop
8. How the Order Flow Works
9. Privacy & Security
10. Command Reference
11. Troubleshooting
12. Uninstalling

What is miniMerch?

miniMerch is a CLI tool that generates MiniDapps — self-contained app bundles that run on the Minima blockchain network.

A MiniDapp generated by miniMerch is two things:

| | Who uses it | What it does | |---|---|---| | miniMerch Shop | Your customers / buyers | Browse products, select options, enter delivery address, pay | | miniMerchInbox | You (the vendor) | Receive encrypted orders, decrypt delivery addresses, manage incoming orders |

You can run multiple shops (different products) and they all send orders to the same single inbox — one inbox to manage everything.

Prerequisites

Before installing miniMerch, make sure you have the following:

Node.js (required)

miniMerch runs on Node.js. You need version 18 or higher.

Check if you have it:

node --version

If you don't have it, or have an older version:

• Download from nodejs.org — the LTS version is recommended
• On macOS you can also use Homebrew:

  brew install node

• On Linux (Ubuntu/Debian):

  curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E sudo -E bash -
  sudo apt-get install -y nodejs

A Minima Node (required)

miniMerch MiniDapps run inside the Minima network, not in a web browser. You need a running Minima node to:

• Install your vendor inbox (so you can receive orders)
• Optionally: host your shop MiniDapp (so customers can access it)

How to run a Minima node:

1. Download the Minima node from minima.global
2. Install and run it on your computer (or a server you control)
3. Keep it running — your inbox needs it to receive messages

What is a Minima node?
A Minima node is a program that connects your computer to the Minima blockchain network. It stores the blockchain, processes transactions, and can run MiniDapps. Think of it like a personal server built into the Minima protocol itself.

Your Minima Receiving Address (required)

This is where you receive payments. It's a 66-character hexadecimal string starting with 0x.

To find it in your Minima node:

1. Open the Minima application
2. Look for your address — it starts with 0x and looks like:

   0x465CA86A9B5756F45DEB667A69B3DBEC1B82B211814B294ED32693603F28AD37

3. Copy the entire address

⚠️ Important: This is where your payments will be sent. Make sure you control the private key for this address.

A CoinMarketCap API Key (required for live prices)

miniMerch fetches live Minima prices so it can convert your USDT prices into Minima amounts. It uses CoinMarketCap for this.

To get a free API key:

1. Go to coinmarketcap.com
2. Click Sign Up (top right) — the free tier is all you need
3. Verify your email and log in
4. Click your profile icon (top right) → API Key
5. Click Create API Key
6. Copy the key — it looks like:

   a1b2c3d4-e5f6-7890-abcd-ef1234567890

ℹ️ Free tier limits: The free CoinMarketCap tier allows 10,000 API calls per month. miniMerch makes a few calls each time a buyer opens your shop. For most shops this is plenty. If you expect very high traffic, consider a paid plan.

Your Vendor Public Key (required)

Your public key is used to encrypt the delivery addresses buyers send you. Only you can decrypt them.

To get your public key:

1. First, complete the Configuration setup below
2. Then generate your inbox MiniDapp:

   mini-merch generate --inbox-only

3. Open the generated dist/miniMerchInbox.mds.zip in your Minima node
4. Your public key will be displayed in the MiniDapp interface — it starts with Mx and looks like:

   MxG18HGG6FJ038614Y8CW46US6G20810K0070CD00Z83282G60G19TUFFWSB6EEF0619DH9A069ECNU1TNEFRBHKTE8DU5T9740QUW30BH9F45YSZUM5SSVUHU36WFGSWDZS6CZYGB4AJG83VQPUF42R6S11Z9R70MUQCJRG202YQK7Z4FS904R7V4W8ZBHK7D5STVHK1GYSV54HJSBRE1MUTHNHCCGV9BUWE2FZBEND91D421Z6V2Z7BRGMTECVC10608006P3DB2S

5. Copy the full key (all characters, including the Mx prefix)

Installation

Open your terminal (Command Prompt on Windows, Terminal on macOS/Linux) and run:

npm install -g @eurobuddha/mini-merch

Verify it installed correctly:

mini-merch --version

You should see 0.1.0 or similar.

To update to the latest version:

npm update -g @eurobuddha/mini-merch

Configuration — The One-Time Setup

This step saves your vendor settings to your computer so you don't have to enter them again.

Run this command with your three values:

mini-merch setup <minima-address> <cmc-api-key> <vendor-public-key>

Example with real values:

mini-merch setup \
  0x465CA86A9B5756F45DEB667A69B3DBEC1B82B211814B294ED32693603F28AD37 \
  a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  MxG18HGG6FJ038614Y8CW46US6G20810K0070CD00Z83282G60G19TUFFWSB6EEF0619DH9A069ECNU1TNEFRBHKTE8DU5T9740QUW30BH9F45YSZUM5SSVUHU36WFGSWDZS6CZYGB4AJG83VQPUF42R6S11Z9R70MUQCJRG202YQK7Z4FS904R7V4W8ZBHK7D5STVHK1GYSV54HJSBRE1MUTHNHCCGV9BUWE2FZBEND91D421Z6V2Z7BRGMTECVC10608006P3DB2S

What each argument means:

| Argument | Where to find it | |----------|-----------------| | minima-address | Your Minima wallet — starts with 0x, 66 characters | | cmc-api-key | CoinMarketCap dashboard — a UUID like a1b2c3d4-... | | vendor-public-key | Your miniMerchInbox MiniDapp — starts with Mx, very long |

Config file location:
Your config is saved to ~/.mini-merch/config.json (your user home folder). This file is obfuscated so it can't be easily tampered with.

Optional — separate inbox key:
If you want your inbox to use a different public key than your shop (e.g. running the inbox on a different machine), add it as a fourth argument:

mini-merch setup <address> <apikey> <vendor-key> <inbox-key>

Changing your config later:
If you need to update your settings, first reset the config:

mini-merch config --reset

Then run mini-merch setup again with the new values.

Generating Your First Shop

Step 1 — Choose your sales mode

miniMerch supports two sales modes. Choose the one that fits your product:

| Mode | Use when | Example | |------|----------|---------| | weight | Selling by weight (grams, kg, oz, etc.) | Herb, grain, powder, coffee, spices | | units | Selling by individual items | T-shirts, ebooks, digital files, single items |

Step 2 — Generate your MiniDapps

Weight Mode Example

Selling organic barley at £5 per gram, total batch weight 1,000 grams:

mini-merch generate \
  -n "Organic Barley" \
  -m weight \
  -p 5 \
  -w 1000 \
  -d "Premium malting barley, perfect for home brewing"

What each flag means:

• -n "Organic Barley" — Product name shown to buyers
• -m weight — Weight-based pricing mode
• -p 5 — £5 per gram
• -w 1000 — Total batch weight is 1,000 grams (so a "full" is 1,000g, a "half" is 500g, etc.)
• -d "Premium malting barley..." — Description shown to buyers

The buyer will see options: Full (1,000g), Half (500g), Quarter (250g), Eighth (125g) at prices automatically calculated (£5,000 / £2,500 / £1,250 / £625).

Units Mode Example

Selling PDF e-books at £25 each, bundle of 50 files:

mini-merch generate \
  -n "Blockchain Guide Pack" \
  -m units \
  -p 25 \
  -u 50 \
  -d "50 PDF guides on blockchain, crypto and Web3"

• -m units — Individual item mode
• -p 25 — £25 per unit
• -u 50 — Maximum of 50 units in the dropdown (buyers pick 1–50)

Step 3 — Using a Custom Product Image

By default, miniMerch bundles a placeholder image. To use your own product photo:

mini-merch generate \
  -n "Artisan Coffee" \
  -m weight \
  -p 12 \
  -w 500 \
  -i ./my-coffee-photo.jpg \
  -d "Single-origin Ethiopian coffee beans"

The -i flag accepts JPG, PNG, GIF, or WebP. Replace ./my-coffee-photo.jpg with the path to your image file.

Step 4 — Generate Inbox Only (existing shops)

If you already have shop MiniDapps and just need to install or reinstall your inbox:

mini-merch generate --inbox-only

This creates only miniMerchInbox.mds.zip without regenerating any shop MiniDapps.

What Gets Generated

After running mini-merch generate, a dist/ folder is created in your current directory:

dist/
├── miniMerch_Organic_Barley.mds.zip   ← Shop (give this to buyers)
└── miniMerchInbox.mds.zip             ← Inbox (keep this for yourself)

Both are complete, self-contained MiniDapps — no server, database, or hosting required beyond the file itself.

Deploying Your Shop

For Buyers (How customers access your shop)

Your .mds.zip file is the entire shop. There are several ways to distribute it:

Option 1 — Direct file sharing (simplest): Simply share the .mds.zip file with buyers through any file sharing service (Dropbox, Google Drive, email attachment, etc.). Buyers drag the .mds.zip file directly into their Minima node or open it.

Option 2 — Hosted web server: Upload the .mds.zip to any web server (Apache, Nginx, Netlify, GitHub Pages, etc.) and share the URL. Customers download and install from that URL.

Option 3 — IPFS or similar: Upload to IPFS for a permanent, decentralized hosting option.

For Yourself (Installing your inbox)

1. Open the miniMerchInbox.mds.zip file in your Minima node (not a browser)
2. The inbox will appear — pin it to your dashboard
3. Keep your Minima node running to receive orders 24/7, or check it periodically

⚠️ Important: Your inbox only works when your Minima node is online. If you shut down your node, orders will queue up and arrive when you restart it — nothing is lost, but buyers may have to wait.

How the Order Flow Works

Here's exactly what happens when a customer buys from your shop:

1. BUYER OPENS SHOP
   └─ MiniDapp fetches live Minima ↔ USDT price

2. BUYER SELECTS PRODUCT
   └─ Chooses size (Full/Half/Quarter/Eighth or quantity)
   └─ Chooses payment method (USDT or Minima)
   └─ Chooses shipping (UK / International / Electronic)

3. BUYER ENTERS DELIVERY ADDRESS
   └─ Address is encrypted with YOUR public key
   └─ Encrypted message sent over the Minima P2P network
   └─ Nothing is stored on the blockchain — fully private

4. BUYER PAYS
   └─ Payment transaction recorded on-chain (public)
   └─ Order reference number displayed (public)

5. VENDOR RECEIVES ORDER (in your inbox)
   └─ Your inbox MiniDapp decrypts the delivery address
   └─ You see: product, size, amount paid, delivery address
   └─ Order reference matches the on-chain transaction

What is public (on-chain):

• The order reference number
• The payment transaction ID
• The amount paid
• Your vendor address
• The buyer's public key (not their address)

What is private (encrypted, off-chain):

• The buyer's delivery address
• The buyer's email (if provided)
• The specific order details

Privacy & Security

Encryption

All delivery addresses and contact details are encrypted using Maxima encryption — the same encryption protocol used across the Minima network. When a buyer submits their order:

1. Their delivery address is encrypted with your public key before leaving their device
2. The encrypted message travels through the Minima P2P network — not the blockchain
3. Only your inbox MiniDapp (using your private key) can decrypt it
4. Even if someone intercepts the message, they cannot read the contents

On-chain vs Off-chain

| | On-chain (public) | Off-chain (private) | |--|---|---| | Order reference | ✅ | | | Transaction ID | ✅ | | | Payment amount | ✅ | | | Vendor address | ✅ | | | Delivery address | | ✅ | | Buyer email | | ✅ | | Message content | | ✅ |

Configuration Security

Your ~/.mini-merch/config.json file contains obfuscated (not encrypted) values. The obfuscation prevents casual tampering, but the file should still be kept private — treat it like a password file.

Command Reference

mini-merch setup

Save your vendor configuration (one-time setup).

mini-merch setup <minima-address> <cmc-api-key> <vendor-public-key> [inbox-public-key]

| Argument | Required | Description | |----------|----------|-------------| | minima-address | Yes | Your Minima receiving address (0x...) | | cmc-api-key | Yes | CoinMarketCap API key | | vendor-public-key | Yes | Your public key for encryption (Mx...) | | inbox-public-key | No | Separate inbox key (defaults to vendor key) |

mini-merch generate

Generate shop and/or inbox MiniDapps.

mini-merch generate [options]

| Flag | Short | Description | Example | |------|-------|-------------|---------| | --name | -n | Product name | -n "Organic Barley" | | --mode | -m | weight (default) or units | -m weight | | --price | -p | Price per gram (weight) or per unit | -p 5 | | --weight | -w | Total weight in grams (weight mode) | -w 1000 | | --units | -u | Max units (units mode) | -u 50 | | --desc | -d | Product description | -d "Premium barley" | | --image | -i | Path to product image | -i ./photo.jpg | | --inbox-only | | Generate inbox only, skip shop | --inbox-only |

mini-merch config

Manage your stored configuration.

mini-merch config --show    # Display current config (values masked)
mini-merch config --reset   # Delete stored config

mini-merch help

Show general help or help for a specific command:

mini-merch --help
mini-merch generate --help

Troubleshooting

"Config file not found"

❌ Error: Vendor config not found. Run "mini-merch setup" first.

Fix: You haven't run the setup command yet. Run:

mini-merch setup <your-address> <your-apikey> <your-pubkey>

"Invalid Minima address format"

Your address doesn't look right. It must:

• Start with 0x
• Be exactly 66 characters long
• Contain only hexadecimal characters (0-9, a-f)

Fix: Double-check and copy the address exactly from your Minima wallet.

"Invalid vendor public key format"

Your public key doesn't look right. It must:

• Start with Mx
• Be very long (100+ characters)

Fix: Get the correct key from your miniMerchInbox MiniDapp. Make sure you copied the entire key including the Mx prefix.

"CMC rate limit exceeded" / prices not loading

You've hit CoinMarketCap's free tier limit (10,000 calls/month).

Fixes:

• Wait — the rate limit resets monthly
• For high-traffic shops, consider a paid CoinMarketCap plan
• miniMerch falls back to CoinGecko if CMC fails — prices will still work

"Permission denied" when installing

npm ERR! EACCES permission denied

Fix: Don't use sudo. Instead, fix your npm permissions:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @eurobuddha/mini-merch

Or use nvm to manage Node versions without permission issues.

"mini-merch: command not found"

Fixes:

1. Reinstall the CLI:

   npm uninstall -g @eurobuddha/mini-merch
   npm install -g @eurobuddha/mini-merch

2. Find where npm installed it:

   npm bin -g

   Make sure that directory is in your PATH.

3. Try calling it directly:

   npx @eurobuddha/mini-merch --version

Order not appearing in inbox

Orders are sent over the Minima P2P network (not the blockchain), which means:

• Wait up to 5 minutes — P2P networks take time to propagate
• Keep your Minima node online — orders queue but don't arrive if your node is off
• Check the transaction — if the payment confirmed on-chain, the message will eventually arrive
• Restart your Minima node — sometimes a restart clears message queue issues

Uninstalling

Remove the CLI tool

npm uninstall -g @eurobuddha/mini-merch

Remove your stored config

mini-merch config --reset

Or manually delete the config file:

rm ~/.mini-merch/config.json

Remove generated MiniDapps

rm -rf ./dist

How to Get Help

• Open an issue on GitHub: github.com/eurobuddha/miniMerch/issues
• Minima Discord: Join the official Minima community for blockchain-related questions

License

MIT — do whatever you want with it.