Skill: upn-130guthub/x402-cfo (version 0.1.0)

--- name: x402-cfo description: Financial brain for x402 payments — budget enforcement, cost policies, spend analytics, anomaly detection, and audit trail for autonomous agents. version: 0.2.0 author: x402-cfo tags: [x402, payments, budget, finance, usdc, analytics, cfo, audit] tools: [exec, read, write] --- # x402-cfo Skill You are an AI agent with financial awareness. You have access to x402-cfo, which gives you budget enforcement, cost policies, spend analytics, and anomaly detection for any x402 payment you make. ## Setup Before using this skill, ensure x402-cfo is installed in the current project: ```bash npm list x402-cfo 2>/dev/null || npm install x402-cfo ``` ## How to use x402-cfo When you need to make HTTP requests to x402-compatible paid APIs (any endpoint that returns HTTP 402), you MUST route the request through the AgentCFO instead of making raw fetch calls. ### Initialization At the start of any session involving paid API calls, initialize the CFO: ```typescript import { AgentCFO, JsonFileStorage } from 'x402-cfo'; const cfo = new AgentCFO({ wallet: walletInstance, // Your x402-compatible wallet budget: { hourly: parseFloat(process.env.X402_BUDGET_HOURLY || '5'), daily: parseFloat(process.env.X402_BUDGET_DAILY || '50'), session: parseFloat(process.env.X402_BUDGET_SESSION || '200'), }, policy: { maxPerRequest: parseFloat(process.env.X402_MAX_PER_REQUEST || '2.00'), allowedCurrencies: ['USDC'], allowedNetworks: (process.env.X402_NETWORKS || 'base').split(','), blocklist: (process.env.X402_BLOCKLIST || '').split(',').filter(Boolean), }, storage: new JsonFileStorage('./x402-cfo-ledger.json'), }); ``` ### Making paid requests ALWAYS use `cfo.fetch()` instead of raw `fetch()` for any x402 endpoint: ```typescript const response = await cfo.fetch('https://api.paid-service.com/v1/data'); ``` The CFO will automatically: 1. Check if the URL passes your cost policies 2. Check if you have remaining budget 3. Pay the x402 challenge if approved 4. Log the payment to the audit ledger 5. Fire events if spending is getting hot ### Before committing to expensive operations Check if you can afford it: ```typescript const estimate = cfo.estimateCost('https://api.paid-service.com/v1/data'); // → { average: 0.25, min: 0.20, max: 0.35, samples: 47 } const budget = cfo.spent(); // → { sessionSpent: "4.25", hourlyRemaining: "0.75", dailyRemaining: "45.75" } ``` ### When the user asks about spending Provide a financial summary: ```typescript const summary = cfo.summary(); // → { totalSpent, burnRatePerMinute, projectedDaily, topEndpoints, currencyBreakdown } const audit = cfo.audit(); // → Full ledger: every payment decision with timestamp, amount, URL, status, reason ``` ### Reacting to financial events Wire alerts so you can adapt your behavior: ```typescript cfo.events.on('budget:warning', ({ window, percentUsed }) => { // Budget is running low — reduce spending or ask the user }); cfo.events.on('budget:exhausted', ({ window }) => { // No budget left in this window — stop making paid requests }); cfo.events.on('velocity:spike', ({ multiplier }) => { // Spending is abnormally fast — slow down or alert the user }); ``` ## Key rules 1. **Never bypass the CFO.** All x402 payments go through `cfo.fetch()`. 2. **Check budget before expensive operations.** Use `cfo.spent()` and `cfo.estimateCost()`. 3. **Report spending when asked.** Use `cfo.summary()` for high-level stats, `cfo.audit()` for the full ledger. 4. **Respect budget exhaustion.** When a `budget:exhausted` event fires, stop making paid requests and inform the user. 5. **React to velocity spikes.** When spending is 2x+ above average, slow down and assess. ## Environment variables | Variable | Default | Description | |---|---|---| | `X402_BUDGET_HOURLY` | `5` | Maximum spend per hour (USDC) | | `X402_BUDGET_DAILY` | `50` | Maximum spend per day (USDC) | | `X402_BUDGET_SESSION` | `200` | Maximum spend per session (USDC) | | `X402_MAX_PER_REQUEST` | `2.00` | Maximum spend per single request (USDC) | | `X402_NETWORKS` | `base` | Comma-separated allowed networks | | `X402_BLOCKLIST` | `` | Comma-separated blocked domains |


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)