# SpendOS -- The First Autonomous Agent That Governs Its Own Spending

An AI agent that earns USDC, self-funds its own inference, proposes investments, creates its own revenue streams, and never spends a dime without your approval -- all governed by OWS policies, audited on-chain.

**Live demo:** [spendos.xyz](https://spendos.xyz)

## OWS Hackathon 2026

| Track | How SpendOS Fits |
|-------|-----------------|
| **Agent Spend Governance & Identity** | OWS delegations, session keys, policy engine, dead man's switch |
| **Pay-Per-Call Services & API Monetization** | x402 micropayments, dynamic job registry, agent-created endpoints |
| **Multi-Agent Systems & Autonomous Economies** | Self-funding inference, autonomous revenue, public MCP for external agents |
| **Creative / Unhinged** | An AI that runs a business and proposes its own investments |

## Quick Start (3 commands)

```bash
git clone https://github.com/consensus-hq/spendos.git
cd spendos
./setup.sh
```

The setup script:
- Installs dependencies
- Generates your admin token and vault passphrase
- Walks you through adding your mnemonic and API keys
- Creates your `.env`

Then run:

```bash
npx tsx src/server.ts
```

Dashboard at `http://localhost:3030/?token=YOUR_ADMIN_TOKEN`

## Deploy to Railway (1 command)

```bash
./setup.sh --deploy --provider railway
```

This provisions your SpendOS instance on Railway with all env vars set. Add a persistent volume at `/data` in the Railway dashboard, and you're live.

## What It Does

```
Customer pays $0.01 USDC --> SpendOS (x402) --> Venice AI --> Summary returned
                                  |
                        Agent earns revenue
                                  |
                        Agent proposes: "Stake on Aave"
                                  |
                        Owner approves in dashboard
                                  |
                        On-chain audit (Base mainnet)
```

1. **Earns revenue** -- sells AI compute via x402 micropayments ($0.01/query)
2. **Self-funds inference** -- pays Venice AI from its own wallet (SIWE auth, no API keys)
3. **Creates new products** -- writes JSON job files, endpoints go live instantly
4. **Proposes investments** -- scans for yield opportunities, requests delegations
5. **Waits for approval** -- owner reviews proposals in the governance dashboard
6. **Executes within policy** -- approved delegations create OWS session keys with expiry
7. **Self-destructs access** -- dead man's switch auto-revokes expired delegations
8. **Audits everything on-chain** -- every decision logged to Base mainnet

## Architecture

```
spendos.xyz (public)              /?token=xxx (dashboard)
       |                                |
  Landing Page                    SpendOS Server (:3030)
  (live P&L, tracks)                   |
                                  +----+----+
                                  |         |
                            OpenClaw    Express Routes
                            (:18789)
                                  |         |
                            Venice AI   /api/summarize (x402)
                            (SIWE)      /api/jobs/:name (x402)
                                        /api/delegate (governance)
                                        /api/chat (streaming)
```

## Key Features

- **Job Registry** -- Agent creates new paid endpoints by dropping JSON files
- **x402 on Base Mainnet** -- Real USDC payments via CDP facilitator
- **Retry Loop Protection** -- Server-side guards: 15KB max, 2min timeout, repetition detection
- **Persistent Chat** -- Conversation history survives page refresh + redeploy
- **OWS Integration** -- Session keys, policies, dead man's switch
- **On-chain Audit** -- Basescan-verifiable governance decisions via Tenderly RPC
- **Public MCP Client** -- External agents pay to use SpendOS tools

## Configuration

Copy `.env.example` to `.env`:

```env
# Required
OWS_IMPORT_MNEMONIC=your twelve word mnemonic phrase here
OWS_PASSPHRASE=your-vault-passphrase
SPENDOS_ADMIN_TOKEN=$(openssl rand -hex 32)
DEPLOYER_PRIVATE_KEY=0x...

# x402 Payments (Base mainnet)
CDP_API_KEY_ID=your-cdp-key-id
CDP_API_KEY_SECRET=your-cdp-key-secret

# RPC (Tenderly recommended)
SPENDOS_RPC_URL=https://base.gateway.tenderly.co/YOUR_KEY
```

All values are auto-generated by `./setup.sh` except the mnemonic and deployer key.

## File Structure

```
src/
  server.ts           -- Express server, routes, x402 gate, chat proxy
  governance.ts       -- OWS wallet, delegations, P&L, dead man's switch
  job-registry.ts     -- Dynamic job creation with x402 pricing
  venice-x402.ts      -- Venice SIWE wallet auth + self-funding
  audit.ts            -- On-chain audit logging (Base mainnet)
  agent.ts            -- Venice inference with dynamic cost tracking
  mcp-server.ts       -- Internal MCP tools for OpenClaw agent
  mcp-public.ts       -- Public MCP client for external agents
  xmtp.ts             -- XMTP notification system
  zerion.ts           -- Wallet portfolio enrichment
public/
  index.html          -- Governance dashboard
  landing.html        -- Public revenue dashboard
jobs/
  *.json              -- Agent-created paid endpoints
setup.sh              -- One-command setup + Railway deploy
SOUL.md               -- Agent personality and rules
start.sh              -- Container startup orchestration
Dockerfile            -- Single container (SpendOS + OpenClaw)
```

## Built With

| Partner | Role |
|---------|------|
| **OWS** | Wallet, signing, session keys, policies |
| **MoonPay** | Agent crypto capabilities (filtered: quote/search/balance only) |
| **OpenClaw** | Agent runtime + skill system |
| **Venice** | Decentralized inference (SIWE wallet auth, self-funded) |
| **x402** | Agent earns revenue via HTTP 402 micropayments |
| **Zerion** | Wallet portfolio enrichment |
| **Base** | On-chain audit log (mainnet) |
| **XMTP** | Governance alerts |

## Team

Roman Mondello ([@integrate-your-mind](https://github.com/integrate-your-mind)) + Claude Opus 4.6

## License

MIT