airwallex-finance-manager

Airwallex AI Finance Manager

This is a reference demo, not a product. Clone it to see how a self-hosted Hermes Agent can talk to you on Telegram and act as a company finance manager on top of Airwallex AgentOS. Use it as a starting point for your own agent — do not treat it as production software, financial advice, or an official Airwallex application.

Airwallex supplies the financial primitives. This repo supplies the install path, Hermes skills, and a local MCP for computed tools (runway, anomalies, budget variance, CFO summary). It is not a hosted bot and not an AgentOS proxy. You run everything on your own machine against your Airwallex account.

Dollar amounts in skills, tests, and knowledge/*.example.yaml are fictional.

Telegram → Hermes → Airwallex AgentOS MCP
                 → this repo's finance-manager MCP
                 → this repo's skills + SOUL.md

What you get

Prerequisites

A laptop is enough. You can skip Telegram at first and use hermes chat on the CLI.

Quickstart

git clone https://github.com/awx-devx/airwallex-finance-manager.git
cd airwallex-finance-manager
./scripts/install.sh

The installer checks for hermes and uv, syncs the MCP, and merges this pack into ~/.hermes/ (config, env key names, SOUL.md). It does not log you into Airwallex or write secrets into this clone.

Then, on that same machine:

1. Put your model key in ~/.hermes/.env (OPENAI_API_KEY or ANTHROPIC_API_KEY).

2. Bind your Airwallex account (browser OAuth — no API key in this repo):

   hermes mcp login airwallex
   

   Sign in to the org you want the agent to see. Hermes stores tokens under ~/.hermes/mcp-tokens/. On a VPS, run this on the server as the gateway user and paste the browser callback URL back into the prompt (remote OAuth).

3. Optional knowledge files (live copies are gitignored):

   cp knowledge/budgets.example.yaml knowledge/budgets.yaml
   cp knowledge/vendors.example.yaml knowledge/vendors.yaml
   cp knowledge/policies/spending.example.md knowledge/policies/spending.md
   

4. hermes gateway setup (Telegram) and allowlist numeric user IDs, or set TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS in ~/.hermes/.env.

5. hermes gateway — or hermes chat if you are not using Telegram yet.

6. In Telegram, send /new (a restored DM keeps the old session), then ask a finance question. Skills do not load on "hi".

Do not add this bot to a public group. Anyone who can prompt it inherits your Airwallex scopes.

Try it

Once the gateway is up, DM the bot something like:

• “How much cash do we have, and how many months of runway?”
• “Anything unusual in spending this month?”
• “Are we over budget on cloud?”
• “Prepare the month-end pack.”

Sample threads (tool sequence, not live data) live in examples/.

Environment variables

Secrets live in ~/.hermes/.env, not in this repository. hermes/env.example lists the names; install.sh sets FINANCE_MANAGER_ROOT for you.

There is no AIRWALLEX_API_KEY here. AgentOS uses OAuth (hermes mcp login airwallex).

Sandbox vs production

AgentOS MCP (https://mcp.airwallex.com/mcp) talks to the live org you sign in with. There is no sandbox clone of AgentOS.

Sandbox is a different server — Developer MCP — and tool names will not match 1:1. Details: docs/repo-guide.md §5.3.

Use a separate Hermes profile and Telegram bot for experiments vs anything you treat as real finance.

Security

Read SECURITY.md and docs/repo-guide.md §7–8.

• Allowlist only. Private DMs first.
• Credentials stay in ~/.hermes/.env and ~/.hermes/mcp-tokens/. Never commit them. Never paste them into a prompt.
• The custom MCP has no money-out tools. AgentOS money-out is off by default; financial-controls still requires an explicit confirmation from an allowlisted user.
• This is not financial advice. You are responsible for your Airwallex account, scopes, and compliance.

Layout

airwallex-finance-manager/
├── README.md
├── LICENSE
├── SECURITY.md
├── docs/                  # how the pack is structured; product thesis
├── hermes/                # SOUL.md, config fragment, env key names
├── skills/                # Hermes SKILL.md workflows
├── mcp/finance-manager/   # local FastMCP server (Python)
├── knowledge/             # example budgets, vendors, policies
├── examples/              # sample Telegram threads
└── scripts/install.sh     # merge the pack into ~/.hermes/

Hermes reads from ~/.hermes/, not from the git clone, unless you point it here.

Development

cd mcp/finance-manager
uv sync --extra dev
uv run pytest

Add a skill as skills/<name>/SKILL.md. Add a compute-first tool on the MCP — do not wrap AgentOS get_accounts() “for convenience.” See docs/repo-guide.md §9.

Docs

License

MIT. Airwallex, Telegram, and Hermes are trademarks of their respective owners. This project is not affiliated with, endorsed by, or an official product of Airwallex.