Documentation

oathwall is a self-hosted autonomous trading agent for Robinhood Chain. Everything runs on your machine; your keys never leave it. This guide takes you from install to a named agent you chat with on Telegram.

Install

Runs on Linux, macOS, and Windows — one Node package, no Docker, no clone. Requires Node 22.12+ (for the built-in SQLite); no Node yet? The one-line installer sets it up and puts oathwall on your PATH.

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/rempprandy-afk/oathwall/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/rempprandy-afk/oathwall/main/install.ps1 | iex

Already have Node 22.12+? This works on any OS:

npm install -g oathwall
oathwall setup      # checks node / npm / PATH, prints exact fixes
oathwall start      # dashboard at localhost:3100 + the worker
oathwall update     # upgrade later (stops the agent, installs, restarts)

On a headless Linux box the dashboard won't auto-open — it prints localhost:3100; set OATHWALL_HOST=0.0.0.0 to reach it across a trusted LAN. Verify a fresh box with oathwall doctor — it checks Node, SQLite, RPC reach, keys, and paper/live mode, no wallet needed.

All your data lives in ~/.oathwall (settings, grant, ledger, your strategies, your agent's soul). The install is disposable — upgrades never touch your data. The dashboard binds to localhost only; to reach it from your phone on a trusted network, start with OATHWALL_HOST=0.0.0.0 oathwall start.

Create & fund a wallet

Open localhost:3100/grant. There is nothing to connect — oathwall generates a fresh account, shows you the owner key to back up, and lets you fund it. Pick your ground:

The caps you set — per-trade, daily, ops/day, drawdown breaker, key expiry — are enforced by the account contract on every operation. The worker can tighten within them but never widen them without a new signed grant.

Run it

oathwall start      # dashboard (localhost:3100) + the 24/7 worker
oathwall doctor     # node / keys / RPC / bundler / grant / db checks
oathwall status     # heartbeat, grant, trades, equity
oathwall selftest   # one policy-legal no-op through the full pipeline
oathwall kill       # kill switch — destroys the grant

Each tick the worker runs: grant sync → market safety → strategy proposes → policy check → quote simulation → execute → record. It re-reads your settings every tick, so dashboard changes apply within one tick — no restart.

Set up Telegram

1. Message @BotFather → /newbot → copy the token.
2. Dashboard → Settings → Telegram → paste the token, hit test connection (it shows your @botname), enable.
3. Message your bot /link <code> — the one-time code is shown in settings. You become the owner; only allowlisted chats are obeyed.

There's a Chat on Telegram button on the dashboard too. Commands work bare; with an Anthropic key set, plain English works — “how are we doing?”, “pause everything”, “why did you buy that?”.

Commands

It speaks first too (toggle in settings): a ping the moment a trade lands or the wall turns one back, warnings for grant expiry / drawdown / low gas, your price alerts, and a daily report at the hour you pick.

Transfers

Sending USDG out of the account is triple-guarded:

• Off by default — enable “allow transfers” in settings.
• Amount-capped on-chain — the grant's call policy caps the per-transfer amount.
• Always confirmed — every transfer echoes the full recipient address and waits for an explicit /confirm (90s), plus a daily transfer budget.

A prompt-injected “send everything to 0xevil” can at worst produce a confirmation card you will see and /cancel. Transfers need a wallet created with the transfer permission; a pre-transfer grant gets a “re-create your wallet” reply instead.

PC remote control

Enable the remote control section in settings and your agent can act on the machine it runs on, from Telegram. It is a hot wallet for your desktop, so the whole design is safety-first:

• Off by default, then one capability at a time. /pc shows what's on; the master switch off kills all of it.
• Allowlists for the sharp edges: shell runs only your exact pre-approved commands (chaining/redirects refused); files are confined to one root (no .. escape); apps to a name list.
• Confirm gate: shell, keyboard, file-send, and power never fire until you /confirm the exact action echoed back.

Voice & vision

Send a Telegram voice note and it's transcribed and run as a command (needs an OpenAI-compatible transcription key, set in the dashboard). Vision (“what am I looking at?”) screenshots your screen and answers with Claude — powered by your own Anthropic key.

The soul

Every agent is an individual. Its soul lives as plain markdown in ~/.oathwall/soul/:

The bond deepens over time — new companion → trusted companion (a week) → old friend (a month) → sworn brother-in-arms (100 days), with milestone messages and a tone that warms to match. Memory is context, never capability: soul files flavor chat only, and the sanitizer refuses anything address-, key-, or code-shaped.

Strategies

Pick one in settings (or /strategy <name> from Telegram):

Write your own bot

Your strategies live in ~/.oathwall/strategies/ — hot-reloaded, crash-isolated, and unable to exceed the caps you signed.

oathwall strategy new my-bot   # commented template
# edit it, select "my-bot" in settings — done

Default-export { name, tick(snapshot, ctx) }. ctx injects the verified registry (ctx.tokenBySymbol.QQQ, ctx.usdg(10)). Every intent still passes shape validation → the policy wall → quote simulation → the on-chain session key.

Stream to Virtuals

Put your agent's activity live on its page at app.virtuals.io. When you turn it on, every landed trade and the daily report are posted to your agent's public Virtuals Terminal — a running activity log (rejections aren't posted one-by-one; the daily report summarizes them).

It is a log, not a proof: anyone reading it is taking your word for the numbers. What they can check independently is the audit export — oathwall exportwrites the hash-chained journal, and oathwall verify checks it against nothing but itself and the chain. Share that if you want to be believed rather than trusted.

1. Grab your Virtuals API key from your agent's page on app.virtuals.io.
2. In oathwall settings → virtuals terminal, paste the key and flip stream to Virtuals on.

Safety model

One rule: the model proposes, deterministic code disposes. No strategist, Telegram message, or voice note ever constructs calldata, moves funds, or touches your PC without passing a closed, typed command set and — for money — the on-chain policy wall.

• Trades pass caps enforced by the account contract; every swap is simulated first.
• Transfers are amount-capped on-chain, off by default, and confirm-gated.
• PC actions are off by default, per-capability, allowlisted, and the sharp ones are confirmed.
• Secrets live only in ~/.oathwall and are masked before they ever reach the browser.
• The kill switch destroys the grant; hard on-chain key expiry is the backstop.

Why not a platform's own agent?

A first-party agent is custodial by construction — their servers, their keys, their discretion; the safety story is a terms-of-service. oathwall inverts the trust: the agent runs on your machine, the keys never leave it, and the caps live in your account contract on-chain — so a compromised agent can trade inside the wall, but cannot sign on your behalf, cannot send funds to an address you never registered, and cannot touch your ETH. And you can check, not believe: the dashboard links the account contract, session key, and every cap to the block explorer, and its prove the wall button fires malicious intents — an oversized trade, a “send everything to 0xevil” transfer, an expired key — through the live policy so you can watch each one bounce.

Configuration

The dashboard Settings is the source of truth — Essentials up front, everything else under Advanced. Saved to ~/.oathwall/settings.json; secrets are masked and never echo back. Precedence: settings file → env var → default. Env vars are the headless fallback (OATHWALL_BUNDLER_URL, ANTHROPIC_API_KEY, OATHWALL_TELEGRAM_BOT_TOKEN, OATHWALL_HOST, …). See the README for the full table.

Troubleshooting

Windows: “running scripts is disabled on this system”

Windows PowerShell ships locked to Restricted, which blocks npm's and oathwall's .ps1 command shims (you'll see PSSecurityException). The installer fixes this for you now; if you installed earlier, run this once — no admin needed, current user only:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Then oathwall setup works. Or skip the policy entirely and call it as oathwall.cmd setup (or run from cmd.exe / Git Bash).

The dashboard won't open

Run oathwall doctor. The prebuilt dashboard ships with the package, so a missing build usually means an interrupted install — reinstall with npm i -g oathwall@latest.

Trades never land

Live trading needs three things together: the wallet on mainnet · 4663, a Pimlico API key in settings (or a full bundler URL), and the smart account funded with ETH for gas and USDG for capital. Without a bundler key the agent stays in practice mode — it simulates but never signs. On testnet no trade can land by design: the stock-token venues aren't deployed, so swaps no-route, and any USDG you sent there reads 0 because oathwall only knows the mainnet token addresses. Switch to mainnet for real fills.

Telegram says “not authorized”

Only allowlisted chats are obeyed. Send /link <code> with the code from settings to claim ownership.

A PC command is refused

Enable remote control and the specific capability in settings. Shell/apps also need the exact command/app on their allowlist; /pc shows what's on.

Still stuck?

Ask in the beta group on Telegram, email support@oathwall.dev, or open an issue on GitHub — include your OS and what oathwall doctor prints.

oathwall doctor is safe to share: it reports whether a key is set, never the key itself (it does print install paths, which include your username). Your bot token, private key and grant link are a different matter — nobody helping you needs them, and the beta group is a room with strangers in it. If you screenshot the settings page, check what's in the fields first.

FAQ

My session key expired — do I pay to renew it? Do I have to redeploy?

No and no. The expiry is a safety timer, not a subscription. A grant is a signature your owner key makes locally — nothing goes on-chain to create one, so renewing costs zero gas and zero fees, and your wallet, funds, and history stay exactly where they are. When the key is close to expiring (or already dead), the /grant page shows a “renew the key (free)” button — one click re-signs the same wallet with a fresh key under the same caps. Your agent also pings you on Telegram before it expires.

Does the expiry apply in paper mode too?

Yes — expiry applies in every mode, paper and live. It's the guarantee that a forgotten agent can't run forever, and it's enforced twice: the worker retires the agent, and on-chain the account contract refuses the dead key regardless. Renewal is the same free one-click either way.

This feels built for devs — is easier onboarding coming? A desktop app?

Heard, and yes. Today the easiest path is the one-line installer — it checks Node, installs oathwall, and oathwall start opens the dashboard in your browser; you never need to write code (strategies are optional, presets cover the rest). The 1-click desktop app (.exe/.dmg — no terminal at all) also ships now, on the releases page. Either way it's the same stack — self-host it on your machine, or run it hosted from a URL. Your owner key stays with you regardless; a hosted server only ever holds a capped, revocable session key.

To keep it running across logouts and reboots, oathwall service install (or the tray toggle in the desktop app). Said plainly: that survives logout, sleep and reboot — it can't run while the computer is off. Nothing does except a machine that stays on, and the honest version of that is your own always-on box, not us holding your keys.