snaplii-agent-payments

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Snaplii Agent Payments

Snaplii Agent支付功能

Skill by ara.so — AI Agent Skills collection.

Snaplii unlocks real-world commerce for AI agents through a safe, tokenized payment layer powered by 500+ merchant gift cards. It's the only payment solution that saves you money (up to 10% per transaction) while maintaining security through pre-funded, isolated, non-reusable transactions.

由ara.so提供的Skill — AI Agent Skills合集。

Snaplii通过由500+商户礼品卡支持的安全代币化支付层，为AI Agent解锁真实世界的商业消费能力。这是唯一一款既能为你省钱（每笔交易最高省10%），又能通过预充值、隔离、不可重复使用的交易保障安全性的支付解决方案。

What It Does

功能介绍

Snaplii solves the payment problem for AI agents:

Safe: No shared credentials, each transaction is pre-funded and isolated
Controlled: Users fund Snaplii Cash, agents operate within strict boundaries
Value-added: Up to 10% savings that stack with existing merchant deals
Tokenized: 500+ merchant gift cards available (CA and US)

The flow: User → Agent → Snaplii → Merchant

Snaplii解决了AI Agent的支付难题：

安全可靠：无共享凭证，每笔交易均为预充值且独立隔离
可控性强：用户充值Snaplii Cash，Agent在严格限制范围内操作
增值优惠：最高10%的折扣可与商户现有优惠叠加使用
代币化支持：覆盖加拿大和美国的500+商户礼品卡

流程：用户 → Agent → Snaplii → 商户

Installation

安装步骤

Requirements

前置要求

Python 3.10+ (CLI works on 3.9+, MCP server requires 3.10+)
Snaplii Mobile App (iOS / Android)

Python 3.10+（CLI工具可在3.9+版本运行，MCP服务器需3.10+）
Snaplii移动应用（iOS / Android）

Clone the Repository

克隆仓库

bash

git clone https://github.com/Snaplii-Inc/agent-to-merchant-payments.git
cd agent-to-merchant-payments

bash

git clone https://github.com/Snaplii-Inc/agent-to-merchant-payments.git
cd agent-to-merchant-payments

Install CLI with pipx (Recommended)

使用pipx安装CLI（推荐）

macOS:

bash

brew install pipx
pipx ensurepath
pipx install -e ./snaplii-cli

Linux:

bash

python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install -e ./snaplii-cli

Windows (with Scoop):

powershell

scoop install pipx
pipx ensurepath
pipx install -e ./snaplii-cli

After installation, restart your terminal and verify:

bash

snaplii --help

macOS系统：

bash

brew install pipx
pipx ensurepath
pipx install -e ./snaplii-cli

Linux系统：

bash

python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install -e ./snaplii-cli

Windows系统（搭配Scoop）：

powershell

scoop install pipx
pipx ensurepath
pipx install -e ./snaplii-cli

安装完成后，重启终端并验证：

bash

snaplii --help

Alternative: Install with pip

替代方案：使用pip安装

bash

pip install -e ./snaplii-cli

If you get

externally-managed-environment

error:

bash

pip install -e ./snaplii-cli --break-system-packages

bash

pip install -e ./snaplii-cli

若遇到

externally-managed-environment

错误：

bash

pip install -e ./snaplii-cli --break-system-packages

Getting Your API Key

获取API密钥

Download and open the Snaplii mobile app
Register an account and bind a payment method to load Snaplii Cash
Navigate to: More → Payment Methods → AI Payment Management
Tap + New API Key
Set a name, permission scope (Read-only or Purchase), and spending limit
Copy the API key (format:
```
snp_sk_live_...
```
) — it's shown only once

Store the key securely in your environment:

bash

export SNAPLII_API_KEY="snp_sk_live_your_key_here"

下载并打开Snaplii移动应用
注册账号并绑定支付方式以充值Snaplii Cash
导航至：更多 → 支付方式 → AI支付管理
点击**+ 新建API密钥**
设置名称、权限范围（只读或可消费）以及消费限额
复制API密钥（格式：
```
snp_sk_live_...
```
）—— 密钥仅显示一次

将密钥安全存储到环境变量中：

bash

export SNAPLII_API_KEY="snp_sk_live_your_key_here"

Authentication

身份验证

Authenticate the CLI with your API key:

bash

snaplii init

