使用说明

小齿轮os

客户端SDK、Claude Code插件和技能服务器框架小齿轮.在Base上处理x402微支付，因此您的代码（或您的代理）可以调用链上技能，而无需考虑支付。

建筑

                        +------------------------+
                        |   Your App / Agent /   |
                        |     Claude Code        |
                        +-----------+------------+
                                    |
                     +--------------+--------------+
                     |        pinion-os SDK        |
                     |   x402 signing & payments   |
                     +--------------+--------------+
                                    |
                     +--------------+--------------+
                     |   pinionos.com  /  custom   |
                     |      x402 skill server      |
                     +--------------+--------------+
                                    |
                        +-----------+------------+
                        |     Base L2 Network     |
                        |    USDC  settlement     |
                        +------------------------+

三层：你的代码与SDK对话，SDK处理x402支付签名，技能服务器通过协助者验证支付并返回数据。

x402付款流程

  Client                    Skill Server                 Facilitator
    |                             |                           |
    |--- GET /price/ETH --------->|                           |
    |<-- 402 + pay requirements --|                           |
    |                             |                           |
    |  [sign EIP-3009 auth]       |                           |
    |                             |                           |
    |--- GET /price/ETH --------->|                           |
    |    X-PAYMENT: <signed>      |--- verify + settle ------>|
    |                             |<-- ok --------------------|
    |<-- 200 { price: 2650 } -----|                           |

SDK会自动处理步骤2-4。你只需调用一个方法并获取数据。

快速入门

# 1. install
npm install pinion-os

# 2. set your wallet key (needs ETH for gas, USDC for payments on Base)
export PINION_PRIVATE_KEY=0xYOUR_PRIVATE_KEY

# 3. use in code
node -e "
  import('pinion-os').then(async ({ PinionClient }) => {
    const p = new PinionClient({ privateKey: process.env.PINION_PRIVATE_KEY });
    console.log(await p.skills.price('ETH'));
  })
"

# 4. or run as MCP plugin for Claude
npx pinion-os

# 5. or build your own skill server
npx ts-node examples/custom-skill.ts

安装

npm install pinion-os

SDK使用

import { PinionClient } from "pinion-os";

const pinion = new PinionClient({
  privateKey: process.env.PINION_PRIVATE_KEY,
});

// check balances
const bal = await pinion.skills.balance("0x1234...");
console.log(bal.data);  // { eth: "1.5", usdc: "100.0" }

// get token price
const price = await pinion.skills.price("ETH");
console.log(price.data);  // { token: "ETH", usd: "2650.00" }

// look up a transaction
const tx = await pinion.skills.tx("0xabc...");
console.log(tx.data);  // { from, to, value, ... }

// generate a wallet
const w = await pinion.skills.wallet();
console.log(w.data);  // { address, privateKey }

// chat with the agent
const chat = await pinion.skills.chat("what is x402?");
console.log(chat.data);  // { response: "..." }

// construct a send transaction (sign + broadcast yourself)
const send = await pinion.skills.send("0xRecipient...", "0.1", "ETH");
console.log(send.data);  // { tx: { to, value, data, chainId }, ... }

// swap tokens via 1inch (returns unsigned tx)
const trade = await pinion.skills.trade("USDC", "ETH", "10");
console.log(trade.data);  // { swap: { to, data, value }, approve?: {...} }

// check funding status for a wallet
const fund = await pinion.skills.fund("0x1234...");
console.log(fund.data);  // { balances, funding: { steps, ... } }

// sign and broadcast a transaction
const txResult = await pinion.skills.broadcast(send.data.tx);
console.log(txResult.data);  // { hash: "0x..." }

// purchase unlimited access ($100 USDC one-time)
const unlimited = await pinion.skills.unlimited();
console.log(unlimited.data);  // { apiKey: "pk_...", address, plan: "unlimited" }

// once you have an API key, set it to skip x402 payments
pinion.setApiKey(unlimited.data.apiKey);
// all subsequent calls are free

服务器端技能通过x402在Base上花费0.01美元。付款是自动处理的。

调用任何x402端点

使用 payX402Service 要调用任何支持x402协议的服务器：

import { PinionClient, payX402Service } from "pinion-os";

const pinion = new PinionClient({
  privateKey: process.env.PINION_PRIVATE_KEY,
});

// call an external x402 service
const result = await payX402Service(pinion.signer, "https://example.com/api/weather", {
  method: "GET",
  maxAmount: "100000", // max $0.10 USDC
});
console.log(result.data);

