01 — Problem & thesis

1. Who this is for

Three audiences, one artifact:

1. Developers building agentic-commerce products: an AI agent that holds a wallet, trades across venues, pays for its own compute, buys/sells services, and is driven from a chat surface. They want plug-and-play: they should not have to personally reverse-engineer every venue's auth model or every wallet provider's signer semantics.
2. The Privy team: Privy already provides auth, embedded wallets, server wallets, server-wallet-v2 (agent wallets), and the new chain-agnostic deposit address (useDepositAddress). OAW shows how those compose into a complete agent economic actor and asks for a few targeted additions (08).
3. The Virtuals team: Virtuals built EconomyOS / ACP / DegenClaw / tokenization on top of Privy wallet infrastructure. OAW shows how a third-party backend can link and operate a Virtuals agent today, and asks Virtuals for a server-safe creation/registration surface so the Mode-A/Mode-B split can collapse into one (09).

2. The five pain points (each is a real wall devs hit)

P1 — "What is the agent's wallet, and can I create it for the user?"

The agent needs spending authority. Options are a maze: embedded wallet (user signs each time — not autonomous), server wallet, server-wallet-v2/agent wallet (programmatic, policy-bounded — this is the one), or a Virtuals agent wallet (which adds caps + agentmail + Stripe card + ACP identity + tokenization). The killer question: is the Virtuals one headlessly creatable by my backend? (Answer: no, today — see 03.) Devs need a model that uses the programmatic wallet by default and links the Virtuals one when the user has it.

P2 — "How do I bind one wallet to many venues?"

Every venue has a different connection story:

• Hyperliquid: agent/API wallet + approveAgent on Arbitrum, perps/spot/HIP-3/4.
• Polymarket: deposit wallet + CLOB credentials + EIP-1271 sig + Polygon pUSD, plus an any-chain USDC deposit bridge.
• Pump.fun: Solana managed wallet.
• Bankr: Base account.
• Binance: BNB / CEX API keys.
• Trade.xyz: route-proof binding.
• Virtuals DegenClaw: ACP-routed; needs Virtuals identity + signer.

A dev should declare a venue once and get binding, readiness, funding, and execution gates for free. That is the venue capability contract + pre-bind gate (04).

P3 — "How do I fund a venue on a chain my wallet isn't on?"

The agent wallet is native to Base/Solana/ARC (Virtuals) or wherever Privy put it. Venues settle elsewhere: Polymarket→Polygon, Hyperliquid→Arbitrum. The dev needs routing: chain-agnostic deposit addresses (Privy useDepositAddress, Polymarket's any-chain bridge) + swaps/bridges across the supported chains. That is the cross-chain funding router (05).

P4 — "How do I let the agent act from chat without prompt injection moving money?"

If the LLM both decides and signs, a poisoned market description or a crafted user message can drain the wallet. The agent must be a brain that plans behind a backend that is the sole executor and policy authority. And intent recognition must be reasoning-based, not keyword-based — "should I fund Hyperliquid?" must never trigger a transfer. See 06.

P5 — "How do I reuse Virtuals' rich wallet without its chain limits?"

Virtuals supports Base, Solana, and ARC. Devs want Abstract, Arbitrum, BNB, Ethereum, HyperEVM, Hypercore, Monad, Optimism, Polygon, Tron, Tempo, ARC. The answer is not to abandon Virtuals; it is to keep the Virtuals wallet as the authority/control surface (Mode B) and let the funding router + provider adapter reach any chain, settling back to the venue's native chain. Where Virtuals' own settlement is needed, route through it; everywhere else, route through the provider/funding layer.

3. Thesis

One agent authority object, many venue bindings, a cross-chain funding router, and a chat-brain that never holds keys — with wallet creation abstracted behind a provider interface so "Privy agent wallet" and "linked Virtuals wallet" are two implementations of the same authority.

Concretely:

AgentAuthority (provider-agnostic)
  ├─ provider adapter      → privy_agent_wallet | virtuals_linked | external
  ├─ VenueBinding[]        → one per venue, gated by a pre-bind authority check
  ├─ FundingRouter         → CAIP-2 chain map + deposit-address/bridge/swap routes
  └─ ExecutionContext      → agent_authority block + policy + spend-intent + receipt

The product north star: a user says "Bind Polymarket, fund it with $50, and buy YES on this market" in chat, and the system — under policy, fail-closed, with real receipts — provisions authority, binds the venue, routes the funds across chains, and executes, asking for confirmation only when policy/limits/compliance genuinely require a human.

4. Goals

• G1. A single authority object that any venue binds under, independent of whether the wallet is provider-managed or Virtuals-linked.
• G2. A declarative venue registry so adding a venue is data + one adapter, not a rewrite.
• G3. Cross-chain funding that treats "deposit USDC anywhere → agent funds the venue" as a first-class operation.
• G4. A hard security boundary: the brain plans, the backend executes; the LLM never holds a key; intent is classified by reasoning, executed deterministically.
• G5. Reuse Virtuals' EconomyOS wallet (caps/agentmail/card/tokenization/ACP) via linking, and a clear upgrade path (Modes C/D) if Virtuals exposes server-safe creation.
• G6. Everything fail-closed: live money movement is off by default, gated behind explicit flags + policy + approval, and produces durable receipts.

5. Non-goals (explicitly out of scope for OAW core)

• NG1. OAW is not a wallet provider. It does not custody keys itself; it delegates to Privy / Virtuals / the dev's chosen provider via the adapter.
• NG2. OAW is not a venue. It does not run an exchange or a matching engine.
• NG3. OAW does not ship trading strategy. Strategy is the agent brain's job; OAW provides the safe rails underneath.
• NG4. OAW does not fabricate Virtuals identities/signers, shell out to the ACP CLI in production, or auto-switch wallet authority. These are anti-patterns the reference implementation explicitly forbids.
• NG5. OAW does not replace x402 / AP2 / other payment protocols; it composes with them at the funding/execution layer.

6. Design principles (carried from hard-won Betvax experience)

1. One parent authority, many venue children. Never build ensure_polymarket_wallet() / ensure_hyperliquid_wallet() per venue. Build ensure_agent_wallet() + ensure_venue_binding(venue). (Betvax wrong→right model: [claudecodesession10.md §2].)
2. Resolve authority before any venue setup. No binding, signer, deposit wallet, or credential is created until the parent authority is ready — the pre-bind gate.
3. Verification is not ownership. Proving a Virtuals agent exists (verify_identity) is not proving the user controls it (verify_authority_proof). Active authority only switches to a linked wallet after ownership proof.
4. Prepare is preflight inside an execution-capable pipeline — never a prepare-only dead end. execute_or_plan(execute: bool).
5. Fail-closed beats fake-working. If Mode B execution isn't wired for a venue, return virtuals_authority_execution_not_supported_for_venue, never a silent fallback to Mode A.
6. Reasoning decides intent; keywords only decide whether to ask the model. No regex maps to a money action.
7. Every economic action is logged to a durable spend-intent + receipt + audit chain. No secrets in responses, logs, tests, or fixtures.

These principles are the spec. The rest of the folder is how to satisfy them.