@darksol/terminal 0.6.0 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darksol/terminal",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "DARKSOL Terminal — unified CLI for all DARKSOL services. Market intel, trading, oracle, casino, and more.",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -1,177 +1,356 @@
 ---
 name: darksol-terminal
-description: "DARKSOL Terminal — unified CLI for trading, wallets, execution scripts, AI-powered market analysis, secure agent signing, and all DARKSOL services. Use when: (1) swapping/sniping tokens on Base/Ethereum/L2s, (2) managing encrypted wallets, (3) running automated trading scripts, (4) DCA strategies, (5) market intel lookups, (6) on-chain oracle/casino/cards, (7) natural language trading via LLM, (8) signing transactions securely for x402/contracts without exposing private keys."
+description: "DARKSOL Terminal — unified CLI + x402 platform for trading, wallets, AI-powered market analysis, on-chain casino (4 games), random oracle (x402 auto-pay), prepaid crypto cards, secure agent signing, execution scripts, and all DARKSOL services. Use when: (1) swapping/sniping tokens on Base/Ethereum/L2s, (2) managing encrypted wallets, (3) running automated trading scripts, (4) DCA strategies, (5) market intel lookups, (6) playing on-chain casino games (coinflip, dice, hilo, slots), (7) using the random oracle (x402-gated, auto-pays via agent signer), (8) ordering prepaid Visa/Mastercard cards with crypto, (9) natural language trading via LLM, (10) signing transactions securely for x402/contracts without exposing private keys."
 ---
 
-# DARKSOL Terminal
+# DARKSOL Terminal — OpenClaw Agent Skill
 
 **All DARKSOL services. One terminal. Zero trust required. 🌑**
 
-## Install
+`@darksol/terminal` v0.6.x | npm: `npm install -g @darksol/terminal`
 
+---
+
+## For OpenClaw Agents — How To Use This
+
+You're an AI agent. This skill gives you a full crypto terminal. Here's what matters:
+
+### Setup (one-time)
 ```bash
 npm install -g @darksol/terminal
+darksol setup                          # Interactive first-run wizard
+darksol config set output json         # JSON output for programmatic parsing
 ```
 
-## Quick Reference
+### Agent Signer (REQUIRED for trading + x402)
+The agent signer is your secure wallet interface. It runs as a local HTTP server and signs transactions without ever exposing the private key.
 
-### Wallet Management
 ```bash
-darksol wallet create <name>           # Create new wallet (AES-256-GCM encrypted)
+# Start the signer with a wallet
+darksol signer start <wallet-name>
+darksol signer start <wallet-name> --max-value 0.5 --daily-limit 2.0
+
+# Or set env vars for non-interactive use
+export DARKSOL_WALLET_PASSWORD=<password>
+export DARKSOL_SIGNER_TOKEN=<token>     # Set after first start, reuse for API calls
+```
+
+**Signer API (127.0.0.1:18790):**
+| Endpoint | Method | What |
+|---|---|---|
+| `/health` | GET | Check signer status |
+| `/address` | GET | Get wallet address |
+| `/balance` | GET | ETH balance |
+| `/send` | POST | Sign + broadcast transaction |
+| `/sign-message` | POST | Sign EIP-191 message |
+| `/sign-typed-data` | POST | Sign EIP-712 typed data (x402) |
+| `/policy` | GET | Spending limits + daily remaining |
+| `/audit` | GET | Last 50 operations log |
+
+**Security:** PK never leaves the signer process. Bearer token auth. Blocked selectors (transferOwnership, selfdestruct). Spending limits enforced. Full audit log.
+
+---
+
+## Complete Command Reference
+
+### 💰 Wallet Management
+```bash
+darksol wallet create <name>           # Create new wallet (AES-256-GCM + scrypt)
 darksol wallet import <name>           # Import from private key
 darksol wallet list                    # List all wallets
-darksol wallet balance [name]          # Check ETH + USDC balance
+darksol wallet balance [name]          # ETH + USDC balance
 darksol wallet use <name>              # Set active wallet
-darksol wallet export [name]           # Export details (password required for PK)
+darksol wallet export [name]           # Export (password required for PK)
 ```
 
-### Trading
+### 📊 Trading (5 chains)
 ```bash
-darksol trade swap -i ETH -o USDC -a 0.1      # Swap via Uniswap V3
+darksol trade swap -i ETH -o USDC -a 0.1      # Uniswap V3 swap with slippage protection
+darksol trade swap -i USDC -o ETH -a 100 -c polygon  # Swap on Polygon
 darksol trade snipe <token> -a 0.05            # Fast buy with gas boost
 darksol trade snipe <token> -a 0.05 -g 2.0     # Snipe with 2x gas priority
-darksol trade watch                             # Monitor new pairs
+darksol trade watch                             # Monitor new pairs (experimental)
+darksol send                                   # Interactive ETH/ERC-20 transfer
+darksol receive                                # Show your address for receiving
 ```
 