通过Stripe x402支付Web2服务

任何使用web2的服务条纹x402 可以由您的Pinion代理商支付。SDK会自动检测服务器是使用v1还是v2 x402传输，无需配置。

import { PinionClient, payX402Service } from "pinion-os";

const pinion = new PinionClient({
  privateKey: process.env.PINION_PRIVATE_KEY,
});

// pay a Stripe-powered API -- works the same as any x402 endpoint
const result = await payX402Service(pinion.signer, "https://api.example.com/premium-data", {
  method: "GET",
  maxAmount: "100000", // max $0.10 USDC
});
console.log(result.data);

或者通过Claude使用MCP插件：

"Call https://api.example.com/premium-data using pinion_pay_service"

代理人按基数支付美元。Stripe在服务器端处理结算。代理端不需要Stripe帐户——服务器运营商拥有Stripe帐户。

同时支持x402 v1(x402-express)v2(@x402/expressStripe）服务器自动运行。

MCP插件设置

该插件向任何MCP兼容主机公开了十二个工具： pinion_balance, pinion_tx, pinion_price, pinion_wallet, pinion_chat, pinion_send, pinion_trade, pinion_fund, pinion_pay_service, pinion_spend_limit, pinion_unlimited, pinion_unlimited_verify.

克劳德桌面版

添加到您的配置文件中：

操作系统	路径
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
窗户	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

{
  "mcpServers": {
    "pinion": {
      "command": "npx",
      "args": ["pinion-os"],
      "env": {
        "PINION_PRIVATE_KEY": "0xYOUR_KEY"
      }
    }
  }
}

保存后重新启动Claude Desktop。

克劳德代码

添加市场并安装：

/plugin marketplace add chu2bard/pinion-os
/plugin install pinion-os

在系统提示时设置env var，或在启动前导出：

export PINION_PRIVATE_KEY=0xYOUR_KEY

安装后，Claude可以使用所有十二个小齿轮工具：余额、交易、价格、钱包、聊天、发送、交易、资金、支付服务、支出限制、无限、无限验证。

替代方案（仅MCP，无插件功能）：

claude mcp add pinion -- npx pinion-os

光标IDE

增添 .cursor/mcp.json 在项目根目录中：

{
  "mcpServers": {
    "pinion": {
      "command": "npx",
      "args": ["pinion-os"],
      "env": {
        "PINION_PRIVATE_KEY": "0xYOUR_KEY"
      }
    }
  }
}

通用MCP主机

PINION_PRIVATE_KEY=0xYOUR_KEY npx pinion-os

该插件使用标准MCP协议通过stdio进行通信。

可用技能

服务器端（x402付费，每个0.01美元）

技能	SDK方法	端点	价格	退货
平衡	`skills.balance(addr)`	GET/rebalance/：地址	$0.01	ETH+USDC余额
tx	`skills.tx(hash)`	GET/tx/：哈希	$0.01	解码的tx详细信息
价格	`skills.price(token)`	GET/price/：代币	$0.01	美元价格
钱包	`skills.wallet()`	获取/钱包/生成	$0.01	新密钥对
聊天	`skills.chat(msg)`	POST/聊天	$0.01	代理响应
发送	`skills.send(to, amt, token)`	POST/发送	$0.01	未签名的转账交易
贸易	`skills.trade(src, dst, amt)`	POST/交易	$0.01	未签名的掉期交易（1英寸）
基金	`skills.fund(addr)`	GET/资金/：地址	$0.01	余额+存款信息
广播	`skills.broadcast(tx)`	POST/广播	$0.01	签名+广播tx哈希
无限制	`skills.unlimited()`	POST/unlimited	100.00美元	用于无限访问的API密钥

客户端（仅限SDK/MCP插件）

技能	SDK/MCP工具	说明
按服务付费	`payX402Service(wallet, url)` / `pinion_pay_service`	呼叫互联网上的任何x402端点
支出限额	`pinion_spend_limit` （仅限MCP）	每节USDC预算跟踪
无限制验证	`skills.unlimitedVerify(key)` / `pinion_unlimited_verify`	检查无限制的API密钥是否有效

培养自己的技能

使用服务器框架创建x402付费墙端点：

import { createSkillServer, skill } from "pinion-os/server";

const server = createSkillServer({
  payTo: "0xYOUR_WALLET",
  network: "base",
});

server.add(skill("analyze", {
  price: "$0.02",
  endpoint: "/analyze/:address",
  handler: async (req, res) => {
    const data = await analyzeAddress(req.params.address);
    res.json(data);
  },
}));

server.add(skill("score", {
  price: "$0.05",
  endpoint: "/score/:address",
  handler: async (req, res) => {
    const score = await getScore(req.params.address);
    res.json({ score });
  },
}));

server.listen(4020);
// -> http://localhost:4020/analyze/0x... (x402 paywalled)
// -> http://localhost:4020/score/0x...  (x402 paywalled)

服务器自动执行以下操作：

返回402，其中包含未经身份验证的请求的付款要求
通过协调人验证x402付款签名
将Base上的USDC结算到您的钱包

配置

变量	必填	默认	描述
`PINION_PRIVATE_KEY`	yes	--	Base上带有USDC的十六进制私钥（0x…）
`PINION_API_URL`	没有	`https://pinionos.com/skill`	覆盖技能API终结点
`PINION_NETWORK`	没有	`base`	网络： `base` 或 `base-sepolia`
`PINION_API_KEY`	no	--	无限制API密钥（pk_…）以绕过x402付款
`ADDRESS`	仅限服务器	--	用于接收付款的钱包地址
`FACILITATOR_URL`	仅限服务器	`https://facilitator.payai.network`	x402主持人端点
`ANTHROPIC_API_KEY`	聊天技巧	--	聊天技巧的Anthropic API密钥
`ONEINCH_API_KEY`	交易技巧	--	1英寸API密钥，用于代币交换（服务器端）

项目结构

pinion-os/
  .claude-plugin/
    plugin.json        Claude Code plugin manifest
    marketplace.json   Plugin marketplace catalog
  .mcp.json            MCP server auto-config
  src/
    client/            SDK for calling pinion skills
      index.ts           PinionClient class
      skills.ts          typed skill wrappers
      types.ts           TypeScript interfaces
      x402.ts            EIP-3009 payment signing
      x402-generic.ts    generic x402 caller for any endpoint
      x402-v2.ts           x402 v2 transport (Stripe) support
    plugin/            Claude MCP server
      server.ts          MCP request handlers
      tools.ts           tool definitions + dispatch (12 tools)
      limits.ts          per-session spend limit tracker
      config.ts          env/arg configuration
      index.ts           CLI entry point (npx pinion-os)
    server/            Framework for building skills
      index.ts           createSkillServer factory
      skill.ts           skill() definition helper
      middleware.ts      x402 middleware wrapper
      types.ts           server types
    skills/            Built-in skill handlers
      balance.ts         ETH/USDC balance lookup
      tx.ts              transaction decoder
      price.ts           token price via CoinGecko
      wallet.ts          keypair generation
      chat.ts            AI chat via Anthropic
    shared/            Shared utilities
      constants.ts       RPC URLs, contract addresses
      rpc.ts             Base JSON-RPC helper
      errors.ts          custom error classes
  examples/
    use-sdk.ts           SDK usage example
    custom-skill.ts      custom skill server example
    claude-config.json   example MCP config
  tests/
    client.test.ts       SDK tests
    x402.test.ts         payment signing tests
    server.test.ts       skill server tests
  openclaw.plugin.json   OpenClaw skill manifest

故障排除

PINION_PRIVATE_KEY or WALLET_KEY environment variable is required

在运行之前设置env变量。密钥必须是以开头的十六进制字符串 0x.

insufficient USDC balance

您的钱包需要Base上的USDC（不是以太坊主网）。通过以下方式将USDC连接到基地 https://bridge.base.org或者直接在Base上购买。

402 Payment Required 作为回应

SDK应自动处理此问题。如果你看到402个原始响应，请检查您的私钥在Base上同时有ETH（用于天然气）和USDC（用于支付）。

MCP插件未在Claude中显示

确保配置文件路径适合您的操作系统（请参阅上面的设置部分）。更改配置后重新启动Claude Desktop或Claude Code。

Cannot find module 'pinion-os'

跑 npm install pinion-os 在您的项目中，或使用 npx pinion-os 自动安装。

ESOCKETTIMEDOUT 或网络错误

检查您的互联网连接。SDK调用 pinionos.com 默认情况下。您可以用以下命令覆盖 PINION_API_URL 有人是。

发展

git clone https://github.com/chu2bard/pinion-os
cd pinion-os
npm install
npm run build
npm test

贡献

PR欢迎。保持简单：

分叉并创建分支
进行更改
跑 npm test 和 npm run lint
打开一个带有清晰描述的PR

不需要复杂的提交消息。只需描述发生了什么变化以及原因。

许可证

麻省理工学院