@thirdfy/agent-cli 0.2.14 → 0.2.16

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.2.16] - 2026-06-30
+
+### Added
+
+- `credits` command group: `balance`, `transactions` (with `includeMetadata`), `usage`, `models list`, `models estimate`, and `pricing quote`. Passes `toolCallsList` into pricing estimate for action-tier line items. Pairs with Thirdfy API **v3.8.2+** and `thirdfy-mcp` **v0.0.65+**.
+
+## [0.2.15] - 2026-06-26
+
+### Added
+
+- Hummingbot API provider: `hummingbot` command group (`status`, `connectors`, `executor-schema`, `executor-create`) and provider runbook [`docs/providers/hummingbot.md`](./docs/providers/hummingbot.md). Pairs with Thirdfy API **v3.6.0+** (governed `/api/v1/agent/hummingbot/*` proxy) and `thirdfy-mcp` **v0.0.64+**.
+
 ## [0.2.14] - 2026-06-24
 
 ### Changed

package/README.md

@@ -40,9 +40,9 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## What's new in v0.2.14
+## What's new in v0.2.16
 
-- HTTP client retries once on Thirdfy API **502/503/504** and client timeouts (bounded `AbortController`), so PostgREST outages surface as transient failures instead of hanging Hermes read cycles. Pairs with Thirdfy API **v3.5.6+**.
+- `credits` commands for balance, transactions (optional billing metadata), usage summary, model pricing, turn estimate, and action quote. Pairs with Thirdfy API **v3.8.2+** and `thirdfy-mcp` **v0.0.65+**.
 
 Older versions: see [CHANGELOG.md](./CHANGELOG.md) and [GitHub Releases](https://github.com/thirdfy/agent-cli/releases).
 
@@ -304,6 +304,7 @@ Provider and venue guides are kept outside `README` so this page stays stable as
 - Discovery: `catalogs list`, `actions` (optional `--provider`, `--chain-id`; see [`docs/command-reference.md`](./docs/command-reference.md) for trading vs earn vs prediction providers and case-insensitive matching)
 - Execution: `preflight`, `run`, `intent-status`, `jeff preflight`, `jeff trade`, `jeff status`
 - Polymarket: `polymarket status`, `polymarket setup`, `polymarket dry-run`
+- Hummingbot: `hummingbot status`, `hummingbot connectors`, `hummingbot executor-schema`, `hummingbot executor-create`
 - Managed signer execution: `wallet execute`, `wallet sign`, `wallet submit`, `agent run`
 - Profiles: `profile init`, `profile use`, `profile show`, `whoami`
 - Onboarding: `login email`, `help onboarding`, `doctor auth`, `wallet list`, `bootstrap begin`, `bootstrap complete`, `onboarding begin`, `onboarding complete`, `agent auth challenge`, `agent auth verify`, `agent register`, `agent key rotate`, `agent key revoke`, `developer bootstrap`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {

package/src/cli/help.mjs

@@ -38,6 +38,10 @@ Core commands:
   thirdfy-agent polymarket status [--agent-key <key>] [--amount-pusd <n>] [--json]
   thirdfy-agent polymarket setup [--agent-key <key>] [--params <json>] [--json]
   thirdfy-agent polymarket dry-run --params <json> [--action place_polymarket_order] [--json]
+  thirdfy-agent hummingbot status [--org-id <id>] [--runtime-id <id>] [--agent-api-key <key>] [--json]
+  thirdfy-agent hummingbot connectors [--org-id <id>] [--json]
+  thirdfy-agent hummingbot executor-schema [--org-id <id>] [--executor-type position_executor] [--json]
+  thirdfy-agent hummingbot executor-create --agent-api-key <key> --user-did <did> [--org-id <id>] [--connector <name>] [--pair <pair>] [--params <json>] [--json]
   thirdfy-agent wallet sign --agent-api-key <key> --action <id> --params <json> [--chain-id <id>] [--json]
   thirdfy-agent wallet submit --signed-tx-hex <hex> [--chain-id <id>] [--rpc-url <url>] [--json]
   thirdfy-agent agent run --agent-api-key <key> --action <id> --params <json> [--signer-method managed_wallet_server|byow|fanout_intent] [--strategy-intent single_wallet|fanout] [--run-mode <mode>] [--user-did <did>] [--json]
@@ -64,6 +68,11 @@ Core commands:
   thirdfy-agent prompt "<natural language prompt>" [--json]
   thirdfy-agent intent-status --intent-id <id> [--json]
   thirdfy-agent credits balance --auth-token <token> [--json]
+  thirdfy-agent credits transactions --auth-token <token> [--page <n>] [--limit <n>] [--include-metadata] [--json]
+  thirdfy-agent credits usage --auth-token <token> [--range 7d|30d|90d] [--json]
+  thirdfy-agent models list --auth-token <token> [--json]
+  thirdfy-agent models estimate --auth-token <token> --model <key> [--input-tokens <n>] [--output-tokens <n>] [--json]
+  thirdfy-agent pricing quote --auth-token <token> --action <action-key> [--chain-id <id>] [--json]
 
 Global flags:
   --api-base <url>   default: https://api.thirdfy.com

package/src/cli/manifest.mjs

@@ -92,6 +92,31 @@ export const CLI_MANIFEST = [
     options: ['auth', 'execution', 'polymarket'],
     description: 'Polymarket dry-run preflight',
   },
+  {
+    path: ['hummingbot', 'status'],
+    handler: 'commandHummingbotStatus',
+    options: ['auth', 'hummingbot'],
+    description: 'Hummingbot instance health summary for an org',
+  },
+  {
+    path: ['hummingbot', 'connectors'],
+    handler: 'commandHummingbotConnectors',
+    options: ['auth', 'hummingbot'],
+    description: 'List Hummingbot connectors for an org HB instance',
+  },
+  {
+    path: ['hummingbot', 'executor-schema'],
+    handler: 'commandHummingbotExecutorSchema',
+    options: ['auth', 'hummingbot'],
+    description: 'Fetch Hummingbot executor config schema',
+  },
+  {
+    path: ['hummingbot', 'executor-create'],
+    handler: 'commandHummingbotExecutorCreate',
+    tier: 'online',
+    options: ['auth', 'execution', 'hummingbot'],
+    description: 'Governed Hummingbot executor create via Thirdfy proxy',
+  },
   // online
   {
     path: ['agent', 'run'],
@@ -136,6 +161,41 @@ export const CLI_MANIFEST = [
     options: ['auth'],
     description: 'Credits balance',
   },
+  {
+    path: ['credits', 'transactions'],
+    handler: 'commandCreditsTransactions',
+    tier: 'online',
+    options: ['auth', 'credits'],
+    description: 'Paginated credit transactions with optional billing metadata',
+  },
+  {
+    path: ['credits', 'usage'],
+    handler: 'commandCreditsUsage',
+    tier: 'online',
+    options: ['auth', 'credits'],
+    description: 'Credits usage summary by model, provider, and action',
+  },
+  {
+    path: ['models', 'list'],
+    handler: 'commandModelsList',
+    tier: 'online',
+    options: ['auth'],
+    description: 'List model pricing from chat_model_catalog',
+  },
+  {
+    path: ['models', 'estimate'],
+    handler: 'commandModelsEstimate',
+    tier: 'online',
+    options: ['auth', 'credits', 'execution'],
+    description: 'Estimate model and action credits before execution',
+  },
+  {
+    path: ['pricing', 'quote'],
+    handler: 'commandPricingQuote',
+    tier: 'online',
+    options: ['auth', 'execution'],
+    description: 'Quote action-tier credits for a catalog action',
+  },
   {
     path: ['data', 'summary'],
     handler: 'commandDataSummary',

package/src/cli/options/credits.mjs

@@ -0,0 +1,15 @@
+export function attachCreditsOptions(cmd) {
+  return cmd
+    .option('--page <n>', 'page number for transactions', '1')
+    .option('--limit <n>', 'page size for transactions', '20')
+    .option('--include-metadata', 'include unified billing metadata on transactions')
+    .option('--range <range>', 'usage summary range (7d, 30d, 90d)', '7d')
+    .option('--model <key>', 'chat model key for pricing estimate')
+    .option('--input-tokens <n>', 'estimated input tokens for pricing estimate', '0')
+    .option('--output-tokens <n>', 'estimated output tokens for pricing estimate', '0')
+    .option(
+      '--tool-calls <value>',
+      'tool call count or comma-separated AgentKit tool names for pricing estimate',
+    )
+    .option('--surface <surface>', 'billing surface (console, automation, cli, agent_api)', 'cli');
+}

package/src/cli/options/hummingbot.mjs

@@ -0,0 +1,8 @@
+export function attachHummingbotOptions(cmd) {
+  return cmd
+    .option('--org-id <id>', 'Hummingbot org id (default: HUMMINGBOT_ORG_ID or default)')
+    .option('--runtime-id <id>', 'EarnClaw runtime id for health summary scoping')
+    .option('--executor-type <type>', 'Hummingbot executor type')
+    .option('--connector <name>', 'Hummingbot connector name')
+    .option('--pair <pair>', 'Hummingbot trading pair');
+}

package/src/cli/options/index.mjs

@@ -8,8 +8,10 @@ import { attachBootstrapOptions } from './bootstrap.mjs';
 import { attachCredentialsOptions } from './credentials.mjs';
 import { attachAnalyticsOptions } from './analytics.mjs';
 import { attachPolymarketOptions } from './polymarket.mjs';
+import { attachHummingbotOptions } from './hummingbot.mjs';
 import { attachAgentRegisterOptions } from './agent.mjs';
 import { attachChainOptions } from './chains.mjs';
+import { attachCreditsOptions } from './credits.mjs';
 
 const BUNDLES = {
   auth: attachAuthOptions,
@@ -21,8 +23,10 @@ const BUNDLES = {
   credentials: attachCredentialsOptions,
   analytics: attachAnalyticsOptions,
   polymarket: attachPolymarketOptions,
+  hummingbot: attachHummingbotOptions,
   agent: attachAgentRegisterOptions,
   chains: attachChainOptions,
+  credits: attachCreditsOptions,
 };
 
 /** @param {import('commander').Command} cmd */

package/src/commands/credits.mjs

@@ -0,0 +1,134 @@
+import { requireFlag } from '../core/args.mjs';
+import { apiGet, apiPost } from '../core/http.mjs';
+
+function resolveToolCallsEstimate(flags) {
+  const raw = flags.toolCalls ?? flags.toolCallsList;
+  if (raw == null || raw === '') {
+    return { toolCalls: 0, toolCallsList: undefined };
+  }
+
+  const value = String(raw).trim();
+  if (!value) {
+    return { toolCalls: 0, toolCallsList: undefined };
+  }
+
+  if (/^\d+$/.test(value)) {
+    return { toolCalls: Number(value), toolCallsList: undefined };
+  }
+
+  const toolCallsList = value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+
+  return {
+    toolCalls: toolCallsList.length,
+    toolCallsList,
+  };
+}
+
+export function createCreditsCommands({ printEnvelope, getAuthToken }) {
+  async function commandCreditsTransactions(ctx, flags) {
+    const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for credits transactions');
+    const page = Number(flags.page || 1);
+    const limit = Number(flags.limit || 20);
+    const includeMetadata = flags.includeMetadata === true || flags.includeMetadata === 'true';
+    const response = await apiGet(
+      ctx,
+      `/api/v1/credits/transactions?page=${page}&limit=${limit}&includeMetadata=${includeMetadata}`,
+      { Authorization: `Bearer ${authToken}` },
+    );
+    printEnvelope({
+      success: true,
+      code: 'OK',
+      message: 'Credit transactions loaded',
+      data: response,
+      meta: { apiBase: ctx.apiBase, page, limit, includeMetadata },
+    });
+  }
+
+  async function commandCreditsUsage(ctx, flags) {
+    const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for credits usage');
+    const range = String(flags.range || '7d');
+    const response = await apiGet(ctx, `/api/v1/credits/usage/summary?range=${encodeURIComponent(range)}`, {
+      Authorization: `Bearer ${authToken}`,
+    });
+    printEnvelope({
+      success: true,
+      code: 'OK',
+      message: 'Credits usage summary loaded',
+      data: response,
+      meta: { apiBase: ctx.apiBase, range },
+    });
+  }
+
+  async function commandModelsList(ctx, flags) {
+    const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for models list');
+    const response = await apiGet(ctx, '/api/v1/credits/pricing/models', {
+      Authorization: `Bearer ${authToken}`,
+    });
+    printEnvelope({
+      success: true,
+      code: 'OK',
+      message: 'Model pricing loaded',
+      data: response,
+      meta: { apiBase: ctx.apiBase },
+    });
+  }
+
+  async function commandModelsEstimate(ctx, flags) {
+    const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for models estimate');
+    const modelKey = requireFlag(flags, 'model', 'Missing --model for models estimate');
+    const { toolCalls, toolCallsList } = resolveToolCallsEstimate(flags);
+    const response = await apiPost(
+      ctx,
+      '/api/v1/credits/pricing/estimate',
+      {
+        modelKey,
+        inputTokens: Number(flags.inputTokens || 0),
+        outputTokens: Number(flags.outputTokens || 0),
+        toolCalls,
+        toolCallsList,
+        chainId: Number(flags.chainId || 0) || undefined,
+        surface: flags.surface || 'cli',
+      },
+      { Authorization: `Bearer ${authToken}` },
+    );
+    printEnvelope({
+      success: true,
+      code: 'OK',
+      message: 'Model estimate generated',
+      data: response,
+      meta: { apiBase: ctx.apiBase, modelKey },
+    });
+  }
+
+  async function commandPricingQuote(ctx, flags) {
+    const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for pricing quote');
+    const action = requireFlag(flags, 'action', 'Missing --action for pricing quote');
+    const response = await apiPost(
+      ctx,
+      '/api/v1/credits/pricing/quote',
+      {
+        actionKey: action,
+        chainId: Number(flags.chainId || 8453),
+      },
+      { Authorization: `Bearer ${authToken}` },
+    );
+    printEnvelope({
+      success: true,
+      code: 'OK',
+      message: 'Action pricing quote generated',
+      data: response,
+      meta: { apiBase: ctx.apiBase, action },
+    });
+  }
+
+  return {
+    commandCreditsTransactions,
+    commandCreditsUsage,
+    commandModelsList,
+    commandModelsEstimate,
+    commandPricingQuote,
+  };
+}

package/src/commands/hummingbot.mjs

@@ -0,0 +1,79 @@
+import { apiGet, apiPost } from '../core/http.mjs';
+import { parseJsonFlag } from '../core/args.mjs';
+import { resolveConfigAgentKey } from './polymarket.mjs';
+
+function orgIdFromFlags(flags) {
+  return String(flags.orgId || flags.org_id || process.env.HUMMINGBOT_ORG_ID || 'default').trim();
+}
+
+function agentApiKeyFromFlags(flags, ctx) {
+  return String(flags.agentApiKey || flags.agent_api_key || ctx?.agentApiKey || '').trim();
+}
+
+export function createHummingbotCommands({ printEnvelope }) {
+  async function commandHummingbotStatus(ctx, flags) {
+    const orgId = orgIdFromFlags(flags);
+    const agentApiKey = agentApiKeyFromFlags(flags, ctx);
+    const query = new URLSearchParams({ orgId });
+    if (flags.runtimeId) query.set('runtimeId', String(flags.runtimeId));
+    const headers = agentApiKey ? { 'x-agent-api-key': agentApiKey } : {};
+    const data = await apiGet(ctx, `/api/v1/agent/hummingbot/health/summary?${query.toString()}`, headers);
+    printEnvelope({ success: true, data, meta: { apiBase: ctx.apiBase, orgId } });
+  }
+
+  async function commandHummingbotConnectors(ctx, flags) {
+    const orgId = orgIdFromFlags(flags);
+    const data = await apiGet(ctx, `/api/v1/agent/hummingbot/connectors?orgId=${encodeURIComponent(orgId)}`);
+    printEnvelope({ success: true, data, meta: { apiBase: ctx.apiBase, orgId } });
+  }
+
+  async function commandHummingbotExecutorSchema(ctx, flags) {
+    const orgId = orgIdFromFlags(flags);
+    const executorType = String(flags.executorType || flags.executor_type || 'position_executor');
+    const data = await apiGet(
+      ctx,
+      `/api/v1/agent/hummingbot/executors/types/${encodeURIComponent(executorType)}/config?orgId=${encodeURIComponent(orgId)}`
+    );
+    printEnvelope({ success: true, data, meta: { apiBase: ctx.apiBase, orgId, executorType } });
+  }
+
+  async function commandHummingbotExecutorCreate(ctx, flags) {
+    const orgId = orgIdFromFlags(flags);
+    const agentApiKey = agentApiKeyFromFlags(flags, ctx);
+    const userDid = String(flags.userDid || flags.user_did || '').trim();
+    const params = parseJsonFlag(flags, 'params') || {};
+    if (!agentApiKey || !userDid) {
+      printEnvelope({
+        success: false,
+        code: 'MISSING_AUTH',
+        message: 'Provide --agent-api-key and --user-did for governed executor create',
+        data: {},
+      });
+      process.exit(1);
+    }
+    const body = {
+      ...params,
+      orgId,
+      userDid,
+      connector_name: flags.connector || params.connector_name,
+      trading_pair: flags.pair || params.trading_pair,
+      estimatedAmountUsd: Number(flags.estimatedAmountUsd || params.estimatedAmountUsd || 0),
+      type: flags.executorType || flags.executor_type || params.type || 'position_executor',
+    };
+    const data = await apiPost(
+      ctx,
+      '/api/v1/agent/hummingbot/executors',
+      body,
+      { 'x-agent-api-key': agentApiKey }
+    );
+    printEnvelope({ success: true, data, meta: { apiBase: ctx.apiBase, orgId } });
+  }
+
+  return {
+    commandHummingbotStatus,
+    commandHummingbotConnectors,
+    commandHummingbotExecutorSchema,
+    commandHummingbotExecutorCreate,
+    resolveHummingbotAgentKey: resolveConfigAgentKey,
+  };
+}

package/src/commands/index.mjs

@@ -1,6 +1,7 @@
 export { createPolymarketCommands, resolveConfigAgentKey } from './polymarket.mjs';
 export { createHyperliquidHelpers } from './hyperliquid.mjs';
 export { createLighterHelpers } from './lighter.mjs';
+export { createHummingbotCommands } from './hummingbot.mjs';
 export { createExecuteCommands } from './execute.mjs';
 export { createWalletCommands } from './wallet.mjs';
 export { createDelegationCommands } from './delegation.mjs';

package/src/runtime/handlers.mjs

@@ -1,5 +1,6 @@
 import { negotiateCapabilities } from '../core/http.mjs';
 import { createPolymarketCommands } from '../commands/polymarket.mjs';
+import { createHummingbotCommands } from '../commands/hummingbot.mjs';
 import { createHyperliquidHelpers } from '../commands/hyperliquid.mjs';
 import { createLighterHelpers } from '../commands/lighter.mjs';
 import { createExecuteCommands } from '../commands/execute.mjs';
@@ -7,6 +8,7 @@ import { createWalletCommands } from '../commands/wallet.mjs';
 import { createDelegationCommands } from '../commands/delegation.mjs';
 import { createBootstrapCommands } from '../commands/bootstrap.mjs';
 import { createDiscoveryCommands } from '../commands/discovery.mjs';
+import { createCreditsCommands } from '../commands/credits.mjs';
 import { createTelemetryCommands } from '../commands/telemetry.mjs';
 import { createCredentialsCommands } from '../commands/credentials.mjs';
 import { createAgentCommands } from '../commands/agent.mjs';
@@ -55,6 +57,11 @@ export function createRuntimeHandlers(deps) {
     resolveAgentApiKey,
   });
 
+  const __credits = createCreditsCommands({
+    printEnvelope,
+    getAuthToken,
+  });
+
   const __telemetry = createTelemetryCommands({
     printEnvelope,
     resolveAgentApiKey,
@@ -142,6 +149,10 @@ export function createRuntimeHandlers(deps) {
     printEnvelope,
   });
 
+  const __hummingbot = createHummingbotCommands({
+    printEnvelope,
+  });
+
   const __bootstrap = createBootstrapCommands({
     printEnvelope,
     extractAgentApiKey,
@@ -160,6 +171,7 @@ export function createRuntimeHandlers(deps) {
     ...__wallet,
     ...__delegation,
     ...__polymarket,
+    ...__hummingbot,
     ...__bootstrap,
     ...__discovery,
     ...__telemetry,
@@ -173,6 +185,11 @@ export function createRuntimeHandlers(deps) {
     commandCatalogsList: __discovery.commandCatalogsList,
     commandActions: __discovery.commandActions,
     commandCreditsBalance: __discovery.commandCreditsBalance,
+    commandCreditsTransactions: __credits.commandCreditsTransactions,
+    commandCreditsUsage: __credits.commandCreditsUsage,
+    commandModelsList: __credits.commandModelsList,
+    commandModelsEstimate: __credits.commandModelsEstimate,
+    commandPricingQuote: __credits.commandPricingQuote,
     commandDataSummary: __telemetry.commandDataSummary,
     commandTrackList: __telemetry.commandTrackList,
     commandTrackAction: __telemetry.commandTrackAction,