agent-financial-advisor

# Agent Financial Advisor

The compliance officer, risk manager, tax advisor and performance auditor for AI agents that trade and advise.
Agents call it before they act; it answers with sourced, deterministic checks and charges a small fee per call.


## Tools

| Tool | Price | Does |
|---|---|---|
| `rules_digest` | free | Current US trading/margin/settlement/tax rules with effective dates and sources |
| `pre_trade_check` | $0.005 | Buying power, cash-account violations, intraday margin (post-PDT), Reg SHO, wash sales, concentration, risk-to-stop, liquidity, spread, fat finger, leverage, market hours |
| `position_size` | $0.005 | Fixed-fractional, volatility-target or fractional-Kelly sizing with caps |
| `tax_lot_plan` | $0.02 | FIFO/LIFO/HIFO/min-tax lot selection, ST/LT split, wash sales, loss harvesting scan |
| `portfolio_review` | $0.05 | Weights, HHI, sector/asset-class exposure, rebalance trades, Sharpe/Sortino/drawdown/VaR/beta |
| `strategy_audit` | $0.10 | Trade stats, t-stat, Probabilistic and Deflated Sharpe Ratio, overfitting red flags |
| `suitability_check` | $0.03 | Reg BI / fiduciary suitability review with a hashed audit memo |

## Run locally (Node 20+, no dependencies)

```
npm test          # 21 tests
npm start         # http://localhost:8787  (payments off until PAY_TO is set)
```

Try it:

```
curl localhost:8787/llms.txt
curl -X POST localhost:8787/v1/tools/position_size -H "content-type: application/json" \
  -d '{"equity":50000,"entry_price":100,"stop_price":95,"method":"fixed_fractional"}'
```

MCP clients: point a streamable-HTTP MCP connection at `http://localhost:8787/mcp`
(send `Authorization: Bearer <key>` for the keyed free tier and credits).

## Endpoints

| Method | Path | |
|---|---|---|
| GET | `/`, `/llms.txt` | Agent-readable overview |
| GET | `/v1/tools`, `/openapi.json`, `/pricing`, `/.well-known/x402` | Discovery |
| POST | `/v1/tools/{name}` | Run a tool |
| POST | `/mcp` | MCP JSON-RPC |
| POST | `/v1/keys` | Free API key |
| GET | `/v1/keys/me` | Key balance |
| POST | `/v1/credits?pack=5\|20\|100` | Buy credits with x402 |
| GET | `/admin/revenue` | Revenue and usage (ADMIN_TOKEN) |

## Configuration (env vars)

| Var | Default | |
|---|---|---|
| `PAY_TO` | unset | USDC receiving address. Unset = free preview, no payments |
| `X402_NETWORK` | `base-sepolia` | `base` for real money |
| `CDP_API_KEY_JSON` | unset | Secret: the downloaded CDP key file. When set, payments go through the Coinbase CDP facilitator (needed for mainnet). `CDP_API_KEY_ID` + `CDP_API_KEY_SECRET` also work |
| `FACILITATOR_URL` | CDP if a key is set, else `https://x402.org/facilitator` | Override the facilitator |
| `FACILITATOR_AUTH` | unset | Static Authorization header for a non-CDP facilitator |
| `X402_MIN_USD` | `0.01` | Minimum pay-per-call x402 price (credits pay list price) |
| `FREE_DAILY_CALLS` / `FREE_DAILY_ANON` | 25 / 5 | Free tier |
| `ADMIN_TOKEN` | unset | For `/admin/revenue` |
| `DATA_DIR` | `./data` | Node store and ledger |
| `PUBLIC_URL` | request host | Used in payment requirements |

## Deploy (free)

Cloudflare Workers: `npx wrangler kv namespace create AFA_KV`, put the id in `wrangler.toml`, then `npx wrangler deploy`.

Real USDC: `npx wrangler secret put CDP_API_KEY_JSON < secrets/cdp_api_key.json`, set `X402_NETWORK = "base"` in `wrangler.toml`, deploy.

## Payments (x402)

Speaks x402 v2: a 402 carries a base64 `PAYMENT-REQUIRED` header (CAIP-2 network, e.g. `eip155:8453`), clients pay with
`PAYMENT-SIGNATURE`, and the settlement comes back in `PAYMENT-RESPONSE`. v1 clients (`X-PAYMENT`, body `accepts`) still work.

End-to-end test on the test network: `npm i --no-save viem && node scripts/e2e-payment.mjs <server url> --fund`.

## Layout

```
src/app.js            fetch-style router: REST, MCP, billing hooks
src/server.js         Node entry
src/worker.js         Cloudflare Workers entry (KV store)
src/billing/          free tier, API keys, credits, x402, ledger
src/tools/            the advisory tools
src/lib/regs.js       rule table with sources (reviewed weekly)
src/lib/calendar.js   NYSE calendar
test/                 node --test suites
```