@2bad/walt 1.0.1 → 2.1.0

package/README.md

@@ -21,6 +21,9 @@ npm install @2bad/walt
 
 ESM only. Requires Node.js 26 or later.
 
+`@2bad/walt/client` exports everything except `TelegramTokenSource`.
+It imports no Node.js API and no Telegram library, for runtimes such as Cloudflare Workers.
+
 ## Quick start
 
 ```ts
@@ -36,12 +39,13 @@ await source.disconnect()
 
 ## Examples
 
-- [Connecting](examples/connecting.md): Telegram credentials, token storage, retries and pacing
+- [Connecting](examples/connecting.md): Telegram credentials, token storage, refreshing without Telegram, retries and pacing
 - [Balances](examples/balances.md): accounts, portfolio, profit and loss, staked funds
 - [Prices](examples/prices.md): coin rates, charts and past prices
 - [Exchange](examples/exchange.md): available pairs, quotes, exchanges and limit orders
 - [Transactions](examples/transactions.md): history, details and reading a transaction
 - [Errors](examples/errors.md): `WaltRequestError`, `WaltAuthError` and what is retried
+- [Command line](examples/cli.md): the read-only `walt` command for balances, history, prices and orders
 
 A runnable script is in [examples/portfolio.ts](examples/portfolio.ts).
 
@@ -55,11 +59,18 @@ type TelegramTokenSource = {
   disconnect(): Promise<void>
 }
 
+new RefreshTokenSource(options: RefreshTokenSourceOptions)
+
+type RefreshTokenSource = {
+  token(rejected?: string): Promise<string>
+}
+
 new WaltClient(options: WaltClientOptions)
 
 type WaltClient = {
   accounts(): Promise<AccountsResponse>
   portfolio(): Promise<Portfolio>
+  balances(fiatCurrency: FiatCurrency): Promise<Balances>
   pnl(): Promise<PnlResponse>
   portfolioHistory(dateFrom: Date | string, resolution: '1d' | '1m'): Promise<PortfolioHistory>
   frozenBalances<T = unknown>(): Promise<T[]>
@@ -74,6 +85,7 @@ type WaltClient = {
   charts(currency: string, fiatCurrency: FiatCurrency): Promise<Charts>
   priceForFiatAtTime(crypto: string, fiat: FiatCurrency, amount: number | string, time: Date | string | number): Promise<PriceAtTime>
   localCurrency(): Promise<FiatCurrency>
+  candles(requests: CandleRequest[]): Promise<CandleSeries[]>
 
   availableExchanges(): Promise<AvailableExchanges>
   quote(fromCurrency: string, toCurrency: string, fromAmount: number): Promise<ExchangeQuote>
@@ -85,6 +97,11 @@ type WaltClient = {
   limitOrderBounds(baseCurrency: string): Promise<LimitOrderBounds>
   limitOrderTokens(): Promise<LimitOrderToken[]>
 
+  perpContracts(contractId?: number): Promise<PerpContract[]>
+  perpSystemStatus(): Promise<PerpSystemStatus>
+  perpPositions(options?: { statuses?: PerpPositionStatus[]; contractId?: number }): Promise<PerpPosition[]>
+  perpOrders(options?: { contractId?: number; statuses?: PerpOrderStatus[]; limit?: number }): Promise<PerpOrdersPage>
+
   transactions(limit?: number, cursor?: string): Promise<TransactionsPage>
   accountTransactions(currency: string, limit?: number, cursor?: string): Promise<TransactionsPage>
   allTransactions(limit?: number): AsyncGenerator<Transaction>

package/build/api/balances.d.ts

@@ -0,0 +1,23 @@
+export type Balance = {
+  /** `REGULAR` for spot, `HOLD_LIMIT` for USDT reserved by open limit orders, `EARN_V2` for staked funds. */
+  account_type: string;
+  currency: string;
+  asset_currency: string;
+  total_balance: string;
+  available_balance: string;
+  balance_hold: string;
+  is_always_on_main: boolean;
+  category: string;
+  rate_to_fiat: string;
+  rate_to_usd: string;
+  available_balance_fiat_amount: string;
+  available_balance_usd_amount: string;
+};
+export type Balances = {
+  accounts: Balance[];
+  fiat_currency: string;
+  /** Spot, staked and limit order holds together. */
+  overall_available_balance_fiat_amount: string;
+  /** Also `true` when the perps account has no open position. */
+  has_open_perp_position: boolean;
+};

package/build/api/balances.js

@@ -0,0 +1 @@
+export {};

package/build/api/candles.d.ts

@@ -0,0 +1,22 @@
+export type CandleRequest = {
+  /** `<currency>/USD/SPOT`, or `<base>/USD/PERP_TRADE` for a perps contract. */
+  ticker: string;
+  /** Accepted: `1m`, `5m`, `15m`, `1h`, `4h`, `1d`, `1w`, `1mo`. */
+  resolution: string;
+  /** At least 1. The whole batch may ask for 3000 candles at most. */
+  limit: number;
+};
+export type Candle = {
+  o: string;
+  h: string;
+  l: string;
+  c: string;
+  v: string;
+};
+export type CandleSeries = {
+  ticker: string;
+  resolution: string;
+  /** Opening time of the first candle, in ms. */
+  start_ts: number;
+  candles: Candle[];
+};

package/build/api/candles.js

@@ -0,0 +1 @@
+export {};

package/build/api/perps.d.ts

@@ -0,0 +1,155 @@
+export type PerpContract = {
+  contract_id: number;
+  contract_name: string;
+  base_asset: string;
+  quote_asset: string;
+  venue_status: string;
+  is_active: boolean;
+  price_decimals: number;
+  size_decimals: number;
+  tick_size: string;
+  step_size: string;
+  min_size_base: string;
+  max_size_base: string;
+  max_size_quote: string;
+  min_size_quote: string;
+  max_leverage: number;
+  maker_fee_pct: string;
+  taker_fee_pct: string;
+  base_taker_fee_pct: string;
+  taker_fee_subscription_id: number;
+  price_slippage: string;
+  tpsl_buffer_pct: string;
+  funding_rate_hourly: string;
+  next_funding_at: string;
+  open_interest_usd: string;
+  volume_24h_usd: string;
+  trading_hours_state: unknown;
+  market_data: {
+    server_time: string;
+    /** `fresh`, or `stale` with both prices `null`. */
+    status: string;
+    mark_price: string | null;
+    index_price: string | null;
+    source_timestamp: string;
+    expires_at: string;
+  };
+  /** Fractions in basis points: `1000` is 10%, so 10x leverage. */
+  margin: {
+    default_initial_margin_fraction: number;
+    min_initial_margin_fraction: number;
+    maintenance_margin_fraction: number;
+    closeout_margin_fraction: number;
+  };
+};
+export type PerpSystemStatus = {
+  actions: {
+    open_enabled: boolean;
+    cancel_enabled: boolean;
+    close_enabled: boolean;
+    add_margin_enabled: boolean;
+    remove_margin_enabled: boolean;
+    auto_close_enabled: boolean;
+  };
+  exchange_status: {
+    exchange_partner_tech_name: string;
+    operational_state: string;
+    is_trading_halted: boolean;
+    message: unknown;
+    current_status: unknown;
+    upcoming_maintenance: unknown;
+    last_changed_at: string;
+    last_checked_at: string;
+  };
+};
+export type PerpOrdersPage = {
+  orders: PerpOrder[];
+  next_cursor: unknown;
+  /** `sort_ts` of the last order on the page, `null` on an empty page. */
+  last_sort_ts: string | null;
+};
+export type PerpPositionStatus = 'open' | 'closed';
+export type PerpOrderStatus = 'pending' | 'processing' | 'processed' | 'filled' | 'partially_filled' | 'failed' | 'canceled';
+type PerpPositionCore = {
+  contract_id: number;
+  contract_name: string;
+  contract_base_asset: string;
+  contract_quote_asset: string;
+  /** Seen: `long`, `short`. */
+  side: string;
+  /** Seen: `closed`. */
+  status: string;
+  leverage: number;
+  /** Seen: `isolated`. */
+  margin_type: string;
+  value_base: string;
+  margin_quote: string;
+  avg_entry_price: string;
+  liquidation_price: string;
+  funding_paid_quote: string;
+  created_at: string;
+  updated_at: string;
+  synced_at: string;
+};
+export type PerpPosition = PerpPositionCore & {
+  trading_agent_code: string;
+  /** Priced at the current mark, closed positions included, so it is not the P/L a closed position realised. */
+  valuation: {
+    server_time: string;
+    status: string;
+    mark_price: string;
+    index_price: string;
+    source_timestamp: string;
+    expires_at: string;
+    unrealized_pnl_quote: string;
+    equity_quote: string;
+  };
+  auto_close: unknown;
+};
+export type PerpOrder = {
+  order_id: string;
+  contract_id: number;
+  contract_name: string;
+  contract_base_asset: string;
+  contract_quote_asset: string;
+  side: string;
+  /** Seen: `market`. */
+  type: string;
+  /** Seen: `open`, `close`, `stop_loss`, `take_profit`. */
+  category: string;
+  status: string;
+  error_code: unknown;
+  leverage: number;
+  base_size: string;
+  base_price: string;
+  accounting_base_amount: string;
+  accounting_quote_amount: string;
+  filled_price: string | null;
+  filled_base_amount: string | null;
+  filled_quote_amount: string | null;
+  pnl_quote: string | null;
+  pnl_quote_charged: unknown;
+  roi: string | null;
+  trigger_price_quote: string | null;
+  limit_price_quote: string | null;
+  /** Unix seconds. */
+  valid_to: number | null;
+  liquidation_fee: unknown;
+  liquidation_fee_charged: unknown;
+  integrator_fee: string | null;
+  integrator_fee_charged: string | null;
+  venue_fee: string | null;
+  total_fee: string | null;
+  total_fee_charged: string | null;
+  margin_returned_amount: string | null;
+  created_at: string;
+  updated_at: string;
+  filled_at: string | null;
+  canceled_at: unknown;
+  sort_ts: string;
+  position: PerpPositionCore & {
+    fee_quote: unknown;
+    close_price: string;
+  };
+};
+export {};

package/build/api/perps.js

@@ -0,0 +1 @@
+export {};

package/build/bin/quiet-localstorage.js

@@ -0,0 +1,8 @@
+// source/bin/quiet-localstorage.ts
+const nodeOptions = (process.env["NODE_OPTIONS"] ?? "").split(/\s+/);
+if (![...process.execArgv, ...nodeOptions].some((arg) => arg.startsWith("--localstorage-file"))) Object.defineProperty(globalThis, "localStorage", {
+	value: void 0,
+	configurable: true,
+	writable: true
+});
+export {};

package/build/bin/walt.d.ts

@@ -0,0 +1 @@
+export {}

package/build/bin/walt.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+import "./quiet-localstorage.js";
+import { COMMANDS, UsageError, run } from "../cli/run.js";
+import { WaltClient } from "../client.js";
+import { TelegramTokenSource } from "../telegram/auth.js";
+import { WaltAuthError, WaltRequestError } from "../transport.js";
+import { TelegramClient } from "teleproto";
+import { StringSession } from "teleproto/sessions/index.js";
+import { readFileSync } from "node:fs";
+import { stdin, stdout } from "node:process";
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "node:util";
+// source/bin/walt.ts
+/**
+* Signs in to Telegram interactively and prints the session string to save as `TG_SESSION`.
+*
+* @returns The process exit code.
+*/
+const login = async () => {
+	const rl = createInterface({
+		input: stdin,
+		output: stdout
+	});
+	const ask = (question) => rl.question(question);
+	const apiId = Number(process.env["TG_API_ID"] || await ask("API id (from https://my.telegram.org): "));
+	if (!Number.isSafeInteger(apiId) || apiId <= 0) {
+		rl.close();
+		console.error("The API id must be the number shown at https://my.telegram.org");
+		return 1;
+	}
+	const apiHash = process.env["TG_API_HASH"] || await ask("API hash: ");
+	const client = new TelegramClient(new StringSession(""), apiId, apiHash, { connectionRetries: 3 });
+	await client.start({
+		phoneNumber: () => ask("Phone (+country...): "),
+		phoneCode: () => ask("Code you received: "),
+		password: () => ask("2FA password (blank if none): "),
+		onError: (error) => console.error(error)
+	});
+	rl.close();
+	console.log("\nLogged in. Save this as TG_SESSION (keep it secret):\n");
+	console.log(client.session.save());
+	await client.disconnect();
+	return 0;
+};
+const USAGE = `Usage: walt <command> [options]
+
+${COMMANDS}
+  login                     sign in to Telegram and print TG_SESSION
+  token                     sign in as a new device and print its token state as JSON
+
+Options:
+  --json                    print JSON instead of a table
+  --fiat CODE               currency for values (default USD)
+  --env-file PATH           read TG_API_ID, TG_API_HASH and TG_SESSION from a file
+  -h, --help                show this help
+  -v, --version             show the version
+
+Needs TG_API_ID and TG_API_HASH from https://my.telegram.org and TG_SESSION from \`walt login\`.
+Every command is read-only.`;
+const fail = (message, code) => {
+	console.error(`walt: ${message}`);
+	process.exit(code);
+};
+const parse = () => {
+	try {
+		return parseArgs({
+			allowPositionals: true,
+			options: {
+				json: { type: "boolean" },
+				fiat: { type: "string" },
+				"env-file": { type: "string" },
+				asset: { type: "string" },
+				limit: { type: "string" },
+				from: { type: "string" },
+				monthly: { type: "boolean" },
+				all: { type: "boolean" },
+				closed: { type: "boolean" },
+				help: {
+					type: "boolean",
+					short: "h"
+				},
+				version: {
+					type: "boolean",
+					short: "v"
+				}
+			}
+		});
+	} catch (error) {
+		return fail(`${error.message}\nRun \`walt --help\` for usage.`, 2);
+	}
+};
+const { values, positionals } = parse();
+const [command, ...args] = positionals;
+if (values.version) {
+	const manifest = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+	console.log(manifest.version);
+	process.exit(0);
+}
+if (values.help || command === void 0) {
+	console.log(USAGE);
+	process.exit(command === void 0 && !values.help ? 2 : 0);
+}
+if (values["env-file"] !== void 0) try {
+	process.loadEnvFile(values["env-file"]);
+} catch (error) {
+	fail(`cannot read ${values["env-file"]}: ${error.message}`, 2);
+}
+if (command === "login") process.exit(await login());
+const session = process.env["TG_SESSION"];
+const apiId = Number(process.env["TG_API_ID"]);
+const apiHash = process.env["TG_API_HASH"];
+if (!session || !apiId || !apiHash) fail("set TG_API_ID, TG_API_HASH and TG_SESSION first (run `walt login` for the session)", 2);
+if (command === "token") console.log = console.error;
+let issued = null;
+const source = new TelegramTokenSource({
+	session: session ?? "",
+	apiId,
+	apiHash: apiHash ?? "",
+	...command === "token" && { storage: {
+		load: async () => null,
+		save: async (state) => {
+			issued = state;
+		}
+	} }
+});
+const client = new WaltClient({ tokenProvider: (rejected) => source.token(rejected) });
+let exitCode = 0;
+try {
+	if (command === "token") {
+		await source.token();
+		stdout.write(`${JSON.stringify(issued)}\n`);
+	} else console.log(await run(client, command, args, values));
+} catch (error) {
+	if (error instanceof UsageError) {
+		console.error(`walt: ${error.message}\nRun \`walt --help\` for usage.`);
+		exitCode = 2;
+	} else if (error instanceof WaltRequestError) {
+		const code = error.body?.code;
+		console.error(`walt: ${error.message}${typeof code === "string" ? ` (${code})` : ""}`);
+		exitCode = 1;
+	} else if (error instanceof WaltAuthError) {
+		console.error(`walt: sign-in failed: ${error.message}`);
+		exitCode = 1;
+	} else {
+		console.error(`walt: ${error instanceof Error ? error.message : String(error)}`);
+		exitCode = 1;
+	}
+} finally {
+	await source.disconnect();
+}
+process.exit(exitCode);
+export {};

