Skip to content
Back to search

pinion-os

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/chu2bard--pinion-os/badge.svg)](/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.ts

What 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)

  1. {
  2. "name": "pinion-os",
  3. "owner": {
  4. "name": "chu2bard"
  5. },
  6. "metadata": {
  7. "description": "Pinion protocol plugins for Claude Code"
  8. },
  9. "plugins": [
  10. {
  11. "name": "pinion-os",
  12. "description": "On-chain AI skills (balance, tx, price, wallet, chat, send, trade, fund) via x402 micropayments on Base",
  13. "version": "0.3.2",
  14. "source": {
  15. "source": "github",
  16. "repo": "chu2bard/pinion-os"
  17. },
  18. "author": { "name": "chu2bard" },
  19. "homepage": "https://github.com/chu2bard/pinion-os",
  20. "keywords": ["x402", "mcp", "claude", "agents", "payments", "base"]
  21. }
  22. ]
  23. }
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)

  1. <p align="center">
  2. <img src="assets/banner.png" alt="Pinion OS" width="100%" />
  3. </p>
  4. # pinion-os
  5. 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.
  6. ## Architecture
  7. ```
  8. +------------------------+
  9. | Your App / Agent / |
  10. | Claude Code |
  11. +-----------+------------+
  12. |
  13. +--------------+--------------+
  14. | pinion-os SDK |
  15. | x402 signing & payments |
  16. +--------------+--------------+
  17. |
  18. +--------------+--------------+
  19. | pinionos.com / custom |
  20. | x402 skill server |
  21. +--------------+--------------+
  22. |
  23. +-----------+------------+
  24. | Base L2 Network |
  25. | USDC settlement |
  26. +------------------------+
  27. ```
  28. Three layers: your code talks to the SDK, the SDK handles x402 payment signing,
  29. the skill server verifies payment through a facilitator and returns data.
  30. ## x402 Payment Flow
  31. ```
  32. Client Skill Server Facilitator
  33. | | |
  34. |--- GET /price/ETH --------->| |
  35. |<-- 402 + pay requirements --| |
  36. | | |
  37. | [sign EIP-3009 auth] | |
  38. | | |
  39. |--- GET /price/ETH --------->| |
  40. | X-PAYMENT: <signed> |--- verify + settle ------>|
  41. | |<-- ok --------------------|
  42. |<-- 200 { price: 2650 } -----| |
  43. ```
  44. The SDK handles steps 2-4 automatically. You just call a method and get data back.
  45. ## Quickstart
  46. ```bash
  47. # 1. install
  48. npm install pinion-os
  49. # 2. set your wallet key (needs ETH for gas, USDC for payments on Base)
  50. export PINION_PRIVATE_KEY=0xYOUR_PRIVATE_KEY
  51. # 3. use in code
  52. node -e "
  53. import('pinion-os').then(async ({ PinionClient }) => {
  54. const p = new PinionClient({ privateKey: process.env.PINION_PRIVATE_KEY });
  55. console.log(await p.skills.price('ETH'));
  56. })
  57. "
  58. # 4. or run as MCP plugin for Claude
  59. npx pinion-os
  60. # 5. or build your own skill server
  61. npx ts-node examples/custom-skill.ts
  62. ```
  63. ## Install
  64. ```
  65. npm install pinion-os
  66. ```
  67. ## SDK Usage
  68. ```typescript
  69. import { PinionClient } from "pinion-os";
  70. const pinion = new PinionClient({
  71. privateKey: process.env.PINION_PRIVATE_KEY,
  72. });
  73. // check balances
  74. const bal = await pinion.skills.balance("0x1234...");
  75. console.log(bal.data); // { eth: "1.5", usdc: "100.0" }
  76. // get token price
  77. const price = await pinion.skills.price("ETH");
  78. console.log(price.data); // { token: "ETH", usd: "2650.00" }
  79. // look up a transaction
  80. const tx = await pinion.skills.tx("0xabc...");
  81. console.log(tx.data); // { from, to, value, ... }
  82. // generate a wallet
  83. const w = await pinion.skills.wallet();
  84. console.log(w.data); // { address, privateKey }
  85. // chat with the agent
  86. const chat = await pinion.skills.chat("what is x402?");
  87. console.log(chat.data); // { response: "..." }
  88. // construct a send transaction (sign + broadcast yourself)
  89. const send = await pinion.skills.send("0xRecipient...", "0.1", "ETH");
  90. console.log(send.data); // { tx: { to, value, data, chainId }, ... }
  91. // swap tokens via 1inch (returns unsigned tx)
  92. const trade = await pinion.skills.trade("USDC", "ETH", "10");
  93. console.log(trade.data); // { swap: { to, data, value }, approve?: {...} }
  94. // check funding status for a wallet
  95. const fund = await pinion.skills.fund("0x1234...");
  96. console.log(fund.data); // { balances, funding: { steps, ... } }
  97. // sign and broadcast a transaction
  98. const txResult = await pinion.skills.broadcast(send.data.tx);
  99. console.log(txResult.data); // { hash: "0x..." }
  100. // purchase unlimited access ($100 USDC one-time)
  101. const unlimited = await pinion.skills.unlimited();
  102. console.log(unlimited.data); // { apiKey: "pk_...", address, plan: "unlimited" }
  103. // once you have an API key, set it to skip x402 payments
  104. pinion.setApiKey(unlimited.data.apiKey);
  105. // all subsequent calls are free
  106. ```
  107. Server-side skills cost $0.01 USDC on Base via x402. Payment is handled automatically.
  108. ### Calling any x402 endpoint
  109. Use `payX402Service` to call any server that supports the x402 protocol:
  110. ```typescript
  111. import { PinionClient, payX402Service } from "pinion-os";
  112. const pinion = new PinionClient({
  113. privateKey: process.env.PINION_PRIVATE_KEY,
  114. });
  115. // call an external x402 service
  116. const result = await payX402Service(pinion.signer, "https://example.com/api/weather", {
  117. method: "GET",
  118. maxAmount: "100000", // max $0.10 USDC
  119. });
  120. console.log(result.data);
  121. ```
  122. ### Pay Web2 Services via Stripe x402
  123. 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.
  124. ```typescript
  125. import { PinionClient, payX402Service } from "pinion-os";
  126. const pinion = new PinionClient({
  127. privateKey: process.env.PINION_PRIVATE_KEY,
  128. });
  129. // pay a Stripe-powered API -- works the same as any x402 endpoint
  130. const result = await payX402Service(pinion.signer, "https://api.example.com/premium-data", {
  131. method: "GET",
  132. maxAmount: "100000", // max $0.10 USDC
  133. });
  134. console.log(result.data);
  135. ```
  136. Or via Claude with the MCP plugin:
  137. ```
  138. "Call https://api.example.com/premium-data using pinion_pay_service"
  139. ```
  140. The agent pays USDC on Base. Stripe handles settlement on the server side.
  141. No Stripe account needed on the agent side -- the server operator has the Stripe account.
  142. Supports both x402 v1 (`x402-express`) and v2 (`@x402/express`, Stripe) servers automatically.
  143. ## MCP Plugin Setup
  144. The plugin exposes twelve tools to any MCP-compatible host: `pinion_balance`,
  145. `pinion_tx`, `pinion_price`, `pinion_wallet`, `pinion_chat`, `pinion_send`,
  146. `pinion_trade`, `pinion_fund`, `pinion_pay_service`, `pinion_spend_limit`, `pinion_unlimited`, `pinion_unlimited_verify`.
  147. ### Claude Desktop
  148. Add to your config file:
  149. | OS | Path |
  150. |----|------|
  151. | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
  152. | Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
  153. | Linux | `~/.config/Claude/claude_desktop_config.json` |
  154. ```json
  155. {
  156. "mcpServers": {
  157. "pinion": {
  158. "command": "npx",
  159. "args": ["pinion-os"],
  160. "env": {
  161. "PINION_PRIVATE_KEY": "0xYOUR_KEY"
  162. }
  163. }
  164. }
  165. }
  166. ```
  167. Restart Claude Desktop after saving.
  168. ### Claude Code
  169. Add the marketplace and install:
  170. ```
  171. /plugin marketplace add chu2bard/pinion-os
  172. /plugin install pinion-os
  173. ```
  174. Set the env var when prompted, or export before launching:
  175. ```bash
  176. export PINION_PRIVATE_KEY=0xYOUR_KEY
  177. ```
  178. After installing, Claude can use all twelve pinion tools: balance, tx, price, wallet, chat, send, trade, fund, pay_service, spend_limit, unlimited, unlimited_verify.
  179. Alternative (MCP-only, without plugin features):
  180. ```bash
  181. claude mcp add pinion -- npx pinion-os
  182. ```
  183. ### Cursor IDE
  184. Add to `.cursor/mcp.json` in your project root:
  185. ```json
  186. {
  187. "mcpServers": {
  188. "pinion": {
  189. "command": "npx",
  190. "args": ["pinion-os"],
  191. "env": {
  192. "PINION_PRIVATE_KEY": "0xYOUR_KEY"
  193. }
  194. }
  195. }
  196. }
  197. ```
  198. ### Generic MCP Host
  199. ```bash
  200. PINION_PRIVATE_KEY=0xYOUR_KEY npx pinion-os
  201. ```
  202. The plugin communicates over stdio using the standard MCP protocol.
  203. ## Available Skills
  204. ### Server-side (x402-paid, $0.01 USDC each)
  205. | Skill | SDK Method | Endpoint | Price | Returns |
  206. |-------|------------|----------|-------|---------|
  207. | balance | `skills.balance(addr)` | GET /balance/:address | $0.01 | ETH + USDC balances |
  208. | tx | `skills.tx(hash)` | GET /tx/:hash | $0.01 | Decoded tx details |
  209. | price | `skills.price(token)` | GET /price/:token | $0.01 | USD price |
  210. | wallet | `skills.wallet()` | GET /wallet/generate | $0.01 | New keypair |
  211. | chat | `skills.chat(msg)` | POST /chat | $0.01 | Agent response |
  212. | send | `skills.send(to, amt, token)` | POST /send | $0.01 | Unsigned transfer tx |
  213. | trade | `skills.trade(src, dst, amt)` | POST /trade | $0.01 | Unsigned swap tx (1inch) |
  214. | fund | `skills.fund(addr)` | GET /fund/:address | $0.01 | Balance + deposit info |
  215. | broadcast | `skills.broadcast(tx)` | POST /broadcast | $0.01 | Signed + broadcast tx hash |
  216. | unlimited | `skills.unlimited()` | POST /unlimited | $100.00 | API key for unlimited access |
  217. ### Client-side (SDK/MCP plugin only)
  218. | Skill | SDK / MCP Tool | Description |
  219. |-------|---------------|-------------|
  220. | pay-for-service | `payX402Service(wallet, url)` / `pinion_pay_service` | Call any x402 endpoint on the internet |
  221. | spend-limit | `pinion_spend_limit` (MCP only) | Per-session USDC budget tracking |
  222. | unlimited-verify | `skills.unlimitedVerify(key)` / `pinion_unlimited_verify` | Check if an unlimited API key is valid |
  223. ## Build Your Own Skills
  224. Use the server framework to create x402-paywalled endpoints:
  225. ```typescript
  226. import { createSkillServer, skill } from "pinion-os/server";
  227. const server = createSkillServer({
  228. payTo: "0xYOUR_WALLET",
  229. network: "base",
  230. });
  231. server.add(skill("analyze", {
  232. price: "$0.02",
  233. endpoint: "/analyze/:address",
  234. handler: async (req, res) => {
  235. const data = await analyzeAddress(req.params.address);
  236. res.json(data);
  237. },
  238. }));
  239. server.add(skill("score", {
  240. price: "$0.05",
  241. endpoint: "/score/:address",
  242. handler: async (req, res) => {
  243. const score = await getScore(req.params.address);
  244. res.json({ score });
  245. },
  246. }));
  247. server.listen(4020);
  248. // -> http://localhost:4020/analyze/0x... (x402 paywalled)
  249. // -> http://localhost:4020/score/0x... (x402 paywalled)
  250. ```
  251. The server automatically:
  252. - Returns 402 with payment requirements for unauthenticated requests
  253. - Verifies x402 payment signatures via the facilitator
  254. - Settles USDC on Base to your wallet
  255. ## Configuration
  256. | Variable | Required | Default | Description |
  257. |----------|----------|---------|-------------|
  258. | `PINION_PRIVATE_KEY` | yes | -- | Hex private key (0x...) with USDC on Base |
  259. | `PINION_API_URL` | no | `https://pinionos.com/skill` | Override the skill API endpoint |
  260. | `PINION_NETWORK` | no | `base` | Network: `base` or `base-sepolia` |
  261. | `PINION_API_KEY` | no | -- | Unlimited API key (pk_...) to bypass x402 payments |
  262. | `ADDRESS` | server only | -- | Wallet address to receive payments |
  263. | `FACILITATOR_URL` | server only | `https://facilitator.payai.network` | x402 facilitator endpoint |
  264. | `ANTHROPIC_API_KEY` | chat skill | -- | Anthropic API key for the chat skill |
  265. | `ONEINCH_API_KEY` | trade skill | -- | 1inch API key for token swaps (server-side) |
  266. ## Project Structure
  267. ```
  268. pinion-os/
  269. .claude-plugin/
  270. plugin.json Claude Code plugin manifest
  271. marketplace.json Plugin marketplace catalog
  272. .mcp.json MCP server auto-config
  273. src/
  274. client/ SDK for calling pinion skills
  275. index.ts PinionClient class
  276. skills.ts typed skill wrappers
  277. types.ts TypeScript interfaces
  278. x402.ts EIP-3009 payment signing
  279. x402-generic.ts generic x402 caller for any endpoint
  280. x402-v2.ts x402 v2 transport (Stripe) support
  281. plugin/ Claude MCP server
  282. server.ts MCP request handlers
  283. tools.ts tool definitions + dispatch (12 tools)
  284. limits.ts per-session spend limit tracker
  285. config.ts env/arg configuration
  286. index.ts CLI entry point (npx pinion-os)
  287. server/ Framework for building skills
  288. index.ts createSkillServer factory
  289. skill.ts skill() definition helper
  290. middleware.ts x402 middleware wrapper
  291. types.ts server types
  292. skills/ Built-in skill handlers
  293. balance.ts ETH/USDC balance lookup
  294. tx.ts transaction decoder
  295. price.ts token price via CoinGecko
  296. wallet.ts keypair generation
  297. chat.ts AI chat via Anthropic
  298. shared/ Shared utilities
  299. constants.ts RPC URLs, contract addresses
  300. rpc.ts Base JSON-RPC helper
  301. errors.ts custom error classes
  302. examples/
  303. use-sdk.ts SDK usage example
  304. custom-skill.ts custom skill server example
  305. claude-config.json example MCP config
  306. tests/
  307. client.test.ts SDK tests
  308. x402.test.ts payment signing tests
  309. server.test.ts skill server tests
  310. openclaw.plugin.json OpenClaw skill manifest
  311. ```
  312. ## Troubleshooting
  313. **`PINION_PRIVATE_KEY or WALLET_KEY environment variable is required`**
  314. Set the env var before running. The key must be a hex string starting with `0x`.
  315. **`insufficient USDC balance`**
  316. Your wallet needs USDC on Base (not Ethereum mainnet). Bridge USDC to Base via
  317. https://bridge.base.org or buy directly on Base.
  318. **`402 Payment Required` in response**
  319. The SDK should handle this automatically. If you see raw 402 responses, check that
  320. your private key has both ETH (for gas) and USDC (for payments) on Base.
  321. **MCP plugin not showing up in Claude**
  322. Make sure the config file path is correct for your OS (see setup section above).
  323. Restart Claude Desktop or Claude Code after changing config.
  324. **`Cannot find module 'pinion-os'`**
  325. Run `npm install pinion-os` in your project, or use `npx pinion-os` to auto-install.
  326. **`ESOCKETTIMEDOUT` or network errors**
  327. Check your internet connection. The SDK calls `pinionos.com` by default.
  328. You can override with `PINION_API_URL` env var.
  329. ## Development
  330. ```bash
  331. git clone https://github.com/chu2bard/pinion-os
  332. cd pinion-os
  333. npm install
  334. npm run build
  335. npm test
  336. ```
  337. ## Contributing
  338. PRs welcome. Keep it simple:
  339. 1. Fork and create a branch
  340. 2. Make your changes
  341. 3. Run `npm test` and `npm run lint`
  342. 4. Open a PR with a clear description
  343. No need for elaborate commit messages. Just describe what changed and why.
  344. ## License
  345. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.