09 — Proposal to Virtuals.io

Framing: Virtuals built something genuinely valuable on top of Privy — an agent wallet with native spending caps, agentmail, a Stripe-powered card, ACP identity, tokenization, DegenClaw/Arena, and compute credits (EconomyOS). The single thing blocking third-party devs from making that the default substrate for their agents is that wallet creation is not headless — it's an owner/portal flow (app.virtuals.io/acp/new), and the verified ACP client can operate an existing agent but cannot create one. This proposal asks Virtuals to close exactly that gap, in a way that preserves Virtuals' security model.

The verified state (so we're precise, not accusatory)

• The inspected ACP v3 client exposes: verify_identity, signer_status, verify_authority_proof, wallet_balance, create_job / create_fund_transfer_job / fund_job / complete_job / reject_job, send_message, submit_deliverable, drain_events, get_job, list_resources, and the dgclaw_* family.
• It has no create_agent / create_agent_wallet.
• The docs direct creation to the owner/portal flow and explicitly forbid faking server-side identity/signers or shelling out to acp-cli in production.

Conclusion (the wording we hold):

No production-safe, server-side Virtuals agent-wallet creation surface has been verified. The verified path is owner/user creation, then link-and-operate. The door is open for Virtuals to expose a server-safe surface — that is this PR.

How OAW uses Virtuals today (and why it already works)

• Mode B — link existing Virtuals agent: a user who created an agent in the portal can be linked (with ownership proof via verify_authority_proof), and the dev backend operates it — ACP jobs, DegenClaw, the native caps/agentmail/card. This is shipped and correct.
• OAW's Virtuals adapter is a thin wrapper over the verified ACP client; it never fabricates identity and never shells out to the CLI in production.

The limitation: new users without a Virtuals agent can't get one headlessly, so OAW must fall back to Mode A (Privy agent wallet) for them — which lacks the EconomyOS envelope. The two asks below collapse that gap.

---

Proposal V1 (primary) — Mode C: a server-safe agent-wallet creation API

Ask: expose a backend API that provisions an EconomyOS agent wallet (with its native caps / agentmail / card / ACP identity / tokenization slot) for a developer, on behalf of a user, without a browser/portal step — or with an explicit, auditable consent token that a backend can obtain programmatically.

POST /v1/economyos/agents
  Authorization: Bearer <developer_api_key>
  {
    "owner_user_ref": "dev-side user id",
    "consent": { "type": "signed_consent_token | oauth_grant", "value": "…" },
    "policy": { "spend_caps": [...], "autonomy_mode": "…" },
    "chains": ["base","solana","arc","arbitrum","polygon", …],
    "idempotency_key": "…"
  }
→ {
    "agent_id": "…", "wallet_address": "…", "signer_status": "ready|pending",
    "capabilities": { "agentmail": true, "card": "provisioning", "acp_identity": "…", "tokenization": "available" }
  }

Security-preserving design notes (so this is acceptable to Virtuals):

• Gate it behind a developer API key + an explicit user-consent token (signed or OAuth-granted) so creation is never fully unattended — it's "headless for the dev, consented by the user," not "anyone mints wallets."
• Default the new wallet to conservative, fail-closed policy (low caps, live-execution off) so a freshly minted agent can't move material money until the owner raises limits.
• Keep the owner/portal flow as the privileged path for high-trust capabilities (e.g. raising caps, card issuance) via owner_handoff_required — OAW already models that status precisely.

Impact: Mode C makes Mode A and Mode B converge — every user can get a Virtuals agent wallet instantly, and OAW no longer needs a Privy fallback for new users. This is the highest-leverage ask.

Proposal V2 — Mode D: register an external (Privy) wallet into EconomyOS

Ask: expose an API to adopt an existing external wallet (e.g. a Privy agent wallet the dev already created) into EconomyOS, attaching the agentmail / card / ACP identity / tokenization envelope to that wallet rather than minting a new one.

POST /v1/economyos/agents/register-wallet
  { "owner_user_ref": "…", "wallet": { "provider":"privy", "address":"0x…", "proof": {…} },
    "consent": {…}, "idempotency_key": "…" }
→ { "agent_id": "…", "capabilities": {…} }

Why this is elegant: because Virtuals already runs on Privy, adopting a Privy agent wallet means the signer substrate is unchanged — Virtuals wraps caps / agentmail / card / ACP around a wallet the dev controls. The dev keeps one wallet (no migration, no fund-shuffling) and gains the EconomyOS capabilities. This is the cleanest convergence of the two ecosystems.

Proposal V3 — A IEvmProviderAdapter for ACP execution with an external signer

Ask: let ACP jobs / DegenClaw execute with signatures from an external signer the dev provides (the agent wallet's signer), via a documented IEvmProviderAdapter-style interface, rather than requiring Virtuals' internal keychain. The dev never hands Virtuals a raw key; they implement a sign callback.

Why: this is what makes Mode B → real execution possible for ACP-native venues without the dev surrendering custody. OAW's agent_authority.execution_route = "virtuals_acp_sidecar" becomes fully functional when the sidecar can call back to the dev's signer. (Today, OAW correctly returns virtuals_authority_execution_not_supported_for_venue where this isn't wired — V3 removes that blocker.)

Proposal V4 — Chain expansion beyond Base/Solana/ARC

Ask: extend EconomyOS agent-wallet settlement/holding support across the CAIP-2 set (Arbitrum, Polygon, BNB, Ethereum, Optimism, Abstract, HyperEVM, Monad, Tron, Tempo). Where native support lags, document the bridge/swap contract so OAW's funding router can settle to a venue's native chain deterministically.

Why: Virtuals' 3-chain limit is the exact constraint OAW routes around today. First-class multi-chain support (or a documented bridge contract) lets the agent trade Hyperliquid (Arbitrum), Polymarket (Polygon), and Pump.fun (Solana) under one EconomyOS wallet without OAW having to stitch external bridges.

Proposal V5 — Programmatic capability/status surface

Ask: a read API for an agent's EconomyOS capabilities + status (caps, agentmail address, card state, ACP identity, tokenization, compute credits balance) as non-secret JSON, matching what the portal shows.

Why: OAW's Virtuals adapter capabilities() and the chat surface need to tell the user "your agent has $X compute credits, card is active, daily cap is $Y" without scraping the portal.

---

What OAW contributes back

• A reference @oaw/adapter-virtuals implementing WalletProviderAdapter against the verified ACP surface today, with createManagedAgentWallet (Mode C) and registerExternalWallet (Mode D) stubbed and ready to light up the moment V1/V2 ship.
• The ownership-proof model (verify_identity ≠ ownership; verify_authority_proof gates active authority) as a reference for safe linking.
• A conformance suite: link-without-proof stays non-authoritative, no secret leakage, ACP-native venue gating, idempotent create.

Minimal viable subset

If only one thing ships: V2 (register external Privy wallet into EconomyOS). It requires no new signer infrastructure (the wallet is already a Privy wallet Virtuals can manage), gives every dev's existing Mode-A agent the EconomyOS envelope, and instantly makes "use Virtuals wallet infrastructure" true for the whole developer base — which is precisely the goal that motivated Open Agent Wallet.