-### DCA (Dollar-Cost Averaging)
+**Supported chains:** Base (default), Ethereum, Polygon, Arbitrum, Optimism
+**Swap routers:** Base uses SwapRouter02 (V2), others use V1 SwapRouter. Handled automatically.
+
+### 📈 DCA (Dollar-Cost Averaging)
 ```bash
-darksol dca create                     # Interactive DCA order creation
-darksol dca list                       # List active DCA orders
+darksol dca create                     # Interactive DCA setup
+darksol dca list                       # Active orders
 darksol dca run                        # Execute pending orders
-darksol dca cancel <id>                # Cancel an order
+darksol dca cancel <id>                # Cancel
 ```
 
-### AI Trading Assistant
+### 🤖 AI Trading Assistant
 ```bash
-darksol ai chat                        # Interactive AI trading chat
-darksol ai ask "buy 0.5 ETH of AERO"  # Parse natural language trade intent
+darksol ai chat                        # Interactive AI chat (supports swap/send/price/casino/cards)
+darksol ai ask "buy 0.5 ETH of AERO"  # Parse natural language → trade intent
+darksol ai ask "flip a coin" -x        # Auto-execute if confidence ≥ 60%
 darksol ai strategy VIRTUAL -b 500     # DCA strategy recommendation
-darksol ai analyze AERO                # AI-powered token analysis
+darksol ai analyze AERO                # Token analysis
 ```
 
-### Execution Scripts
+**AI Intent Actions:** swap, send, snipe, dca, price, balance, info, analyze, gas, cards, casino, unknown
+
+The AI understands natural language and maps it to executable commands:
+- "swap 100 USDC to ETH" → `darksol trade swap -i USDC -o ETH -a 100`
+- "bet on heads" → `darksol casino bet coinflip -c heads`
+- "order a $50 prepaid card" → `darksol cards order -a 50`
+- "what's the price of AERO" → `darksol market token AERO`
+
+### 📝 Execution Scripts
 ```bash
-darksol script templates               # List available templates
-darksol script create                  # Create from template (buy, sell, limit-buy, stop-loss, etc.)
-darksol script list                    # List saved scripts
-darksol script run <name>              # Execute (requires wallet password)
-darksol script run <name> -p "pw" -y   # Non-interactive (for automation/cron)
+darksol script templates               # 7 templates: buy, sell, limit-buy, stop-loss, multi-buy, transfer, empty
+darksol script create                  # Interactive template builder
+darksol script list                    # Saved scripts
+darksol script run <name>              # Execute (password required)
+darksol script run <name> -p "pw" -y   # Non-interactive (for cron/automation)
 darksol script show <name>             # View code + params
-darksol script edit <name>             # Edit params/wallet/chain
-darksol script clone <name> <new>      # Clone a script
-darksol script delete <name>           # Delete a script
+darksol script edit <name>             # Edit
+darksol script clone <name> <new>      # Clone
+darksol script delete <name>           # Delete
 ```
 
-Script templates: `buy-token`, `sell-token`, `limit-buy`, `stop-loss`, `multi-buy`, `transfer`, `empty` (custom)
-
-### Market Intel
+### 📈 Market Intel
 ```bash
-darksol market top                     # Top movers on Base
-darksol market top -c ethereum         # Top movers on Ethereum
-darksol market token VIRTUAL           # Full token detail
+darksol market top                     # Top movers on active chain
+darksol market top -c ethereum         # Top movers on specific chain
+darksol market token VIRTUAL           # Full token detail (price, volume, liquidity, chain, DEX)
 darksol market compare ETH AERO VIRTUAL # Side-by-side comparison
+darksol price ETH AERO USDC           # Quick multi-token price check
+darksol watch ETH                      # Live streaming price updates
 ```
 
-### Secure Agent Signer (for OpenClaw / AI agents)
+### 🎰 Casino (The Clawsino)
+All bets are $1 USDC. House edge: 5%. Results verified on-chain.
+
 ```bash
-darksol agent start <wallet>           # Start signing proxy
-darksol agent start <wallet> --max-value 0.5 --daily-limit 2.0
-darksol agent docs                     # Full security documentation
+darksol casino status                  # House stats, balance, game list
+darksol casino bet                     # Interactive (picks game → params → wallet → confirm)
+darksol casino bet coinflip -c heads   # Coin flip — 1.90x payout
+darksol casino bet dice -d over -t 3   # Dice over 3 — variable payout
+darksol casino bet hilo -c higher      # Hi-Lo — ~2.06x payout
+darksol casino bet slots               # Slots — 1.50-5.00x payout
+darksol casino tables                  # Recent bets
+darksol casino receipt <id>            # Bet receipt
+darksol casino verify <id>             # On-chain verification (Basescan links)
+```
+
+**API:** `POST https://casino.darksol.net/api/bet`
+```json
+{
+  "gameType": "coinflip",
+  "betParams": { "choice": "heads" },
+  "agentWallet": "0x..."
+}
 ```
 
