@thirdfy/agent-cli 0.2.76 → 0.2.78

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to `@thirdfy/agent-cli` are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.78] - 2026-09-24
+
+### Changed
+
+- **Avantis is now Veranta.** The Base perps venue rebranded (ticker AVNT unchanged). Help, errors, provider hints and docs say Veranta. Provider hints for `avantis` / `avantis-vault` list Veranta action names (`place_veranta_perps_order`, `deposit_veranta_vault`, ...) and carry `displayName: "Veranta"` and `providerAliases`.
+
+### Added
+
+- **Veranta names work against every API deployment.** A Veranta action name (`*_veranta_*`) resolves to the catalog row the API in hand has: the Veranta row on an API with Veranta names, the Avantis row on one without. Avantis names keep working, including against a catalog that lists them only as aliases of Veranta rows. With no catalog to check, a Veranta name is sent in the Avantis spelling, which every deployment accepts. `pricing quote` does the same.
+- **`veranta` / `veranta-vault` provider aliases.** `--provider veranta` lists the same actions as `--provider avantis` (and `veranta-vault` as `avantis-vault`). `venue readiness|setup|fund veranta` calls the API with the `avantis` venue id. `avantis` is still accepted everywhere.
+- **Hardcoded venue lists recognise both spellings:** the offchain-venue lane guard (`OFFCHAIN_VENUE_ORDER_SELF_UNSUPPORTED`), the 180s long timeout for onboarding and market open/close, the `agent_wallet` `traderAddress` default, the `complete_*_onboarding` `estimatedAmountUsd` default, and `certify` venue fixtures (a live Veranta row replaces the Avantis fixture; the schema digest is spelling-independent).
+- Error codes and internal identifiers are unchanged (`avantis_delegate`, `AVANTIS_*` setup blockers, provider ids `avantis` / `avantis-vault`). Pin: `test/veranta-rebrand.test.cjs`.
+
+## [0.2.77] - 2026-09-24
+
+### Changed
+
+- **Dependencies on current releases:**
+  - `commander` 14.0.3: 12 → 14 is two majors.
+  - `ethers` 6.17.0 and `@open-wallet-standard/core` 1.4.2.
+  - Commander 15 is held back because it needs Node ≥22.12. agent-cli still supports Node ≥20, and Hermes runtimes install `@latest` on the Node their image already has.
+- **Extra positional arguments are still accepted.** Commander 13+ rejects them by default; the CLI opts back in (`allowExcessArguments`), so a command like `intent-status <id>` behaves as in 0.2.76. Pin: `test/commander-routing.test.cjs`.
+- **`-ni` still works.** Commander 13+ rejects two-letter short flags. The option is `--not-interactive`, and a bare `-ni` is rewritten to it before parsing. Pin: `test/commander-routing.test.cjs`.
+- **`venue readiness|setup|fund` declare `<venue>`.** The manifest passed `true` as the argument name, which commander 12 accepted as one required positional. The behavior is unchanged: `thirdfy-agent venue readiness avantis`.
+- **CI and release:**
+  - CI tests Node 20, 22 and 24.
+  - Release and live e2e run on Node 24.
+  - `actions/checkout@v7`, `actions/setup-node@v7`.
+  - Dependabot with weekly updates.
+- **agent_wallet reads make one API call.** A read in `agent_wallet` mode skips the `/execution-wallet` preflight, because the API resolves the execution wallet itself. The preflight still runs when the read needs its answer: `--wallet-address` set to a wallet other than the agent key, chain 4663 (Robinhood delegated lane), or a Hyperliquid/Lighter/Avantis address default. With `--wallet-address` equal to the agent key, the wallet the API reports is checked after the read (same `EXECUTION_WALLET_MISMATCH` rule). The result shows `executionWalletPreflight: { skipped: "read_fast_path" }`. Matches `thirdfy-mcp` `walletExecute`.
+- **`WRITE_OUTCOME_UNKNOWN` advice matches `thirdfy-mcp`.** The error names the action and the idempotency key: re-read state first; if the write landed, do not resend; if unsure and retrying, reuse the exact same key; if the re-read shows it did not land, send it with a new key. The API holds an unknown-outcome claim for 24 h.
+- **Unknown actions.** An action that is not in the catalog, or not allowed for the agent key, still fails with `error: PARAMS_SCHEMA_INVALID`, now with `blockedReason: UNKNOWN_ACTION`, `resolvedAction: null`, and `suggestions` (closest catalog actions). Same shape as `thirdfy-mcp` 0.1.6.
+- **Write timeout floor (pin only).** The CLI picks write timeouts from its own read/write classifier, not the catalog `behavior.latencyClass`, so a write never gets the read timeout. `test/mcp-api-parity.test.cjs` pins it.
+
+### Security
+
+- **The agent API key never goes in a URL.** The policy-aware actions listing (`thirdfy-agent actions --agent-api-key …`, and action resolution before `run` / `preflight` / `wallet execute`) called `GET /api/v1/agent/actions?agentApiKey=…`. It now sends the key in the `x-agent-api-key` header, which every agent route reads since Thirdfy API 3.15; a key in the query string gets `Deprecation` headers. Pin: `test/mcp-api-parity.test.cjs`.
+
+### Added
+
+- **Replayed writes are labeled.** When the API answers a value-moving write from an earlier identical one (`Idempotent-Replayed: true` header or `idempotentReplay: true` in the body), the result carries `idempotentReplay: true` and a note: nothing new was executed; send a new `executionIdempotencyKey` (`idempotencyKey` on execute-intent) to place another. Both come from `--idempotency-key`. Matches `thirdfy-mcp` `idempotentReplayFields`.
+- **`deposit_earn_position` amount aliases.** `amountHuman` and `amountInHuman` are accepted in place of `amount` (a decimal token-unit string). Two amounts, or raw base units (`amountInRaw`, `amountIn`), fail with `EARN_AMOUNT_*` before any request. **New refusal:** earn deposits that sent `amountIn` / `amountInRaw` used to reach the API, which reads `amount` as token units; they now fail locally. `execute_optimal_swap` takes the same `amountInRaw` / `amountInHuman` + `tokenInDecimals` contract as `swap`. Matches the `thirdfy-mcp` params gate (`earn_deposit_decimal_amount`, `evm_erc20_amount_in`).
+
 ## [0.2.76] - 2026-09-23
 
 ### Fixed

