blofin-cli 0.1.0

package/README.md

@@ -0,0 +1,176 @@
+# blofin-cli
+
+Agent-first CLI for BloFin exchange. Exposes all 30 tools from `blofin-core` as grouped shell commands.
+
+## Installation
+
+```bash
+npm install -g blofin-cli
+```
+
+## Quick Start
+
+```bash
+# Configure API credentials (interactive)
+blofin setup
+
+# Get ticker prices (table output by default)
+blofin market tickers --instId=BTC-USDT
+
+# JSON output
+blofin market tickers --instId=BTC-USDT -o json
+
+# Use demo trading environment
+blofin --demo market tickers
+```
+
+## Setup
+
+Run the interactive setup wizard to save API credentials to `~/.config/blofin/config.json`:
+
+```bash
+blofin setup
+```
+
+The wizard prompts for API key, secret key, passphrase, and demo mode preference. Existing values are shown masked (`...xxxx`); press Enter to keep them.
+
+Alternatively, use environment variables (they take priority over the config file):
+
+```bash
+export BLOFIN_API_KEY="your-key"
+export BLOFIN_API_SECRET="your-secret"
+export BLOFIN_PASSPHRASE="your-passphrase"
+```
+
+## Usage
+
+```bash
+blofin [flags] <group> <subcommand> [--param=value ...]
+```
+
+### Market Data (no auth required)
+
+```bash
+blofin market tickers --instId=BTC-USDT
+blofin market instruments
+blofin market orderbook --instId=BTC-USDT --size=20
+blofin market candles --instId=BTC-USDT --bar=1H --limit=24
+blofin market mark-price --instId=BTC-USDT
+blofin market trades --instId=BTC-USDT
+blofin market funding-rate --instId=BTC-USDT
+```
+
+### Account
+
+```bash
+blofin account balance --productType=USDT-FUTURES
+blofin account positions
+blofin account config
+blofin account leverage --instId=BTC-USDT --marginMode=cross          # query
+blofin account leverage --instId=BTC-USDT --marginMode=cross --leverage=10  # set
+blofin account margin-mode                                             # query
+blofin account margin-mode --marginMode=cross                          # set
+blofin account position-mode
+```
+
+### Trading
+
+```bash
+# Dangerous operations require --confirm
+blofin trade place --instId=BTC-USDT --side=buy --orderType=market \
+  --size=0.01 --marginMode=cross --positionSide=net --confirm
+
+blofin trade cancel --orderId=123456 --confirm
+
+blofin trade close --instId=BTC-USDT --marginMode=cross \
+  --positionSide=net --confirm
+
+# Read operations
+blofin trade orders --instId=BTC-USDT              # pending orders
+blofin trade orders --orderId=123456                # order detail
+blofin trade orders --status=filled                 # order history
+blofin trade fills --instId=BTC-USDT
+
+# TP/SL and algo orders
+blofin trade tpsl --instId=BTC-USDT --side=sell --marginMode=cross \
+  --positionSide=net --tpTriggerPrice=55000 --tpOrderPrice=-1 --size=-1
+blofin trade tpsl-orders --instId=BTC-USDT
+blofin trade cancel-tpsl --tpslId=123456
+blofin trade algo --instId=BTC-USDT --orderType=trigger \
+  --side=buy --size=0.01 --triggerPrice=50000 --marginMode=cross --positionSide=net
+blofin trade algo-orders --orderType=trigger
+blofin trade cancel-algo --algoId=123456
+```
+
+### Assets
+
+```bash
+blofin asset balances --accountType=futures
+blofin asset transfer --currency=USDT --fromAccount=funding \
+  --toAccount=futures --amount=100 --confirm
+blofin asset bills
+blofin asset deposits
+blofin asset withdrawals
+blofin asset apikey-info
+```
+
+## Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--help` | Show help (global or per-group) |
+| `--version` | Show version |
+| `-o, --output <format>` | Output format: `table` (default) or `json` |
+| `--demo` | Use demo trading environment |
+| `--confirm` | Required for dangerous operations |
+| `--read-only` | Only expose read-level tools |
+| `--modules=<list>` | Comma-separated module filter (e.g. `public,account`) |
+
+## Output Formats
+
+### Table (default)
+
+```
+┌────────────┬──────────┬──────────┐
+│ instId     │ last     │ vol24h   │
+├────────────┼──────────┼──────────┤
+│ BTC-USDT   │ 67000.5  │ 12345.67 │
+└────────────┴──────────┴──────────┘
+```
+
+### JSON (`-o json`)
+
+```json
+{
+  "tool": "get_tickers",
+  "ok": true,
+  "data": { "code": "0", "data": [...] },
+  "timestamp": 1700000000000
+}
+```
+
+## Credential Resolution
+
+Priority (highest to lowest):
+
+1. **Environment variables** — `BLOFIN_API_KEY`, `BLOFIN_API_SECRET`, `BLOFIN_PASSPHRASE`
+2. **Config file** — `~/.config/blofin/config.json` (created by `blofin setup`)
+3. **Defaults** — empty strings (public endpoints only)
+
+The `--demo` flag and `BLOFIN_BASE_URL` env var control which environment is used:
+
+| Condition | Base URL |
+|-----------|----------|
+| `--demo` flag | `https://demo-trading-openapi.blofin.com` |
+| `demo: true` in config | `https://demo-trading-openapi.blofin.com` |
+| `BLOFIN_BASE_URL` set | Uses that URL (overrides all) |
+| Otherwise | `https://openapi.blofin.com` (production) |
+
+## Command Groups
+
+| Group | Description | Subcommands |
+|-------|-------------|-------------|
+| `market` | Market data (public) | `instruments`, `tickers`, `orderbook`, `trades`, `candles`, `mark-price`, `funding-rate` |
+| `account` | Account information | `balance`, `positions`, `config`, `leverage`, `margin-mode`, `position-mode` |
+| `trade` | Trading operations | `place`, `cancel`, `close`, `orders`, `tpsl`, `cancel-tpsl`, `tpsl-orders`, `algo`, `cancel-algo`, `algo-orders`, `fills` |
+| `asset` | Asset management | `balances`, `transfer`, `bills`, `deposits`, `withdrawals`, `apikey-info` |

