Agent To Merchant Payments
Payments are broken for AI agents. Snaplii unlocks real-world commerce with a safe, tokenized payment layer β powered by 500+ merchant gift cards β and is the only one that actually saves you money (up to 10% per transaction), on top of any existing deals or promotions.
Ask AI about Agent To Merchant Payments
Powered by Claude Β· Grounded in docs
I know everything about Agent To Merchant Payments. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Agent-to-Merchant Payments by Snaplii
Payments are broken for AI agents.
Snaplii unlocks real-world commerce with a safe, tokenized payment layer β powered by 500+ merchant gift cards β and is the only one that actually saves you money (up to 10% per transaction), on top of any existing deals or promotions.
The Problem
AI agents can already:
- decide what to buy
- compare options
- navigate merchant platforms
But they still canβt safely pay. Payments require trust, compliance, and risk control β things AI agents are not designed to handle.
Giving agents access to cards is not a solution. Itβs a risk.
The Solution
Snaplii introduces a new model: User β Agent β Snaplii β Merchant
- Users fund Snaplii
- Agents operate within a controlled boundary
- Each transaction is pre-funded, isolated, and non-reusable
No shared credentials. No persistent risk.
In addition, Snaplii embeds value directly into the payment layer β
transactions can save up to 10% and stack seamlessly with existing merchant deals and promotions.
Table of Contents
- Requirements
- Quick Start
- Components
- CLI Commands
- Claude Desktop Setup MCP Server
- Claude Code Skill
- Troubleshooting
- Security
- License
Requirements
- Python 3.10+
CLI works on Python 3.9+, but the MCP server requires Python 3.10+. - Git
- Snaplii Mobile App
Required to generate your API key.
Mac users: check your Python version
python3 --version
If your Python version is below 3.10, install Python via Homebrew:
brew install python@3.12
Then use python3.12 and pip3.12 instead of python3 / pip3 in the steps below.
Quick Start
1. Get Your API Key via Snaplii App
Before using the CLI or configuring your AI agent, generate a secure API key from the Snaplii mobile app:
- Download the Snaplii app for iOS or Android.
- Register an account and bind a payment method to load your Snaplii Cash balance.
- In the app, go to More β Payment Methods β AI Payment Management.
- Tap + New API Key.
- Set a name, define the permission scope, and set a hard spending limit.
- Example scopes: Read-only or Purchase
- Copy the API key.
- Format:
snp_sk_live_... - Keep it safe β it will only be shown once.
- Format:
2. Get the Code
git clone https://github.com/Snaplii-Inc/agent-to-merchant-payments.git
cd agent-to-merchant-payments
3. Install the CLI
pipx is the smoothest path. It installs the CLI in its own isolated environment and puts the snaplii executable on your PATH.
macOS
brew install pipx
pipx ensurepath
Linux
python3 -m pip install --user pipx
python3 -m pipx ensurepath
Windows
Option A β Scoop (recommended):
scoop install pipx
pipx ensurepath
Option B β pip:
py -m pip install --user pipx
If you see a warning that
pipx.exeis not on PATH, run the following from the displayed path:.\pipx.exe ensurepath
Restart your terminal after running ensurepath.
Note: If you installed Python from the Microsoft Store, use
python3instead ofpy.
All platforms
pipx install -e ./snaplii-cli
Open a new terminal window so the updated PATH takes effect, then verify the installation:
snaplii --help
If you see
command not found, see Troubleshooting.
4. Authenticate
Link your local CLI to your Snaplii account using the API key generated in Step 1:
snaplii init
The CLI will prompt for your API key via hidden input (like a password prompt). The key is used only to obtain a session token and is never stored on disk. Agent ID is auto-derived from the key.
5. Use the CLI
snaplii browse tags --prov CA # Browse gift card categories (CA or US)
snaplii browse brand --id CB... # See denominations and cashback
snaplii giftcard list # View owned cards
snaplii purchase --item-id CB...-CT... --price 50 --prov ON # Buy a card
--item-idis formatted as{cardBrandId}-{cardTemplateId}. Both IDs are available fromsnaplii browse brand.Note on
--prov: Forbrowse tags, use country code (CAfor Canada,USfor United States). Forpurchase, use province/state code (ON,QC,BC,NY,CA,TX, etc.).
Components
agent-to-merchant-payments/
βββ snaplii-cli/ # Python CLI β pip-installable
βββ mcp-server/ # MCP server for Claude Desktop
βββ skills/ # Claude Code skill definition
βββ clawhub-publish/ # ClawHub skill artifact
βββ clawhub-plugin/ # ClawHub MCP bundle plugin
CLI Commands
| Command | Purpose |
|---|---|
snaplii init | Authenticate with your Snaplii API key |
snaplii config show | Show current config and auth status |
snaplii browse tags | Browse card categories and brands |
snaplii browse brand --id ID | View brand details, denominations, and cashback |
snaplii giftcard list | List owned gift cards |
snaplii giftcard detail --card-no NO | View card redemption code and PIN |
snaplii purchase --item-id ID --price P --prov PROV | Purchase a gift card (prov = province/state) |
snaplii smart cashback --brand-id ID --amount A | Calculate cashback savings |
snaplii smart dashboard | View card inventory summary |
Claude Desktop Setup MCP Server
Claude Desktop cannot run CLI commands directly. It requires an MCP server to bridge the gap. The Snaplii MCP server exposes tools that let Claude browse gift cards and make purchases through natural conversation.
Step 1: Install dependencies
The MCP server requires Python 3.10+ and the mcp package. Install both the CLI and server dependencies:
pip3 install -e ./snaplii-cli
pip3 install "mcp[cli]"
If you get an externally-managed-environment error, add --break-system-packages:
pip3 install -e ./snaplii-cli --break-system-packages
pip3 install "mcp[cli]" --break-system-packages
Step 2: Authenticate one time
The MCP server reads credentials from ~/.snaplii/config.json. If you have not authenticated yet, run:
snaplii init
Enter your API key when prompted.
Step 3: Configure Claude Desktop
Edit your Claude Desktop config file:
| OS | Config file location |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |
Add the mcpServers section. Create the file if it does not exist. Use absolute paths:
{
"mcpServers": {
"snaplii": {
"command": "/absolute/path/to/python",
"args": ["/absolute/path/to/agent-to-merchant-payments/mcp-server/server.py"]
}
}
}
[!IMPORTANT]
commandmust point to the Python interpreter wheremcpis installed. Find it withwhich python3orecho ~/.venvs/snaplii/bin/python.argsmust be the exact path toserver.pyinside your cloned repo.
Step 4: Restart Claude Desktop
Fully quit Claude Desktop, for example with Cmd+Q on macOS, then reopen it. You should now see the Snaplii tools available.
Step 5: Verify
In a new Claude Desktop conversation, ask:
What gift cards are available on Snaplii?
Claude should automatically call snaplii_browse_tags and display the categories.
Claude Code Skill
Claude Code expects each skill in its own directory containing a SKILL.md file:
mkdir -p ~/.claude/skills/snaplii-cli
cp skills/snaplii-cli.md ~/.claude/skills/snaplii-cli/SKILL.md
Then open:
~/.claude/skills/snaplii-cli/SKILL.md
If the file contains a line like this:
Always prepend `export PATH="$PATH:/Users/.../bin" &&` before any snaplii command.
Replace the path with the directory that holds your snaplii binary. You can find it with:
which snaplii
On Windows, use:
where.exe snaplii
If snaplii is already on your default PATH, you can delete the export PATH=... prefix entirely.
Troubleshooting
snaplii: command not found after install
The console script was placed somewhere not on your PATH. Run:
python3 -m pip show -f snaplii-cli
Look for an entry ending in bin/snaplii or Scripts\snaplii.exe on Windows. Then either prepend that directory to PATH in your shell configuration, or reinstall using pipx.
externally-managed-environment from pip
Your system Python forbids global package installs. Use pipx, which is recommended, or a virtual environment. As a last resort, append --break-system-packages to the pip command.
Claude Desktop logs ModuleNotFoundError: No module named 'mcp' or 'snaplii'
The Python interpreter referenced by command in claude_desktop_config.json does not have the required dependencies. Confirm with:
/absolute/path/to/python -c "import mcp, snaplii; print('ok')"
If it fails, install the missing packages into that specific interpreter:
pip install -e ./snaplii-cli
pip install "mcp[cli]"
Security
- Limited authorization: agents can only spend from Snaplii Cash, your prepaid balance.
- Scoped API keys: keys can be restricted to
PAY_READview-only orPAY_WRITEview + purchase. - Spending limits: strict per-key consumption caps are set via the mobile app.
- Data protection: card redemption codes and PINs are strictly masked and never exposed without explicit user consent.
License
This project is licensed under the Apache License 2.0.
See the Apache License 2.0 for details.
