@heyamiko/amiko-cli 0.9.0-beta.1 → 0.9.0-beta.5

package/README.md

@@ -41,8 +41,8 @@ amiko market search "AI agents" --wallet <solana-address>
 amiko market image "a sunset over mountains" --wallet <solana-address>
 
 # Swap tokens on Solana
-amiko swap quote 1.0 SOL USDC
-amiko swap send 1.0 SOL USDC --yes
+amiko wallets swap quote 1.0 SOL USDC
+amiko wallets swap send 1.0 SOL USDC --yes
 
 # Call any MPP service
 amiko market service list
@@ -125,17 +125,17 @@ amiko market amazon quote B01GGKYKQM            # price quote (free)
 ## Swap
 
 ```bash
-amiko swap quote <amount> <from> <to>    # get Jupiter quote
-amiko swap send <amount> <from> <to>     # execute swap via Crossmint
-amiko swap tokens                        # list supported tokens
+amiko wallets swap quote <amount> <from> <to>    # get Jupiter quote
+amiko wallets swap send <amount> <from> <to>     # execute swap via Crossmint
+amiko wallets swap tokens                        # list supported tokens
 ```
 
 **Examples:**
 
 ```bash
-amiko swap quote 1.0 SOL USDC
-amiko swap send 0.5 USDC AMIKO --yes
-amiko swap send 100 AMIKO SOL --slippage 100
+amiko wallets swap quote 1.0 SOL USDC
+amiko wallets swap send 0.5 USDC AMIKO --yes
+amiko wallets swap send 100 AMIKO SOL --slippage 100
 ```
 
 Swaps execute via Jupiter on Solana. Supports SOL, USDC, USDT, AMIKO, PYUSD, BONK, JUP, RAY, JitoSOL, mSOL, or any mint address. `swap send` is hard-gated: in a non-interactive shell you must pass `--yes` after quoting the cost to the user (`Solana gas + 10bps platform fee`).
@@ -143,12 +143,12 @@ Swaps execute via Jupiter on Solana. Supports SOL, USDC, USDT, AMIKO, PYUSD, BON
 ## Bridge
 
 ```bash
-amiko bridge quote <amount>              # cross-chain USDC quote via Across Protocol
-amiko bridge send <amount>               # execute bridge transfer (gated — requires --yes in non-TTY)
-amiko bridge send <amount> --raw         # print transaction JSON without sending (no gate)
-amiko bridge status <txHash>             # check bridge status
-amiko bridge routes                      # available bridge routes
-amiko bridge limits                      # min/max limits per route
+amiko wallets bridge quote <amount>              # cross-chain USDC quote via Across Protocol
+amiko wallets bridge send <amount>               # execute bridge transfer (gated — requires --yes in non-TTY)
+amiko wallets bridge send <amount> --raw         # print transaction JSON without sending (no gate)
+amiko wallets bridge status <txHash>             # check bridge status
+amiko wallets bridge routes                      # available bridge routes
+amiko wallets bridge limits                      # min/max limits per route
 ```
 
 Default route: Solana → Tempo. Use `--from` and `--to` flags for other chains. Like `swap send`, `bridge send` refuses to run in a non-interactive shell without `--yes` so agents must quote the Across fee + gas to the user before executing.
@@ -265,7 +265,6 @@ Supported keys (both camelCase and SCREAMING_SNAKE_CASE):
 - `amikoTwinId` / `AMIKO_TWIN_ID` — twin identifier (needed for paid ops)
 - `amikoUserId` / `AMIKO_USER_ID` — user identifier (optional, for MPP topup)
 - `amikoPlatformUrl` / `AMIKO_PLATFORM_URL` — platform base URL override
-- `billingBase` — billing API URL override
 - `apiBase` — MPP service URL override
 
 ## Configuration
@@ -274,7 +273,6 @@ Defaults (no config file needed — override in `.amiko.json` if needed):
 
 | Key | Default |
 |-----|---------|
-| `billingBase` | `https://billing.heyamiko.com` |
 | `apiBase` | `https://mpp.amikomarkets.com` |
 | `platformUrl` | `https://platform.heyamiko.com` |
 
@@ -372,9 +370,8 @@ Every new command accepts `--json` for structured output and `--twin <id>` where
 
 | Client | Base URL | Purpose |
 |--------|----------|---------|
-| Amiko Web | `platform.heyamiko.com` | Twin identity, wallet balances, docs, voice, avatar, friends, feed, Composio |
-| MPP API | `mpp.amikomarkets.com` | Marketplace services, search, image, audio |
-| Billing API | `billing.heyamiko.com` | Credits, topup, wallet transfers/swaps, keys |
+| Platform | `platform.heyamiko.com` | Twin identity, wallets, credits, transfers/swaps, docs, voice, avatar, friends, feed, Composio |
+| MPP API | `mpp.amikomarkets.com` | Marketplace services: search, image, amazon, audio |
 
 ## Build
 