-The agent signer creates a local HTTP server at `127.0.0.1:18790` that signs transactions without exposing the private key. AI agents authenticate with a one-time bearer token.
+**Games:**
+| Game | Params | Payout |
+|---|---|---|
+| `coinflip` | `{ "choice": "heads"\|"tails" }` | 1.90x |
+| `dice` | `{ "direction": "over"\|"under", "threshold": 2-5 }` | variable |
+| `hilo` | `{ "choice": "higher"\|"lower" }` | ~2.06x |
+| `slots` | `{}` | 1.50-5.00x |
 
-**Endpoints:**
-- `GET /address` — wallet address
-- `GET /balance` — ETH balance
-- `POST /send` — sign + broadcast transaction
-- `POST /sign-message` — sign EIP-191 message (x402)
-- `POST /sign-typed-data` — sign EIP-712 typed data (x402)
-- `GET /policy` — spending limits
-- `GET /audit` — operation log
+### 🎲 Random Oracle (x402-gated)
+On-chain verifiable randomness. Each call costs $0.05 USDC on Base via x402 protocol.
 
-### Oracle
 ```bash
+darksol oracle health                  # Status (free)
 darksol oracle flip                    # Coin flip
 darksol oracle dice 20                 # Roll d20
 darksol oracle number 1 100            # Random 1-100
 darksol oracle shuffle a b c d         # Shuffle list
 ```
 
-### Casino
+**x402 Auto-Pay:** If the agent signer is running, oracle requests auto-pay via EIP-3009 (transferWithAuthorization). No manual payment needed.
+
+**API:** `https://acp.darksol.net/api/oracle/`
+- `GET /health` — free, returns status + contract address
+- `GET /coin` — 402 → x402 payment → result
+- `GET /dice?sides=N` — 402 → x402 payment → result
+- `GET /number?min=N&max=M` — 402 → x402 payment → result
+- `POST /shuffle` — 402 → x402 payment → result
+
+### 💳 Prepaid Cards (Crypto → Visa/Mastercard)
 ```bash
-darksol casino bet coin-flip heads     # Place a bet
-darksol casino tables                  # View games
-darksol casino stats                   # House stats
-darksol casino receipt <id>            # Verify on-chain
+darksol cards catalog                  # Available providers + amounts
+darksol cards order                    # Interactive (prompts for everything)
+darksol cards order -p swype -a 50 -e me@email.com -t usdc    # Full flags
+darksol cards status <tradeId>         # Check order status
 ```
 
-### Prepaid Cards
+**Providers:** swype (Mastercard, Global), mpc (Mastercard, US), reward (Visa, US)
+**Amounts:** $10, $25, $50, $100, $250, $500, $1000
+**Crypto payments:** usdc/base, usdc/ERC20, usdt/trc20, btc/Mainnet, eth/ERC20, sol/Mainnet, xmr/Mainnet
+
+Invalid inputs re-prompt instead of failing — fully guided flow.
+
+### 🔗 x402 Facilitator
+Free on-chain payment settlement. Zero fees — DARKSOL covers gas.
+
 ```bash
-darksol cards catalog                  # Available providers
-darksol cards order -p swype -a 50     # Order a card
-darksol cards status <id>              # Check order
+darksol facilitator health             # Status, chains, contracts, settlement stats
+darksol facilitator verify <payment>   # Verify payment off-chain
+darksol facilitator settle <payment>   # Settle on-chain (free)
 ```
 
-### Builder Index
+**Chains:** Base + Polygon
+**API:** `https://facilitator.darksol.net/`
+- `GET /` — service info + chain status
+- `POST /verify` — verify payment
+- `POST /settle` — settle on-chain
+
+### 🏗️ Builder Index
 ```bash
 darksol builders leaderboard           # ERC-8021 builder rankings
 darksol builders lookup <code>         # Builder profile
 darksol builders feed                  # Recent transactions
 ```
 
-### Facilitator
+### 📧 AgentMail
 ```bash
-darksol facilitator health             # Status
-darksol facilitator verify <payment>   # Verify off-chain
-darksol facilitator settle <payment>   # Settle on-chain (free)
+darksol mail setup                     # Set up email inbox
+darksol mail inbox                     # View messages
+darksol mail send <to> -s "Subject"    # Send email
+darksol mail read <id>                 # Read message
+darksol mail reply <id>                # Reply
 ```
 
-### API Keys
+### ⛽ Gas & Network
 ```bash
-darksol keys list                      # Show all services + status
-darksol keys add openai                # Add OpenAI key
-darksol keys add coingecko             # Add CoinGecko Pro key
-darksol keys add alchemy               # Add Alchemy RPC key
-darksol keys remove <service>          # Remove a key
+darksol gas                            # Gas prices on active chain
+darksol gas --all                      # Gas across all 5 chains
+darksol networks                       # Chain reference table
 ```
 
-Supported: `openai`, `anthropic`, `openrouter`, `ollama`, `coingecko`, `dexscreener`, `alchemy`, `infura`, `quicknode`, `oneinch`, `paraswap`
-
-### Configuration
+### 🔧 Configuration
 ```bash
 darksol config show                    # View all settings
 darksol config set chain base          # Set active chain
-darksol config set slippage 1.0        # Set slippage %
-darksol config rpc base https://...    # Custom RPC endpoint
+darksol config set slippage 1.0        # Slippage %
+darksol config rpc base https://...    # Custom RPC
 ```
 