package/dist/chunk-ZOIYPWGU.js

@@ -0,0 +1,53 @@
+// src/config.ts
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { DEMO_BASE_URL, PROD_BASE_URL } from "blofin-core";
+function configDir() {
+  return join(homedir(), ".config", "blofin");
+}
+function configFile() {
+  return join(configDir(), "config.json");
+}
+function getConfigPath() {
+  return configFile();
+}
+function defaultConfig() {
+  return { apiKey: "", secretKey: "", passphrase: "", demo: false };
+}
+function loadCliConfig() {
+  try {
+    const raw = readFileSync(configFile(), "utf-8");
+    const parsed = JSON.parse(raw);
+    return {
+      apiKey: typeof parsed.apiKey === "string" ? parsed.apiKey : "",
+      secretKey: typeof parsed.secretKey === "string" ? parsed.secretKey : "",
+      passphrase: typeof parsed.passphrase === "string" ? parsed.passphrase : "",
+      demo: typeof parsed.demo === "boolean" ? parsed.demo : false
+    };
+  } catch {
+    return defaultConfig();
+  }
+}
+function saveCliConfig(config) {
+  mkdirSync(configDir(), { recursive: true, mode: 448 });
+  writeFileSync(configFile(), JSON.stringify(config, null, 2) + "\n", {
+    mode: 384
+  });
+}
+function resolveCredentials(flags) {
+  const fileConfig = loadCliConfig();
+  const apiKey = process.env.BLOFIN_API_KEY ?? fileConfig.apiKey ?? "";
+  const secretKey = process.env.BLOFIN_API_SECRET ?? fileConfig.secretKey ?? "";
+  const passphrase = process.env.BLOFIN_PASSPHRASE ?? fileConfig.passphrase ?? "";
+  const demo = flags.demo ?? fileConfig.demo;
+  const baseUrl = process.env.BLOFIN_BASE_URL ?? (demo ? DEMO_BASE_URL : PROD_BASE_URL);
+  return { apiKey, secretKey, passphrase, baseUrl };
+}
+
+export {
+  getConfigPath,
+  loadCliConfig,
+  saveCliConfig,
+  resolveCredentials
+};

