跳转到主要内容
v0.2.0 — 在GitHub上开源

ClawPurse
402 Gateway

在Neutaro区块链上用NTMPI微支付保护任何API的HTTP反向代理。面向AI代理、自动化脚本和机器间商务的按请求付费和预付余额流程。

  客户端(AI代理、脚本、浏览器)
    │
    ├── GET /api/data ─────────────────────▶  402 Gateway
    │                                              │
    │   ◀── 402 Payment Required ────────────────┘
    │       { invoiceId, amount, address, memo }
    │
    ├── clawpurse send <address> <amount> --memo <memo> --yes
    │       (链上NTMPI支付)
    │
    ├── GET /api/data ─────────────────────▶  402 Gateway
    │   Header: X-Payment-Proof: <invoiceId>     │
    │                                              │
    │   网关在Neutaro上验证支付    │
    │                                              │
    │   ◀── 200 OK (从上游代理) ────┘
支付流程

两种微支付流程:按请求付费和预付余额

无论您的代理按次付费还是预充值余额,网关都会自动处理发票创建、链上验证和上游代理。

1

按请求付费

客户端访问受保护端点并收到带发票的402。链上支付后使用X-Payment-Proof头重试。网关在Neutaro上验证交易并代理到上游。

2

预付余额

客户端通过/prepaid/deposit一次性存入NTMPI。后续请求包含X-Client-Id头,网关按次扣减——无需重复链上交易。

功能

为AI代理和机器间商务而构建

机器间微支付层所需的一切,仅此而已。

链上验证

查询Neutaro REST API确认支付金额、备注和区块确认。

🧾

路由级定价

设置默认价格并通过GATEWAY_ROUTES按路由覆盖。便宜的读取,昂贵的写入。

🔒

管理API

用于内部钱包、交易和轻量级区块链账本的JWT保护端点。

🔄

反向代理

透明地将已认证请求转发到上游API。任何后端,任何语言。

📦

SQLite存储

发票、预付余额和支付日志存储在单个本地文件中。零外部依赖。

🐳

Docker就绪

使用docker compose up一键部署。包含Ubuntu部署脚本。

API

网关API端点参考

用于健康检查、发票查询和余额查询的免费端点。其他请求通过402网关。

免费——无需支付

方法路径描述
GET /health 带网关配置的健康检查
GET /invoices/:id 检查发票状态(触发链上验证)
POST /prepaid/deposit 注册存款(先链上验证tx)
GET /prepaid/balance/:clientId 检查预付余额

管理——JWT保护

方法路径描述
POST/manage/auth/register注册管理员账户
POST/manage/auth/login登录,获取JWT令牌
POST/manage/wallet创建内部钱包
GET/manage/wallet列出您的钱包
GET/manage/wallet/:id按ID获取钱包
POST/manage/transactions创建内部交易
GET/manage/transactions/:id按ID获取交易

402网关——全局捕获