-### Reference
+### 🔑 API Keys (Encrypted Vault)
+```bash
+darksol keys list                      # All services + status
+darksol keys add openai                # Add key (encrypted AES-256-GCM)
+darksol keys add anthropic             # Supported: openai, anthropic, openrouter, ollama,
+darksol keys add email                 #   coingecko, dexscreener, alchemy, infura, email
+darksol keys remove <service>          # Remove key
+```
+
+### 🌐 Web Shell (GUI)
+```bash
+darksol serve                          # Launch web terminal at localhost:18791
+darksol serve -p 3000                  # Custom port
+```
+
+Web shell includes: full CLI, AI chat, interactive menus, casino, cards ordering, wallet management, agent signer controls.
+
+### 📚 Reference
 ```bash
 darksol tips                           # Trading + scripting tips
-darksol tips --trading                 # Trading tips only
-darksol networks                       # Chain reference table
 darksol quickstart                     # Getting started guide
-darksol lookup 0x...                   # Look up address on-chain
+darksol lookup 0x...                   # On-chain address lookup
+darksol setup                          # Re-run setup wizard
 ```
 
-## Supported Chains
-- **Base** (default) — chain ID 8453
-- **Ethereum** — chain ID 1
-- **Polygon** — chain ID 137
-- **Arbitrum** — chain ID 42161
-- **Optimism** — chain ID 10
+---
+
+## x402 Payment Flow (for agents)
+
+The terminal includes a built-in x402 client (`src/utils/x402.js`). When a service returns HTTP 402:
+
+1. Parse `payment-required` header (base64 JSON)
+2. Sign EIP-3009 `transferWithAuthorization` via agent signer
+3. Retry request with `X-PAYMENT` header containing the signed authorization
+4. Facilitator settles on-chain (free, DARKSOL covers gas)
+
+**For agents:** Just start the signer and make requests. x402 auto-pay handles the rest.
+
+```javascript
+import { fetchWithX402 } from '@darksol/terminal/src/utils/x402.js';
+
+const result = await fetchWithX402(
+  'https://acp.darksol.net/api/oracle/coin',
+  {},
+  { signerToken: process.env.DARKSOL_SIGNER_TOKEN }
+);
+// result.data = { result: "heads", proof: "0x..." }
+// result.paid = true
+```
+
+---
+
+## Agent Integration Patterns
+
+### Non-interactive mode (for cron / automation)
+```bash
+# All trading commands accept flags for non-interactive use
+darksol trade swap -i ETH -o USDC -a 0.1 -y
+darksol script run my-dca -p "password" -y
+darksol casino bet coinflip -c heads -w 0x1234...
+
+# Set JSON output for parsing
+darksol config set output json
+```
+
+### Environment variables
+```bash
+DARKSOL_WALLET_PASSWORD    # Skip password prompts
+DARKSOL_SIGNER_TOKEN       # Reuse signer auth token
+```
+
+### Programmatic imports
+```javascript
+// Direct service access from Node.js
+import { casinoBet, casinoHealth, GAMES } from '@darksol/terminal/src/services/casino.js';
+import { oracleFlip, oracleDice } from '@darksol/terminal/src/services/oracle.js';
+import { cardsCatalog, cardsOrder } from '@darksol/terminal/src/services/cards.js';
+import { facilitatorHealth } from '@darksol/terminal/src/services/facilitator.js';
+import { fetchWithX402 } from '@darksol/terminal/src/utils/x402.js';
+import { parseIntent, executeIntent } from '@darksol/terminal/src/llm/intent.js';
+import { topMovers, tokenDetail } from '@darksol/terminal/src/services/market.js';
+```
+
+### OpenClaw cron example
+```bash
+# Run a DCA script every 4 hours
+darksol script run eth-dca -p "$DARKSOL_WALLET_PASSWORD" -y
+```
+
+---
+
+## Service Endpoints
+
+| Service | URL | Auth |
+|---|---|---|
+| Casino | `https://casino.darksol.net/api/` | None (wallet for payouts) |
+| Oracle | `https://acp.darksol.net/api/oracle/` | x402 ($0.05 USDC) |
+| Cards | `https://acp.darksol.net/api/cards/` | None |
+| Facilitator | `https://facilitator.darksol.net/` | None |
+| Builders | `https://builders.darksol.net/` | None |
+| Casino Docs | `https://casino.darksol.net/docs` | — |
+| Oracle Docs | `https://acp.darksol.net/oracle` | — |
+| Facilitator Docs | `https://acp.darksol.net/facilitator` | — |
+
+---
 
-## Agent Integration Notes
+## Security Model
 