package/dist/index.js

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+import {
+  resolveCredentials
+} from "./chunk-ZOIYPWGU.js";
+
+// src/index.ts
+import { fileURLToPath } from "url";
+import { resolve } from "path";
+import { readFileSync } from "fs";
+import { parseArgs } from "util";
+import {
+  ALL_MODULES,
+  buildTools,
+  loadConfig,
+  BlofinClient
+} from "blofin-core";
+
+// src/commands.ts
+function group(description, commands) {
+  const map = /* @__PURE__ */ new Map();
+  for (const [sub, toolName, desc, risk] of commands) {
+    map.set(sub, { toolName, description: desc, riskLevel: risk });
+  }
+  return { description, commands: map };
+}
+var COMMAND_GROUPS = /* @__PURE__ */ new Map([
+  [
+    "market",
+    group("Market data (public)", [
+      ["instruments", "get_instruments", "List available instruments", "read"],
+      ["tickers", "get_tickers", "Get ticker prices", "read"],
+      ["orderbook", "get_order_book", "Get order book depth", "read"],
+      ["trades", "get_market_trades", "Get recent trades", "read"],
+      ["candles", "get_candlesticks", "Get candlestick/kline data", "read"],
+      ["mark-price", "get_mark_price", "Get mark price", "read"],
+      ["funding-rate", "get_funding_rate", "Get funding rate", "read"]
+    ])
+  ],
+  [
+    "account",
+    group("Account information", [
+      ["balance", "get_balance", "Get account balance", "read"],
+      ["positions", "get_positions", "Get open positions", "read"],
+      ["config", "get_account_config", "Get account configuration", "read"],
+      ["leverage", "manage_leverage", "Get or set leverage", "write"],
+      ["margin-mode", "manage_margin_mode", "Get or set margin mode", "write"],
+      ["position-mode", "manage_position_mode", "Get or set position mode", "write"]
+    ])
+  ],
+  [
+    "trade",
+    group("Trading operations", [
+      ["place", "place_order", "Place a new order", "dangerous"],
+      ["cancel", "cancel_order", "Cancel an order", "dangerous"],
+      ["close", "close_position", "Close a position", "dangerous"],
+      ["orders", "get_orders", "Get order list", "read"],
+      ["tpsl", "place_tpsl", "Place take-profit/stop-loss", "write"],
+      ["cancel-tpsl", "cancel_tpsl", "Cancel TP/SL order", "write"],
+      ["tpsl-orders", "get_tpsl_orders", "Get TP/SL orders", "read"],
+      ["algo", "place_algo_order", "Place an algo order", "write"],
+      ["cancel-algo", "cancel_algo_order", "Cancel an algo order", "write"],
+      ["algo-orders", "get_algo_orders", "Get algo orders", "read"],
+      ["fills", "get_fills_history", "Get fill history", "read"]
+    ])
+  ],
+  [
+    "asset",
+    group("Asset management", [
+      ["balances", "get_asset_balances", "Get asset balances", "read"],
+      ["transfer", "fund_transfer", "Transfer between accounts", "dangerous"],
+      ["bills", "get_transfer_history", "Get transfer history", "read"],
+      ["deposits", "get_deposit_history", "Get deposit history", "read"],
+      ["withdrawals", "get_withdrawal_history", "Get withdrawal history", "read"],
+      ["apikey-info", "get_apikey_info", "Get API key info", "read"]
+    ])
+  ]
+]);
+function resolveCommand(groupName, subcommand) {
+  return COMMAND_GROUPS.get(groupName)?.commands.get(subcommand);
+}
+
+// src/output.ts
+import Table from "cli-table3";
+import { toToolResponse, toToolError } from "blofin-core";
+function outputTable(rows, columns, title) {
+  if (rows.length === 0) return title ? `${title}
+(no data)` : "(no data)";
+  const cols = columns ?? Object.keys(rows[0]);
+  const table = new Table({ head: [...cols] });
+  for (const row of rows) {
+    table.push(cols.map((c) => String(row[c] ?? "")));
+  }
+  const rendered = table.toString();
+  return title ? `${title}
+${rendered}` : rendered;
+}
+function outputResult(toolName, data, format) {
+  if (format === "json") {
+    return JSON.stringify(toToolResponse(toolName, data), null, 2);
+  }
+  const rows = extractRows(data);
+  if (rows.length > 0) {
+    return outputTable(rows);
+  }
+  return JSON.stringify(data, null, 2);
+}
+function outputError(toolName, error, format) {
+  if (format === "json") {
+    return JSON.stringify(toToolError(toolName, error), null, 2);
+  }
+  const msg = error instanceof Error ? error.message : String(error);
+  return `Error: ${msg}`;
+}
+function extractRows(data) {
+  if (data == null || typeof data !== "object") return [];
+  const envelope = data;
+  const inner = envelope.data;
+  if (Array.isArray(inner) && inner.length > 0 && isRecord(inner[0])) {
+    return inner;
+  }
+  if (isRecord(inner)) {
+    return [inner];
+  }
+  if (Array.isArray(data) && data.length > 0 && isRecord(data[0])) {
+    return data;
+  }
+  return [];
+}
+function isRecord(v) {
+  return v != null && typeof v === "object" && !Array.isArray(v);
+}
+
+// src/index.ts
+var CLI_VERSION = (() => {
+  const pkgPath = new URL("../package.json", import.meta.url);
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+  return pkg.version;
+})();
+var VALID_MODULES = new Set(ALL_MODULES);
+var CLI_FLAGS = /* @__PURE__ */ new Set([
+  "help",
+  "version",
+  "read-only",
+  "confirm",
+  "modules",
+  "output",
+  "demo"
+]);
+function formatGlobalHelp() {
+  const lines = [
+    `blofin-cli v${CLI_VERSION}`,
+    "",
+    "Usage: blofin [flags] <group> <subcommand> [--param=value ...]",
+    "",
+    "Groups:"
+  ];
+  for (const [name, group2] of COMMAND_GROUPS) {
+    lines.push(`  ${name.padEnd(12)} ${group2.description}`);
+  }
+  lines.push(
+    "",
+    "Commands:",
+    "  setup          Configure API credentials",
+    "",
+    "Global flags:",
+    "  --help         Show help",
+    "  --version      Show version",
+    "  -o, --output   Output format: table (default) | json",
+    "  --demo         Use demo trading environment",
+    "  --read-only    Exclude write/dangerous tools",
+    "  --confirm      Allow dangerous operations",
+    "  --modules      Comma-separated module filter",
+    "",
+    "Run 'blofin <group> --help' for subcommand details."
+  );
+  return lines.join("\n");
+}
+function formatGroupHelp(groupName) {
+  const group2 = COMMAND_GROUPS.get(groupName);
+  if (!group2) return `Unknown group: ${groupName}`;
+  const lines = [
+    `blofin ${groupName} \u2014 ${group2.description}`,
+    "",
+    "Subcommands:"
+  ];
+  const maxSub = Math.max(
+    ...[...group2.commands.keys()].map((k) => k.length)
+  );
+  for (const [sub, cmd] of group2.commands) {
+    const tag = `[${cmd.riskLevel}]`;
+    lines.push(`  ${sub.padEnd(maxSub + 2)} ${tag.padEnd(14)} ${cmd.description}`);
+  }
+  return lines.join("\n");
+}
+function parseModules(raw) {
+  const ids = raw.split(",");
+  const invalid = ids.filter((id) => !VALID_MODULES.has(id));
+  if (invalid.length > 0) {
+    return `Invalid module(s): ${invalid.join(", ")}. Valid modules: ${ALL_MODULES.join(", ")}`;
+  }
+  return ids;
+}
+var SHORT_VALUE_FLAGS = /* @__PURE__ */ new Map([
+  ["-o", "output"]
+]);
+function expandShortFlags(args) {
+  const result = [];
+  for (let i = 0; i < args.length; i++) {
+    const longName = SHORT_VALUE_FLAGS.get(args[i]);
+    if (longName && i + 1 < args.length) {
+      result.push(`--${longName}=${args[i + 1]}`);
+      i++;
+    } else {
+      result.push(args[i]);
+    }
+  }
+  return result;
+}
+async function runCli(args) {
+  const normalizedArgs = expandShortFlags(args);
+  const { values, positionals } = parseArgs({
+    args: normalizedArgs,
+    strict: false,
+    allowPositionals: true
+  });
+  const help = values["help"] === true;
+  const version = values["version"] === true;
+  const readOnly = values["read-only"] === true;
+  const confirm = values["confirm"] === true;
+  const demo = values["demo"] === true ? true : void 0;
+  const modulesRaw = typeof values["modules"] === "string" ? values["modules"] : void 0;
+  const outputFlag = typeof values["output"] === "string" ? values["output"] : void 0;
+  const format = outputFlag === "json" ? "json" : "table";
+  if (version) {
+    return { output: CLI_VERSION, ok: true };
+  }
+  let modules;
+  if (modulesRaw) {
+    const parsed = parseModules(modulesRaw);
+    if (typeof parsed === "string") {
+      return {
+        output: outputError("cli", new Error(parsed), format),
+        ok: false
+      };
+    }
+    modules = parsed;
+  }
+  if (positionals.length === 0 || help && positionals.length === 0) {
+    return { output: formatGlobalHelp(), ok: true };
+  }
+  const first = positionals[0];
+  if (first === "setup") {
+    const { runSetup } = await import("./setup-2N757DQH.js");
+    return runSetup();
+  }
+  const groupName = first;
+  const group2 = COMMAND_GROUPS.get(groupName);
+  if (!group2) {
+    return {
+      output: outputError(
+        "cli",
+        new Error(`Unknown command: ${first}. Run 'blofin --help' for usage.`),
+        format
+      ),
+      ok: false
+    };
+  }
+  if (help || positionals.length < 2) {
+    return { output: formatGroupHelp(groupName), ok: true };
+  }
+  const subcommand = positionals[1];
+  const cmdDef = resolveCommand(groupName, subcommand);
+  if (!cmdDef) {
+    return {
+      output: outputError(
+        "cli",
+        new Error(
+          `Unknown subcommand: ${groupName} ${subcommand}. Run 'blofin ${groupName} --help' for available subcommands.`
+        ),
+        format
+      ),
+      ok: false
+    };
+  }
+  const creds = resolveCredentials({ demo });
+  const config = loadConfig({
+    modules,
+    readOnly,
+    apiKey: creds.apiKey,
+    secretKey: creds.secretKey,
+    passphrase: creds.passphrase,
+    baseUrl: creds.baseUrl
+  });
+  const tools = buildTools(config);
+  const tool = tools.find((t) => t.name === cmdDef.toolName);
+  if (!tool) {
+    return {
+      output: outputError(
+        cmdDef.toolName,
+        new Error(
+          `Tool '${cmdDef.toolName}' not available (may be excluded by --read-only or --modules).`
+        ),
+        format
+      ),
+      ok: false
+    };
+  }
+  if (tool.riskLevel === "dangerous" && !confirm) {
+    return {
+      output: outputError(
+        tool.name,
+        new Error(
+          `Command '${groupName} ${subcommand}' is dangerous. Use --confirm to execute.`
+        ),
+        format
+      ),
+      ok: false
+    };
+  }
+  const params = {};
+  for (const [key, value] of Object.entries(values)) {
+    if (CLI_FLAGS.has(key)) continue;
+    params[key] = value;
+  }
+  const client = new BlofinClient(config);
+  const ctx = { client, config };
+  try {
+    const result = await tool.handler(params, ctx);
+    return {
+      output: outputResult(tool.name, result, format),
+      ok: true
+    };
+  } catch (error) {
+    return {
+      output: outputError(tool.name, error, format),
+      ok: false
+    };
+  }
+}
+function isMainModule() {
+  if (typeof process === "undefined" || !process.argv[1]) {
+    return false;
+  }
+  const self = fileURLToPath(import.meta.url);
+  const invoked = resolve(process.argv[1]);
+  return self === invoked;
+}
+if (isMainModule()) {
+  runCli(process.argv.slice(2)).then(({ output, ok }) => {
+    if (output) console.log(output);
+    if (!ok) process.exit(1);
+  }).catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}
+export {
+  runCli
+};

