pinion-os

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,
});