gachadex 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GachaDex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# gachadex
+
+Command-line client for the [GachaDex](https://github.com/gachadex) perpetual-futures exchange —
+built for humans and AI agents. Trade leveraged perps on TCG-card prices from your terminal.
+
+```bash
+npm i -g gachadex          # or: npx gachadex <command>
+export GACHADEX_API_URL=https://your-gachadex-api
+gachadex markets --search pikachu
+```
+
+## Authentication
+
+Use a **delegated trade-only key** (it can trade but never withdraw). Point `GACHADEX_KEY` at a
+base58 secret or a Solana keyfile path:
+
+```bash
+# a master wallet mints a delegated key for a bot:
+gachadex keys create --master-keyfile ~/master.json --label bot --save bot
+# then the bot trades with it:
+export GACHADEX_KEY=~/.config/gachadex/keys/bot.json
+gachadex balance
+```
+
+Keys live under `~/.config/gachadex/keys/` (chmod 0600). `--keyfile` and `--master-keyfile`
+override the env/defaults per command.
+
+## Commands
+
+| | |
+|---|---|
+| `markets [--kind --game --search]` · `market <id\|symbol>` · `candles <m> [--tf]` | browse markets + card detail |
+| `balance` · `positions` · `history <kind>` | account state |
+| `long <m> --margin 100 --lev 5 [--max-slippage 1]` · `short …` · `close <id> [--fraction 50]` | trade |
+| `keys create\|list\|revoke` | manage delegated keys (master) |
+| `watch <m…>` · `events` | live mark / private streams (NDJSON) |
+| `faucet` · `leaderboard` · `config get\|set` | misc |
+
+## Built for agents
+
+- **JSON when piped** (or `--json`); data → stdout, errors → stderr as `{error, code}`.
+- **Typed exit codes:** `0` ok · `2` auth · `3` validation · `4` confirmation required · `5` retry (rate-limit/5xx/network).
+- **Confirmation protocol:** `long`/`short`/`close` print a JSON preview and exit `4` unless `--yes`.
+  The preview carries the exact re-run `command` (with a fixed `--idempotency-key`) — run it to
+  execute. Reuse that key on retries so a timeout can't double-open. `--dry-run` previews at exit 0
+  (no key needed).
+
+See [`skills/gachadex-trading/SKILL.md`](../../skills/gachadex-trading/SKILL.md) for the agent skill.
+
+## License
+
+[MIT](../../LICENSE) © GachaDex

package/dist/index.js

@@ -0,0 +1,524 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command, CommanderError } from "commander";
+
+// src/lib/output.ts
+function jsonMode(force) {
+  return !!force || !process.stdout.isTTY;
+}
+var bigintReplacer = (_k, v) => typeof v === "bigint" ? v.toString() : v;
+function emit(data, human, opts = {}) {
+  if (jsonMode(opts.json)) process.stdout.write(JSON.stringify(data, bigintReplacer, 2) + "\n");
+  else process.stdout.write(human() + "\n");
+}
+function emitError(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  const code = err && typeof err === "object" && "code" in err ? err.code : void 0;
+  if (!process.stderr.isTTY) {
+    process.stderr.write(JSON.stringify({ error: message, ...typeof code === "string" ? { code } : {} }) + "\n");
+  } else {
+    process.stderr.write(`${useColor() ? "\x1B[31merror\x1B[0m" : "error"}: ${message}${typeof code === "string" ? ` (${code})` : ""}
+`);
+  }
+}
+function useColor() {
+  return process.stdout.isTTY && !process.env.NO_COLOR;
+}
+
+// src/lib/exit.ts
+import { GachaDexError, isRetryable } from "@gachadex/sdk";
+var EXIT = {
+  OK: 0,
+  GENERAL: 1,
+  AUTH: 2,
+  // missing/invalid key, 401/403
+  VALIDATION: 3,
+  // bad args / 400 / 404 / 409
+  CONFIRM: 4,
+  // a mutation needs --yes
+  RETRY: 5
+  // transient: 429 / 5xx / network
+};
+var CliError = class extends Error {
+  constructor(exitCode, message, code) {
+    super(message);
+    this.exitCode = exitCode;
+    this.code = code;
+    this.name = "CliError";
+  }
+  exitCode;
+  code;
+};
+function exitCodeFor(err) {
+  if (err instanceof CliError) return err.exitCode;
+  if (err instanceof GachaDexError) {
+    if (isRetryable(err)) return EXIT.RETRY;
+    if (err.status === 401 || err.status === 403) return EXIT.AUTH;
+    if (err.status === 400 || err.status === 404 || err.status === 409) return EXIT.VALIDATION;
+    return EXIT.GENERAL;
+  }
+  return EXIT.GENERAL;
+}
+
+// src/commands/read.ts
+import { formatUsd, formatSignedUsd } from "@gachadex/sdk";
+
+// src/lib/dex.ts
+import { GachaDex } from "@gachadex/sdk";
+
+// src/lib/config.ts
+import { homedir } from "os";
+import { join } from "path";
+import { mkdirSync, readFileSync, writeFileSync, existsSync, chmodSync } from "fs";
+import { keypairSigner } from "@gachadex/sdk";
+function configDir() {
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(base, "gachadex");
+}
+function keysDir() {
+  return join(configDir(), "keys");
+}
+function configPath() {
+  return join(configDir(), "config.json");
+}
+function ensureDir(d) {
+  mkdirSync(d, { recursive: true, mode: 448 });
+}
+function loadConfig() {
+  try {
+    return JSON.parse(readFileSync(configPath(), "utf8"));
+  } catch {
+    return {};
+  }
+}
+function saveConfig(c) {
+  ensureDir(configDir());
+  writeFileSync(configPath(), JSON.stringify(c, null, 2) + "\n", { mode: 384 });
+}
+function keyPath(name) {
+  return join(keysDir(), `${name}.json`);
+}
+function saveKey(name, secretKey) {
+  ensureDir(keysDir());
+  const p = keyPath(name);
+  writeFileSync(p, JSON.stringify([...secretKey]), { mode: 384 });
+  chmodSync(p, 384);
+  return p;
+}
+function signerFromValue(v) {
+  const val = v.trim();
+  if (existsSync(val)) return keypairSigner(readFileSync(val, "utf8").trim());
+  return keypairSigner(val);
+}
+function resolveSigner(opts = {}) {
+  if (opts.keyfile) return signerFromValue(opts.keyfile);
+  if (process.env.GACHADEX_KEY) return signerFromValue(process.env.GACHADEX_KEY);
+  const def = keyPath(loadConfig().defaultKey || "default");
+  if (existsSync(def)) return keypairSigner(readFileSync(def, "utf8").trim());
+  throw new CliError(EXIT.AUTH, "no key configured \u2014 run `gachadex login --keyfile <path>` or set GACHADEX_KEY", "no_key");
+}
+function resolveMaster(opts = {}) {
+  if (opts.masterKeyfile) return signerFromValue(opts.masterKeyfile);
+  if (process.env.GACHADEX_MASTER_KEY) return signerFromValue(process.env.GACHADEX_MASTER_KEY);
+  return resolveSigner();
+}
+
+// src/lib/dex.ts
+function resolveApiUrl(flagApi) {
+  return flagApi || process.env.GACHADEX_API_URL || loadConfig().apiUrl || "http://localhost:4000";
+}
+function makeDex(flagApi) {
+  return new GachaDex({ apiUrl: resolveApiUrl(flagApi) });
+}
+async function connect(signer, flagApi) {
+  const dex = makeDex(flagApi);
+  const session = await dex.login(signer);
+  return { dex, session };
+}
+
+// src/commands/_common.ts
+function withApi(c) {
+  return c.option("--api <url>", "API base URL (or set GACHADEX_API_URL)").option("--json", "force JSON output");
+}
+function withKey(c) {
+  return withApi(c).option("-k, --keyfile <path>", "trade key file (or set GACHADEX_KEY)");
+}
+function withConfirm(c) {
+  return withKey(c).option("--yes", "execute (without this, prints a preview and exits 4)").option("--dry-run", "print the preview and exit 0 without calling the API").option("--idempotency-key <key>", "reuse a key across retries (auto-generated otherwise)");
+}
+
+// src/commands/read.ts
+var priceOf = (m) => m.markE6 ? formatUsd(BigInt(m.markE6)) : "\u2014";
+function marketLine(m) {
+  return `${m.symbol.padEnd(26)} ${priceOf(m).padStart(12)}  ${m.displayName}`;
+}
+function renderMarket(m, d) {
+  const meta = d?.metadata;
+  const lines = [
+    `${m.displayName}  (${m.symbol})`,
+    `  market   ${priceOf(m)}   ${m.kind} \xB7 ${m.game} \xB7 ${m.status}${m.tradeable ? "" : " \xB7 not tradeable"}`,
+    `  leverage up to ${m.maxLeverage}x   fee ${m.feeBps ?? 0} bps   maint ${m.maintMarginBps} bps`
+  ];
+  if (meta?.setName) lines.push(`  set      ${meta.setName}`);
+  if (d?.gradedPsa10E6) lines.push(`  PSA-10   ${formatUsd(BigInt(d.gradedPsa10E6))}`);
+  return lines.join("\n");
+}
+function positionLine(p) {
+  const qty = Number(p.qtyE6) / 1e6;
+  return `${p.symbol.padEnd(22)} ${p.side.padEnd(5)} ${qty} @ ${formatUsd(BigInt(p.avgEntryE6))}  mark ${formatUsd(BigInt(p.markE6))}  uPnL ${formatSignedUsd(p.unrealizedPnlUusdc)}  liq ${formatUsd(BigInt(p.liqPriceE6))}`;
+}
+var HISTORY_KINDS = ["orders", "trades", "transactions", "positions"];
+function registerRead(program2) {
+  withApi(
+    program2.command("markets").description("List markets").option("--kind <kind>", "card | index").option("--game <game>", "pokemon | onepiece | mtg").option("--search <q>", "filter by symbol or name")
+  ).action(async (o) => {
+    let markets = await makeDex(o.api).markets();
+    if (o.kind) markets = markets.filter((m) => m.kind === o.kind);
+    if (o.game) markets = markets.filter((m) => m.game === o.game);
+    if (o.search) {
+      const q = String(o.search).toLowerCase();
+      markets = markets.filter((m) => m.symbol.toLowerCase().includes(q) || m.displayName.toLowerCase().includes(q));
+    }
+    emit(markets, () => markets.map(marketLine).join("\n"), { json: o.json });
+  });
+  withApi(program2.command("market <market>").description("Show one market (id or symbol) with card details")).action(async (market, o) => {
+    const dex = makeDex(o.api);
+    const m = await dex.market(market);
+    const d = await dex.marketDetails(m.id).catch(() => null);
+    emit({ ...m, details: d }, () => renderMarket(m, d), { json: o.json });
+  });
+  withApi(program2.command("candles <market>").description("Price history").option("--tf <tf>", "1D|1W|1M|3M|1Y", "1M")).action(async (market, o) => {
+    const dex = makeDex(o.api);
+    const m = await dex.market(market);
+    const candles = await dex.candles(m.id, o.tf);
+    emit(candles, () => candles.map((c) => `${new Date(c.time * 1e3).toISOString().slice(0, 10)}  ${formatUsd(c.value)}`).join("\n"), { json: o.json });
+  });
+  withApi(program2.command("leaderboard").description("Top traders").option("--limit <n>", "rows", "100")).action(async (o) => {
+    const data = await makeDex(o.api).leaderboard(Number(o.limit));
+    emit(data, () => JSON.stringify(data, null, 2), { json: o.json });
+  });
+  withKey(program2.command("balance").description("Account balance + equity")).action(async (o) => {
+    const { session } = await connect(resolveSigner(o), o.api);
+    const b = await session.balance();
+    emit(b, () => [
+      `available  ${formatUsd(BigInt(b.availableUusdc))}`,
+      `locked     ${formatUsd(BigInt(b.lockedMarginUusdc))}`,
+      `uPnL       ${formatSignedUsd(b.unrealizedPnlUusdc)}`,
+      `equity     ${formatUsd(BigInt(b.equityUusdc))}`
+    ].join("\n"), { json: o.json });
+  });
+  withKey(program2.command("positions").description("Open positions")).action(async (o) => {
+    const { session } = await connect(resolveSigner(o), o.api);
+    const positions = await session.positions();
+    emit(positions, () => positions.length ? positions.map(positionLine).join("\n") : "no open positions", { json: o.json });
+  });
+  withKey(
+    program2.command("history <kind>").description("Transaction history: orders | trades | transactions | positions").option("--limit <n>", "rows").option("--before <cursor>", "page cursor")
+  ).action(async (kind, o) => {
+    if (!HISTORY_KINDS.includes(kind)) throw new CliError(EXIT.VALIDATION, `kind must be one of: ${HISTORY_KINDS.join(", ")}`, "bad_history_kind");
+    const { session } = await connect(resolveSigner(o), o.api);
+    const rows = await session.history(kind, { limit: o.limit ? Number(o.limit) : void 0, before: o.before });
+    emit(rows, () => JSON.stringify(rows, null, 2), { json: o.json });
+  });
+}
+
+// src/commands/trade.ts
+import { randomUUID } from "crypto";
+import {
+  notional,
+  initialMargin,
+  fee,
+  liquidationPrice,
+  qtyFromMargin,
+  toE6,
+  formatUsd as formatUsd2,
+  formatSignedUsd as formatSignedUsd2
+} from "@gachadex/sdk";
+function sizeQty(o, m, levE2, markE6) {
+  const step = BigInt(m.qtyStepE6);
+  let qtyE6;
+  if (o.qty != null) {
+    const n = Number(o.qty);
+    if (!Number.isFinite(n) || n <= 0) throw new CliError(EXIT.VALIDATION, "--qty must be a positive number", "bad_order");
+    qtyE6 = BigInt(Math.round(n * 1e6)) / step * step;
+  } else if (o.margin != null) {
+    const n = Number(o.margin);
+    if (!Number.isFinite(n) || n <= 0) throw new CliError(EXIT.VALIDATION, "--margin must be a positive number", "bad_order");
+    qtyE6 = qtyFromMargin({ marginUusdc: toE6(n), leverageE2: levE2, priceE6: markE6, qtyStepE6: step });
+  } else {
+    throw new CliError(EXIT.VALIDATION, "provide --margin <usd> or --qty <units>", "bad_order");
+  }
+  if (qtyE6 < BigInt(m.minQtyE6)) throw new CliError(EXIT.VALIDATION, `size is below the market minimum (${m.minQtyE6})`, "below_min");
+  return qtyE6;
+}
+function planOpen(side, m, o) {
+  if (!m.tradeable || m.status !== "active") throw new CliError(EXIT.VALIDATION, `${m.symbol} is not tradeable`, "market_halted");
+  if (!m.markE6) throw new CliError(EXIT.VALIDATION, `${m.symbol} has no price yet`, "no_price");
+  const lev = Number(o.lev);
+  if (!Number.isFinite(lev) || lev < 1 || lev > m.maxLeverage) throw new CliError(EXIT.VALIDATION, `--lev must be 1..${m.maxLeverage}`, "bad_leverage");
+  const levE2 = Math.round(lev * 100);
+  const markE6 = BigInt(m.markE6);
+  const qtyE6 = sizeQty(o, m, levE2, markE6);
+  const notionUusdc = notional(qtyE6, markE6);
+  const marginUusdc = initialMargin(notionUusdc, levE2);
+  const feeUusdc = fee(notionUusdc, m.feeBps ?? 0);
+  const liqE6 = liquidationPrice({ side, entryE6: markE6, leverageE2: levE2, maintMarginBps: m.maintMarginBps });
+  let limitPriceE6;
+  if (o.maxSlippage != null) {
+    const bps = BigInt(Math.round(Number(o.maxSlippage) * 100));
+    limitPriceE6 = side === "long" ? markE6 * (10000n + bps) / 10000n : markE6 * (10000n - bps) / 10000n;
+  }
+  const preview = {
+    action: "open",
+    side,
+    market: m.symbol,
+    marketId: m.id,
+    qtyE6: qtyE6.toString(),
+    qty: Number(qtyE6) / 1e6,
+    leverage: lev,
+    entryMark: formatUsd2(markE6),
+    notional: formatUsd2(notionUusdc),
+    margin: formatUsd2(marginUusdc),
+    fee: formatUsd2(feeUusdc),
+    liqPrice: formatUsd2(liqE6),
+    ...limitPriceE6 !== void 0 ? { limitPrice: formatUsd2(limitPriceE6) } : {},
+    idempotencyKey: o.idempotencyKey || randomUUID()
+  };
+  return { qtyE6, limitPriceE6, preview };
+}
+function rerunOpen(side, market, o, idem) {
+  const parts = [`gachadex ${side} ${market}`];
+  if (o.margin != null) parts.push(`--margin ${o.margin}`);
+  if (o.qty != null) parts.push(`--qty ${o.qty}`);
+  if (o.lev != null) parts.push(`--lev ${o.lev}`);
+  if (o.maxSlippage != null) parts.push(`--max-slippage ${o.maxSlippage}`);
+  if (o.api) parts.push(`--api ${o.api}`);
+  if (o.keyfile) parts.push(`-k ${o.keyfile}`);
+  parts.push(`--idempotency-key ${idem}`, "--yes");
+  return parts.join(" ");
+}
+function previewLines(p) {
+  return [
+    `${p.side.toUpperCase()} ${p.qty} ${p.market} @ ${p.entryMark} (${p.leverage}x)`,
+    `  notional ${p.notional}   margin ${p.margin}   fee ${p.fee}   liq ${p.liqPrice}` + (p.limitPrice ? `   limit ${p.limitPrice}` : "")
+  ].join("\n");
+}
+async function runOpen(side, market, o) {
+  const dex = makeDex(o.api);
+  const m = await dex.market(market);
+  const plan = planOpen(side, m, o);
+  const p = plan.preview;
+  if (o.dryRun) {
+    emit({ dryRun: true, ...p }, () => previewLines(p), { json: o.json });
+    return;
+  }
+  if (!o.yes) {
+    const command = rerunOpen(side, market, o, p.idempotencyKey);
+    emit({ confirm: true, command, ...p }, () => `${previewLines(p)}
+
+confirm with --yes (or re-run: ${command})`, { json: o.json });
+    process.exitCode = EXIT.CONFIRM;
+    return;
+  }
+  const { session } = await connect(resolveSigner(o), o.api);
+  const result = await session.openPosition({
+    market: m.id,
+    side,
+    leverage: Number(o.lev),
+    qtyE6: plan.qtyE6.toString(),
+    ...plan.limitPriceE6 !== void 0 ? { limitPriceE6: plan.limitPriceE6.toString() } : {},
+    idempotencyKey: p.idempotencyKey
+  });
+  emit({ ...p, result }, () => `opened ${side} ${p.qty} ${p.market} \u2014 position ${result.positionId}`, { json: o.json });
+}
+function registerTrade(program2) {
+  for (const side of ["long", "short"]) {
+    withConfirm(
+      program2.command(`${side} <market>`).description(`Open a ${side} (size with --margin or --qty)`).option("--margin <usd>", "margin to commit, in USD").option("--qty <units>", "quantity in units").option("--lev <x>", "leverage").option("--max-slippage <pct>", "reject if the fill moves more than this %")
+    ).action((market, o) => runOpen(side, market, o));
+  }
+  withConfirm(
+    program2.command("close <positionId>").description("Close a position (full, or --fraction <pct>)").option("--fraction <pct>", "percent to close (default 100)")
+  ).action(async (positionId, o) => {
+    const { session } = await connect(resolveSigner(o), o.api);
+    const pos = (await session.positions()).find((x) => x.id === positionId);
+    if (!pos) throw new CliError(EXIT.VALIDATION, `no open position ${positionId}`, "position_not_found");
+    const fractionBps = o.fraction != null ? Math.round(Number(o.fraction) * 100) : 1e4;
+    if (fractionBps <= 0 || fractionBps > 1e4) throw new CliError(EXIT.VALIDATION, "--fraction must be 0..100", "bad_fraction");
+    const idem = o.idempotencyKey || randomUUID();
+    const preview = {
+      action: "close",
+      positionId,
+      market: pos.symbol,
+      side: pos.side,
+      closingPct: fractionBps / 100,
+      uPnl: formatSignedUsd2(pos.unrealizedPnlUusdc),
+      idempotencyKey: idem
+    };
+    const human = () => `CLOSE ${preview.closingPct}% of ${pos.symbol} (${pos.side}) \u2014 unrealized ${preview.uPnl}`;
+    if (o.dryRun) {
+      emit({ dryRun: true, ...preview }, human, { json: o.json });
+      return;
+    }
+    if (!o.yes) {
+      const command = `gachadex close ${positionId} --fraction ${preview.closingPct}${o.api ? ` --api ${o.api}` : ""} --idempotency-key ${idem} --yes`;
+      emit({ confirm: true, command, ...preview }, () => `${human()}
+
+confirm with --yes (or re-run: ${command})`, { json: o.json });
+      process.exitCode = EXIT.CONFIRM;
+      return;
+    }
+    const result = await session.closePosition(positionId, { fractionBps, idempotencyKey: idem });
+    emit({ ...preview, result }, () => `closed ${preview.closingPct}% of ${pos.symbol} \u2014 realized ${formatSignedUsd2(result.realizedPnlUusdc)}`, { json: o.json });
+  });
+}
+
+// src/commands/keys.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { parseSecretKey, formatUsd as formatUsd3 } from "@gachadex/sdk";
+function parseExpires(s) {
+  if (!s) return {};
+  const m = /^(\d+)\s*d?$/.exec(s.trim());
+  if (m) return { expiresInDays: Number(m[1]) };
+  const d = new Date(s);
+  if (Number.isNaN(d.getTime())) throw new CliError(EXIT.VALIDATION, '--expires must be a number of days (e.g. "30") or an ISO date', "bad_expiry");
+  return { expiresAt: d.toISOString() };
+}
+function registerKeys(program2) {
+  withKey(program2.command("login").description("Verify a key and show the account it controls").option("--save", "save this key as the default")).action(async (o) => {
+    const { session } = await connect(resolveSigner(o), o.api);
+    const me = await session.me();
+    let savedTo;
+    if (o.save && o.keyfile) {
+      saveKey("default", parseSecretKey(readFileSync2(o.keyfile, "utf8").trim()));
+      saveConfig({ ...loadConfig(), defaultKey: "default" });
+      savedTo = "default";
+    }
+    emit({ account: me.pubkey, scope: me.scope, ...me.act ? { actingKey: me.act } : {}, ...savedTo ? { savedAs: savedTo } : {} }, () => `account ${me.pubkey}
+scope   ${me.scope}${me.act ? `
+key     ${me.act}` : ""}${savedTo ? `
+saved as "${savedTo}" (default)` : ""}`, { json: o.json });
+  });
+  const keys = program2.command("keys").description("Manage delegated trade-only keys");
+  withApi(
+    keys.command("create").description("Mint a delegated trade-only key (needs the master key)").option("--label <label>", "a name for the key").option("--expires <when>", 'e.g. "30d" or an ISO date').option("--master-keyfile <path>", "master wallet key (or GACHADEX_MASTER_KEY)").option("--save <name>", "save the new key under this name")
+  ).action(async (o) => {
+    const { session } = await connect(resolveMaster(o), o.api);
+    const del = await session.delegateKey({ label: o.label, ...parseExpires(o.expires) });
+    const name = o.save || o.label || del.delegate.pubkey.slice(0, 8);
+    const savedTo = saveKey(name, del.secretKey);
+    emit(
+      { delegate: del.delegate, savedAs: name, savedTo, secretKeyBase58: del.secretKeyBase58 },
+      () => `minted trade-only key ${del.delegate.pubkey}
+  label   ${del.delegate.label || "(none)"}
+  expires ${del.delegate.expiresAt ?? "never"}
+  saved   ${savedTo}
+  use it: GACHADEX_KEY=${savedTo} gachadex balance`,
+      { json: o.json }
+    );
+  });
+  withApi(keys.command("list").description("List this account's delegated keys").option("--master-keyfile <path>", "master wallet key")).action(async (o) => {
+    const { session } = await connect(resolveMaster(o), o.api);
+    const delegates = await session.listDelegates();
+    emit(delegates, () => delegates.length ? delegates.map((d) => `${d.pubkey}  ${d.active ? "active " : "revoked"}  ${d.label || "(no label)"}  expires ${d.expiresAt ?? "never"}`).join("\n") : "no delegated keys", { json: o.json });
+  });
+  withApi(keys.command("revoke <pubkey>").description("Revoke a delegated key (permanent)").option("--master-keyfile <path>", "master wallet key")).action(async (pubkey, o) => {
+    const { session } = await connect(resolveMaster(o), o.api);
+    await session.revokeDelegate(pubkey);
+    emit({ ok: true, revoked: pubkey }, () => `revoked ${pubkey}`, { json: o.json });
+  });
+  withKey(program2.command("faucet").description("Claim play-money USDC (play-money instances only)").option("--amount <usd>", "amount in USD")).action(async (o) => {
+    if ((await makeDex(o.api).health()).realFunds) {
+      throw new CliError(EXIT.VALIDATION, "faucet is disabled on this real-funds instance \u2014 deposit USDC instead", "faucet_disabled");
+    }
+    const { session } = await connect(resolveSigner(o), o.api);
+    const r = await session.faucet(o.amount ? Number(o.amount) : void 0);
+    emit(r, () => `faucet ok \u2014 available ${formatUsd3(BigInt(r.availableUusdc))}`, { json: o.json });
+  });
+}
+
+// src/commands/stream.ts
+import { formatUsd as formatUsd4 } from "@gachadex/sdk";
+function streamPrinter(json, label) {
+  return (m) => {
+    if (m.ch === "_") return;
+    if (jsonMode(json)) process.stdout.write(JSON.stringify(m) + "\n");
+    else process.stdout.write((label ? label(m) : `${m.ch} ${m.type} ${JSON.stringify(m.data)}`) + "\n");
+  };
+}
+function onSigint(close) {
+  process.on("SIGINT", () => {
+    close();
+    process.exit(0);
+  });
+}
+function registerStream(program2) {
+  withApi(program2.command("watch <markets...>").description("Stream live marks for one or more markets (Ctrl+C to stop)")).action(async (markets, o) => {
+    const dex = makeDex(o.api);
+    const resolved = await Promise.all(markets.map((x) => dex.market(x)));
+    const idToSymbol = new Map(resolved.map((m) => [m.id, m.symbol]));
+    const stream = dex.stream();
+    onSigint(() => stream.close());
+    process.stderr.write(`watching ${resolved.map((m) => m.symbol).join(", ")} \u2026 (Ctrl+C to stop)
+`);
+    stream.subscribe(
+      resolved.map((m) => `mark:${m.id}`),
+      streamPrinter(o.json, (m) => {
+        const id = m.ch.split(":")[1] ?? "";
+        const d = m.data;
+        return `${(idToSymbol.get(id) ?? id).padEnd(24)} ${d.markE6 ? formatUsd4(BigInt(d.markE6)) : "\u2014"}`;
+      })
+    );
+  });
+  withKey(program2.command("events").description("Stream your private events: fills, orders, liquidations, balance (Ctrl+C to stop)")).action(async (o) => {
+    const { dex, session } = await connect(resolveSigner(o), o.api);
+    const stream = dex.stream();
+    onSigint(() => stream.close());
+    process.stderr.write(`streaming account events for ${session.user.pubkey} \u2026 (Ctrl+C to stop)
+`);
+    stream.privateChannels(session, ["positions", "orders", "balance", "liquidations"], streamPrinter(o.json, (m) => `${m.ch.split(":")[0]} ${m.type} ${JSON.stringify(m.data)}`));
+  });
+}
+
+// src/commands/config.ts
+var KEYS = ["apiUrl", "defaultKey"];
+function registerConfig(program2) {
+  const config = program2.command("config").description(`Read/write CLI config (${configDir()}/config.json)`);
+  config.command("get [key]").option("--json", "force JSON output").action((key, o) => {
+    const c = loadConfig();
+    const out = key ? { [key]: c[key] } : c;
+    emit(out, () => key ? String(c[key] ?? "") : KEYS.map((k) => `${k}=${c[k] ?? ""}`).join("\n"), { json: o.json });
+  });
+  config.command("set <key> <value>").action((key, value, o) => {
+    if (!KEYS.includes(key)) throw new CliError(EXIT.VALIDATION, `unknown config key "${key}" (one of: ${KEYS.join(", ")})`, "bad_config_key");
+    const c = loadConfig();
+    c[key] = value;
+    saveConfig(c);
+    emit({ ok: true, [key]: value }, () => `${key} = ${value}`, { json: o.json });
+  });
+}
+
+// src/index.ts
+var program = new Command();
+program.name("gachadex").description("Command-line client for the GachaDex perpetual-futures exchange \u2014 for humans and AI agents.").version("0.1.0", "-v, --version").showSuggestionAfterError(false);
+registerRead(program);
+registerTrade(program);
+registerKeys(program);
+registerStream(program);
+registerConfig(program);
+if (process.argv.slice(2).length === 0) {
+  program.outputHelp();
+  process.exit(EXIT.OK);
+}
+program.exitOverride();
+try {
+  await program.parseAsync(process.argv);
+} catch (err) {
+  if (err instanceof CommanderError) {
+    if (err.code === "commander.version" || err.code.startsWith("commander.help")) process.exit(EXIT.OK);
+    process.exit(EXIT.VALIDATION);
+  }
+  emitError(err);
+  process.exit(exitCodeFor(err));
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "gachadex",
+  "version": "0.1.0",
+  "description": "Command-line client for the GachaDex perpetual-futures exchange — built for humans and AI agents.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "gachadex": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gachadex/cli.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/gachadex/cli/tree/main/packages/cli",
+  "keywords": [
+    "gachadex",
+    "perpetuals",
+    "trading",
+    "solana",
+    "tcg",
+    "cli",
+    "agent"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0",
+    "@gachadex/sdk": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test \"test/**/*.test.ts\""
+  }
+}