X402 Cfo

Financial brain for x402 payments — budget enforcement, cost policies, spend analytics, anomaly detection, and audit trail for autonomous agents.

Security Scan

The skill's instructions fit a CFO/middleware role, but there are several incoherences and trust risks (missing credential declaration, no verified package source, and instructions to run npm/install code and write a local ledger) that you should resolve before installing.

Purpose & Capability

The SKILL.md describes a payment/budget middleware that needs a wallet, budget limits, and a local ledger — that purpose aligns with the documented runtime behavior. However the registry metadata lists no primary credential and no required env vars, yet the instructions clearly expect a wallet instance and use environment variables for budget and policy. The skill also has no homepage or authoritative source; asking the agent to npm install an unverified package is disproportionate if the publisher can't be vetted.

Instruction Scope

The instructions tell the agent to run shell commands (npm list / npm install) and to always funnel x402-paid HTTP calls through cfo.fetch(), create and write a local ledger file (./x402-cfo-ledger.json), and wire event handlers. These behaviors are consistent with a CFO role but they also broaden the agent's runtime actions to installing third-party code and writing potentially sensitive ledger data to disk. The SKILL.md references process.env variables and a wallet object but doesn't explain where the wallet comes from or how its secrets are protected.

Install Mechanism

There is no formal install spec in the registry (instruction-only), but the SKILL.md explicitly instructs running 'npm install x402-cfo'. Installing an unverified npm package fetched at runtime can execute arbitrary code on the host. Because there is no homepage/source or known publisher metadata, this is a moderate-to-high risk compared to using a vetted package or known release.

Credentials

The SKILL.md documents several environment variables for budgets and policies (X402_BUDGET_*, X402_MAX_PER_REQUEST, X402_NETWORKS, X402_BLOCKLIST). Those are reasonable as optional configuration, but the skill also requires a 'wallet' object (sensitive credential) for payments; the registry metadata does not declare any primary credential or required config paths for a wallet. This mismatch is important: the runtime needs a wallet (private key or provider) but the package doesn't declare how that credential should be supplied or protected.

Persistence & Privilege

The skill does not request always:true and does not modify other skills. It does instruct creating a local ledger file and relies on agent file read/write/exec capabilities. Combined with the ability to install and run npm packages, that gives it the power to persist data locally and execute code, which is expected for this purpose but warrants caution (reviewed below).

Scan Findings in Context

[no_code_files_detected] expected: Static scanner found no code files — this SKILL is instruction-only. That means the scanner had nothing to analyze; the SKILL.md itself contains commands to install and use an npm package (x402-cfo) which will pull code at install/runtime and was not available for pre-install analysis.

What to consider before installing

What to check before installing or using this skill: - Don't install or run code from an unverified package. Ask the publisher for a homepage, repository URL, or package audit (who publishes x402-cfo?). Prefer packages with a public GitHub repo, pinned release, and reviewable source. - Clarify how the wallet is provided. The skill requires a 'wallet' object (sensitive). Do not provide your main production private key. Use a constrained test wallet or a signing gateway with limited funds and explicit approval for payments. - Consider running the npm install and any execution in a sandbox/container first; inspect the package contents and its dependencies before allowing your agent to use it. - Review the ledger file path (./x402-cfo-ledger.json). It will contain payment/audit data — ensure its filesystem location and permissions are acceptable and that sensitive fields are redacted or encrypted if needed. - If you allow autonomous agent invocation, realize the agent could make payment decisions using the wallet. If you want to limit risk, disable autonomous invocation for the agent that will use this skill or require user confirmation for payments. - Ask the skill author for explicit declaration of required credentials (primaryEnv) and for proof of the package's integrity (package name, publisher, version, signature). If the author cannot provide a verifiable source or if you cannot audit the package, treat this skill as high-risk and avoid installing it. If you want, I can draft specific questions to ask the publisher or produce a checklist for auditing the npm package contents.

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:

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:

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:

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:

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:

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:

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