-- All commands work non-interactively with flags (`-p`, `-y`, `--key`, etc.)
-- Set `darksol config set output json` for programmatic JSON responses
-- Scripts can be executed via cron: `darksol script run my-dca -p "pass" -y`
-- The agent signer is the recommended way to give AI agents wallet access
-- Helper functions available at `@darksol/terminal/src/utils/helpers.js`
+- **Private keys:** AES-256-GCM + scrypt (N=2^18), never stored in plaintext
+- **Agent signer:** PK-isolated HTTP proxy, bearer auth, loopback only (127.0.0.1)
+- **Spending limits:** Per-tx max value + daily spend limit
+- **Blocked selectors:** transferOwnership, selfdestruct, approve(max), setApprovalForAll
+- **Audit log:** Every sign/send operation logged with timestamp + details
+- **API key vault:** AES-256-GCM encrypted, machine-derived password
+- **No PK endpoint:** Literally no code path returns the private key
 
-## Security
-- Private keys encrypted with AES-256-GCM + scrypt KDF
-- Agent signer: PK never exposed, loopback-only, bearer auth, spending limits
-- Dangerous contract calls (transferOwnership, selfdestruct) blocked by default
-- Full audit logging on all signing operations
+Built with teeth. 🌑

package/src/config/store.js

