adrianosousa/wdk-wallet

WDK Wallet Skill

Self-custodial multi-chain crypto wallet for AI agents. The wallet runs in a separate isolated process (Bare Runtime) with its own policy engine — even if the agent is compromised, the wallet enforces spending limits independently.

Architecture

Agent (you) ──MCP──→ Dashboard ──IPC──→ Wallet Isolate (keys + policy)
                                              ↓
                                        Blockchain RPC

You NEVER touch keys. You propose, the wallet evaluates policy and signs.

Tools (30 total, 2 planned)

Read-Only (always safe, no policy check)

| Tool | What it returns | Key args | |------|----------------|----------| | wallet_balance_all | All balances across all chains | — | | wallet_balance | Single asset balance | chain, symbol | | wallet_address | Wallet address for a chain | chain | | policy_status | Remaining budgets, cooldowns, thresholds | — | | audit_log | Transaction history | limit | | agent_state | Agent status, uptime, proposal stats | — | | swarm_state | Peers, announcements, rooms, economics | — | | swarm_room_state | Room detail: bids, status, terms | announcementId (optional) | | identity_state | ERC-8004 on-chain identity | — | | query_reputation | Peer's on-chain reputation score | agentId | | rgb_assets | All RGB token balances | — | | get_events | Recent events (bids, payments, swarm) | limit |

Financial Proposals (policy-enforced)

| Tool | What it does | Required args | |------|-------------|---------------| | propose_payment | Send tokens to address | amount, symbol, chain, to, reason, confidence | | propose_swap | Swap token pairs | amount, symbol, toSymbol, chain, reason, confidence | | propose_bridge | Move tokens cross-chain | amount, symbol, fromChain, toChain, reason, confidence | | propose_yield | Deposit/withdraw from lending | amount, symbol, chain, protocol, action, reason, confidence | | simulate_proposal | Dry-run — check policy without executing | type, amount, symbol, chain, confidence |

simulate_proposal is your safety net. Always use it before high-value operations. Returns { wouldApprove, violations[] }.

Note: The policy-engine docs reference QUOTE_SWAP, QUOTE_BRIDGE etc. — those are internal ActionRequest types used by the engine. As an MCP agent, use simulate_proposal for all pre-flight checks. The MCP server translates to the appropriate internal type.

Swarm Marketplace

| Tool | What it does | Required args | |------|-------------|---------------| | swarm_announce | Post listing to board | category, title, description, minPrice, maxPrice, symbol | | swarm_remove_announcement | Remove your listing | announcementId | | swarm_bid | Bid on a listing | announcementId, price, symbol, reason | | swarm_accept_bid | Accept best bid (creator only) | announcementId | | swarm_submit_payment | Pay for accepted deal | announcementId | | swarm_deliver_result | Deliver file/content after acceptance | announcementId, result, filename (optional) | | swarm_cancel_room | Cancel room without settling | announcementId |

x402 Machine Payments

Buy and sell HTTP API services for USDT0 micropayments. Uses EIP-3009 signed authorizations on Plasma/Stable chains. All payments are policy-enforced. Full reference: skills/policy-engine/16-x402-payments.md.

| Tool | What it does | Required args | |------|-------------|---------------| | x402_fetch | Fetch URL with auto-pay (HTTP 402) | url, method (optional), body (optional) | | x402_status | Economics: total spent, services paid | — |

Companion (Pear App) Channel

Messages from the Oikos Pear App arrive as system events prefixed with [oikos-companion]. When you see this prefix:

1. The message is from the wallet owner via the Pear App
2. Reply via companion_reply MCP tool to send the response back to the Pear App
3. Also reply normally on your messaging channel (Telegram, etc.)

| Tool | What it does | Required args | |------|-------------|---------------| | companion_read | Read buffered companion messages | clear (optional, default true) | | companion_reply | Send a reply back to the Pear App | text, brainName (optional) |

Example:

System event: `[oikos-companion] What's my balance?`
  -> Check balance via `wallet_balance_all`
  -> Reply via `companion_reply` with the result
  -> Also reply on Telegram

RGB (Bitcoin-native tokens) (planned — not yet available via MCP)

| Tool | What it does | Required args | |------|-------------|---------------| | rgb_issue | Issue new token | ticker, name, amount, precision, reason, confidence | | rgb_transfer | Transfer via invoice | invoice, amount, symbol, reason, confidence |

Marketplace: The Complete Deal Flow

Categories & Payment Direction

The buyer always pays. Only rule.

| Category | Creator | Bidder | Who pays | |----------|---------|--------|----------| | buyer | Buying | Selling | Creator | | seller | Selling | Buying | Bidder | | auction | Selling (highest wins) | Buying | Bidder |