package/build/cli/run.d.ts

@@ -0,0 +1,22 @@
+import { WaltClient } from "../client.js";
+export type CliOptions = {
+  json?: boolean;
+  fiat?: string;
+  asset?: string;
+  limit?: string;
+  from?: string;
+  monthly?: boolean;
+  all?: boolean;
+  closed?: boolean;
+};
+export declare class UsageError extends Error {}
+export declare const COMMANDS = "Commands:\n  balances [--all]          every asset: spot, staked and held by limit orders,\n                            and with --all the ones worth less than 0.01\n  history [--monthly]       balance, deposits, withdrawals and P/L per day or month\n          [--from DATE]     start date, YYYY-MM-DD (default: 30 days or 12 months back)\n  transactions              latest transactions\n          [--asset SYM]     only this asset\n          [--limit N]       how many (default 20)\n  price SYM...              current price and change over 24h, 7d and 30d\n  quote FROM TO AMOUNT      what an exchange would give right now, without making it\n  orders [--all]            open limit orders, or every order with --all\n  perps [--closed]          open perpetual positions, or closed ones\n  earn [--all]              your earn stakes, or every active campaign with --all";
+/**
+ * Runs one read-only command and returns what to print.
+ *
+ * @param client - A signed-in client.
+ * @param command - The command name, such as `balances`.
+ * @param args - Positional arguments after the command.
+ * @param options - Parsed flags.
+ */
+export declare const run: (client: WaltClient, command: string, args: string[], options?: CliOptions) => Promise<string>;