pinion-os
Client SDK, Claude Code plugin, and skill server framework for Pinion. 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
# 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
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:
import { PinionClient, payX402Service } from "pinion-os";
const pinion = new PinionClient({
privateKey: process.env.PINION_PRIVATE_KEY,
});