@@ -29,7 +29,7 @@ const config = new Conf({
     services: {
       type: 'object',
       default: {
-        oracle: 'https://acp.darksol.net/oracle',
+        oracle: 'https://acp.darksol.net/api/oracle',
         casino: 'https://casino.darksol.net',
         cards: 'https://acp.darksol.net',
         facilitator: 'https://facilitator.darksol.net',

package/src/services/oracle.js

@@ -1,88 +1,126 @@
 import { fetchJSON } from '../utils/fetch.js';
-import fetch from 'node-fetch';
-import { getServiceURL } from '../config/store.js';
+import { fetchWithX402, isSignerRunning } from '../utils/x402.js';
+import { getServiceURL, getConfig } from '../config/store.js';
 import { theme } from '../ui/theme.js';
-import { spinner, kvDisplay, success, error } from '../ui/components.js';
+import { spinner, kvDisplay, success, error, warn, info } from '../ui/components.js';
 import { showSection } from '../ui/banner.js';
 
-const getURL = () => getServiceURL('oracle') || 'https://acp.darksol.net/oracle';
+// Oracle lives at acp.darksol.net/api/oracle/
+// Health is free; game endpoints are x402-gated ($0.05 USDC on Base)
+const getURL = () => getServiceURL('oracle') || 'https://acp.darksol.net/api/oracle';
 
-export async function oracleFlip() {
-  const spin = spinner('Flipping coin...').start();
+function getSignerToken() {
+  return process.env.DARKSOL_SIGNER_TOKEN || getConfig('signerToken') || null;
+}
+
+export async function oracleHealth() {
+  const spin = spinner('Checking oracle...').start();
   try {
-    const data = await fetchJSON(`${getURL()}/api/coin`);
-    spin.succeed('Coin flipped');
-    showSection('ORACLE — COIN FLIP');
+    const data = await fetchJSON(`${getURL()}/health`);
+    spin.succeed('Oracle online');
+
+    showSection('RANDOM ORACLE 🎲');
     kvDisplay([
-      ['Result', theme.gold.bold(data.result || data.value)],
-      ['Proof', data.proof || data.txHash || 'N/A'],
+      ['Status', data.status === 'ok' ? theme.success('● Online') : theme.error('○ ' + data.status)],
+      ['Contract', data.contract || '-'],
+      ['Chain', data.chain || 'base'],
+      ['Block', String(data.blockNumber || '-')],
     ]);
+
+    // Check signer status
+    const signerUp = await isSignerRunning(getSignerToken());
+    console.log('');
+    if (signerUp) {
+      console.log(`  ${theme.success('●')} Agent signer running — x402 auto-pay enabled`);
+    } else {
+      console.log(`  ${theme.dim('○')} Agent signer not running — start for auto-pay: ${theme.gold('darksol signer start')}`);
+    }
+
+    console.log('');
+    info('Games: coin flip, dice, random number, shuffle ($0.05 USDC each)');
+    info('Docs: https://acp.darksol.net/oracle');
   } catch (err) {
-    spin.fail('Oracle failed');
+    spin.fail('Oracle unreachable');
     error(err.message);
   }
 }
 
-export async function oracleDice(sides = 6) {
-  const spin = spinner(`Rolling d${sides}...`).start();
+async function oraclePlay(endpoint, label, displayFn) {
+  const spin = spinner(`${label}...`).start();
+  const token = getSignerToken();
+
   try {
-    const data = await fetchJSON(`${getURL()}/api/dice?sides=${sides}`);
-    spin.succeed('Dice rolled');
-    showSection(`ORACLE — D${sides}`);
-    kvDisplay([
-      ['Result', theme.gold.bold(data.result || data.value)],
-      ['Sides', sides.toString()],
-      ['Proof', data.proof || data.txHash || 'N/A'],
-    ]);
+    const result = await fetchWithX402(`${getURL()}${endpoint}`, {}, { signerToken: token });
+
+    if (result.x402 && !result.paid) {
+      // Payment required but couldn't auto-pay
+      spin.info('x402 payment required');
+      const accepts = result.paymentInfo?.accepts?.[0];
+      if (accepts) {
+        warn(`Cost: $${(parseInt(accepts.amount) / 1e6).toFixed(2)} USDC on Base`);
+      }
+      if (result.error) {
+        info(result.error);
+      } else {
+        info('Start agent signer for auto-pay: darksol signer start');
+      }
+      return null;
+    }
+
+    if (result.paid) {
+      spin.succeed(`${label} ✓ (paid $0.05 USDC)`);
+    } else {
+      spin.succeed(label);
+    }
+
+    displayFn(result.data);
+    return result.data;
   } catch (err) {
-    spin.fail('Oracle failed');
+    spin.fail(`${label} failed`);
     error(err.message);
+    return null;
   }
 }
 
+export async function oracleFlip() {
+  return oraclePlay('/coin', 'Coin flip', (data) => {
+    showSection('ORACLE — COIN FLIP 🪙');
+    kvDisplay([
+      ['Result', theme.gold.bold(data.result || data.value || '-')],
+      ['Proof', data.proof || data.txHash || '-'],
+    ]);
+  });
+}
+
+export async function oracleDice(sides = 6) {
+  return oraclePlay(`/dice?sides=${sides}`, `Rolling d${sides}`, (data) => {
+    showSection(`ORACLE — D${sides} 🎲`);
+    kvDisplay([
+      ['Result', theme.gold.bold(data.result || data.value || '-')],
+      ['Sides', sides.toString()],
+      ['Proof', data.proof || data.txHash || '-'],
+    ]);
+  });
+}
+
 export async function oracleNumber(min = 1, max = 100) {
-  const spin = spinner(`Generating number ${min}-${max}...`).start();
-  try {
-    const data = await fetchJSON(`${getURL()}/api/number?min=${min}&max=${max}`);
-    spin.succeed('Number generated');
-    showSection('ORACLE — RANDOM NUMBER');
+  return oraclePlay(`/number?min=${min}&max=${max}`, `Number ${min}-${max}`, (data) => {
+    showSection('ORACLE — RANDOM NUMBER 🔢');
     kvDisplay([
-      ['Result', theme.gold.bold(data.result || data.value)],
+      ['Result', theme.gold.bold(data.result || data.value || '-')],
       ['Range', `${min} — ${max}`],
-      ['Proof', data.proof || data.txHash || 'N/A'],
+      ['Proof', data.proof || data.txHash || '-'],
     ]);
-  } catch (err) {
-    spin.fail('Oracle failed');
-    error(err.message);
-  }
+  });
 }
 
 export async function oracleShuffle(items) {
-  const spin = spinner('Shuffling...').start();
-  try {
-    const data = await fetchJSON(`${getURL()}/api/shuffle`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ items }),
-    });
-    spin.succeed('Shuffled');
-    showSection('ORACLE — SHUFFLE');
-    console.log(theme.gold('  Result: ') + (data.result || data.value || []).join(', '));
-  } catch (err) {
-    spin.fail('Oracle failed');
-    error(err.message);
-  }
-}
-
-export async function oracleHealth() {
-  const spin = spinner('Checking oracle...').start();
-  try {
-    const data = await fetchJSON(`${getURL()}/api/health`);
-    spin.succeed('Oracle online');
-    showSection('ORACLE STATUS');
-    kvDisplay(Object.entries(data).map(([k, v]) => [k, String(v)]));
-  } catch (err) {
-    spin.fail('Oracle unreachable');
-    error(err.message);
-  }
+  return oraclePlay('/shuffle', 'Shuffling', (data) => {
+    showSection('ORACLE — SHUFFLE 🔀');
+    const result = data.result || data.value || [];
+    console.log(theme.gold('  Result: ') + (Array.isArray(result) ? result.join(', ') : result));
+    if (data.proof || data.txHash) {
+      console.log(theme.dim(`  Proof: ${data.proof || data.txHash}`));
+    }
+  });
 }

package/src/utils/x402.js

@@ -0,0 +1,232 @@
+import fetch from 'node-fetch';
+
+/**
+ * x402 Payment Flow
+ *
+ * When a server returns 402 with a `payment-required` header (base64-encoded JSON),
+ * this utility:
+ *   1. Decodes the payment requirement
+ *   2. Signs an EIP-3009 transferWithAuthorization via the local agent signer
+ *   3. Retries the original request with the signed payment in the `X-PAYMENT` header
+ *
+ * Requires: agent signer running at 127.0.0.1:18790
+ */
+
+const SIGNER_URL = 'http://127.0.0.1:18790';
+
+// USDC contract details for EIP-3009
+const USDC_CONTRACTS = {
+  8453:  '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // Base
+  137:   '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359', // Polygon
+  1:     '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // Ethereum
+  42161: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831', // Arbitrum
+  10:    '0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85', // Optimism
+};
+
+/**
+ * Parse the payment-required header (base64 JSON)
+ */
+function parsePaymentRequired(header) {
+  try {
+    return JSON.parse(Buffer.from(header, 'base64').toString());
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if agent signer is running
+ */
+async function isSignerRunning(token) {
+  try {
+    const headers = token ? { Authorization: `Bearer ${token}` } : {};
+    const resp = await fetch(`${SIGNER_URL}/health`, { headers, timeout: 2000 });
+    return resp.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get signer address
+ */
+async function getSignerAddress(token) {
+  try {
+    const headers = token ? { Authorization: `Bearer ${token}` } : {};
+    const resp = await fetch(`${SIGNER_URL}/address`, { headers, timeout: 2000 });
+    if (!resp.ok) return null;
+    const data = await resp.json();
+    return data.address;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Sign EIP-712 typed data for x402 payment (EIP-3009 transferWithAuthorization)
+ */
+async function signX402Payment(paymentReq, signerToken) {
+  const accepts = paymentReq.accepts?.[0];
+  if (!accepts) throw new Error('No payment scheme in x402 requirement');
+
+  // Parse network — format is "eip155:<chainId>"
+  const chainId = parseInt(accepts.network?.split(':')[1] || '8453');
+  const usdcAddress = accepts.asset || USDC_CONTRACTS[chainId];
+  const amount = accepts.amount; // in smallest unit (e.g., 50000 = $0.05 USDC)
+  const payTo = accepts.payTo;
+  const deadline = Math.floor(Date.now() / 1000) + (accepts.maxTimeoutSeconds || 300);
+
+  // Get our address
+  const fromAddress = await getSignerAddress(signerToken);
+  if (!fromAddress) throw new Error('Cannot get signer address');
+
+  // Generate random nonce (32 bytes)
+  const nonce = '0x' + [...Array(32)].map(() => Math.floor(Math.random() * 256).toString(16).padStart(2, '0')).join('');
+
+  // EIP-712 domain for USDC
+  const domain = {
+    name: accepts.extra?.name || 'USD Coin',
+    version: accepts.extra?.version || '2',
+    chainId: chainId,
+    verifyingContract: usdcAddress,
+  };
+
+  // EIP-3009 TransferWithAuthorization types
+  const types = {
+    TransferWithAuthorization: [
+      { name: 'from', type: 'address' },
+      { name: 'to', type: 'address' },
+      { name: 'value', type: 'uint256' },
+      { name: 'validAfter', type: 'uint256' },
+      { name: 'validBefore', type: 'uint256' },
+      { name: 'nonce', type: 'bytes32' },
+    ],
+  };
+
+  const value = {
+    from: fromAddress,
+    to: payTo,
+    value: amount,
+    validAfter: '0',
+    validBefore: String(deadline),
+    nonce: nonce,
+  };
+
+  // Sign via agent signer
+  const headers = { 'Content-Type': 'application/json' };
+  if (signerToken) headers.Authorization = `Bearer ${signerToken}`;
+
+  const resp = await fetch(`${SIGNER_URL}/sign-typed-data`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ domain, types, value }),
+  });
+
+  if (!resp.ok) {
+    const err = await resp.text();
+    throw new Error(`Signer refused: ${err}`);
+  }
+
+  const result = await resp.json();
+
+  // Build the x402 payment payload
+  return {
+    x402Version: paymentReq.x402Version || 2,
+    scheme: 'exact',
+    network: accepts.network || `eip155:${chainId}`,
+    payload: {
+      signature: result.signature,
+      authorization: {
+        from: fromAddress,
+        to: payTo,
+        value: amount,
+        validAfter: '0',
+        validBefore: String(deadline),
+        nonce: nonce,
+      },
+    },
+  };
+}
+
+/**
+ * Make an x402-aware fetch request.
+ *
+ * If the server returns 402, this will:
+ * 1. Parse the payment requirement
+ * 2. Sign the payment via agent signer
+ * 3. Retry with the X-PAYMENT header
+ *
+ * @param {string} url - Request URL
+ * @param {object} opts - fetch options
+ * @param {object} x402Opts - { signerToken, autoSign }
+ * @returns {object} { data, paid, paymentInfo }
+ */
+export async function fetchWithX402(url, opts = {}, x402Opts = {}) {
+  const { signerToken, autoSign = true } = x402Opts;
+
+  // First attempt
+  const resp = await fetch(url, opts);
+
+  if (resp.status !== 402) {
+    // Normal response
+    const ct = resp.headers.get('content-type') || '';
+    if (!ct.includes('json')) {
+      const text = await resp.text();
+      throw new Error(`Non-JSON response (${resp.status}): ${text.substring(0, 100)}`);
+    }
+    return { data: await resp.json(), paid: false };
+  }
+
+  // 402 — payment required
+  const paymentHeader = resp.headers.get('payment-required');
+  if (!paymentHeader) {
+    throw new Error('402 but no payment-required header');
+  }
+
+  const paymentReq = parsePaymentRequired(paymentHeader);
+  if (!paymentReq) {
+    throw new Error('Failed to parse payment-required header');
+  }
+
+  if (!autoSign) {
+    return { data: null, paid: false, x402: true, paymentInfo: paymentReq };
+  }
+
+  // Check if signer is running
+  const signerUp = await isSignerRunning(signerToken);
+  if (!signerUp) {
+    return {
+      data: null,
+      paid: false,
+      x402: true,
+      paymentInfo: paymentReq,
+      error: 'Agent signer not running. Start it: darksol signer start',
+    };
+  }
+
+  // Sign the payment
+  const payment = await signX402Payment(paymentReq, signerToken);
+
+  // Retry with payment
+  const retryOpts = { ...opts };
+  retryOpts.headers = {
+    ...(opts.headers || {}),
+    'X-PAYMENT': Buffer.from(JSON.stringify(payment)).toString('base64'),
+  };
+
+  const retryResp = await fetch(url, retryOpts);
+  const ct = retryResp.headers.get('content-type') || '';
+  if (!ct.includes('json')) {
+    const text = await retryResp.text();
+    throw new Error(`Paid but got non-JSON (${retryResp.status}): ${text.substring(0, 100)}`);
+  }
+
+  if (!retryResp.ok) {
+    const errData = await retryResp.json().catch(() => ({}));
+    throw new Error(`Payment sent but request failed (${retryResp.status}): ${JSON.stringify(errData)}`);
+  }
+
+  return { data: await retryResp.json(), paid: true, paymentInfo: paymentReq };
+}
+
+export { parsePaymentRequired, isSignerRunning, getSignerAddress, signX402Payment };

package/src/web/commands.js

@@ -1121,17 +1121,31 @@ async function executeCardOrder(orderMeta, ws) {
 // ORACLE
 // ══════════════════════════════════════════════════
 async function cmdOracle(args, ws) {
+  ws.sendLine(`${ANSI.gold}  ◆ RANDOM ORACLE 🎲${ANSI.reset}`);
+  ws.sendLine(`${ANSI.dim}  ${'─'.repeat(50)}${ANSI.reset}`);
   try {
-    const resp = await fetch('https://acp.darksol.net/oracle');
+    const resp = await fetch('https://acp.darksol.net/api/oracle/health');
+    const ct = resp.headers.get('content-type') || '';
+    if (!ct.includes('json')) throw new Error('not json');
     const data = await resp.json();
 
-    ws.sendLine(`${ANSI.gold}  ◆ ORACLE${ANSI.reset}`);
-    ws.sendLine(`${ANSI.dim}  ${'─'.repeat(50)}${ANSI.reset}`);
-    ws.sendLine(`  ${ANSI.darkGold}Status${ANSI.reset}     ${data.status || 'unknown'}`);
-    ws.sendLine(`  ${ANSI.darkGold}Endpoint${ANSI.reset}   ${ANSI.blue}acp.darksol.net/oracle${ANSI.reset}`);
+    ws.sendLine(`  ${ANSI.darkGold}Status${ANSI.reset}       ${data.status === 'ok' ? `${ANSI.green}● Online${ANSI.reset}` : `${ANSI.red}○ ${data.status}${ANSI.reset}`}`);
+    ws.sendLine(`  ${ANSI.darkGold}Contract${ANSI.reset}     ${ANSI.dim}${data.contract || '-'}${ANSI.reset}`);
+    ws.sendLine(`  ${ANSI.darkGold}Chain${ANSI.reset}        ${ANSI.white}${data.chain || 'base'}${ANSI.reset}`);
+    ws.sendLine(`  ${ANSI.darkGold}Block${ANSI.reset}        ${ANSI.white}${data.blockNumber || '-'}${ANSI.reset}`);
+    ws.sendLine('');
+    ws.sendLine(`  ${ANSI.gold}ENDPOINTS${ANSI.reset}  ${ANSI.dim}x402-gated ($0.05 USDC on Base)${ANSI.reset}`);
+    ws.sendLine(`  ${ANSI.white}🪙 /coin${ANSI.reset}      ${ANSI.dim}Fair coin flip${ANSI.reset}`);
+    ws.sendLine(`  ${ANSI.white}🎲 /dice${ANSI.reset}      ${ANSI.dim}Roll with N sides${ANSI.reset}`);
+    ws.sendLine(`  ${ANSI.white}🔢 /number${ANSI.reset}    ${ANSI.dim}Random in range${ANSI.reset}`);
+    ws.sendLine(`  ${ANSI.white}🔀 /shuffle${ANSI.reset}   ${ANSI.dim}Shuffle a list${ANSI.reset}`);
+    ws.sendLine('');
+    ws.sendLine(`  ${ANSI.dim}CLI: darksol oracle flip / dice / number / shuffle${ANSI.reset}`);
+    ws.sendLine(`  ${ANSI.dim}Docs: https://acp.darksol.net/oracle${ANSI.reset}`);
     ws.sendLine('');
   } catch {
-    ws.sendLine(`  ${ANSI.dim}Oracle unreachable${ANSI.reset}`);
+    ws.sendLine(`  ${ANSI.red}○ Oracle unreachable${ANSI.reset}`);
+    ws.sendLine(`  ${ANSI.dim}Check: https://acp.darksol.net/oracle${ANSI.reset}`);
     ws.sendLine('');
   }
   return {};