package/dist/setup-2N757DQH.js

@@ -0,0 +1,50 @@
+import {
+  getConfigPath,
+  loadCliConfig,
+  saveCliConfig
+} from "./chunk-ZOIYPWGU.js";
+
+// src/setup.ts
+import { createInterface } from "readline/promises";
+function mask(value) {
+  if (value.length <= 4) return value ? "****" : "(not set)";
+  return `...${value.slice(-4)}`;
+}
+async function runSetup() {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stderr
+  });
+  try {
+    const current = loadCliConfig();
+    process.stderr.write("\nBloFin CLI Setup\n");
+    process.stderr.write(`Config file: ${getConfigPath()}
+
+`);
+    const apiKey = await promptField(rl, "API Key", current.apiKey);
+    const secretKey = await promptField(rl, "Secret Key", current.secretKey);
+    const passphrase = await promptField(rl, "Passphrase", current.passphrase);
+    const demoAnswer = await rl.question(
+      `Use demo trading? [${current.demo ? "Y/n" : "y/N"}]: `
+    );
+    const demo = demoAnswer.trim() === "" ? current.demo : demoAnswer.trim().toLowerCase().startsWith("y");
+    const config = { apiKey, secretKey, passphrase, demo };
+    saveCliConfig(config);
+    const msg = `
+Config saved to ${getConfigPath()}
+`;
+    process.stderr.write(msg);
+    return { output: "", ok: true };
+  } finally {
+    rl.close();
+  }
+}
+async function promptField(rl, label, current) {
+  const answer = await rl.question(
+    `${label} [${mask(current)}]: `
+  );
+  return answer.trim() || current;
+}
+export {
+  runSetup
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "blofin-cli",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "blofin": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "blofin-core": "^0.2.2",
+    "cli-table3": "^0.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT"
+}