Back to search
pinion-os
SkillGitHub
Client SDK, Claude plugin and skill framework for the Pinion protocol. x402 micropayments on Base.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/chu2bard--pinion-os)HTML
<a href="/listings/chu2bard--pinion-os"><img src="/api/listings/chu2bard--pinion-os/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
# 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.tsWhat was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 23 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- {
- "name": "pinion-os",
- "owner": {
- "name": "chu2bard"
- },
- "metadata": {
- "description": "Pinion protocol plugins for Claude Code"
- },
- "plugins": [
- {
- "name": "pinion-os",
- "description": "On-chain AI skills (balance, tx, price, wallet, chat, send, trade, fund) via x402 micropayments on Base",
- "version": "0.3.2",
- "source": {
- "source": "github",
- "repo": "chu2bard/pinion-os"
- },
- "author": { "name": "chu2bard" },
- "homepage": "https://github.com/chu2bard/pinion-os",
- "keywords": ["x402", "mcp", "claude", "agents", "payments", "base"]
- }
- ]
- }
README.md · README · 450 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <p align="center">
- <img src="assets/banner.png" alt="Pinion OS" width="100%" />
- </p>
- # pinion-os
- Client SDK, Claude Code plugin, and skill server framework for [Pinion](https://pinionos.com). Handles x402 micropayments on Base so your code (or your agent) can call on-chain skills without thinking about payments.
- ## Architecture
- ```
- +------------------------+
- | Your App / Agent / |
- | Claude Code |
- +-----------+------------+
- |
- +--------------+--------------+
- | pinion-os SDK |
- | x402 signing & payments |
- +--------------+--------------+
- |
- +--------------+--------------+
- | pinionos.com / custom |
- | x402 skill server |
- +--------------+--------------+
- |
- +-----------+------------+
- | Base L2 Network |
- | USDC settlement |
- +------------------------+
- ```
- Three layers: your code talks to the SDK, the SDK handles x402 payment signing,
- the skill server verifies payment through a facilitator and returns data.
- ## x402 Payment Flow
- ```
- 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 } -----| |
- ```
- The SDK handles steps 2-4 automatically. You just call a method and get data back.
- ## Quickstart
- ```bash
- # 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
- ```
- ## Install
- ```
- npm install pinion-os
- ```
- ## SDK Usage
- ```typescript
- 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
- ```
- Server-side skills cost $0.01 USDC on Base via x402. Payment is handled automatically.
- ### Calling any x402 endpoint
- Use `payX402Service` to call any server that supports the x402 protocol:
- ```typescript
- 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);
- ```
- ### Pay Web2 Services via Stripe x402
- Any web2 service using [Stripe x402](https://docs.stripe.com/payments/machine/x402) can be paid by your Pinion agent. The SDK auto-detects whether a server speaks v1 or v2 x402 transport -- no config needed.
- ```typescript
- 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);
- ```
- Or via Claude with the MCP plugin:
- ```
- "Call https://api.example.com/premium-data using pinion_pay_service"
- ```
- The agent pays USDC on Base. Stripe handles settlement on the server side.
- No Stripe account needed on the agent side -- the server operator has the Stripe account.
- Supports both x402 v1 (`x402-express`) and v2 (`@x402/express`, Stripe) servers automatically.
- ## MCP Plugin Setup
- The plugin exposes twelve tools to any MCP-compatible host: `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`.
- ### Claude Desktop
- Add to your config file:
- | OS | Path |
- |----|------|
- | 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": {
- "pinion": {
- "command": "npx",
- "args": ["pinion-os"],
- "env": {
- "PINION_PRIVATE_KEY": "0xYOUR_KEY"
- }
- }
- }
- }
- ```
- Restart Claude Desktop after saving.
- ### Claude Code
- Add the marketplace and install:
- ```
- /plugin marketplace add chu2bard/pinion-os
- /plugin install pinion-os
- ```
- Set the env var when prompted, or export before launching:
- ```bash
- export PINION_PRIVATE_KEY=0xYOUR_KEY
- ```
- After installing, Claude can use all twelve pinion tools: balance, tx, price, wallet, chat, send, trade, fund, pay_service, spend_limit, unlimited, unlimited_verify.
- Alternative (MCP-only, without plugin features):
- ```bash
- claude mcp add pinion -- npx pinion-os
- ```
- ### Cursor IDE
- Add to `.cursor/mcp.json` in your project root:
- ```json
- {
- "mcpServers": {
- "pinion": {
- "command": "npx",
- "args": ["pinion-os"],
- "env": {
- "PINION_PRIVATE_KEY": "0xYOUR_KEY"
- }
- }
- }
- }
- ```
- ### Generic MCP Host
- ```bash
- PINION_PRIVATE_KEY=0xYOUR_KEY npx pinion-os
- ```
- The plugin communicates over stdio using the standard MCP protocol.
- ## Available Skills
- ### Server-side (x402-paid, $0.01 USDC each)
- | Skill | SDK Method | Endpoint | Price | Returns |
- |-------|------------|----------|-------|---------|
- | balance | `skills.balance(addr)` | GET /balance/:address | $0.01 | ETH + USDC balances |
- | tx | `skills.tx(hash)` | GET /tx/:hash | $0.01 | Decoded tx details |
- | price | `skills.price(token)` | GET /price/:token | $0.01 | USD price |
- | wallet | `skills.wallet()` | GET /wallet/generate | $0.01 | New keypair |
- | chat | `skills.chat(msg)` | POST /chat | $0.01 | Agent response |
- | send | `skills.send(to, amt, token)` | POST /send | $0.01 | Unsigned transfer tx |
- | trade | `skills.trade(src, dst, amt)` | POST /trade | $0.01 | Unsigned swap tx (1inch) |
- | fund | `skills.fund(addr)` | GET /fund/:address | $0.01 | Balance + deposit info |
- | broadcast | `skills.broadcast(tx)` | POST /broadcast | $0.01 | Signed + broadcast tx hash |
- | unlimited | `skills.unlimited()` | POST /unlimited | $100.00 | API key for unlimited access |
- ### Client-side (SDK/MCP plugin only)
- | Skill | SDK / MCP Tool | Description |
- |-------|---------------|-------------|
- | pay-for-service | `payX402Service(wallet, url)` / `pinion_pay_service` | Call any x402 endpoint on the internet |
- | spend-limit | `pinion_spend_limit` (MCP only) | Per-session USDC budget tracking |
- | unlimited-verify | `skills.unlimitedVerify(key)` / `pinion_unlimited_verify` | Check if an unlimited API key is valid |
- ## Build Your Own Skills
- Use the server framework to create x402-paywalled endpoints:
- ```typescript
- 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)
- ```
- The server automatically:
- - Returns 402 with payment requirements for unauthenticated requests
- - Verifies x402 payment signatures via the facilitator
- - Settles USDC on Base to your wallet
- ## Configuration
- | Variable | Required | Default | Description |
- |----------|----------|---------|-------------|
- | `PINION_PRIVATE_KEY` | yes | -- | Hex private key (0x...) with USDC on Base |
- | `PINION_API_URL` | no | `https://pinionos.com/skill` | Override the skill API endpoint |
- | `PINION_NETWORK` | no | `base` | Network: `base` or `base-sepolia` |
- | `PINION_API_KEY` | no | -- | Unlimited API key (pk_...) to bypass x402 payments |
- | `ADDRESS` | server only | -- | Wallet address to receive payments |
- | `FACILITATOR_URL` | server only | `https://facilitator.payai.network` | x402 facilitator endpoint |
- | `ANTHROPIC_API_KEY` | chat skill | -- | Anthropic API key for the chat skill |
- | `ONEINCH_API_KEY` | trade skill | -- | 1inch API key for token swaps (server-side) |
- ## Project Structure
- ```
- 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
- ```
- ## Troubleshooting
- **`PINION_PRIVATE_KEY or WALLET_KEY environment variable is required`**
- Set the env var before running. The key must be a hex string starting with `0x`.
- **`insufficient USDC balance`**
- Your wallet needs USDC on Base (not Ethereum mainnet). Bridge USDC to Base via
- https://bridge.base.org or buy directly on Base.
- **`402 Payment Required` in response**
- The SDK should handle this automatically. If you see raw 402 responses, check that
- your private key has both ETH (for gas) and USDC (for payments) on Base.
- **MCP plugin not showing up in Claude**
- Make sure the config file path is correct for your OS (see setup section above).
- Restart Claude Desktop or Claude Code after changing config.
- **`Cannot find module 'pinion-os'`**
- Run `npm install pinion-os` in your project, or use `npx pinion-os` to auto-install.
- **`ESOCKETTIMEDOUT` or network errors**
- Check your internet connection. The SDK calls `pinionos.com` by default.
- You can override with `PINION_API_URL` env var.
- ## Development
- ```bash
- git clone https://github.com/chu2bard/pinion-os
- cd pinion-os
- npm install
- npm run build
- npm test
- ```
- ## Contributing
- PRs welcome. Keep it simple:
- 1. Fork and create a branch
- 2. Make your changes
- 3. Run `npm test` and `npm run lint`
- 4. Open a PR with a clear description
- No need for elaborate commit messages. Just describe what changed and why.
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.