@shreyassp002/pinionos-emulator 0.2.1 → 0.3.0

package/README.md

@@ -10,189 +10,246 @@ Test your app with the same `pinion-os` SDK calls, without real USDC spend.
 
 </div>
 
-## What This Project Is
+## What This Is
 
-`pinionos-emulator` is a local server that mirrors Pinion skill APIs so teams can build and test products safely.
+`pinionos-emulator` is a local server that mimics the real PinionOS skill API. You run it on your machine, point the `pinion-os` SDK at `localhost:4020`, and your entire app works exactly as it would in production — except every call is free, instant, and returns mock data.
 
-Use it when you want to:
-- develop app flows without hitting production
-- run deterministic integration tests in CI
-- exercise x402/unlimited-key paths locally
-- inspect request/response behavior in a terminal dashboard
+```text
+Your app code  -->  pinion-os SDK  -->  PinionOS Emulator (localhost:4020)  -->  mock responses
+```
 
-## Pinion SDK Compatibility
+Your app code does not change. You only swap the URL.
 
-This emulator is designed for `pinion-os` client usage by pointing the SDK to local URL:
+## Quick Start
 
-```ts
-import { PinionClient } from 'pinion-os';
+### 1. Install
 
-const client = new PinionClient({
-  privateKey: process.env.PRIVATE_KEY!,
-  apiUrl: 'http://localhost:4020'
-});
+**Local install (recommended for projects):**
+
+```bash
+npm install --save-dev @shreyassp002/pinionos-emulator
 ```
 
-## Supported SDK Skills
-
-| Skill | SDK Method | Emulator Endpoint | Status |
-|---|---|---|---|
-| balance | `skills.balance(address)` | `GET /balance/:address` | Supported |
-| tx | `skills.tx(hash)` | `GET /tx/:hash` | Supported |
-| price | `skills.price(token)` | `GET /price/:token` | Supported |
-| wallet | `skills.wallet()` | `GET /wallet/generate` | Supported |
-| chat | `skills.chat(message)` | `POST /chat` | Supported |
-| send | `skills.send(to, amount, token)` | `POST /send` | Supported |
-| trade | `skills.trade(src, dst, amount, slippage)` | `POST /trade` | Supported |
-| fund | `skills.fund(address)` | `GET /fund/:address` | Supported |
-| broadcast | `skills.broadcast(tx)` | `POST /broadcast` | Supported |
-| unlimited | `skills.unlimited()` | `POST /unlimited` | Supported |
-| unlimited-verify | `skills.unlimitedVerify(key)` | `GET /unlimited/verify?key=...` | Supported |
-
-## Supported MCP Tools
-
-Your emulator MCP server currently exposes:
-- `pinion_price`
-- `pinion_balance`
-- `pinion_wallet`
-- `pinion_tx`
-- `pinion_chat`
-- `pinion_send`
-- `pinion_trade`
-- `pinion_fund`
-- `pinion_broadcast`
-- `pinion_unlimited`
-- `pinion_unlimited_verify`
-- `pinion_pay_service`
-- `pinion_facilitator_verify`
-
-## Emulator Features Beyond Core Skills
-
-- x402 middleware mode (`--x402`) with 402 challenge flow
-- unlimited API key issuance and verification
-- generic x402 test service (`/x402/*`)
-- mock facilitator endpoints (`/facilitator/verify`, `/facilitator/status`)
-- request recording (`/recording/start`, `/recording/stop`, `/recording/status`)
-- chaos/error injection via config (`errorSimulation`)
-- mutable in-memory balances + reset (`POST /reset`)
-- terminal dashboard (feed, prices, wallet, inspector)
+**Global install:**
 
-## Quick Start
+```bash
+npm install -g @shreyassp002/pinionos-emulator
+```
 
-Install in your project:
+### 2. Start the emulator
 
 ```bash
-npm install @shreyassp002/pinionos-emulator
+# Local install
+npx pinionos-emulator
+
+# Global install
+pinionos-emulator
 ```
 
-Start emulator (local install):
+This opens a terminal dashboard with live prices, a skill call feed, wallet info, and request inspector.
+
+For headless/CI mode:
 
 ```bash
-npx pinionos-emulator
+npx pinionos-emulator --no-dashboard
+# or
+pinionos-emulator --no-dashboard
 ```
 
-Health check:
+### 3. Verify it's running
 
 ```bash
 curl -s http://localhost:4020/health | jq
 ```
 
-Headless mode:
+### 4. Point your SDK at it
 
-```bash
-npx pinionos-emulator --no-dashboard
+```ts
+import { PinionClient } from 'pinion-os';
+
+const client = new PinionClient({
+  privateKey: process.env.PRIVATE_KEY!,
+  apiUrl: 'http://localhost:4020'   // <-- this is the only change
+});
+
+// Everything else stays the same
+const price = await client.skills.price('ETH');
+const wallet = await client.skills.wallet();
 ```
 
-Optional global install:
+That's it. Your app now talks to the emulator instead of production.
+
+## CLI Reference
 
-```bash
-npm install -g @shreyassp002/pinionos-emulator
-pinionos-emulator
 ```
+pinionos-emulator [command] [options]
+```
+
+**Commands:**
+
+| Command | Description |
+|---------|-------------|
+| `start` | Start the emulator (default, can be omitted) |
+| `mcp` | Start MCP stdio server (emulator must already be running) |
+| `init` | Generate a starter `config.json` in the current directory |
 
-## CLI Commands
+**Options:**
 
-Local install (recommended):
+| Flag | Description |
+|------|-------------|
+| `--port <n>` | Port to listen on (default: 4020) |
+| `--x402` | Enable x402 payment simulation mode |
+| `--network <name>` | `base` (default) or `base-sepolia` |
+| `--no-dashboard` | Run without the terminal dashboard UI |
+| `--config <path>` | Path to config.json (default: `./config.json`) |
+
+**Examples (local install with npx):**
 
 ```bash
-npx pinionos-emulator start
-npx pinionos-emulator mcp
-npx pinionos-emulator init
+npx pinionos-emulator                       # Start with defaults + dashboard
+npx pinionos-emulator start                 # Same as above (start is default)
+npx pinionos-emulator --port 3000 --x402    # Custom port + x402 mode
+npx pinionos-emulator --no-dashboard        # Headless for CI
+npx pinionos-emulator init                  # Create config.json
+npx pinionos-emulator mcp                   # Start MCP server
 ```
 
-Global install:
+**Examples (global install):**
 
 ```bash
-pinionos-emulator start
-pinionos-emulator mcp
-pinionos-emulator init
+pinionos-emulator                       # Start with defaults + dashboard
+pinionos-emulator start                 # Same as above (start is default)
+pinionos-emulator --port 3000 --x402    # Custom port + x402 mode
+pinionos-emulator --no-dashboard        # Headless for CI
+pinionos-emulator init                  # Create config.json
+pinionos-emulator mcp                   # Start MCP server
 ```
 
-`start` is the default command, so `npx pinionos-emulator` and `pinionos-emulator` are equivalent to `... start`.
+## Supported Skills
+
+Every skill from the `pinion-os` SDK is supported:
+
+| Skill | SDK Method | Emulator Endpoint |
+|-------|-----------|-------------------|
+| Price | `skills.price('ETH')` | `GET /price/:token` |
+| Balance | `skills.balance(address)` | `GET /balance/:address` |
+| Wallet | `skills.wallet()` | `GET /wallet/generate` |
+| Transaction | `skills.tx(hash)` | `GET /tx/:hash` |
+| Chat | `skills.chat(message, history?)` | `POST /chat` |
+| Send | `skills.send(to, amount, token)` | `POST /send` |
+| Trade | `skills.trade(src, dst, amount, slippage?)` | `POST /trade` |
+| Fund | `skills.fund(address)` | `GET /fund/:address` |
+| Broadcast | `skills.broadcast(tx, privateKey?)` | `POST /broadcast` |
+| Unlimited | `skills.unlimited()` | `POST /unlimited` |
+| Unlimited Verify | `skills.unlimitedVerify(key)` | `GET /unlimited/verify?key=...` |
+| Catalog | `GET /catalog` | `GET /catalog` |
+
+## System Endpoints
+
+These are emulator-specific endpoints for testing and debugging:
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /health` | Health check |
+| `POST /reset` | Reset all balances and API keys to defaults |
+| `GET /catalog` | List all available skills with prices |
+| `POST /recording/start` | Start recording all requests |
+| `POST /recording/stop` | Stop recording |
+| `GET /recording/status` | Check recording status |
+| `POST /facilitator/verify` | Mock x402 facilitator verification |
+| `GET /facilitator/status` | Facilitator status |
+| `ALL /x402/*` | Generic x402 test service |
+
+## MCP Tools
+
+For AI agents using Model Context Protocol, start the MCP server:
 
-Useful options:
-- `--port <n>`
-- `--x402`
-- `--network base|base-sepolia`
-- `--no-dashboard`
-- `--config <path>`
+```bash
+npx pinionos-emulator mcp
+```
 
-## Product Testing Workflow
+The emulator must already be running in another terminal.
+
+**Available tools:**
+
+| Tool | Description |
+|------|-------------|
+| `pinion_setup` | Configure wallet (required before paid tools) |
+| `pinion_spend_limit` | Set/check/clear spend budget |
+| `pinion_catalog` | List available skills and prices |
+| `pinion_price` | Get token price |
+| `pinion_balance` | Get wallet balances |
+| `pinion_wallet` | Generate wallet |
+| `pinion_tx` | Look up transaction |
+| `pinion_chat` | Chat with AI agent |
+| `pinion_send` | Build send transaction |
+| `pinion_trade` | Build swap transaction |
+| `pinion_fund` | Get funding instructions |
+| `pinion_broadcast` | Sign and broadcast transaction |
+| `pinion_unlimited` | Purchase unlimited access |
+| `pinion_unlimited_verify` | Verify API key |
+| `pinion_pay_service` | Call generic x402 service |
+| `pinion_facilitator_verify` | Verify x402 payment |
+
+## Configuration
+
+Run `pinionos-emulator init` to generate a `config.json`:
+
+```json
+{
+  "port": 4020,
+  "mockPayments": true,
+  "prices": {
+    "ETH": "useApi:coingecko",
+    "BTC": "useApi:coingecko",
+    "SOL": "useApi:coingecko",
+    "USDC": 1
+  },
+  "fallbackPrices": {
+    "ETH": 3000,
+    "BTC": 90000,
+    "SOL": 180,
+    "USDC": 1
+  },
+  "balances": {
+    "default": { "ETH": "1.5", "USDC": "250.00" }
+  }
+}
+```
 
-1. Start emulator locally.
-2. Configure your app's Pinion client with `apiUrl: 'http://localhost:4020'`.
-3. Run your app and test suite.
-4. Assert your product behavior (not just raw route responses).
+**Price resolution order:** config override -> CoinGecko API -> Binance API -> fallback prices.
 
-CI example:
+**Price values can be:**
+- A number (e.g. `1`) — fixed override
+- `"useApi:coingecko"` — fetch from CoinGecko (60s cache)
+- `"useApi:binance"` — fetch from Binance (60s cache)
+- Absent — uses `fallbackPrices` value
 
-```bash
-npx pinionos-emulator --no-dashboard > /tmp/pinionos-emulator.log 2>&1 & EMU_PID=$!
-sleep 2
-npm test
-kill $EMU_PID
-```
+**Custom balances:** Add wallet addresses as keys under `balances` to set specific balances. Any unknown address gets the `default` balance.
+
+## Emulator Features
+
+- **Terminal dashboard** — live skill call feed, price tickers, wallet info, request inspector
+- **x402 mode** — full 402 payment challenge flow with `--x402` flag
+- **Unlimited keys** — issue and verify API keys via `/unlimited`
+- **Request recording** — capture all requests to `pinion-requests.jsonl` for debugging
+- **Error simulation** — inject failures via config for resilience testing
+- **Mutable balances** — balances update on send/trade, reset with `POST /reset`
+- **Skill catalog** — `GET /catalog` for agent auto-discovery
+- **MCP server** — full MCP tool set with wallet setup and spend tracking
+
+## Notes
 
-## Route Summary
-
-Core routes:
-- `GET /price/:token`
-- `GET /balance/:address`
-- `GET /wallet`
-- `GET /wallet/generate`
-- `GET /tx/:hash`
-- `POST /send`
-- `POST /trade`
-- `GET /fund/:address`
-- `POST /chat`
-- `POST /broadcast`
-- `GET /unlimited`
-- `POST /unlimited`
-- `GET /unlimited/verify?key=...`
-- `GET /unlimited/verify/:key`
-
-System routes:
-- `GET /`
-- `GET /health`
-- `POST /reset`
-- `POST /recording/start`
-- `POST /recording/stop`
-- `GET /recording/status`
-- `POST /facilitator/verify`
-- `GET /facilitator/status`
-- `ALL /x402/*`
-
-## Notes On Behavior
-
-- Responses are mock/simulated with realistic structure.
-- Success envelope includes `mock: true` and payment metadata.
-- Price path uses config override -> CoinGecko -> Binance -> fallback.
-- This is for development/testing, not production settlement.
+- All responses include `mock: true` and a simulated payment receipt.
+- The success envelope spreads data at root level AND nests under `data`, so both `result.priceUSD` and `result.data.priceUSD` work.
+- `/tx/:hash` is deterministic — same hash always returns the same addresses.
+- `/trade` rejects same-token swaps and applies 0.3% fee + slippage.
+- This is for development and testing only, not production settlement.
 
 ## Documentation
 
-- Detailed usage and testing guide: [user_guide.md](user_guide.md)
-- Planning/spec docs: [`docs/`](docs)
+- Testing guide: [user_guide.md](user_guide.md)
+- Planning docs: [`docs/`](docs)
 
 ## License
 

package/dist/src/app.js

@@ -21,6 +21,7 @@ const send_1 = require("./routes/send");
 const trade_1 = require("./routes/trade");
 const facilitator_1 = require("./routes/facilitator");
 const tx_1 = __importDefault(require("./routes/tx"));
+const catalog_1 = __importDefault(require("./routes/catalog"));
 const unlimited_1 = __importDefault(require("./routes/unlimited"));
 const x402service_1 = require("./routes/x402service");
 const balances_1 = require("./state/balances");
@@ -60,6 +61,7 @@ function createApp(opts = {}) {
     });
     app.use((0, paymentLogger_1.paymentLogger)(db));
     app.use((0, x402_1.x402Middleware)(db));
+    app.use('/catalog', catalog_1.default);
     app.get('/', (_req, res) => {
         res.json({ status: 'ok', emulator: true });
     });

package/dist/src/client/MockPinionClient.js

@@ -40,6 +40,11 @@ class MockPinionClient {
             trade: (src, dst, amount, slippage) => this.post('/trade', { src, dst, amount, slippage: slippage ?? 1 }),
             broadcast: (tx, privateKey) => this.post('/broadcast', { tx, privateKey }),
             unlimited: () => this.post('/unlimited', {}),
+            catalog: async () => {
+                const start = Date.now();
+                const res = await this.http.get('/catalog');
+                return { status: res.status, data: res.data, paidAmount: '0', responseTimeMs: Date.now() - start };
+            },
             unlimitedVerify: async (key) => {
                 const res = await this.http.get('/unlimited/verify', { params: { key } });
                 return res.data;

package/dist/src/mcp/server.js

@@ -8,7 +8,35 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const node_crypto_1 = require("node:crypto");
 const zod_1 = require("zod");
+// ── Spend tracker ──────────────────────────────────────────────────────
+const spendTracker = { maxAtomic: 0, spentAtomic: 0, calls: 0, limited: false };
+const SKILL_COST_ATOMIC = 10000; // $0.01 in USDC 6-decimal atomic units
+const UNLIMITED_COST_ATOMIC = 100000000; // $100
+function checkSpend(cost) {
+    if (!spendTracker.limited)
+        return null;
+    if (spendTracker.spentAtomic + cost > spendTracker.maxAtomic) {
+        const remaining = Math.max(0, spendTracker.maxAtomic - spendTracker.spentAtomic);
+        return `Spend limit exceeded. Remaining: $${(remaining / 1000000).toFixed(6)}, required: $${(cost / 1000000).toFixed(6)}`;
+    }
+    return null;
+}
+function recordSpend(cost) {
+    if (!spendTracker.limited)
+        return;
+    spendTracker.spentAtomic += cost;
+    spendTracker.calls += 1;
+}
+// ── Wallet setup state ─────────────────────────────────────────────────
+let setupAddress = process.env.PINION_PRIVATE_KEY ? '0x_from_env' : null;
+function requireSetup() {
+    if (!setupAddress) {
+        return 'Wallet not configured. Call pinion_setup first with action "import" or "generate".';
+    }
+    return null;
+}
 function normalizeBaseUrl(baseUrl) {
     return baseUrl.replace(/\/+$/, '');
 }
@@ -54,11 +82,82 @@ async function main() {
     // Use the typed tool registration API
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const tool = server.tool.bind(server);
-    tool('pinion_price', 'Get the current USD price for a token (ETH, BTC, SOL, USDC, MATIC). Returns priceUSD and 24h change.', { token: zod_1.z.string().describe('Token symbol, e.g. ETH') }, async ({ token }) => wrapResult(await get(`/price/${token}`)));
-    tool('pinion_balance', 'Get ETH and USDC balances for a Base wallet address.', { address: zod_1.z.string().describe('Ethereum/Base wallet address (0x...)') }, async ({ address }) => wrapResult(await get(`/balance/${address}`)));
-    tool('pinion_wallet', 'Generate a fresh Base wallet keypair (address + private key). For testing only — never use for real funds.', {}, async () => wrapResult(await get('/wallet/generate')));
-    tool('pinion_tx', 'Look up decoded transaction details for a Base tx hash.', { hash: zod_1.z.string().describe('Transaction hash (0x...)') }, async ({ hash }) => wrapResult(await get(`/tx/${hash}`)));
-    tool('pinion_chat', 'Chat with the Pinion AI agent. Pass a message and optionally conversation history.', {
+    /** Wraps a paid tool handler with setup + spend checks */
+    function paidTool(name, description, schema, handler, cost = SKILL_COST_ATOMIC) {
+        tool(name, description, schema, async (args) => {
+            const setupErr = requireSetup();
+            if (setupErr)
+                return wrapResult({ error: setupErr });
+            const spendErr = checkSpend(cost);
+            if (spendErr)
+                return wrapResult({ error: spendErr });
+            const result = await handler(args);
+            recordSpend(cost);
+            return result;
+        });
+    }
+    // ── Free tools ──────────────────────────────────────────────────────
+    tool('pinion_setup', 'Configure wallet for PinionOS. Required before using paid tools.', {
+        action: zod_1.z.enum(['import', 'generate']).describe('"import" to use an existing key, "generate" to create a new one'),
+        private_key: zod_1.z.string().optional().describe('Private key (required for "import")')
+    }, async ({ action, private_key }) => {
+        if (action === 'import') {
+            if (!private_key || !private_key.startsWith('0x') || private_key.length < 66) {
+                return wrapResult({ error: 'Invalid private key. Must be a 0x-prefixed 64-character hex string.' });
+            }
+            setupAddress = `0x${(0, node_crypto_1.randomBytes)(20).toString('hex')}`;
+            return wrapResult({ status: 'ok', address: setupAddress, action: 'imported' });
+        }
+        // generate
+        const addr = `0x${(0, node_crypto_1.randomBytes)(20).toString('hex')}`;
+        const key = `0x${(0, node_crypto_1.randomBytes)(32).toString('hex')}`;
+        setupAddress = addr;
+        return wrapResult({ status: 'ok', address: addr, privateKey: key, action: 'generated' });
+    });
+    tool('pinion_spend_limit', 'Manage spend budget for PinionOS skill calls. Actions: set, status, clear.', {
+        action: zod_1.z.enum(['set', 'status', 'clear']).describe('Action to perform'),
+        max_usdc: zod_1.z.string().optional().describe('Max budget in USDC (required for "set"), e.g. "0.05"')
+    }, async ({ action, max_usdc }) => {
+        if (action === 'set') {
+            if (!max_usdc)
+                return wrapResult({ error: 'max_usdc is required for "set" action' });
+            const parsed = parseFloat(max_usdc);
+            if (isNaN(parsed) || parsed <= 0)
+                return wrapResult({ error: 'max_usdc must be a positive number' });
+            spendTracker.maxAtomic = Math.round(parsed * 1000000);
+            spendTracker.spentAtomic = 0;
+            spendTracker.calls = 0;
+            spendTracker.limited = true;
+            return wrapResult({ status: 'ok', maxBudget: max_usdc, message: `Spend limit set to $${max_usdc} USDC` });
+        }
+        if (action === 'clear') {
+            spendTracker.limited = false;
+            spendTracker.maxAtomic = 0;
+            spendTracker.spentAtomic = 0;
+            spendTracker.calls = 0;
+            return wrapResult({ status: 'ok', message: 'Spend limit cleared' });
+        }
+        // status
+        const max = spendTracker.limited ? (spendTracker.maxAtomic / 1000000).toFixed(6) : 'unlimited';
+        const spent = (spendTracker.spentAtomic / 1000000).toFixed(6);
+        const remaining = spendTracker.limited
+            ? (Math.max(0, spendTracker.maxAtomic - spendTracker.spentAtomic) / 1000000).toFixed(6)
+            : 'unlimited';
+        return wrapResult({
+            maxBudget: max,
+            spent,
+            remaining,
+            callCount: spendTracker.calls,
+            isLimited: spendTracker.limited
+        });
+    });
+    tool('pinion_catalog', 'List all available PinionOS skills with prices and descriptions.', {}, async () => wrapResult(await get('/catalog')));
+    // ── Paid tools ──────────────────────────────────────────────────────
+    paidTool('pinion_price', 'Get the current USD price for a token (ETH, BTC, SOL, USDC, MATIC). Returns priceUSD and 24h change.', { token: zod_1.z.string().describe('Token symbol, e.g. ETH') }, async ({ token }) => wrapResult(await get(`/price/${token}`)));
+    paidTool('pinion_balance', 'Get ETH and USDC balances for a Base wallet address.', { address: zod_1.z.string().describe('Ethereum/Base wallet address (0x...)') }, async ({ address }) => wrapResult(await get(`/balance/${address}`)));
+    paidTool('pinion_wallet', 'Generate a fresh Base wallet keypair (address + private key). For testing only — never use for real funds.', {}, async () => wrapResult(await get('/wallet/generate')));
+    paidTool('pinion_tx', 'Look up decoded transaction details for a Base tx hash.', { hash: zod_1.z.string().describe('Transaction hash (0x...)') }, async ({ hash }) => wrapResult(await get(`/tx/${hash}`)));
+    paidTool('pinion_chat', 'Chat with the Pinion AI agent. Pass a message and optionally conversation history.', {
         message: zod_1.z.string().describe('The user message to send'),
         history: zod_1.z
             .array(zod_1.z.object({ role: zod_1.z.string(), content: zod_1.z.string() }))
@@ -70,19 +169,19 @@ async function main() {
             : [{ role: 'user', content: message }];
         return wrapResult(await post('/chat', { messages }));
     });
-    tool('pinion_send', 'Build an unsigned ETH or ERC-20 transfer transaction. Sign and broadcast with pinion_broadcast.', {
+    paidTool('pinion_send', 'Build an unsigned ETH or ERC-20 transfer transaction. Sign and broadcast with pinion_broadcast.', {
         to: zod_1.z.string().describe('Recipient address (0x...)'),
         amount: zod_1.z.string().describe('Amount to send, e.g. "0.01"'),
         token: zod_1.z.string().describe('Token to send (ETH, USDC, WETH, DAI, WBTC, CBETH)')
     }, async (args) => wrapResult(await post('/send', args)));
-    tool('pinion_trade', 'Get an unsigned swap transaction via Uniswap V3 on Base. Sign and broadcast with pinion_broadcast.', {
+    paidTool('pinion_trade', 'Get an unsigned swap transaction via Uniswap V3 on Base. Sign and broadcast with pinion_broadcast.', {
         src: zod_1.z.string().describe('Source token symbol, e.g. ETH'),
         dst: zod_1.z.string().describe('Destination token symbol, e.g. USDC'),
         amount: zod_1.z.string().describe('Amount of src token to swap'),
         slippage: zod_1.z.number().optional().describe('Slippage tolerance in percent, default 1')
     }, async (args) => wrapResult(await post('/trade', args)));
-    tool('pinion_fund', 'Get wallet balance and funding instructions for a Base address. Includes deposit address and bridging steps.', { address: zod_1.z.string().describe('Wallet address to check and get funding info for') }, async ({ address }) => wrapResult(await get(`/fund/${address}`)));
-    tool('pinion_broadcast', 'Sign and broadcast a transaction on Base. Pass the unsigned tx object from pinion_send or pinion_trade.', {
+    paidTool('pinion_fund', 'Get wallet balance and funding instructions for a Base address. Includes deposit address and bridging steps.', { address: zod_1.z.string().describe('Wallet address to check and get funding info for') }, async ({ address }) => wrapResult(await get(`/fund/${address}`)));
+    paidTool('pinion_broadcast', 'Sign and broadcast a transaction on Base. Pass the unsigned tx object from pinion_send or pinion_trade.', {
         tx: zod_1.z
             .object({
             to: zod_1.z.string().describe('Transaction recipient'),
@@ -93,7 +192,7 @@ async function main() {
             .describe('Unsigned transaction object'),
         privateKey: zod_1.z.string().optional().describe('Private key to sign with (uses emulator default if omitted)')
     }, async (args) => wrapResult(await post('/broadcast', args)));
-    tool('pinion_unlimited', 'Purchase (simulated) unlimited access to all Pinion OS skills. Returns an API key for X-API-KEY header.', {}, async () => wrapResult(await post('/unlimited', {})));
+    paidTool('pinion_unlimited', 'Purchase (simulated) unlimited access to all Pinion OS skills. Returns an API key for X-API-KEY header.', {}, async () => wrapResult(await post('/unlimited', {})), UNLIMITED_COST_ATOMIC);
     tool('pinion_unlimited_verify', 'Verify whether an unlimited API key is valid. Returns validity status and associated address.', { key: zod_1.z.string().describe('The API key to verify (from pinion_unlimited)') }, async ({ key }) => {
         const res = await axios_1.default.get(`${API}/unlimited/verify`, { params: { key } });
         return wrapResult(res.data);

package/dist/src/middleware/x402.js

@@ -59,7 +59,7 @@ function parsePaymentHeader(header) {
     }
 }
 // Routes that skip x402 (free endpoints, health checks, etc.)
-const SKIP_PATHS = new Set(['/', '/health', '/reset']);
+const SKIP_PATHS = new Set(['/', '/health', '/reset', '/catalog']);
 const SKIP_PREFIXES = ['/unlimited/verify', '/facilitator', '/x402/', '/recording'];
 function shouldSkip(path, method) {
     if (method === 'OPTIONS')

package/dist/src/routes/catalog.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = require("express");
+const config_1 = require("../config");
+const MOCK_PAY_TO = '0x000000000000000000000000000000000000dead';
+const SKILLS = [
+    { name: 'balance', path: '/balance/:address', method: 'GET', description: 'Get wallet balances' },
+    { name: 'tx', path: '/tx/:hash', method: 'GET', description: 'Look up transaction details' },
+    { name: 'price', path: '/price/:token', method: 'GET', description: 'Get token price in USD' },
+    { name: 'wallet', path: '/wallet/generate', method: 'GET', description: 'Generate a new wallet' },
+    { name: 'chat', path: '/chat', method: 'POST', description: 'Chat with Pinion AI agent' },
+    { name: 'send', path: '/send', method: 'POST', description: 'Build a token transfer transaction' },
+    { name: 'trade', path: '/trade', method: 'POST', description: 'Build a swap transaction' },
+    { name: 'fund', path: '/fund/:address', method: 'GET', description: 'Get funding instructions' },
+    { name: 'broadcast', path: '/broadcast', method: 'POST', description: 'Sign and broadcast a transaction' },
+];
+const catalogRouter = (0, express_1.Router)();
+catalogRouter.get('/', (_req, res) => {
+    const net = (0, config_1.getNetworkInfo)();
+    res.json({
+        skills: SKILLS.map((s) => ({
+            ...s,
+            price: '0.01',
+            priceToken: 'USDC',
+        })),
+        payTo: MOCK_PAY_TO,
+        network: net.name,
+        mock: true,
+    });
+});
+exports.default = catalogRouter;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shreyassp002/pinionos-emulator",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Local PinionOS emulator for free agent development",
   "main": "dist/src/emulator.js",
   "bin": {