package/README.md

@@ -40,10 +40,11 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## What's new in v0.2.76
+## What's new in v0.2.78
 
-- Writes (orders, TP/SL updates, closes) get a 90s HTTP timeout instead of 30s. Override with `THIRDFY_CLI_WRITE_TIMEOUT_MS`.
-- A write whose request times out is no longer resent. The CLI reports `WRITE_OUTCOME_UNKNOWN`: re-read positions before retrying.
+- Avantis, the Base perps venue, is now **Veranta**. Use `--provider veranta` / `veranta-vault` and Veranta action names such as `place_veranta_perps_order` and `get_veranta_positions`.
+- Avantis names (`--provider avantis`, `place_avantis_perps_order`, `venue readiness avantis`) keep working. A Veranta name finds the matching action whether the Thirdfy API catalog lists Veranta or Avantis names.
+- `venue readiness|setup|fund veranta` works; `avantis` is still accepted.
 - See [CHANGELOG.md](./CHANGELOG.md) and GitHub Releases for older versions.
 
 ## Quick start
@@ -323,7 +324,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`
-- Venue tooling: `venue readiness`, `venue setup`, `venue fund` (`polymarket`, `hyperliquid`, `lighter`, `avantis`)
+- Venue tooling: `venue readiness`, `venue setup`, `venue fund` (`polymarket`, `hyperliquid`, `lighter`, `veranta`)
 - Hummingbot: `hummingbot status`, `connectors`, `executor-schema`, `executor-create`, `executor-stop`, `gateway-networks`, `gateway-connectors`
 - Condor Pattern A: `condor policy-status`, `condor preflight`
 - Managed signer execution: `wallet execute`, `wallet sign`, `wallet submit`, `agent run`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.2.76",
+  "version": "0.2.78",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {
@@ -71,8 +71,8 @@
   },
   "homepage": "https://github.com/thirdfy/agent-cli#readme",
   "dependencies": {
-    "@open-wallet-standard/core": "^1.3.0",
-    "commander": "^12.1.0",
-    "ethers": "^6.16.0"
+    "@open-wallet-standard/core": "^1.4.2",
+    "commander": "^14.0.3",
+    "ethers": "^6.17.0"
   }
 }

package/src/cli/manifest.mjs

@@ -103,8 +103,8 @@ export const CLI_MANIFEST = [
     path: ['venue', 'readiness'],
     handler: 'commandVenueReadiness',
     options: ['auth', 'venue'],
-    description: 'Normalized venue readiness (polymarket, hyperliquid, lighter, avantis)',
-    args: { query: true },
+    description: 'Normalized venue readiness (polymarket, hyperliquid, lighter, veranta)',
+    args: { query: '<venue>' },
     tier: 'online',
   },
   {
@@ -112,7 +112,7 @@ export const CLI_MANIFEST = [
     handler: 'commandVenueSetup',
     options: ['auth', 'venue'],
     description: 'Prepare or complete venue onboarding via shared API contract',
-    args: { query: true },
+    args: { query: '<venue>' },
     tier: 'online',
   },
   {
@@ -120,7 +120,7 @@ export const CLI_MANIFEST = [
     handler: 'commandVenueFund',
     options: ['auth', 'venue'],
     description: 'Return venue funding plan (does not move funds implicitly)',
-    args: { query: true },
+    args: { query: '<venue>' },
     tier: 'online',
   },
   {

package/src/cli/options/bootstrap.mjs

@@ -1,3 +1,9 @@
+/** Commander 13+ rejects multi-character short flags; keep the historical `-ni` spelling working. */
+export function normalizeLegacyShortFlags(argv) {
+  const end = argv.indexOf('--');
+  return argv.map((arg, index) => (arg === '-ni' && (end === -1 || index < end) ? '--not-interactive' : arg));
+}
+
 export function attachBootstrapOptions(cmd) {
   return cmd
     .option('--proof-type <type>', 'session_token|wallet_signature')
@@ -10,7 +16,7 @@ export function attachBootstrapOptions(cmd) {
     .option('--otp <otp>', 'email OTP alias')
     .option('--accept-terms', 'accept terms for email login')
     .option('--key-name <name>', 'Privy key name')
-    .option('-ni, --not-interactive', 'fail fast when required login input is missing')
+    .option('--not-interactive', 'fail fast when required login input is missing (alias: -ni)')
     .option('--no-bootstrap-agent', 'skip agent bootstrap on email login')
     .option('--rotate-agent-key', 'rotate agent key')
     .option('--login-attempt-id <id>', 'email login attempt id')

package/src/cli/program.mjs

@@ -3,3 +3,4 @@ import { buildCliProgram } from './register.mjs';
 export { buildCliProgram };
 export { collectRootFlags, collectLegacyFlags } from './flags.mjs';
 export { configureCommanderErrors, handleRootOnlyFlows, collectVersionFlagsFromArgv } from './errors.mjs';
+export { normalizeLegacyShortFlags } from './options/bootstrap.mjs';

package/src/cli/register.mjs

@@ -107,6 +107,9 @@ function registerManifestEntry(program, entry, nodeByPath, deps) {
 export function buildCliProgram(deps) {
   const program = new Command('thirdfy-agent');
   program.name('thirdfy-agent');
+  // Commander 13+ rejects extra positional arguments by default. 0.2.76 (commander 12) ignored them,
+  // and agents that pass an id positionally (`intent-status <id>`) must keep working.
+  program.allowExcessArguments(true);
   attachGlobalOptions(program);
   program.addHelpCommand(false);
   program.showHelpAfterError(false);

package/src/commands/avantis.mjs

@@ -1,11 +1,14 @@
+import { toLegacyVenueActionKey } from '../core/venueBrand.mjs';
+
+/**
+ * Veranta (formerly Avantis) helpers. Names keep the Avantis spelling (internal identifiers); every
+ * check accepts both the `*_avantis_*` and `*_veranta_*` action spellings.
+ */
 export function createAvantisHelpers(deps) {
   const { getPreparedParams, resolveManagedExecutionPreflight } = deps;
 
   function avantisDefaultAddressParamForAction(action) {
-    const canonical = String(action || '')
-      .trim()
-      .toLowerCase()
-      .replace(/_/g, '-');
+    const canonical = toLegacyVenueActionKey(action).replace(/_/g, '-');
     if (
       canonical === 'get-avantis-open-orders' ||
       canonical === 'get-avantis-positions' ||

package/src/commands/credits.mjs

@@ -1,5 +1,6 @@
 import { requireFlag } from '../core/args.mjs';
 import { apiGet, apiPost } from '../core/http.mjs';
+import { toAvantisSpelling } from '../core/venueBrand.mjs';
 import {
   formatCreditsEstimateSummary,
   formatCreditsModelsSummary,
@@ -117,7 +118,8 @@ export function createCreditsCommands({ printEnvelope, getAuthToken }) {
       ctx,
       '/api/v1/credits/pricing/quote',
       {
-        actionKey: action,
+        // Veranta names price as their Avantis spelling, which every API deployment knows.
+        actionKey: toAvantisSpelling(action),
         chainId: Number(flags.chainId || 8453),
       },
       { Authorization: `Bearer ${authToken}` },

package/src/commands/telemetry.mjs

@@ -1,5 +1,6 @@
 import { requireFlag, parseJsonFlag } from '../core/args.mjs';
 import { apiGet, apiPost } from '../core/http.mjs';
+import { hasVerantaToken, normalizeVenueProviderId } from '../core/venueBrand.mjs';
 export function createTelemetryCommands({ printEnvelope, resolveAgentApiKey }) {
 function applySharedPortfolioListingFiltersToQuery(query, flags) {
   if (flags.chainId) query.set('chainId', String(flags.chainId));
@@ -110,7 +111,10 @@ async function commandTrackAction(ctx, flags, capabilities) {
   if (flags.idempotencyKey) payload.idempotencyKey = String(flags.idempotencyKey);
   if (flags.category) payload.category = String(flags.category);
   if (flags.source) payload.source = String(flags.source);
-  if (flags.provider) payload.provider = String(flags.provider);
+  if (flags.provider) {
+    // `veranta` / `veranta-vault` report under the internal `avantis` / `avantis-vault` ids.
+    payload.provider = hasVerantaToken(flags.provider) ? normalizeVenueProviderId(flags.provider) : String(flags.provider);
+  }
   if (flags.protocol) payload.protocol = String(flags.protocol);
   if (flags.namespace) payload.namespace = String(flags.namespace);
   if (flags.actionType) payload.actionType = String(flags.actionType);

package/src/commands/venue.mjs

@@ -1,13 +1,16 @@
 import { apiGet, apiPost } from '../core/http.mjs';
 import { loadProfileConfig } from '../core/context.mjs';
+import { normalizeVenueProviderId } from '../core/venueBrand.mjs';
 
+// `avantis` is the internal venue id the API expects; `veranta` (the venue's new name) maps onto it.
 const VENUES = new Set(['polymarket', 'hyperliquid', 'lighter', 'avantis']);
 
 function resolveVenue(flags) {
   const fromQuery = Array.isArray(flags.query) ? flags.query[0] : flags.query;
-  const venue = String(flags.venue || fromQuery || '').trim().toLowerCase();
+  const requested = String(flags.venue || fromQuery || '').trim().toLowerCase();
+  const venue = normalizeVenueProviderId(requested);
   if (!VENUES.has(venue)) {
-    throw new Error(`Unsupported venue "${venue}". Use polymarket, hyperliquid, lighter, or avantis.`);
+    throw new Error(`Unsupported venue "${requested}". Use polymarket, hyperliquid, lighter, or veranta.`);
   }
   return venue;
 }

package/src/core/actionTimeouts.mjs

@@ -1,5 +1,6 @@
 import { DEFAULT_TIMEOUT_MS } from './constants.mjs';
 import { isReadOnlyActionName, isReadOnlyResolvedAction } from './readOnlyActions.mjs';
+import { toLegacyVenueActionKey } from './venueBrand.mjs';
 
 /**
  * Default HTTP timeout for managed writes. A perps order or TP/SL update signs, broadcasts, and waits
@@ -8,6 +9,7 @@ import { isReadOnlyActionName, isReadOnlyResolvedAction } from './readOnlyAction
  */
 const DEFAULT_WRITE_TIMEOUT_MS = 90_000;
 
+// Keyed by the Avantis spelling; `normalizeActionId` maps Veranta names onto it.
 const LONG_RUNNING_ACTIONS = new Set([
   'complete_avantis_onboarding',
   'get_avantis_setup_status',
@@ -29,17 +31,14 @@ const LONG_RUNNING_ACTIONS = new Set([
   'swap',
   'execute_optimal_swap',
   'deposit_hyperliquid_cctp',
-  // Avantis market open/close: the API streams the batched order for up to 90s, then polls its
+  // Veranta (formerly Avantis) market open/close: the API streams the batched order for up to 90s, then polls its
   // tracking status for up to 90s more before it answers.
   'place_avantis_perps_order',
   'close_avantis_position',
 ]);
 
 function normalizeActionId(action) {
-  return String(action || '')
-    .trim()
-    .replace(/-/g, '_')
-    .toLowerCase();
+  return toLegacyVenueActionKey(action).replace(/-/g, '_');
 }
 
 function positiveEnvMs(...names) {

package/src/core/context.mjs

@@ -131,11 +131,11 @@ export async function getCachedActionsCatalog(ctx, flags) {
   if (hit && hit.expiresAt > now) {
     return hit.actions;
   }
-  let endpoint = '/api/v1/agent/actions/catalog';
-  if (policyAware) {
-    endpoint = `/api/v1/agent/actions?agentApiKey=${encodeURIComponent(String(flags.agentApiKey))}`;
-  }
-  const response = await apiGet(ctx, endpoint);
+  // The agent key goes in the `x-agent-api-key` header, never the URL: URLs land in access logs and
+  // proxies, and API 3.15 answers a URL key with Deprecation headers.
+  const response = policyAware
+    ? await apiGet(ctx, '/api/v1/agent/actions', { 'x-agent-api-key': String(flags.agentApiKey) })
+    : await apiGet(ctx, '/api/v1/agent/actions/catalog');
   const actions = extractActions(response);
   catalogCache.set(cacheKey, {
     actions,

package/src/core/hostedRuntimeIdempotency.mjs

@@ -42,3 +42,31 @@ export function wrapWriteIdempotencyKeyForHostedRuntime(existingKey, runtimeId,
   }
   return existing;
 }
+
+/** Told to the caller when the API answered a write from an earlier identical one. */
+export const idempotentReplayNote = (keyArg = 'executionIdempotencyKey') =>
+  `This result is from an earlier identical write; nothing new was executed. Send a new ${keyArg} to place another.`;
+
+export const IDEMPOTENT_REPLAY_NOTE = idempotentReplayNote();
+
+function hasReplayFlag(value, depth) {
+  if (!value || typeof value !== 'object' || depth > 4) return false;
+  if (Array.isArray(value)) return value.some((item) => hasReplayFlag(item, depth + 1));
+  if (value.idempotentReplay === true) return true;
+  return Object.values(value).some((item) => hasReplayFlag(item, depth + 1));
+}
+
+/**
+ * `{ idempotentReplay: true, note }` when the API replayed an earlier write with the same key:
+ * `idempotentReplay: true` anywhere in the body, or an `Idempotent-Replayed: true` header (API
+ * 3.15). The note names the key field to change (`executionIdempotencyKey` on /execute,
+ * `idempotencyKey` on /execute-intent; both come from `--idempotency-key`). Mirrors thirdfy-mcp
+ * `idempotentReplayFields`.
+ */
+export function idempotentReplayFields(data, headers, keyArg) {
+  const header = headers
+    ? Object.entries(headers).find(([name]) => name.toLowerCase() === 'idempotent-replayed')?.[1]
+    : undefined;
+  const replayed = String(header ?? '').trim().toLowerCase() === 'true' || hasReplayFlag(data, 0);
+  return replayed ? { idempotentReplay: true, note: idempotentReplayNote(keyArg) } : {};
+}

package/src/core/http.mjs

@@ -17,21 +17,71 @@ function isTimeoutError(error) {
   return error?.name === 'AbortError' || message.includes('abort') || message.includes('timeout');
 }
 
+/** The idempotency key a write body carries, and the field that carries it. */
+function writeIdempotencyKey(init) {
+  try {
+    const body = JSON.parse(String(init?.body || '{}'));
+    const executionKey = String(body?.executionIdempotencyKey || '').trim();
+    if (executionKey) return { key: executionKey, keyArg: 'executionIdempotencyKey', action: body?.action };
+    const intentKey = String(body?.idempotencyKey || '').trim();
+    if (intentKey) return { key: intentKey, keyArg: 'idempotencyKey', action: body?.action };
+    return { key: '', keyArg: 'executionIdempotencyKey', action: body?.action };
+  } catch {
+    return { key: '', keyArg: 'executionIdempotencyKey', action: undefined };
+  }
+}
+
 /**
  * A write whose request timed out may already be on chain. Resending it can double a trade, so the
- * caller gets `WRITE_OUTCOME_UNKNOWN` and re-reads state before any retry.
+ * caller gets `WRITE_OUTCOME_UNKNOWN` and re-reads state before any retry. The advice matches
+ * thirdfy-mcp `thirdfyWriteOutcomeUnknownPayload`: reusing the same key lets the API answer with
+ * the first write's result if it landed (the API holds an unknown-outcome claim for 24 h).
  */
-function writeOutcomeUnknownError(route, ctx, cause) {
-  const error = new Error(
-    `WRITE_OUTCOME_UNKNOWN: ${route} timed out after ${ctx.timeoutMs}ms; the write may have executed. Re-read state before retrying.`,
-  );
+function writeOutcomeUnknownError(route, ctx, cause, init) {
+  const { key, keyArg, action } = writeIdempotencyKey(init);
+  const retryAdvice = key
+    ? ` If it landed, do not send it again. If you cannot tell and retry, reuse this exact ${keyArg} ("${key}") so the API cannot run it twice. If the re-read shows it did not land, send it again with a new ${keyArg}.`
+    : '';
+  const details = `Thirdfy did not answer within ${Math.round(Number(ctx.timeoutMs || 0) / 1000)}s. The write may have executed. Re-read positions, orders, or balances first, and do not resend the same write blindly.${retryAdvice}`;
+  const error = new Error(`WRITE_OUTCOME_UNKNOWN: ${route} timed out after ${ctx.timeoutMs}ms. ${details}`);
   error.code = 'WRITE_OUTCOME_UNKNOWN';
   error.statusCode = 504;
-  error.payload = { error: 'WRITE_OUTCOME_UNKNOWN', nextAction: 'reread_state_before_retry', timeoutMs: ctx.timeoutMs };
+  error.payload = {
+    error: 'WRITE_OUTCOME_UNKNOWN',
+    code: 504,
+    ...(action ? { action: String(action) } : {}),
+    ...(key ? { [keyArg]: key } : {}),
+    details,
+    nextAction: 'reread_state_before_retry',
+    timeoutMs: ctx.timeoutMs,
+  };
   error.cause = cause;
   return error;
 }
 
+/**
+ * Response headers a caller may need after `requestJson` returns only the parsed body. Kept off the
+ * body itself so nothing extra is printed. Today: `Idempotent-Replayed` (API 3.15).
+ */
+const responseHeadersByBody = new WeakMap();
+
+const TRACKED_RESPONSE_HEADERS = ['idempotent-replayed'];
+
+function rememberResponseHeaders(data, response) {
+  if (!data || typeof data !== 'object' || typeof response?.headers?.get !== 'function') return;
+  const tracked = {};
+  for (const name of TRACKED_RESPONSE_HEADERS) {
+    const value = response.headers.get(name);
+    if (value !== null && value !== undefined) tracked[name] = String(value);
+  }
+  if (Object.keys(tracked).length) responseHeadersByBody.set(data, tracked);
+}
+
+/** Tracked response headers (lowercase names) for a body returned by `apiGet` / `apiPost`. */
+export function responseHeadersFor(data) {
+  return (data && typeof data === 'object' && responseHeadersByBody.get(data)) || {};
+}
+
 /**
  * Whether a request that timed out may be sent again. GETs, validation-only previews, and calls the
  * caller marks `writeAction: false` are safe. Preflight sends `executionLane: validation_only`
@@ -96,6 +146,7 @@ async function requestJsonOnce(ctx, route, init) {
     });
     const text = await response.text();
     const data = text ? safeJsonParse(text) : {};
+    rememberResponseHeaders(data, response);
     if (!response.ok) {
       const error = new Error(data?.error || data?.message || `HTTP ${response.status}`);
       error.statusCode = response.status;
@@ -116,7 +167,7 @@ export async function requestJson(ctx, route, init) {
     } catch (error) {
       lastError = error;
       if (isTimeoutError(error) && !resendAfterTimeoutIsSafe(ctx, init)) {
-        throw writeOutcomeUnknownError(route, ctx, error);
+        throw writeOutcomeUnknownError(route, ctx, error, init);
       }
       if (attempt === 0 && isRetryableApiError(error)) {
         await sleep(250 + Math.floor(Math.random() * 250));

package/src/core/venueBrand.mjs

@@ -0,0 +1,76 @@
+/**
+ * Veranta (formerly Avantis) naming.
+ *
+ * Avantis, the Base perps venue, rebranded to Veranta. The Thirdfy API is moving its action names
+ * from `*_avantis_*` to `*_veranta_*` (Veranta canonical, Avantis kept as aliases). Until every API
+ * deployment has the Veranta rows, the CLI has to work against both catalogs:
+ *
+ * - A Veranta action name resolves to whatever the catalog in hand has (the Avantis row on an older API).
+ * - An Avantis action name keeps working unchanged.
+ * - Hardcoded CLI lists (lanes, timeouts, address defaults) are keyed by the Avantis spelling, so they
+ *   compare through `toLegacyVenueActionKey`.
+ *
+ * Provider ids `avantis` / `avantis-vault` stay the internal identifiers. `veranta` / `veranta-vault`
+ * are accepted wherever the CLI reads a provider id.
+ */
+
+const LEGACY_TOKEN = 'avantis';
+const BRAND_TOKEN = 'veranta';
+
+// The token only counts as a whole word inside an action or provider id (`_`/`-` separated).
+const BRAND_TOKEN_RE = /(^|[_-])veranta(?=[_-]|$)/gi;
+const LEGACY_TOKEN_RE = /(^|[_-])avantis(?=[_-]|$)/gi;
+
+/** Human-facing venue name. */
+export const VERANTA_DISPLAY_NAME = 'Veranta';
+
+/** True when the id carries the Veranta token (`place_veranta_perps_order`, `veranta-vault`). */
+export function hasVerantaToken(value) {
+  BRAND_TOKEN_RE.lastIndex = 0;
+  return BRAND_TOKEN_RE.test(String(value || ''));
+}
+
+/** True when the id carries the Avantis token (`place_avantis_perps_order`, `avantis-vault`). */
+export function hasAvantisToken(value) {
+  LEGACY_TOKEN_RE.lastIndex = 0;
+  return LEGACY_TOKEN_RE.test(String(value || ''));
+}
+
+/** `place_veranta_perps_order` -> `place_avantis_perps_order`. Other names pass through unchanged. */
+export function toAvantisSpelling(value) {
+  return String(value ?? '').replace(BRAND_TOKEN_RE, `$1${LEGACY_TOKEN}`);
+}
+
+/** `place_avantis_perps_order` -> `place_veranta_perps_order`. Other names pass through unchanged. */
+export function toVerantaSpelling(value) {
+  return String(value ?? '').replace(LEGACY_TOKEN_RE, `$1${BRAND_TOKEN}`);
+}
+
+/**
+ * The other spelling of a venue action name, or null when the name has no Avantis/Veranta token.
+ * Used to retry catalog resolution with the spelling the API in hand still uses.
+ */
+export function alternateVenueActionSpelling(value) {
+  const text = String(value ?? '');
+  if (hasVerantaToken(text)) return toAvantisSpelling(text);
+  if (hasAvantisToken(text)) return toVerantaSpelling(text);
+  return null;
+}
+
+/**
+ * Brand-insensitive action key for hardcoded CLI lists: trimmed, lowercased, Veranta mapped to the
+ * Avantis spelling. Separators are preserved; callers still pick `_` or `-`.
+ */
+export function toLegacyVenueActionKey(value) {
+  return toAvantisSpelling(String(value ?? '').trim().toLowerCase());
+}
+
+/**
+ * Normalize a provider or venue id the CLI reads from flags: trimmed, lowercased, and
+ * `veranta` / `veranta-vault` mapped to the internal `avantis` / `avantis-vault`.
+ */
+export function normalizeVenueProviderId(value) {
+  const id = String(value ?? '').trim().toLowerCase();
+  if (!id) return id;
+  return toAvantisSpelling(id);
+}

package/src/runtime/actions/selection.mjs

@@ -1,5 +1,12 @@
 import { requireFlag } from '../../core/args.mjs';
 import { getCachedActionsCatalog } from '../../core/context.mjs';
+import { suggestCatalogActions } from '../validation/actionParamsGate.mjs';
+import {
+  alternateVenueActionSpelling,
+  normalizeVenueProviderId,
+  toAvantisSpelling,
+  toLegacyVenueActionKey,
+} from '../../core/venueBrand.mjs';
 export function createActionSelection({ getTradingProviderHint, formatProviderAmbiguousActionHint, formatProviderUnknownActionHint }) {
 function getActionKey(action) {
   return String(action?.action || action?.id || action?.key || action?.name || '')
@@ -20,7 +27,8 @@ function formatActionList(items) {
 }
 
 function normalizeProviderId(value) {
-  return String(value || '').trim().toLowerCase();
+  // Lowercased id; `veranta` / `veranta-vault` map to the internal `avantis` / `avantis-vault`.
+  return normalizeVenueProviderId(value || '');
 }
 
 function rowActionKey(action) {
@@ -45,7 +53,8 @@ function canonicalizeCatalogActionKey(value) {
 function inferActionProvider(action) {
   // API catalog metadata (`providerId`, `domain`, `category`) is the source of truth.
   // This fallback only keeps older catalog rows / older API deployments discoverable.
-  const key = canonicalActionKey(action);
+  // Veranta action names infer like their Avantis spelling (`avantis` / `avantis-vault`).
+  const key = toLegacyVenueActionKey(canonicalActionKey(action));
   const knownMap = {
     swap: 'trading',
     'execute-optimal-swap': 'trading',
@@ -262,7 +271,8 @@ function isSpotTradingCatalogAction(action) {
 }
 
 function isProviderActionKey(action, provider) {
-  const actionKey = rowActionKey(action);
+  // Brand-insensitive: `place_veranta_perps_order` matches provider `avantis`.
+  const actionKey = toLegacyVenueActionKey(rowActionKey(action));
   const normalizedProvider = normalizeProviderId(provider).replace(/-/g, '_');
   if (!actionKey || !normalizedProvider) return false;
   return (
@@ -282,6 +292,7 @@ function actionMatchesProvider(action, requestedProvider, allActions) {
   if (requestedProvider === 'hyperliquid') return isProviderActionKey(action, 'hyperliquid');
   if (requestedProvider === 'lighter') return isProviderActionKey(action, 'lighter');
   if (requestedProvider === 'avantis') {
+    // Veranta (formerly Avantis) perps; `--provider veranta` normalizes to `avantis` before this runs.
     return isProviderActionKey(action, 'avantis') && !actionKey.includes('vault');
   }
   if (requestedProvider === 'polymarket') return isProviderActionKey(action, 'polymarket');
@@ -350,20 +361,12 @@ async function resolveActionSelection(ctx, flags) {
   return resolveActionFromRows(requestedAction, actions, flags);
 }
 
-function resolveActionFromRows(requestedAction, actions, flags = {}) {
+/**
+ * Exact catalog match for one spelling: canonical overrides, action id, `_`/`-` canonical id, then
+ * alias. Returns null when nothing matches; throws on ambiguity.
+ */
+function matchCatalogEntry(requestedAction, keyed, flags = {}) {
   const requestedLower = String(requestedAction || '').toLowerCase();
-  const keyed = actions
-    .map((action) => ({
-      key: getActionKey(action),
-      aliases: getActionAliases(action),
-      action,
-    }))
-    .filter((entry) => entry.key);
-
-  if (!keyed.length) {
-    return { requestedAction, resolvedAction: requestedAction, resolvedActionMeta: null };
-  }
-
   const canonicalAliasOverrides = {
     get_vaults_fyi_vaults: 'get-vaults-fyi-vaults',
     get_vaults_fyi_opportunities: 'get-vaults-fyi-vaults',
@@ -445,11 +448,47 @@ function resolveActionFromRows(requestedAction, actions, flags = {}) {
       )}.${formatProviderAmbiguousActionHint(providerHint)}`
     );
   }