The CLI will prompt for your API key via hidden input (like a password). The key is used only to obtain a session token and is never stored on disk. Configuration is saved to

~/.snaplii/config.json

Verify authentication:

bash

snaplii config show

使用API密钥对CLI进行身份验证：

bash

snaplii init

CLI会通过隐藏输入（类似密码输入）提示你输入API密钥。密钥仅用于获取会话令牌，绝不会存储在磁盘上。配置信息将保存至

~/.snaplii/config.json

。

验证身份状态：

bash

snaplii config show

Key CLI Commands

核心CLI命令

Browse Available Gift Cards

浏览可用礼品卡

Browse by category (Canada):

bash

snaplii browse tags --prov CA

Browse by category (United States):

bash

snaplii browse tags --prov US

View specific brand details with denominations and cashback:

bash

snaplii browse brand --id CB_AMAZON_CA

按分类浏览（加拿大地区）：

bash

snaplii browse tags --prov CA

按分类浏览（美国地区）：

bash

snaplii browse tags --prov US

查看特定品牌的面额和返现详情：

bash

snaplii browse brand --id CB_AMAZON_CA

Purchase Gift Cards

购买礼品卡

Purchase a gift card (requires

--item-id

--price

, and

--prov

bash

undefined

购买礼品卡（需指定

--item-id

、

--price

和

--prov

）：

bash

undefined

Ontario, Canada

加拿大安大略省

snaplii purchase --item-id CB_STARBUCKS_CA-CT_DIGITAL --price 25 --prov ON

California, USA

美国加利福尼亚州

snaplii purchase --item-id CB_AMAZON_US-CT_DIGITAL --price 50 --prov CA


**Note on `--prov`:**
- For `browse tags`: use country code (`CA` or `US`)
- For `purchase`: use province/state code (`ON`, `QC`, `BC`, `NY`, `CA`, `TX`, etc.)

**Item ID Format:** `{cardBrandId}-{cardTemplateId}`
Both IDs are available from `snaplii browse brand` output.

snaplii purchase --item-id CB_AMAZON_US-CT_DIGITAL --price 50 --prov CA


**关于`--prov`的说明：**
- 使用`snaplii browse tags`时：使用国家代码（`CA`或`US`）
- 使用`snaplii purchase`时：使用省/州代码（`ON`、`QC`、`BC`、`NY`、`CA`、`TX`等）

**Item ID格式：** `{cardBrandId}-{cardTemplateId}`
两个ID均可通过`snaplii browse brand`命令的输出获取。

Get Purchase Quote

获取购买报价

Preview price with voucher/cashback before buying:

bash

snaplii quote --item-id CB_AMAZON_CA-CT_DIGITAL --price 100

在购买前预览包含优惠券/返现的价格：

bash

snaplii quote --item-id CB_AMAZON_CA-CT_DIGITAL --price 100

Manage Gift Cards

管理礼品卡

List all owned gift cards:

bash

snaplii giftcard list

View card redemption code and PIN:

bash

snaplii giftcard detail --card-no GC_1234567890

列出所有已拥有的礼品卡：

bash

snaplii giftcard list

查看礼品卡的兑换码和PIN码：

bash

snaplii giftcard detail --card-no GC_1234567890

Smart Features

智能功能

Calculate cashback savings:

bash

snaplii smart cashback --brand-id CB_AMAZON_CA --amount 100

View card inventory summary:

bash

snaplii smart dashboard

计算返现节省金额：

bash

snaplii smart cashback --brand-id CB_AMAZON_CA --amount 100

查看礼品卡库存汇总：

bash

snaplii smart dashboard

Python Code Examples

Python代码示例

Using the CLI from Python

在Python中调用CLI

python

import subprocess
import json
import os

python

import subprocess
import json
import os

Set API key in environment

在环境变量中设置API密钥

os.environ['SNAPLII_API_KEY'] = 'snp_sk_live_...'

Browse available tags

浏览可用分类

result = subprocess.run( ['snaplii', 'browse', 'tags', '--prov', 'CA'], capture_output=True, text=True ) print(result.stdout)

Purchase a gift card

购买礼品卡

purchase = subprocess.run( [ 'snaplii', 'purchase', '--item-id', 'CB_AMAZON_CA-CT_DIGITAL', '--price', '50', '--prov', 'ON' ], capture_output=True, text=True ) print(purchase.stdout)

List owned cards

列出已拥有的礼品卡

cards = subprocess.run( ['snaplii', 'giftcard', 'list'], capture_output=True, text=True ) print(cards.stdout)

undefined

cards = subprocess.run( ['snaplii', 'giftcard', 'list'], capture_output=True, text=True ) print(cards.stdout)

undefined

Automated Gift Card Purchase Flow

自动化礼品卡购买流程

python

import subprocess
import json

def get_quote(item_id, price):
    """Get purchase quote with cashback calculation."""
    result = subprocess.run(
        ['snaplii', 'quote', '--item-id', item_id, '--price', str(price)],
        capture_output=True,
        text=True
    )
    return result.stdout

def purchase_card(item_id, price, province):
    """Purchase a gift card and return card details."""
    result = subprocess.run(
        [
            'snaplii', 'purchase',
            '--item-id', item_id,
            '--price', str(price),
            '--prov', province
        ],
        capture_output=True,
        text=True
    )
    
    if result.returncode == 0:
        print(f"✓ Successfully purchased {item_id}")
        return result.stdout
    else:
        print(f"✗ Purchase failed: {result.stderr}")
        return None

def get_card_details(card_no):
    """Retrieve redemption code and PIN for a card."""
    result = subprocess.run(
        ['snaplii', 'giftcard', 'detail', '--card-no', card_no],
        capture_output=True,
        text=True
    )
    return result.stdout

python

import subprocess
import json

def get_quote(item_id, price):
    """获取包含返现计算的购买报价。"""
    result = subprocess.run(
        ['snaplii', 'quote', '--item-id', item_id, '--price', str(price)],
        capture_output=True,
        text=True
    )
    return result.stdout

def purchase_card(item_id, price, province):
    """购买礼品卡并返回卡片详情。"""
    result = subprocess.run(
        [
            'snaplii', 'purchase',
            '--item-id', item_id,
            '--price', str(price),
            '--prov', province
        ],
        capture_output=True,
        text=True
    )
    
    if result.returncode == 0:
        print(f"✓ 成功购买 {item_id}")
        return result.stdout
    else:
        print(f"✗ 购买失败：{result.stderr}")
        return None

def get_card_details(card_no):
    """获取礼品卡的兑换码和PIN码。"""
    result = subprocess.run(
        ['snaplii', 'giftcard', 'detail', '--card-no', card_no],
        capture_output=True,
        text=True
    )
    return result.stdout

Example workflow

示例工作流

item_id = 'CB_STARBUCKS_CA-CT_DIGITAL' quote = get_quote(item_id, 25) print("Quote:", quote)

purchase = purchase_card(item_id, 25, 'ON') if purchase: print(purchase)

undefined

item_id = 'CB_STARBUCKS_CA-CT_DIGITAL' quote = get_quote(item_id, 25) print("报价：", quote)

purchase = purchase_card(item_id, 25, 'ON') if purchase: print(purchase)

undefined

Check Available Balance and Inventory

查看可用余额和库存

python

import subprocess

def check_dashboard():
    """View card inventory summary."""
    result = subprocess.run(
        ['snaplii', 'smart', 'dashboard'],
        capture_output=True,
        text=True
    )
    print(result.stdout)

def calculate_savings(brand_id, amount):
    """Calculate potential cashback savings."""
    result = subprocess.run(
        [
            'snaplii', 'smart', 'cashback',
            '--brand-id', brand_id,
            '--amount', str(amount)
        ],
        capture_output=True,
        text=True
    )
    print(result.stdout)

check_dashboard()
calculate_savings('CB_AMAZON_CA', 100)

python

import subprocess

def check_dashboard():
    """查看礼品卡库存汇总。"""
    result = subprocess.run(
        ['snaplii', 'smart', 'dashboard'],
        capture_output=True,
        text=True
    )
    print(result.stdout)

def calculate_savings(brand_id, amount):
    """计算潜在的返现节省金额。"""
    result = subprocess.run(
        [
            'snaplii', 'smart', 'cashback',
            '--brand-id', brand_id,
            '--amount', str(amount)
        ],
        capture_output=True,
        text=True
    )
    print(result.stdout)

check_dashboard()
calculate_savings('CB_AMAZON_CA', 100)

Claude Desktop MCP Server Setup

Claude Desktop MCP服务器设置

The MCP (Model Context Protocol) server allows Claude Desktop to make Snaplii purchases through natural conversation.

MCP（Model Context Protocol）服务器允许Claude Desktop通过自然对话完成Snaplii支付操作。

Install MCP Dependencies

安装MCP依赖

bash

pip install -e ./snaplii-cli
pip install "mcp[cli]"

If you get

externally-managed-environment

error:

bash

pip install -e ./snaplii-cli --break-system-packages
pip install "mcp[cli]" --break-system-packages

bash

pip install -e ./snaplii-cli
pip install "mcp[cli]"

若遇到

externally-managed-environment

错误：

bash

pip install -e ./snaplii-cli --break-system-packages
pip install "mcp[cli]" --break-system-packages

Authenticate

身份验证

bash

snaplii init

bash

snaplii init

Configure Claude Desktop

配置Claude Desktop

Edit the Claude Desktop config file:

OS	Config 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 this configuration (use absolute paths):

json

{
  "mcpServers": {
    "snaplii": {
      "command": "/absolute/path/to/python3",
      "args": ["/absolute/path/to/agent-to-merchant-payments/mcp-server/server.py"]
    }
  }
}

Find your Python path:

bash

which python3

On Windows:

powershell

where.exe python3

编辑Claude Desktop配置文件：

操作系统	配置文件位置
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

添加以下配置（使用绝对路径）：

json

{
  "mcpServers": {
    "snaplii": {
      "command": "/absolute/path/to/python3",
      "args": ["/absolute/path/to/agent-to-merchant-payments/mcp-server/server.py"]
    }
  }
}

查找Python路径：

bash

which python3

Windows系统：

powershell

where.exe python3

Restart Claude Desktop

重启Claude Desktop

Fully quit Claude Desktop (Cmd+Q on macOS) and reopen it.

完全退出Claude Desktop（macOS系统按Cmd+Q）后重新打开。

Verify in Claude

在Claude中验证

Ask Claude:

What gift cards are available on Snaplii?

Claude should automatically call

snaplii_browse_tags

and display categories.

向Claude提问：

Snaplii上有哪些可用的礼品卡？

Claude应自动调用

snaplii_browse_tags

并显示分类信息。

Claude Code Skill Setup

Claude Code Skill设置

For Claude Code, install the skill definition:

bash

mkdir -p ~/.claude/skills/snaplii-cli
cp skills/snaplii-cli.md ~/.claude/skills/snaplii-cli/SKILL.md

Edit

~/.claude/skills/snaplii-cli/SKILL.md

and update the PATH line if needed:

bash

which snaplii

Replace the path in the skill file with the directory containing your

snaplii

binary. If

snaplii

is already on your PATH, you can remove the

export PATH=...

prefix entirely.

针对Claude Code，安装Skill定义：

bash

mkdir -p ~/.claude/skills/snaplii-cli
cp skills/snaplii-cli.md ~/.claude/skills/snaplii-cli/SKILL.md

编辑

~/.claude/skills/snaplii-cli/SKILL.md

，若需要则更新PATH行：

bash

which snaplii

将Skill文件中的路径替换为包含

snaplii

二进制文件的目录。若

snaplii

已在你的PATH中，可直接移除

export PATH=...

前缀。

Common Patterns

常见模式

Agent-Driven Purchase Workflow

Agent驱动的购买工作流

python

import subprocess

class SnapliAgent:
    def __init__(self):
        self.authenticated = self._check_auth()
    
    def _check_auth(self):
        """Verify authentication status."""
        result = subprocess.run(
            ['snaplii', 'config', 'show'],
            capture_output=True,
            text=True
        )
        return 'authenticated' in result.stdout.lower()
    
    def browse_brands(self, country='CA'):
        """Browse available gift card brands."""
        result = subprocess.run(
            ['snaplii', 'browse', 'tags', '--prov', country],
            capture_output=True,
            text=True
        )
        return result.stdout
    
    def get_brand_details(self, brand_id):
        """Get denominations and cashback for a brand."""
        result = subprocess.run(
            ['snaplii', 'browse', 'brand', '--id', brand_id],
            capture_output=True,
            text=True
        )
        return result.stdout
    
    def make_purchase(self, item_id, price, province):
        """Execute a gift card purchase."""
        if not self.authenticated:
            raise Exception("Not authenticated. Run 'snaplii init' first.")
        
        result = subprocess.run(
            [
                'snaplii', 'purchase',
                '--item-id', item_id,
                '--price', str(price),
                '--prov', province
            ],
            capture_output=True,
            text=True
        )
        
        if result.returncode != 0:
            raise Exception(f"Purchase failed: {result.stderr}")
        
        return result.stdout
    
    def list_inventory(self):
        """List all owned gift cards."""
        result = subprocess.run(
            ['snaplii', 'giftcard', 'list'],
            capture_output=True,
            text=True
        )
        return result.stdout

python

import subprocess

class SnapliAgent:
    def __init__(self):
        self.authenticated = self._check_auth()
    
    def _check_auth(self):
        """验证身份验证状态。"""
        result = subprocess.run(
            ['snaplii', 'config', 'show'],
            capture_output=True,
            text=True
        )
        return 'authenticated' in result.stdout.lower()
    
    def browse_brands(self, country='CA'):
        """浏览可用礼品卡品牌。"""
        result = subprocess.run(
            ['snaplii', 'browse', 'tags', '--prov', country],
            capture_output=True,
            text=True
        )
        return result.stdout
    
    def get_brand_details(self, brand_id):
        """获取品牌的面额和返现信息。"""
        result = subprocess.run(
            ['snaplii', 'browse', 'brand', '--id', brand_id],
            capture_output=True,
            text=True
        )
        return result.stdout
    
    def make_purchase(self, item_id, price, province):
        """执行礼品卡购买操作。"""
        if not self.authenticated:
            raise Exception("未完成身份验证，请先运行'snaplii init'。")
        
        result = subprocess.run(
            [
                'snaplii', 'purchase',
                '--item-id', item_id,
                '--price', str(price),
                '--prov', province
            ],
            capture_output=True,
            text=True
        )
        
        if result.returncode != 0:
            raise Exception(f"购买失败：{result.stderr}")
        
        return result.stdout
    
    def list_inventory(self):
        """列出所有已拥有的礼品卡。"""
        result = subprocess.run(
            ['snaplii', 'giftcard', 'list'],
            capture_output=True,
            text=True
        )
        return result.stdout

Usage

使用示例

agent = SnapliAgent() print(agent.browse_brands('US')) print(agent.get_brand_details('CB_AMAZON_US')) purchase_result = agent.make_purchase( 'CB_AMAZON_US-CT_DIGITAL', 50, 'NY' ) print(purchase_result) print(agent.list_inventory())

undefined

undefined

Bulk Purchase with Error Handling

批量购买及错误处理

python

import subprocess
import time

def bulk_purchase(purchases):
    """
    Purchase multiple gift cards with retry logic.
    
    purchases: list of dicts with keys: item_id, price, province
    """
    results = []
    
    for purchase in purchases:
        max_retries = 3
        retry_count = 0
        
        while retry_count < max_retries:
            try:
                result = subprocess.run(
                    [
                        'snaplii', 'purchase',
                        '--item-id', purchase['item_id'],
                        '--price', str(purchase['price']),
                        '--prov', purchase['province']
                    ],
                    capture_output=True,
                    text=True,
                    timeout=30
                )
                
                if result.returncode == 0:
                    results.append({
                        'success': True,
                        'purchase': purchase,
                        'output': result.stdout
                    })
                    break
                else:
                    retry_count += 1
                    if retry_count >= max_retries:
                        results.append({
                            'success': False,
                            'purchase': purchase,
                            'error': result.stderr
                        })
                    else:
                        time.sleep(2 ** retry_count)  # Exponential backoff
                        
            except subprocess.TimeoutExpired:
                retry_count += 1
                if retry_count >= max_retries:
                    results.append({
                        'success': False,
                        'purchase': purchase,
                        'error': 'Timeout after 30 seconds'
                    })
    
    return results

python

import subprocess
import time

def bulk_purchase(purchases):
    """
    批量购买礼品卡并包含重试逻辑。
    
    purchases: 包含item_id、price、province键的字典列表
    """
    results = []
    
    for purchase in purchases:
        max_retries = 3
        retry_count = 0
        
        while retry_count < max_retries:
            try:
                result = subprocess.run(
                    [
                        'snaplii', 'purchase',
                        '--item-id', purchase['item_id'],
                        '--price', str(purchase['price']),
                        '--prov', purchase['province']
                    ],
                    capture_output=True,
                    text=True,
                    timeout=30
                )
                
                if result.returncode == 0:
                    results.append({
                        'success': True,
                        'purchase': purchase,
                        'output': result.stdout
                    })
                    break
                else:
                    retry_count += 1
                    if retry_count >= max_retries:
                        results.append({
                            'success': False,
                            'purchase': purchase,
                            'error': result.stderr
                        })
                    else:
                        time.sleep(2 ** retry_count)  # 指数退避
                        
            except subprocess.TimeoutExpired:
                retry_count += 1
                if retry_count >= max_retries:
                    results.append({
                        'success': False,
                        'purchase': purchase,
                        'error': '30秒后超时'
                    })
    
    return results

Example usage

使用示例

purchases = [ {'item_id': 'CB_STARBUCKS_CA-CT_DIGITAL', 'price': 25, 'province': 'ON'}, {'item_id': 'CB_AMAZON_CA-CT_DIGITAL', 'price': 50, 'province': 'ON'}, {'item_id': 'CB_WALMART_US-CT_DIGITAL', 'price': 100, 'province': 'NY'} ]

results = bulk_purchase(purchases) for r in results: if r['success']: print(f"✓ {r['purchase']['item_id']}: Success") else: print(f"✗ {r['purchase']['item_id']}: {r['error']}")

undefined

results = bulk_purchase(purchases) for r in results: if r['success']: print(f"✓ {r['purchase']['item_id']}: 成功") else: print(f"✗ {r['purchase']['item_id']}: {r['error']}")

undefined

Configuration

配置说明

Configuration is stored in

~/.snaplii/config.json

after running

snaplii init

Config structure:

json

{
  "agent_id": "derived_from_api_key",
  "session_token": "session_token_here",
  "token_expiry": "2026-06-01T12:00:00Z"
}

Security notes:

API key is NEVER stored on disk
Session tokens expire and require re-authentication
Spending limits and scopes are enforced server-side

View current config:

bash

snaplii config show

运行

snaplii init

后，配置信息将存储在

~/.snaplii/config.json

中。

配置结构：

json

{
  "agent_id": "derived_from_api_key",
  "session_token": "session_token_here",
  "token_expiry": "2026-06-01T12:00:00Z"
}

安全注意事项：

API密钥绝不会存储在磁盘上
会话令牌会过期，需要重新验证身份
消费限额和权限范围由服务器端强制执行

查看当前配置：

bash

snaplii config show

Environment Variables

环境变量

bash

undefined

bash

undefined

Set API key for programmatic access

为程序化访问设置API密钥

export SNAPLII_API_KEY="snp_sk_live_your_key_here"

Optional: Set config directory (defaults to ~/.snaplii)

可选：设置配置目录（默认值为~/.snaplii）

export SNAPLII_CONFIG_DIR="/custom/path/to/config"

undefined

export SNAPLII_CONFIG_DIR="/custom/path/to/config"

undefined

Troubleshooting

故障排除

Command Not Found

命令未找到

snaplii: command not found

after install:

bash

undefined

若安装后出现

snaplii: command not found

：

bash

undefined

Check where it was installed

检查安装位置

python3 -m pip show -f snaplii-cli


Look for `bin/snaplii` or `Scripts\snaplii.exe` in the output. Add that directory to your PATH or use `pipx` instead.

python3 -m pip show -f snaplii-cli


在输出中查找`bin/snaplii`或`Scripts\snaplii.exe`。将该目录添加到你的PATH中，或改用`pipx`安装。

Module Not Found (MCP Server)

模块未找到（MCP服务器）

If Claude Desktop logs

ModuleNotFoundError: No module named 'mcp'

'snaplii'

bash

undefined

若Claude Desktop日志显示

ModuleNotFoundError: No module named 'mcp'

或

'snaplii'

：

bash

undefined

Verify the Python interpreter has required packages

验证Python解释器是否已安装所需包

/absolute/path/to/python -c "import mcp, snaplii; print('ok')"


If it fails, install dependencies to that specific interpreter:
```bash
/absolute/path/to/python -m pip install -e ./snaplii-cli
/absolute/path/to/python -m pip install "mcp[cli]"

/absolute/path/to/python -c "import mcp, snaplii; print('ok')"


若验证失败，为该特定解释器安装依赖：
```bash
/absolute/path/to/python -m pip install -e ./snaplii-cli
/absolute/path/to/python -m pip install "mcp[cli]"

Externally-Managed Environment

外部管理环境错误

If pip refuses to install globally:

Option 1 (Recommended): Use

pipx

bash

pipx install -e ./snaplii-cli

Option 2: Use virtual environment

bash

python3 -m venv ~/.venvs/snaplii
source ~/.venvs/snaplii/bin/activate
pip install -e ./snaplii-cli

Option 3: Override system protection (use cautiously)

bash

pip install -e ./snaplii-cli --break-system-packages

若pip拒绝全局安装：

方案1（推荐）： 使用

pipx

bash

pipx install -e ./snaplii-cli

方案2： 使用虚拟环境

bash

python3 -m venv ~/.venvs/snaplii
source ~/.venvs/snaplii/bin/activate
pip install -e ./snaplii-cli

方案3： 覆盖系统保护（谨慎使用）

bash

pip install -e ./snaplii-cli --break-system-packages

Authentication Issues

身份验证问题

If authentication fails:

Verify API key format starts with
```
snp_sk_live_
```
Check key permissions in Snaplii mobile app
Ensure spending limit is not exhausted
Re-run
```
snaplii init
```
to refresh session

若身份验证失败：

验证API密钥格式是否以
```
snp_sk_live_
```
开头
在Snaplii移动应用中检查密钥权限
确保消费限额未耗尽
重新运行
```
snaplii init
```
以刷新会话

Purchase Failures

购买失败

Common causes:

Insufficient Snaplii Cash balance (load more in mobile app)
Invalid province/state code (use 2-letter codes: ON, QC, NY, CA, TX)
Item ID mismatch (verify with
```
snaplii browse brand --id <brand_id>
```
)
API key lacks
```
PAY_WRITE
```
permission (check scope in mobile app)

Debug with verbose output:

bash

snaplii purchase --item-id CB_AMAZON_CA-CT_DIGITAL --price 50 --prov ON -v

常见原因：

Snaplii Cash余额不足（在移动应用中充值）
省/州代码无效（使用两位代码：ON、QC、NY、CA、TX等）
Item ID不匹配（通过
```
snaplii browse brand --id <brand_id>
```
验证）
API密钥缺少
```
PAY_WRITE
```
权限（在移动应用中检查权限范围）

使用详细输出调试：

bash

snaplii purchase --item-id CB_AMAZON_CA-CT_DIGITAL --price 50 --prov ON -v

Security Best Practices

安全最佳实践

Never hardcode API keys — always use environment variables
Set strict spending limits on each API key in the mobile app
Use scoped permissions — prefer
```
PAY_READ
```
for browse-only agents
Rotate keys regularly especially if exposed in logs
Monitor transactions via the Snaplii mobile app dashboard
Revoke compromised keys immediately in AI Payment Management

切勿硬编码API密钥 — 始终使用环境变量
为每个API密钥设置严格的消费限额（在移动应用中配置）
使用范围化权限 — 仅浏览的Agent优先选择
```
PAY_READ
```
权限
定期轮换密钥，尤其是在日志中暴露后
通过Snaplii移动应用仪表盘监控交易
若密钥泄露，立即在AI支付管理中撤销

Component Overview

组件概述

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

agent-to-merchant-payments/
├── snaplii-cli/       # Python CLI（可通过pip安装）
├── mcp-server/        # 用于Claude Desktop的MCP服务器
├── skills/            # Claude Code Skill定义
├── clawhub-publish/   # ClawHub Skill制品
└── clawhub-plugin/    # ClawHub MCP捆绑插件

Additional Resources

额外资源

Homepage: https://www.snaplii.com/
Repository: https://github.com/Snaplii-Inc/agent-to-merchant-payments
iOS App: https://apps.apple.com/app/snaplii/id1596924498
Android App: https://play.google.com/store/apps/details?id=com.snaplii.app

官网：https://www.snaplii.com/
代码仓库：https://github.com/Snaplii-Inc/agent-to-merchant-payments
iOS应用：https://apps.apple.com/app/snaplii/id1596924498
Android应用：https://play.google.com/store/apps/details?id=com.snaplii.app

License

许可证

Apache License 2.0 — see repository for full license text.

Apache License 2.0 — 详见仓库中的完整许可证文本。