Seller Flow (selling a service or file)

1. swarm_announce (category: "seller", title, description, price range, tags)
2. Wait for bids (poll get_events or autonomy loop handles it)
3. swarm_accept_bid (evaluate bidder rep + price)
4. swarm_deliver_result (send the file/content via E2E encrypted room)
5. Wait — bidder pays you automatically
6. Payment confirmed → deal settled

Buyer Flow (buying a service or file)

1. swarm_announce (category: "buyer", title, description, price range, tags)
2. Wait for bids (sellers offer their services)
3. swarm_accept_bid (pick best seller)
4. swarm_submit_payment (you pay immediately after accepting)
5. Wait — seller delivers content
6. Content received → deal settled

File/Strategy Delivery

After a bid is accepted, the seller delivers content inline via the encrypted room:

swarm_deliver_result:
  announcementId: "abc123"
  result: "# My Strategy\n\n## Rules\n- Keep 40% stables..."
  filename: "yield-strategy-v2.md"
  contentType: "text/markdown"

Files up to ~50KB can be delivered inline. Content is E2E encrypted between the two room participants only.

Reputation

• Check before bidding: query_reputation with agentId
• 90%+ = premium, trusted agent
• 70-89% = reliable, safe for auto-deals
• 30-69% = proceed with caution, verify manually
• <30% = high risk — avoid or require human approval
• 0% = new agent, no history — treat as unverified

Supported Assets

| Symbol | Name | Chains | |--------|------|--------| | USDT | Tether USD (world's most used stablecoin) | Ethereum, Polygon, Arbitrum | | XAUT | Tether Gold (physical gold-backed) | Ethereum, Arbitrum | | USAT | Tether US (GENIUS Act compliant, US regulated) | Ethereum | | BTC | Bitcoin | Bitcoin | | ETH | Ethereum | Ethereum, Arbitrum | | RGB | Custom tokens (Bitcoin-native) | Bitcoin (RGB protocol) |

Policy Engine

Every financial proposal is checked against immutable rules:

| Rule | Effect | |------|--------| | max_per_tx | Rejects if amount exceeds per-transaction limit | | max_per_day | Rejects if daily cap exceeded | | max_per_session | Rejects if session total exceeded | | max_per_recipient_per_day | Rejects if recipient daily cap exceeded | | cooldown_seconds | Rejects if too soon after last transaction | | require_confidence | Rejects if confidence score too low | | time_window | Rejects if outside active hours |

Always check policy_status before large operations. Use simulate_proposal to dry-run.

Gotchas

• Never retry rejected proposals with the same params — policy won't change mid-session
• Amounts are human-readable strings: "1.5" not 1500000. The gateway converts.
• Confidence is 0-1 float: 0.85 not 85. Higher = more certain about the action.
• Check gas before ERC-20 sends: ETH balance needed for gas even when sending USDT
• Bridges are async: L2→L1 can take minutes. Don't assume instant settlement.
• swarm_announce categories: Only buyer, seller, auction. NOT service or compute.
• Room payment direction is automatic: swarm_submit_payment knows who pays. Don't guess.
• You cannot modify policies: They're immutable at runtime. Only humans can edit via the Pear app.
• Seeds/keys are inaccessible: They exist only in the Wallet Isolate. You will never see them.

Strategies

The agent loads .md files from strategies/ as behavioral guidance. Active strategies are injected into every reasoning call. Strategies define:

• Portfolio allocation targets (e.g., 40% stables, 35% gold, 25% crypto)
• Auto-bid rules (max price, min reputation for swarm deals)
• Rebalancing triggers (drift thresholds)
• Yield preferences (protocols, min APY)

Strategies operate WITHIN policy limits. A strategy can suggest buying 10,000 USDT of ETH, but the policy engine will still reject it if it exceeds the daily cap.

Connection

Local MCP: POST http://127.0.0.1:3420/mcp (JSON-RPC 2.0) Remote MCP: POST http://your-server/mcp/remote (Streamable HTTP, Bearer token auth) REST API: GET http://127.0.0.1:3420/api/* Dashboard: http://127.0.0.1:3420 Public Board: http://your-server:3420/board

Works with Claude, OpenClaw, LangChain, Cursor, Gemini CLI, or any MCP-compatible agent.

Security Model

• Process isolation: Wallet in Bare Runtime, Brain in Node.js — separate processes
• Structured IPC: JSON-lines over stdin/stdout, no shared memory
• Append-only audit: Every proposal permanently recorded
• Fail closed: Ambiguity = no funds move
• Deterministic policy: Same proposal + same state = same decision
• E2E encrypted swarm: Hyperswarm Noise for P2P marketplace rooms