Open Agent Wallet (OAW)
A vendor-neutral specification + reference design for agent-operated wallet infrastructure: one agent authority, many venue bindings, cross-chain funding, and a safe chat-brain → backend-executor split — with first-class reference adapters for Privy and Virtuals.io (EconomyOS / ACP / DegenClaw / tokenization).
This folder is not the Betvax product. It is the open, reusable distillation of what Betvax learned the hard way, written so that any developer building agentic-commerce products — and the Privy and Virtuals teams themselves — have a concrete thing to build from and to merge upstream.
Betvax is used throughout only as the reference implementation and proof that the design runs in production. Every claim here is grounded in real, inspected code paths (the file references point at the Betvax tree) or explicitly flagged as unverified / a request to the upstream vendor.
The problem in one paragraph
A developer who wants to build "an AI agent that is an autonomous economic actor" today has to personally solve five hard, undocumented problems before they can ship anything: (1) what is the agent's wallet, and who can create it headlessly? (2) how do you bind that one wallet to many trading venues (Hyperliquid, Polymarket, Pump.fun, Bankr, Binance, Trade.xyz, Virtuals DegenClaw) each with a different auth/signing model? (3) how do you fund those venues across chains when the agent's wallet lives on Base/Solana but the venue settles on Arbitrum/Polygon? (4) how do you let the agent act from a chat surface without letting prompt injection move money? and (5) how do you reuse Virtuals' rich agent wallet (spending caps, agentmail, Stripe card, tokenization, compute credits) instead of rebuilding it — without being locked to Virtuals' three chains? OAW answers all five as one coherent system.
The decisive question, resolved
Everything downstream depends on one question that the public docs never answer cleanly:
Can an agent's Virtuals/EconomyOS wallet (with its native spending caps, agentmail, Stripe card, ACP identity) be created headlessly, server-side, by a third-party developer's backend — or must a human create it in the Virtuals portal first?
Resolved answer (evidence-based, see 03 and 09):
No production-safe, server-side Virtuals agent-wallet creation surface has been verified in the inspected SDK/CLI/docs. The verified production-safe path today is owner/user creation or approval through Virtuals/ACP flows (
app.virtuals.io/acp/new), after which a developer backend links and operates that wallet. The verified ACP client (virtuals_os_acp_v3_client.py) exposesverify_identity,signer_status,verify_authority_proof,create_job/fund_job/complete_job, and thedgclaw_*family — but nocreate_agent/create_agent_wallet. It operates an existing agent; it does not mint one.
This is not "Virtuals can never do programmatic creation." It is "we have not verified a backend-safe creation API yet, and the available surface points at owner/handoff flows." That distinction is the whole reason for the Virtuals PR in 09: we are asking Virtuals to expose exactly that surface.
Because creation is not headless, the agent wallet has two production authority modes and three future ones (full table in 03):
| Mode | Name | Who creates the wallet | Status |
|---|---|---|---|
| A | Provider-managed (e.g. Privy) agent wallet | The dev's backend, programmatically | Shipped / production |
| B | Linked existing Virtuals/EconomyOS wallet (ownership-proof) | The user, in the Virtuals portal | Shipped / production |
| C | Virtuals programmatic create | Virtuals server API (does not exist yet) | Unverified — PR target |
| D | Provider wallet registered into Virtuals/EconomyOS | Virtuals registration API (does not exist yet) | Unverified — PR target |
| E | External imported wallet (user-owned key / capped signer) | The user | Scaffolded |
Modes A and B together already deliver the product: any user gets an autonomous agent wallet instantly (Mode A), and a user who already has a Virtuals agent keeps its native caps/agentmail/card (Mode B). Modes C and D are what we want Virtuals to make real so Mode A and Mode B converge.
The core architecture in one diagram
Chat / mobile surface ── the agent BRAIN (Hermes / any LLM runtime)
│ reasons, plans, classifies intent — but signs NOTHING
▼
┌─────────────────────────────────────────────────────────────────┐
│ OAW backend (the EXECUTOR — the only thing that holds keys) │
│ │
│ 1. Agent Authority layer │
│ AgentAuthority (a.k.a. EconomyOSAgentProfile) │
│ └─ provider adapter: Privy | Virtuals | external │
│ │
│ 2. Venue Binding layer │
│ VenueCapabilityContract (registry) │
│ Pre-bind gate ── resolve authority BEFORE any venue setup │
│ └─ venue adapters: hyperliquid | polymarket | pumpfun | … │
│ │
│ 3. Funding layer │
│ Cross-chain funding router (CAIP-2 aware) │
│ └─ deposit-address + bridge + swap routing │
│ │
│ 4. Execution + policy layer │
│ agent_authority block, spend-intents, receipts, policy │
│ │
│ 5. Intent safety layer │
│ reasoning classifier (deterministic gated execution) │
└─────────────────────────────────────────────────────────────────┘The brain/executor split is a security boundary, not an accident. The LLM is a powerful, prompt-injectable component. It decides what to do; the backend deterministically decides whether it is allowed and is the only thing that ever touches a signer. See 06.
How to read this spec
| Doc | What it gives you |
|---|---|
| 01 – Problem & thesis | The five dev pain points, goals, non-goals, and design principles. |
| 02 – Architecture overview | The five layers, the brain/executor split, the object model. |
| 03 – Agent authority & wallet modes | The heart. Wallet-provider abstraction, Privy wallet types, Virtuals creation question resolved, Modes A–E. |
| 04 – Venue binding & pre-bind gate | The venue capability contract, the universal pre-bind gate, bind lifecycle, venue adapter interface. |
| 05 – Cross-chain funding router | CAIP-2 chains, deposit-address/bridge/swap routing, funding plans, gated execute. |
| 06 – Execution authority & safety | agent_authority execution block, spend-intent/receipt model, the reasoning-classifier intent layer, prompt-injection boundary. |
| 07 – Reference interfaces | The actual SDK surface in TypeScript and Python — provider, venue, funding, authority interfaces. |
| 08 – PR to Privy | A concrete, mergeable proposal to Privy. |
| 09 – PR to Virtuals | A concrete, mergeable proposal to Virtuals. |
| 10 – Roadmap & open questions | Phasing, what's verified vs not, the questions only Privy/Virtuals can answer. |
@oaw/core on GitHub | Runnable @oaw/core — the spec as working, tested TypeScript (61 tests, clean typecheck, zero-install demo). |
Not just a spec — there's working code.
@oaw/coreis a runnable, tested TypeScript implementation of every layer below (node --test --experimental-strip-types "test/**/*.test.ts"→ 61 passing; cleantsc; anode examples/north-star.tsdemo binds → funds → trades from chat). Seven venues are wired (Polymarket, Hyperliquid, Pump.fun·Solana, Bankr·Base, Virtuals, DegenClaw, Trade.xyz), proving the registry+adapter pattern generalizes across EVM, non-EVM, and the ACP-native Mode B path. Paste-ready upstream proposals live in the proposals section.
Status & provenance
- This repository is the implementation. The runnable
@oaw/coreSDK (TypeScript) lives at the repo root (src/,test/,examples/); thisdocs/tree is the spec + landing. The package is Apache-2.0 and npm-publishable. - Origin / proof source: the patterns were first proven in a production agentic-commerce backend (Betvax) running behind fail-closed flags, then generalized here into a vendor-neutral standard. Betvax is cited only as origin evidence — no Betvax context is required to use OAW.
- Verified vs proposed: claims grounded in the verified vendor surface are marked accordingly; proposed items (Modes C/D, Privy/Virtuals API asks) are designs we want the vendors and community to validate — see the proposals. We say "the verified surface does not expose X," never "X cannot exist."
- Honesty: every venue adapter is a reference adapter (no live venue call) until wired — see conformance.