方法路径描述
ANY /* 所有其他请求需要支付或预付余额
集成

代理集成:Python和TypeScript示例

几行代码将402流程接入任何代理。网关处理发票和验证——您的代码只需支付和重试。

agent.py
import requests, subprocess, os

res = requests.get("http://gateway:4020/api/data")

if res.status_code == 402:
    inv = res.json()["payment"]

    # Pay with ClawPurse
    subprocess.run([
        "clawpurse", "send",
        inv["address"], inv["amount"],
        "--memo", inv["memo"], "--yes"
    ])

    # Retry with proof
    res = requests.get(
        "http://gateway:4020/api/data",
        headers={"X-Payment-Proof": inv["invoiceId"]}
    )

data = res.json()
agent.ts
async function paidFetch(url: string) {
  let res = await fetch(url);

  if (res.status === 402) {
    const { payment } = await res.json();

    // Pay with ClawPurse
    const { send, loadKeystore }
      = await import("clawpurse");
    const { wallet, address }
      = await loadKeystore(
          process.env.CLAWPURSE_PASSWORD!
        );
    await send(
      wallet, address,
      payment.address, payment.amount,
      { memo: payment.memo }
    );

    // Retry with proof
    res = await fetch(url, {
      headers: {
        "X-Payment-Proof": payment.invoiceId
      }
    });
  }
  return res.json();
}
快速开始

不到一分钟安装并运行网关

terminal
# Clone and install
git clone https://github.com/mhue-ai/clawpurse-gateway.git
cd clawpurse-gateway && npm install

# Configure
cp .env.example .env
# Set GATEWAY_PAYMENT_ADDRESS and JWT_SECRET

# Start a test upstream
npm run test:upstream

# Start the gateway
npm run dev

# Test the 402 flow
curl http://localhost:4020/api/test
# Pay, then retry with proof:
curl -H "X-Payment-Proof: <invoiceId>" \
     http://localhost:4020/api/test
架构

TypeScript微服务架构

精简的TypeScript代码库——网关逻辑、四个内部服务和中间件。46个单元测试覆盖每一层。

config.ts
环境变量驱动的网关配置
db.ts
SQLite:发票、预付、日志
invoice.ts
发票创建和路由定价
verify.ts
链上支付验证
proxy.ts
反向代理到上游
AuthService
管理API的JWT认证
WalletService
内部钱包账本
TxService
钱包间转账
BlockchainSvc
内部区块链
配置

通过环境变量配置网关

所有设置通过环境变量或.env文件。

变量默认值描述
PORT4020网关监听端口
GATEWAY_UPSTREAMhttp://localhost:3000代理的上游API
GATEWAY_PAYMENT_ADDRESS您的Neutaro钱包地址(必需)
GATEWAY_DEFAULT_PRICE0.001每个请求的默认价格(NTMPI)
GATEWAY_ROUTES路由定价覆盖
GATEWAY_RESThttps://api2.neutaro.ioNeutaro REST API端点
GATEWAY_MIN_CONFIRMATIONS1所需区块确认数
GATEWAY_INVOICE_TTL300发票有效期(秒)
GATEWAY_PREPAIDfalse启用预付余额系统
GATEWAY_DB./gateway.dbSQLite数据库路径
JWT_SECRET管理API JWT密钥(必需)
生态系统

Timpi、Neutaro和ClawPurse生态系统的一部分

ClawPurse钱包

带加密密钥库、护栏、质押和目标白名单的本地NTMPI钱包。网关支付的参考客户端。

github.com/mhue-ai/ClawPurse →

Neutaro区块链

驱动NTMPI的Cosmos SDK链。所有网关支付直接对Neutaro REST API验证——无预言机,无桥接。

neutaro.com →

Timpi网络

隐私优先的去中心化搜索、开放数据API和DePIN节点。使用ClawPurse Gateway通过微支付变现Timpi服务。

timpi.io →

Timpi Drip水龙头

用工作量证明替代CAPTCHA的代理友好型NTMPI水龙头。OpenClaw认证代理获得更高吞吐量。

drip.clawpurse.ai →

Ledger Timpi

Free NTMPI cost basis calculator and tax tool. Auto-fetches transfers, staking rewards, and node payouts from the Neutaro chain — calculates USD cost basis with FIFO/LIFO/HIFO and generates IRS Form 8949.

ledger.clawpurse.ai →

x402 Payment Protocol

Coinbase's open HTTP 402 standard routes every payment through a centralized facilitator that controls settlement. ClawPurse Gateway takes the opposite approach: peer-to-peer payments verified directly on Neutaro — no middleman, no EVM lock-in, no Coinbase SDK. Add prepaid balances for zero-latency repeat access, route-level pricing in one env var, and a full audit trail in SQLite. One Docker command to deploy; zero external dependencies to operate.

Full comparison →

x402.org →

github.com/coinbase/x402 →

FAQ

常见问题

什么是ClawPurse Gateway?

实现402 Payment Required状态码的开源HTTP反向代理,用NTMPI微支付保护任何API。支持按请求付费和预付余额流程。

HTTP 402支付流程如何工作?

客户端收到带发票的402响应,链上支付后使用X-Payment-Proof头重试。网关验证交易并代理到上游。

什么是NTMPI?如何获取?

NTMPI是Neutaro区块链的原生代币,是 Timpi 去中心化搜索网络的一部分。从 Timpi Drip水龙头获取免费NTMPI,或在 MEXC 通过NTMPI/USDT现货对购买,或通过Gravity Bridge桥接到Osmosis使用Keplr或Leap钱包兑换。

AI代理能否自主使用ClawPurse Gateway?

是的。网关为代理AI设计。代理程序化解析402发票,通过 ClawPurse钱包API链上支付并用支付证明头重试——完全无需人工干预。