package/dist/index.js

@@ -17287,7 +17287,6 @@ function resolveAuth() {
     twinId: asString(parsed.amikoTwinId) ?? asString(parsed.AMIKO_TWIN_ID),
     userId: asString(parsed.amikoUserId) ?? asString(parsed.AMIKO_USER_ID),
     platformUrl: asString(parsed.amikoPlatformUrl) ?? asString(parsed.AMIKO_PLATFORM_URL),
-    billingBase: asString(parsed.billingBase),
     apiBase: asString(parsed.apiBase)
   };
 }
@@ -17305,7 +17304,6 @@ function requireAuth() {
 // src/lib/config.ts
 var DEFAULTS = {
   apiBase: "https://mpp.amikomarkets.com",
-  billingBase: "https://billing.heyamiko.com",
   platformUrl: "https://platform.heyamiko.com",
   siteBase: "https://platform.heyamiko.com"
 };
@@ -17313,7 +17311,6 @@ function loadConfig() {
   const auth = resolveAuth();
   return {
     apiBase: auth.apiBase ?? DEFAULTS.apiBase,
-    billingBase: auth.billingBase ?? DEFAULTS.billingBase,
     platformUrl: auth.platformUrl ?? DEFAULTS.platformUrl,
     siteBase: DEFAULTS.siteBase,
     twinToken: auth.twinToken,
@@ -17385,7 +17382,6 @@ function registerConfigCommand(program2) {
     console.log("");
     console.log(heading("Endpoints"));
     console.log(label("  MPP service", config.apiBase));
-    console.log(label("  Billing API", config.billingBase));
     console.log(label("  Platform", config.platformUrl));
     console.log("");
     console.log(heading("Identity"));
@@ -18698,8 +18694,8 @@ function registerBridgeCommand(program2) {
       }
       if (quote.swapTx) {
         console.log("");
-        console.log(dim('Transaction ready. Run "amiko bridge send" to execute.'));
-        console.log(dim(`  amiko bridge send ${amountStr} --from ${opts.from} --to ${opts.to}`));
+        console.log(dim('Transaction ready. Run "amiko wallets bridge send" to execute.'));
+        console.log(dim(`  amiko wallets bridge send ${amountStr} --from ${opts.from} --to ${opts.to}`));
       }
     } catch (err) {
       spinner.stop();
@@ -18752,7 +18748,7 @@ function registerBridgeCommand(program2) {
           cost: quote.fees?.total ? `${formatUsdcAmount(quote.fees.total.amount)} USDC bridge fee + gas` : "gas + Across fee",
           summary: `bridge ${formatUsdcAmount(quote.inputAmount)} USDC ${originName} → ${destName}`,
           yes: opts.yes,
-          commandExample: `amiko bridge send ${amountStr} --from ${opts.from} --to ${opts.to}`
+          commandExample: `amiko wallets bridge send ${amountStr} --from ${opts.from} --to ${opts.to}`
         });
       }
       if (opts.raw) {
@@ -18831,7 +18827,7 @@ function registerBridgeCommand(program2) {
         console.log(dim(output.trim()));
         console.log("");
         console.log(dim("Track status:"));
-        console.log(dim(`  amiko bridge status <txHash> --chain ${originChainId}`));
+        console.log(dim(`  amiko wallets bridge status <txHash> --chain ${originChainId}`));
       } catch (err) {
         bridgeSpinner.fail("Bridge transaction failed");
         console.error(error(err instanceof Error ? err.message : "Transaction failed"));
@@ -19057,15 +19053,9 @@ function formatError(status, body, path) {
 async function fetchCreditsBalance(auth) {
   if (!auth.twinToken)
     return null;
-  const base = (auth.billingBase || "https://billing.heyamiko.com").replace(/\/$/, "");
   try {
-    const res = await fetch(`${base}/api/credits`, {
-      headers: { Authorization: `Bearer ${auth.twinToken}` }
-    });
-    if (!res.ok)
-      return null;
-    const data = await res.json();
-    const raw = data.displayBalance ?? Number(data.credits?.balance ?? 0);
+    const data = await amikoWebFetch(auth, `/api/proxy/service/api/credits`);
+    const raw = data.displayBalance;
     return typeof raw === "number" && isFinite(raw) ? Math.round(raw) : null;
   } catch {
     return null;
@@ -19077,8 +19067,7 @@ async function printBalanceRemaining(auth) {
     console.log(dim("Balance: (could not fetch)"));
     return;
   }
-  const usd2 = (balance / 1e4).toFixed(2);
-  console.log(label("Balance", `${balance.toLocaleString()} credits (~$${usd2})`));
+  console.log(label("Balance", `${balance.toLocaleString()} credits`));
 }
 
 // src/lib/mpp-topup.ts
@@ -19170,8 +19159,7 @@ function registerCreditsCommand(program2) {
       console.log(dim("  Could not fetch credit balance"));
       return;
     }
-    const usd2 = (balance / 1e4).toFixed(2);
-    console.log(label("Balance", `${source_default.bold(balance.toLocaleString())} credits (~$${usd2})`));
+    console.log(label("Balance", source_default.bold(`${balance.toLocaleString()} credits`)));
   });
   credits.command("topup [amount]").description("Top up credits by spending tokens from your agent wallet. <amount> is in credits (10,000 = $1.00). Use --usd <n> to specify dollars, or --spend <n> to specify a token amount (e.g. 1 SOL worth).").option("--token <TOKEN>", "Token to use for top-up").option("--chain <CHAIN>", "Chain to use for top-up").option("--wallet <ADDR>", "Wallet address to use").option("--method <METHOD>", "Payment method: auto, crossmint, mpp", "auto").option("--key-id <ID>", "Platform API key ID (required for --method mpp)").option("--usd <amount>", "Amount in USD instead of credits (e.g. --usd 1 = 10,000 credits)").option("--spend <amount>", "Spend this many units of --token and convert to credits at current price").option("--yes", "Skip the interactive Proceed? prompt").action(async (amountStr, options) => {
     const inputs = [amountStr, options.usd, options.spend].filter((v) => v != null && v !== "");
@@ -19465,7 +19453,7 @@ function registerSwapCommand(program2) {
         console.log(label("Route", dim(route)));
       }
       console.log("");
-      console.log(dim(`To execute: amiko swap send ${amountStr} ${fromToken} ${toToken}`));
+      console.log(dim(`To execute: amiko wallets swap send ${amountStr} ${fromToken} ${toToken}`));
     } catch (err) {
       spinner.stop();
       console.error(error(err instanceof Error ? err.message : "Failed to get quote"));
@@ -19514,7 +19502,7 @@ function registerSwapCommand(program2) {
         cost: "Solana gas + 10bps platform fee",
         summary: `swap ${amountStr} ${fromToken.toUpperCase()} → ~${(Number(quote.outAmount) / 10 ** output.decimals).toFixed(6)} ${output.symbol}`,
         yes: opts.yes,
-        commandExample: `amiko swap send ${amountStr} ${fromToken} ${toToken}`
+        commandExample: `amiko wallets swap send ${amountStr} ${fromToken} ${toToken}`
       });
       const swapSpinner = ora("Executing swap via platform...").start();
       let swapData;
@@ -19561,7 +19549,7 @@ function registerSwapCommand(program2) {
         console.log(`  ${source_default.cyan(t.symbol.padEnd(10))} ${t.name.padEnd(25)} ${dim(truncAddr(t.address))}`);
       }
       console.log("");
-      console.log(dim("Use symbol or mint address: amiko swap quote 5 usdt usdc"));
+      console.log(dim("Use symbol or mint address: amiko wallets swap quote 5 usdt usdc"));
     } catch (err) {
       spinner.stop();
       console.error(error(err instanceof Error ? err.message : "Failed to fetch tokens"));
@@ -21145,6 +21133,98 @@ function registerComposioCommand(program2) {
   });
 }
 
+// src/commands/wallets.ts
+function formatBalance(b) {
+  const n = Number(b.amount) / 10 ** b.decimals;
+  if (!isFinite(n))
+    return b.amount;
+  return n.toLocaleString(undefined, { maximumFractionDigits: 6 });
+}
+function registerWalletsBalanceCommand(program2) {
+  program2.command("balance <address>").description("Sync and show balance for a single wallet").option("--json", "Output raw JSON").action(async (address2, opts) => {
+    let auth;
+    try {
+      auth = requireAuth();
+    } catch (e) {
+      console.error(error(e instanceof Error ? e.message : String(e)));
+      process.exit(1);
+    }
+    const spinner = opts.json ? null : ora("Syncing wallet balance...").start();
+    try {
+      const data = await amikoWebFetch(auth, `/api/agents/${encodeURIComponent(auth.twinId)}/wallets/${encodeURIComponent(address2)}/balance`);
+      spinner?.stop();
+      if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      console.log(heading("Wallet Balance"));
+      console.log("");
+      console.log(label("Address", data.walletAddress));
+      console.log(label("Chain", data.chain_type));
+      if (data.last_synced_at) {
+        console.log(label("Synced", data.last_synced_at));
+      }
+      const entries = Object.entries(data.balances || {});
+      if (entries.length === 0) {
+        console.log(dim("  No balances."));
+        return;
+      }
+      console.log("");
+      const rows = entries.map(([key, v]) => [`  ${key}`, formatBalance(v)]);
+      console.log(table(rows));
+    } catch (e) {
+      spinner?.stop();
+      console.error(error(e instanceof Error ? e.message : "Failed to fetch balance"));
+      process.exit(1);
+    }
+  });
+}
+function registerWalletsListCommand(program2) {
+  program2.command("list").alias("ls").description("List wallets for the authenticated twin").option("--json", "Output raw JSON").action(async (opts) => {
+    let auth;
+    try {
+      auth = requireAuth();
+    } catch (e) {
+      console.error(error(e instanceof Error ? e.message : String(e)));
+      process.exit(1);
+    }
+    const spinner = opts.json ? null : ora("Fetching wallets...").start();
+    try {
+      const data = await amikoWebFetch(auth, `/api/agents/${encodeURIComponent(auth.twinId)}/wallets`);
+      spinner?.stop();
+      if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      const wallets = data.wallets || [];
+      if (wallets.length === 0) {
+        console.log(dim("No wallets found."));
+        return;
+      }
+      console.log(heading("Wallets"));
+      console.log("");
+      for (const w of wallets) {
+        console.log(label("Chain", `${w.chain} (${w.chain_type})`));
+        if (w.name)
+          console.log(label("Name", w.name));
+        console.log(label("Address", w.wallet_address));
+        console.log(label("Short", truncAddr(w.wallet_address)));
+        const balances = Object.entries(w.balance || {}).filter(([, v]) => Number(v.amount) > 0);
+        if (balances.length > 0) {
+          console.log(dim("  Balances:"));
+          const rows = balances.map(([key, v]) => [`    ${key}`, formatBalance(v)]);
+          console.log(table(rows));
+        }
+        console.log("");
+      }
+    } catch (e) {
+      spinner?.stop();
+      console.error(error(e instanceof Error ? e.message : "Failed to list wallets"));
+      process.exit(1);
+    }
+  });
+}
+
 // src/index.ts
 var require2 = createRequire2(import.meta.url);
 var { version: PKG_VERSION } = require2("../package.json");
@@ -21154,12 +21234,15 @@ if (didOnboard)
 var program2 = new Command;
 program2.name("amiko").description("Amiko CLI — swap tokens, manage credits, bridge cross-chain, and call marketplace services").version(PKG_VERSION);
 var market = program2.command("market").description("MPP marketplace — discover and call paid AMIKO services");
+var wallets = program2.command("wallets").description("Manage twin wallets — list, swap, bridge");
 registerCreditsCommand(program2);
 registerSearchCommand(market);
 registerImageCommand(market);
 registerAmazonCommand(market);
-registerSwapCommand(program2);
-registerBridgeCommand(program2);
+registerWalletsListCommand(wallets);
+registerWalletsBalanceCommand(wallets);
+registerSwapCommand(wallets);
+registerBridgeCommand(wallets);
 registerConfigCommand(program2);
 registerServicesCommand(market);
 registerDiscoveryCommand(market);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyamiko/amiko-cli",
-  "version": "0.9.0-beta.1",
+  "version": "0.9.0-beta.5",
   "description": "Amiko CLI — swap tokens, manage credits, bridge cross-chain, and call marketplace agents",
   "type": "module",
   "bin": {

package/skills/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: amiko-cli
-description: Token swaps, credits, search, image generation, audio, and MPP marketplace services
-homepage: https://mpp.amikomarkets.com
+description: Token swaps, credits, marketplace (search/image/amazon/audio), and twin/social operations on Amiko
+homepage: https://platform.heyamiko.com
 metadata: {"openclaw":{"emoji":"🤖","requires":{"bins":["node"]}}}
 ---
 
@@ -9,238 +9,195 @@ metadata: {"openclaw":{"emoji":"🤖","requires":{"bins":["node"]}}}
 
 ## How to invoke
 
-Run `amiko <command>` via your **shell execution tool** (e.g. `bash`). This skill is a documentation reference, not a callable tool. **Do NOT** try to call `amiko_cli`, `amiko-cli`, `amiko`, or this skill's name as a tool — no such tool exists. The only working invocation is the shell command `amiko`.
+Run `amiko <command>` via your **shell execution tool** (e.g. `bash`). This skill is documentation, not a callable tool. **Do NOT** try to call `amiko_cli`, `amiko-cli`, `amiko`, or this skill's name as a tool — no such tool exists. The only working invocation is the shell command `amiko`.
 
-The `amiko` CLI is installed globally. Auth and payments are automatic via `.amiko.json` — never suggest `amiko login` or `amiko connect`.
+The `amiko` CLI is installed globally. Auth is automatic via `.amiko.json` (walking up from cwd, falling back to `/data/.openclaw/workspace/.amiko.json`) — never suggest `amiko login` or `amiko connect`.
+
+## Command layout (v0.9+)
+
+The top level has three groups:
+
+- `amiko market <cmd>` — paid MPP services (search, image, amazon, service, discover)
+- `amiko wallets <cmd>` — wallet operations (list, balance, swap, bridge)
+- `amiko credits <cmd>` — credit balance and topup
+
+Plus flat commands: `config`, `update`, `accounts`, `info`, `twin:*`, `docs*`, `voice:*`, `avatar:*`, `friends*`, `feed`, `post:*`, `composio:*`.
 
 ## Critical Rules
 
-1. **Every paid / value-moving command is hard-gated on `--yes` in a non-interactive shell.** The CLI will *refuse* to run `image`, `search`, `amazon search`, `service call`, `service tts`, `service stt`, `service chat`, `credits topup`, `swap send`, or `bridge send` unless you pass `--yes`. The refusal is loud: it prints the cost and the command you should re-run with `--yes` appended. This means: **you must first quote the cost to the user, get their explicit approval, and only then append `--yes`**. If the user didn't approve, do not add `--yes`. The same applies to destructive non-paid commands (`twin:update --public`, `docs:delete`, `friends:remove`, `avatar:update`, `voice:reset`, `composio:disconnect`).
-2. **After every paid command, report the remaining balance to the user.** The CLI prints a `Balance: N credits (~$X.XX)` line at the end of every paid command — include that figure in your reply so the user knows what they have left.
-3. **Never retry a failed command.** If a command returns an error, report it and stop. Every paid call costs tokens even on failure.
-4. **Never suggest `amiko login` or `amiko connect`.** These commands don't exist. Auth is automatic via `.amiko.json`.
-5. **Check balance before expensive operations.** Run `amiko credits balance` first if unsure about funds.
-6. **Payments are automatic.** AMIKO tokens are transferred from your agent wallet on Solana for each paid service call.
+1. **Every paid / value-moving command is hard-gated on `--yes` in a non-interactive shell.** The CLI *refuses* to run `market image`, `market search`, `market amazon search`, `market service call`, `market service tts`, `market service stt`, `market service chat`, `credits topup`, `wallets swap send`, or `wallets bridge send` unless `--yes` is passed. The refusal is loud: it prints the cost and the command you should re-run. **Quote the cost to the user, get explicit approval, THEN append `--yes`**. Same for destructive non-paid commands (`twin:update --public`, `docs:delete`, `friends:remove`, `avatar:update`, `voice:reset`, `composio:disconnect`).
+2. **After every paid command, report the remaining balance.** The CLI prints a `Balance: N credits` line at the end of every paid command — include that figure in your reply.
+3. **Never retry a failed command.** Report the error and stop. Every paid call costs tokens even on failure.
+4. **Never suggest `amiko login` or `amiko connect`.** These don't exist. Auth is automatic via `.amiko.json`.
+5. **Check balance before expensive operations.** Run `amiko credits balance` first if unsure.
+6. **Payments are automatic.** The platform signs and moves tokens from the twin's wallet for each paid call — the CLI never holds keys.
 
 ### Pricing cheat sheet (quote this to the user before running)
 
 | Command | Cost |
 |---------|------|
-| `amiko search "<query>"` | 1 AMIKO |
-| `amiko image "<prompt>"` | 5 AMIKO |
-| `amiko amazon search "<query>"` | 1 AMIKO |
-| `amiko amazon quote <ASIN>` | Free |
-| `amiko service tts <voiceId> "<text>"` | 1 AMIKO |
-| `amiko service call POST /v1/sfx ...` | $0.05 |
-| `amiko service call POST /v1/music ...` | $0.10 |
-| `amiko service call POST /v1/music/plan ...` | $0.02 |
-| `amiko swap quote ...` | Free |
-| `amiko swap send ...` | Solana gas only |
+| `amiko market search "<query>"` | 1 AMIKO |
+| `amiko market image "<prompt>"` | 5 AMIKO |
+| `amiko market amazon search "<query>"` | 1 AMIKO |
+| `amiko market amazon quote <ASIN>` | Free |
+| `amiko market service tts <voiceId> "<text>"` | 1 AMIKO |
+| `amiko market service call POST /v1/sfx ...` | $0.05 |
+| `amiko market service call POST /v1/music ...` | $0.10 |
+| `amiko market service call POST /v1/music/plan ...` | $0.02 |
+| `amiko wallets swap quote ...` | Free |
+| `amiko wallets swap send ...` | Solana gas + 10bps |
 | `amiko credits topup ...` | Whatever amount you top up |
 
-## Commands
-
-### Credits & Wallet
-
-**Credits are NOT tokens.** 10,000 credits = $1.00 USD.
-
-The `topup` command accepts **one** of three amount forms:
-
-| Form | Meaning | Example |
-|------|---------|---------|
-| `<amount>` (positional) | credits | `amiko credits topup 10000 --token AMIKO` → 10,000 credits = $1 |
-| `--usd <n>` | US dollars | `amiko credits topup --usd 5 --token USDC` → $5 = 50,000 credits |
-| `--spend <n>` | spend N of `--token` | `amiko credits topup --spend 1 --token SOL` → "1 SOL worth of credits" |
+## Credits
 
-**Map user intent directly to the right form** — no manual price math needed:
-
-- "top up 1 SOL of credits" → `amiko credits topup --spend 1 --token SOL`
-- "top up 1 USDC worth of credits" → `amiko credits topup --spend 1 --token USDC`
-- "top up 1 AMIKO" → `amiko credits topup --spend 1 --token AMIKO`
-- "top up $5 in USDC" → `amiko credits topup --usd 5 --token USDC`
-- "top up 10000 credits with AMIKO" → `amiko credits topup 10000 --token AMIKO`
-
-**Always confirm with the user before running.** The CLI prints a `Top-up Summary` (credits, cost in tokens, USD, wallet) and then prompts `Proceed? [y/N]`. Do NOT pass `--yes` unless the user has explicitly approved the summary.
+**Display credits: 10,000 credits = $1.00 USD.**
 
 ```bash
-amiko credits balance                                 # credit balance + wallet balances
-amiko credits topup --spend 1 --token SOL             # "1 SOL worth of credits" — prompts
-amiko credits topup --usd 5 --token USDC              # $5 paying in USDC — prompts
-amiko credits topup 10000 --token AMIKO --yes         # skip prompt (only after user approved summary)
+amiko credits balance                                 # show balance as "N credits"
+amiko credits topup --spend 1 --token SOL --yes       # "1 SOL worth of credits"
+amiko credits topup --usd 5 --token USDC --yes        # $5 paying in USDC
+amiko credits topup 10000 --token AMIKO --yes         # 10,000 credits = $1
 ```
 
-**How topup works:**
-1. You specify credits (e.g. 10000 = $1.00)
-2. CLI fetches live token price via Jupiter
-3. Transfers the equivalent token amount from your agent wallet to treasury
-4. Verifies on-chain and credits your account
-
-Supported tokens: AMIKO, SOL, USDC, USDT. All payments come from your agent's Solana wallet.
+`topup` accepts **one** of three amount forms:
 
-### Search (1 AMIKO)
-
-```bash
-amiko search "AI agents"                        # search X/Twitter
-amiko search "bitcoin" --raw                    # raw JSON output
-```
+| Form | Meaning | Example |
+|------|---------|---------|
+| `<amount>` (positional) | credits | `amiko credits topup 10000 --token AMIKO` |
+| `--usd <n>` | US dollars | `amiko credits topup --usd 5 --token USDC` |
+| `--spend <n>` | spend N of `--token` | `amiko credits topup --spend 1 --token SOL` |
 
-### Image Generation (5 AMIKO)
+Map user intent directly — no manual price math:
 
-```bash
-amiko image "a sunset over mountains"           # gpt-image-1 (default)
-amiko image "logo" --background transparent     # transparent background
-amiko image "portrait" --size 1024x1792         # custom size
-```
+- "top up 1 SOL of credits" → `--spend 1 --token SOL`
+- "top up $5 in USDC" → `--usd 5 --token USDC`
+- "top up 10000 credits with AMIKO" → `10000 --token AMIKO`
 
-Returns a permanent Supabase Storage URL.
+Supported tokens: AMIKO, SOL, USDC, USDT. The CLI fetches the live price, the platform transfers from the twin's wallet, and on-chain verification credits the account.
 
-### Amazon
+## Wallets
 
 ```bash
-amiko amazon search "usb c cable"               # product search (1 AMIKO)
-amiko amazon quote B01GGKYKQM                   # price quote (free)
+amiko wallets list                                   # all twin wallets + cached balances
+amiko wallets balance <address>                      # force-sync one wallet; returns fresh balances
+amiko wallets swap quote 1.0 SOL USDC                # Jupiter quote (free)
+amiko wallets swap send 1.0 SOL USDC --wallet <addr> --yes
+amiko wallets swap tokens                            # supported tokens list
+amiko wallets bridge quote 10 --from solana --to tempo
+amiko wallets bridge send 10 --from solana --to tempo --yes
+amiko wallets bridge status <txHash>
+amiko wallets bridge routes
+amiko wallets bridge limits
 ```
 
-### Token Swaps
+`wallets list` returns cached balances (platform doesn't auto-sync). If balances look stale, run `wallets balance <address>` to force a sync for that wallet.
 
-```bash
-amiko swap quote 1.0 SOL USDC                   # get Jupiter quote
-amiko swap send 1.0 SOL USDC --yes              # execute swap
-amiko swap tokens                                # list supported tokens
-```
+Swaps run via Jupiter on Solana. Supported: SOL, USDC, USDT, AMIKO, PYUSD, BONK, JUP, RAY, JitoSOL — or any mint address. Bridging goes through Across Protocol.
 
-Swaps execute via Jupiter on Solana. Supports: SOL, USDC, USDT, AMIKO, PYUSD, BONK, JUP, RAY, JitoSOL, mSOL, or any mint address.
-
-### MPP Services
+## Market (paid MPP services)
 
 ```bash
-amiko service list                               # all services + prices
-
-# Sound effects ($0.05) — returns { url, format, service }
-amiko service call POST /v1/sfx '{"text":"thunder","duration_seconds":5}'
-
-# Music generation ($0.10) — returns { url, format, service }
-amiko service call POST /v1/music '{"prompt":"lo-fi beat","music_length_ms":30000}'
-
-# Text-to-speech (1 AMIKO) — returns { url, format, service }
-amiko service tts 21m00Tcm4TlvDq8ikWAM "Hello world"
-
-# Composition plan ($0.02)
-amiko service call POST /v1/music/plan '{"prompt":"epic orchestral"}'
-
-# Any endpoint
-amiko service call <METHOD> <path> [body]
+amiko market search "AI agents"                      # 1 AMIKO — X/Twitter search
+amiko market image "a sunset over mountains" --yes   # 5 AMIKO — gpt-image-1 by default
+amiko market image "logo" --background transparent   # transparent bg
+amiko market image "portrait" --size 1024x1792       # custom size
+amiko market amazon search "usb c cable"             # 1 AMIKO — product search
+amiko market amazon quote B01GGKYKQM                 # free — price quote
+amiko market service list                            # all services + prices
+amiko market service call POST /v1/sfx '{"text":"thunder","duration_seconds":5}'
+amiko market service call POST /v1/music '{"prompt":"lo-fi beat","music_length_ms":30000}'
+amiko market service tts 21m00Tcm4TlvDq8ikWAM "Hello world"
+amiko market service call POST /v1/music/plan '{"prompt":"epic orchestral"}'
+amiko market service call <METHOD> <path> [body]     # any MPP endpoint
+amiko market discover                                # service info + pricing
 ```
 
-Audio and image endpoints return permanent Supabase Storage URLs.
+Paid market commands require `--wallet <address>` (the Solana wallet that pays) unless one can be resolved from `.amiko.json`. Audio and image endpoints return permanent Supabase Storage URLs.
 
-### Bridge
+## Account & Twin
 
 ```bash
-amiko bridge quote 10                            # cross-chain USDC quote
-amiko bridge send 10 --from solana --to tempo    # execute bridge
+amiko accounts                                   # resolved identity (authenticated, userId, twinId, platform)
+amiko info                                       # twin info (name, description, public, voice, avatar)
+amiko twin:update --name "New Name"
+amiko twin:update --description "..."
+amiko twin:update --public true --yes            # destructive — requires --yes in non-TTY
 ```
 
-### Other
-
-```bash
-amiko discovery                                  # MPP service info + pricing
-amiko config show                                # view config
-amiko update                                     # update CLI to latest (on twins: also refreshes /data, symlink, skill)
-amiko --help                                     # all commands
-```
-
-Agent wallet balances are surfaced by `amiko credits balance` (shows credit balance + wallet balances across all chains in one call). There is no standalone `wallet` command.
+All twin-scoped commands accept `--twin <id>` to target a non-default twin.
 
-### Account & Twin
+## Documents (RAG)
 
 ```bash
-amiko accounts                                   # show resolved identity (mode, platform, user, active twin, wallets)
-amiko info                                       # fetch twin info (name, description, is_public, voice, avatar)
-amiko twin:update --name "New Name"              # rename the twin
-amiko twin:update --description "..."            # update bio
-amiko twin:update --public true --yes            # flip visibility (destructive — requires --yes in non-TTY)
+amiko docs                                       # list
+amiko docs:upload ./notes.pdf                    # path
+amiko docs:upload https://example.com/x.pdf      # URL
+cat file.pdf | amiko docs:upload - --stdin --name file.pdf
+amiko docs:delete <docId> --yes                  # destructive
+amiko docs:presign ./file.pdf                    # presigned S3 URL only
 ```
 
-All twin-scoped commands accept `--twin <id>` to target a non-default twin.
-
-### Documents (RAG)
+## Voice
 
 ```bash
-amiko docs                                       # list uploaded documents
-amiko docs:upload ./notes.pdf                    # upload a local file
-amiko docs:upload https://example.com/x.pdf      # upload from URL
-cat file.pdf | amiko docs:upload - --stdin --name file.pdf  # upload from stdin
-amiko docs:delete <docId> --yes                  # delete (destructive)
-amiko docs:presign ./file.pdf                    # get a presigned S3 URL (no upload)
+amiko voice:design --description "warm, low, male, confident, measured"  # min 20 chars
+amiko voice:create --sample <generated_voice_id>
+amiko voice:clone ./me.mp3                       # path | URL | -
+amiko voice:reset --yes                          # destructive
 ```
 
-### Voice
+## Avatar
 
 ```bash
-amiko voice:design --description "warm, low, male, confident, measured"  # min 20 chars; returns preview IDs
-amiko voice:create --sample <generated_voice_id>                          # commit a designed preview
-amiko voice:clone ./me.mp3                                                # clone from an audio file (path | URL | -)
-amiko voice:reset --yes                                                   # revert to default (destructive)
+amiko avatar:update --file ./portrait.png --yes  # max 5 MB, destructive
 ```
 
-### Avatar
+## Friends
 
 ```bash
-amiko avatar:update --file ./portrait.png --yes  # max 5 MB image/* (destructive — changes public avatar)
+amiko friends                                    # list all
+amiko friends --type user                        # filter
+amiko friends:add --id <userId>
+amiko friends:accept <friendshipId>
+amiko friends:remove <friendshipId> --yes        # destructive
 ```
 
-### Friends
+## Feed & Posts
 
 ```bash
-amiko friends                                    # list all friends
-amiko friends --type user                        # filter user-to-user
-amiko friends:add --id <userId>                  # send friend request
-amiko friends:accept <friendshipId>              # accept pending
-amiko friends:remove <friendshipId> --yes        # remove (destructive)
+amiko feed                                       # friends feed (default)
+amiko feed --type for_you --limit 20
+amiko feed --hashtag ai
+amiko post:create --content "hello from the CLI"
+amiko post:create --content "private note" --visibility private
+amiko post:create --content "look" --media https://...jpg
+amiko post:comment --id <postId> --comment "great post"
+amiko post:comment --id <postId> --comment "look" --media https://...jpg
+amiko post:comment --id <postId> --comment "..." --twin <id>
 ```
 
-### Feed & Posts
+## Composio
 
 ```bash
-amiko feed                                       # friends feed (default)
-amiko feed --type for_you --limit 20             # public for-you feed
-amiko feed --hashtag ai                          # filter by hashtag
-amiko post:create --content "hello from the CLI"                              # public post (default)
-amiko post:create --content "private note" --visibility private               # private post
-amiko post:create --content "look" --media https://...jpg                     # attach media URL(s)
-amiko post:comment --id <postId> --comment "great post"                       # comment as user
-amiko post:comment --id <postId> --comment "look" --media https://...jpg      # comment with attached media
-amiko post:comment --id <postId> --comment "..." --twin <id>                  # comment as the twin
+amiko composio:connect --app gmail               # prints OAuth URL
+amiko composio:disconnect --app gmail --yes      # destructive
 ```
 
-### Composio (external apps)
+## Other
 
 ```bash
-amiko composio:connect --app gmail               # prints OAuth URL — open in a browser
-amiko composio:disconnect --app gmail --yes      # disconnect (destructive)
+amiko config show                                # resolved config
+amiko update                                     # self-update
+amiko --help                                     # top-level help
+amiko <group> --help                             # e.g. `amiko wallets --help`
 ```
 
-### JSON output
+## JSON output
 
-Every new command supports `--json` for structured output suitable for piping or parsing:
+Most commands support `--json` for structured output:
 
 ```bash
+amiko wallets list --json | jq '.wallets[].wallet_address'
 amiko friends --json | jq '.items[] | .friend.name'
 amiko info --json | jq -r '.name'
 ```
-
-## Service Costs
-
-| Service | Cost | Command |
-|---------|------|---------|
-| X/Twitter search | 1 AMIKO | `amiko search "<query>"` |
-| Image generation | 5 AMIKO | `amiko image "<prompt>"` |
-| Amazon search | 1 AMIKO | `amiko amazon search "<query>"` |
-| Amazon quote | Free | `amiko amazon quote <ASIN>` |
-| Sound effects | $0.05 | `amiko service call POST /v1/sfx ...` |
-| Music generation | $0.10 | `amiko service call POST /v1/music ...` |
-| Text-to-speech | 1 AMIKO | `amiko service tts <voiceId> "<text>"` |
-| Swap quote | Free | `amiko swap quote ...` |
-| Swap execute | Gas only | `amiko swap send ...` |
-| Credit top-up | Amount in credits (10,000 = $1) | `amiko credits topup <credits>` |