Pinion Os

小齿轮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 --------->|                           |
    ||                           |
    |    X-PAYMENT:       |--- verify + settle ------>|
    |                             | {
    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.

克劳德桌面版

添加到您的配置文件中：

{
  "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/MCP插件）

培养自己的技能

使用服务器框架创建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-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欢迎。保持简单：

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

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

许可证

麻省理工学院