| name | budget-oracle |
| description | Multi-skill budget system for expense tracking, budget guardrails, and Pharos onchain financial logs. Use when a user or agent needs to record personal or business expenses, enforce spending limits, summarize weekly or monthly budgets, issue machine-readable warnings, or create a verifiable audit trail on Pharos Network. Includes expense-tracker, budget-guardian, and onchain-ledger sub-skills that can run independently or be chained. |
| license | MIT |
| metadata | {"author":"kane_120","version":"1.0.0","pharos-mainnet-chain-id":"1672","pharos-mainnet-rpc":"https://rpc.pharos.xyz","pharos-testnet-chain-id":"688689","pharos-testnet-rpc":"https://atlantic.dplabs-internal.com"} |
BudgetOracle
BudgetOracle is a composable multi-skill for local expense tracking, budget enforcement, and optional Pharos onchain logging.
Setup
Run from the package root:
npm install
npm run check
Use the unified CLI for normal workflows:
npm run dev -- init --period monthly --income 500000 --budget 300000 --currency NGN
npm run dev -- add --name "Team lunch" --amount 15000 --category Food
npm run dev -- summary
npm run dev -- ledger log --name "Vendor payment" --amount 500000 --category Vendor
Sub-Skills
skills/expense-tracker/SKILL.md: add, remove, edit, list, and summarize local expenses.skills/budget-guardian/SKILL.md: check new spending and audit budget health with warning codes.skills/onchain-ledger/SKILL.md: log, reverse, verify, and list expense hashes on Pharos, with simulated mode when wallet settings are missing.
Prompt Patterns
Use BudgetOracle when users ask to:
- Initialize a weekly or monthly budget with income, limit, and currency.
- Add, remove, edit, or list an expense.
- Check whether a planned purchase is safe.
- Summarize spending, savings rate, or category breakdowns.
- Warn before payroll, vendor, marketing, utilities, or DAO treasury spend.
- Log a financial record on Pharos or verify a previous expense hash.
- Produce JSON that another agent or workflow can consume.
Local And Onchain Modes
Local mode works with no wallet and stores state in assets/state.json.
Onchain mode uses Pharos Network:
- Mainnet: Chain ID
1672, RPC https://rpc.pharos.xyz, explorer https://pharosscan.xyz
- Atlantic testnet: Chain ID
688689, RPC https://atlantic.dplabs-internal.com, explorer https://atlantic.pharosscan.xyz
Set PHAROS_NETWORK=mainnet or PHAROS_NETWORK=testnet, plus PHAROS_PRIVATE_KEY and BUDGET_ORACLE_CONTRACT, for live mode. If wallet settings are missing, onchain-ledger returns simulated JSON instead of crashing.
Chaining Flow
For npm run dev -- add:
budget-guardian check --amount <num> evaluates the planned expense.- The expense is still recorded if
OVER_BUDGET appears.
expense-tracker add writes the expense to local state.- The unified CLI returns guardian warnings and tracker output together.
For npm run dev -- summary:
expense-tracker summary builds totals and category breakdowns.budget-guardian audit adds budget health warnings.- The unified CLI returns both in one JSON object.
Warning Codes
| Code | Level | Trigger |
|---|
OVER_BUDGET | ERROR | Total or projected spend is greater than budget limit |
APPROACHING_LIMIT | WARN | Total or projected spend is above 90% of budget limit |
HIGH_SINGLE_EXPENSE | WARN | New amount is more than 50% of remaining budget |
NO_INCOME_SET | INFO | Income is zero |
NO_BUDGET_SET | INFO | Budget limit is zero |
NEGATIVE_SAVINGS | WARN | Total or projected spend is greater than income |
PERIOD_RESET_DUE | INFO | State was last updated in a previous week or month |
Business Use Cases
| User | BudgetOracle Use |
|---|
| Individual | Daily expense tracking, savings rate, weekly or monthly reviews |
| Freelancer | Client project budgets, invoice expense logs, proof of work records |
| Small Business | Payroll, vendor payments, utilities, marketing, monthly P&L snapshot |
| DAO Treasury | Agent treasury guardrails and onchain-verifiable spend history |
| E-commerce Store | Inventory, campaign spend, revenue-aware operating budget |
| NGO/Nonprofit | Donor allocation tracking and transparent expenditure reporting |
For detailed examples, read references/BUSINESS_USECASES.md. For JSON output contracts, read references/OUTPUT_FORMAT.md. For Pharos setup, read references/PHAROS.md.
