moneo

<h1 align="center">Moneo</h1>

<p align="center">
  Autonomous finance for AI agents.<br>
  A wallet whose keys the model never sees, a spending policy that runs before anything is signed, and execution for markets that never close.
</p>

<p align="center">
  <a href="https://moneolabs.com">moneolabs.com</a> ·
  <a href="#quickstart">Quickstart</a> ·
  <a href="#packages">Packages</a> ·
  <a href="#how-it-fits-together">How it fits together</a> ·
  <a href="#what-is-and-is-not-implemented">Status</a> ·
  <a href="CONTRIBUTING.md">Contributing</a>
</p>

---

An agent that can only read is cheap to get wrong. An agent that can move money is not.
Moneo is the layer in between: it gives an agent its own account, its own limits, and a
record of every attempt, so a mistake costs a refusal instead of a balance.

Built for [Robinhood Chain](https://moneolabs.com), where tokenized equities and USDG settle
around the clock. An agent that can trade at 3am is only useful if it cannot also lose the
account at 3am, which is what the guard is for.

```bash
npm install @moneolabs/wallet @moneolabs/guard @moneolabs/trading
```

Or skip the code entirely and hand your agent host the sandbox — a funded wallet, a cautious
policy, and a simulated venue over [MCP](packages/mcp):

```bash
npx @moneolabs/mcp
```

## Quickstart

```ts
import { createGuard } from "@moneolabs/guard";
import { createWallet, localSigner, memoryRail, toolkit } from "@moneolabs/wallet";

// What this agent may do with money. Data, not code, and versioned.
const guard = createGuard({
  perTransaction: { max: "$25" },
  rolling24h: { max: "$100" },
  counterparties: "allowlist-only",
  allow: ["x402:*", "vendor:acme"],
  escalate: { above: "$50" },
});

// One account per agent. The signer holds the key, the wallet holds a handle.
const wallet = await createWallet({
  agent: "research-agent-01",
  signer: localSigner(),
  rail: memoryRail(),
  guard,
  funding: "$500",
});

await wallet.pay({ to: "x402:api.pricefeed.dev/quote", amount: "$0.04" });

// Hand the tools to your agent framework of choice.
const tools = toolkit(wallet, { guard });
```

Two runnable examples live in [examples/](examples):

```bash
node --experimental-strip-types examples/quickstart.ts
node --experimental-strip-types examples/guarded-trading.ts
```

## Packages

| Package                                | What it does                                                                                        |
| -------------------------------------- | --------------------------------------------------------------------------------------------------- |
| [@moneolabs/wallet](packages/wallet)   | An account per agent. Pluggable custody and rails, an agent toolkit for MCP or function calling.    |
| [@moneolabs/guard](packages/guard)     | Caps, rolling budgets, velocity limits, allowlists, and human escalation, evaluated before signing. |
| [@moneolabs/trading](packages/trading) | Multi-venue quotes, slippage bounds, market, limit, TWAP and bracket orders, positions and P&L.     |
| [@moneolabs/mcp](packages/mcp)         | MCP server over all of it: `npx @moneolabs/mcp` hands any agent host the guarded sandbox.           |
| [@moneolabs/core](packages/core)       | Exact money arithmetic, assets, durations, clocks, price sources. Shared by the rest.               |

Each package works on its own. The guard is useful with no wallet at all: it will happily sit in
front of a payment function you already wrote.

## How it fits together

```
agent
  │  pay / quote / trade
  ▼
wallet ──────► guard ──────► decision: allow | hold | block
  │              │
  │              └─► ledger  (every attempt, verdict and reason, blocks included)
  │
  ├─► signer     (holds the key; the agent never sees it)
  └─► rail       (chain, processor, internal ledger)
```

Three properties fall out of that shape, and they are the point of the project:

**A refusal is free.** Policy runs between intent and signature, so a blocked payment is never
broadcast and never costs a fee. `check()` tells you what would happen without doing it.

**Money in flight is money you do not have.** An allowed decision reserves budget immediately and
settles or releases later. A payment that fails at the rail hands its budget back rather than
leaving it stuck.

**Every verdict is attributable.** Decisions record which agent asked, what for, and which version
of which policy answered. Policy versions are content-addressed, so two policies that differ only
in key order or in how an amount was written get the same id.

## Design notes

**Amounts are never floats.** Every amount is an integer count of minor units in a `bigint`. A
budget that drifts by a fraction of a cent per check is a budget that eventually lets something
through. `parseMoney("$0.001")` throws rather than silently rounding away precision you meant.

**Time is injected.** Rolling windows, velocity limits, and TWAP schedules all read a `Clock`. Pass
`manualClock()` and a thirty minute order takes a millisecond to test. The test suite covers a
twenty five hour budget rollover without waiting for one.

**Refusals are values.** The agent toolkit returns a blocked payment as a normal result with a
reason and a hint, not as an exception. A model that gets a stack trace retries. A model that gets
"this limit is set by the wallet owner, ask them to raise it" stops and says so.

**Externals are interfaces.** `Signer`, `Rail`, `Venue`, `PriceSource`, `Approver`, and
`DecisionLedger` are all interfaces with working reference implementations. The target is
Robinhood Chain, but nothing in the packages hardcodes it: a network is a string you pass and a
rail is an object you supply.

## What is and is not implemented

This repository is honest about its edges.

**Fully implemented and useful today.** The guard is complete: caps, rolling budgets, velocity,
allowlists and denylists, asset and action rules, escalation, reservation and settlement, policy
versioning, replay against history. There is no hosted service behind it and none is needed. The
money arithmetic, the position book, and the order types are equally real.

**Implemented behind an interface, with a local reference adapter.** Custody ships as
`localSigner`, a genuine Ed25519 signer whose key never leaves the process, plus `remoteSigner` for
enclave or MPC services. Value movement ships as `memoryRail`, a real double-entry ledger that
happens to be in memory. Execution ships as `simulatedVenue`, deterministic and driven by a price
table you supply.

**Not included.** There is no hosted Moneo API, no chain client, no card issuing, and no bundled
price feed. Those are the adapters you write or that ship separately.

Which also means **there is no API key and no account to create**. These are libraries, not a
client for a service: policy is evaluated in your process, and the signer and rail are objects you
pass in. The things with credentials are whatever you connect them to.

## Development

```bash
npm install
npm test          # 120 tests, no network, no waiting on real clocks
npm run typecheck
npm run build
npm run check     # format, types, tests, build
```

Requires Node 20 or newer.

## License

MIT. See [LICENSE](LICENSE).

Moneo is developer infrastructure, not a broker, bank, or investment adviser. You are responsible
for the policies your agents run under and for the rails you connect.