+  return null;
+}
+
+function resolveActionFromRows(requestedAction, actions, flags = {}) {
+  const requestedLower = String(requestedAction || '').toLowerCase();
+  const keyed = actions
+    .map((action) => ({
+      key: getActionKey(action),
+      aliases: getActionAliases(action),
+      action,
+    }))
+    .filter((entry) => entry.key);
+
+  if (!keyed.length) {
+    // No catalog to check against: send the Avantis spelling of a Veranta name, which every API
+    // deployment accepts (older ones only know `*_avantis_*`; newer ones keep it as an alias).
+    return {
+      requestedAction,
+      resolvedAction: alternateVenueActionSpelling(requestedAction) ? toAvantisSpelling(requestedAction) : requestedAction,
+      resolvedActionMeta: null,
+      suggestions: [],
+    };
+  }
 
+  const direct = matchCatalogEntry(requestedAction, keyed, flags);
+  if (direct) return direct;
+
+  // Veranta (formerly Avantis): retry with the other spelling so `place_veranta_perps_order` finds the
+  // `place_avantis_perps_order` row on an API that has not shipped Veranta names, and the reverse.
+  const alternate = alternateVenueActionSpelling(requestedAction);
+  if (alternate) {
+    const viaAlternate = matchCatalogEntry(alternate, keyed, flags);
+    if (viaAlternate) return { ...viaAlternate, requestedAction };
+  }
+  const alternateLower = alternate ? alternate.toLowerCase() : null;
+
+  const fuzzyNeedles = alternateLower ? [requestedLower, alternateLower] : [requestedLower];
   const fuzzy = keyed.filter(
     (entry) =>
-      entry.key.toLowerCase().includes(requestedLower) ||
-      entry.aliases.some((a) => a.toLowerCase().includes(requestedLower))
+      fuzzyNeedles.some((needle) => entry.key.toLowerCase().includes(needle)) ||
+      entry.aliases.some((a) => fuzzyNeedles.some((needle) => a.toLowerCase().includes(needle)))
   );
   if (fuzzy.length === 1) {
     return { requestedAction, resolvedAction: fuzzy[0].key, resolvedActionMeta: fuzzy[0].action || null };
@@ -462,7 +501,15 @@ function resolveActionFromRows(requestedAction, actions, flags = {}) {
       )}?${formatProviderAmbiguousActionHint(providerHint)}`
     );
   }
-  return { requestedAction, resolvedAction: requestedAction, resolvedActionMeta: null };
+  return {
+    requestedAction,
+    resolvedAction: requestedAction,
+    resolvedActionMeta: null,
+    suggestions: suggestCatalogActions(
+      requestedAction,
+      keyed.map((entry) => ({ ...entry.action, action: entry.key })),
+    ),
+  };
 }
 
   return {