@candledottv/agent-sdk 0.6.1 → 0.6.3

package/README.md

@@ -134,6 +134,14 @@ const fill = await candle.trade({ mint: "9dXSV8...CNDL", side: "buy", amountRaw:
 - The `perps*` methods (`perpsSetup`, `perpsOpen`, `perpsClose`, `perpsOrders`,
   `perpsPositions`, ...) drive Hyperliquid perps.
 
+Perps setup and signing use this release's builder pin,
+`0xc43ff1f6ad9f93fc94558e07c2071b8458e7470b`, independently of the API.
+`hyperliquidBuilder` deliberately replaces that trust anchor with an explicit nonzero EVM
+address; empty or invalid overrides refuse rather than fall back. The local
+`preview.builderTrust` records the expected address and whether it came from the release or
+an override. Setup answers (including `ready`) and fee-bearing actions naming another builder
+are refused before signing. Builder rotation requires a reviewed client release.
+
 Limit orders are a REST surface only (`/api/v1/trade/agent/orders`); the SDK has no method for
 them.
 

package/dist/client.d.ts

@@ -39,8 +39,13 @@
  *   The README's "Retrying a write that failed or timed out" is the caller-facing procedure.
  */
 import { type SignedTradeLeg } from "./errors";
-import { type HyperliquidNetwork, type HyperliquidTypedData } from "./hyperliquid";
+import { type HyperliquidNetwork, type HyperliquidSubmitOutcome, type HyperliquidTypedData } from "./hyperliquid";
+import { type PerpsTpslParams, type PerpsWorkflowResult } from "./hyperliquid-manage";
+import { type PerpsBookOptions, type PerpsBookResult, type PerpsCandlesOptions, type PerpsCandlesResult, type PerpsMarketResult, type PerpsMarketsOptions, type PerpsMarketsResult } from "./hyperliquid-markets";
 import type { HyperliquidPnlSection } from "./hyperliquid-pnl";
+import { type PerpsAccountLine, type PerpsAccountReport, type PerpsPortfolioSection, type PerpsPositionRow, type PerpsRiskReport, type PerpsRiskSettings, type PerpsRiskThresholds, type PerpsRiskThresholdsReport, type PerpsWatchEvent } from "./hyperliquid-risk";
+import { type PerpsWithdrawAuthorization, type PerpsWithdrawBuild, type PerpsWithdrawPins } from "./hyperliquid-withdraw";
+import { type PerpsFillsPage, type PerpsFundingPage, type PerpsHistoryOptions } from "./perps-history";
 import type { AgentPlansResult, PlanPrice, PlanTable } from "./plans";
 import type { SecretStore } from "./secret-store";
 import type { CandleStaking } from "./staking";
@@ -108,13 +113,20 @@ export interface CandleClientOptions {
     /**
      * Candle's Hyperliquid builder address, pinned by the caller. Every perps build is checked
      * against it before signing: an order must name exactly this builder (or none, on a Max order),
-     * and setup must approve exactly it. Unset, the client uses `CANDLE_HYPERLIQUID_BUILDER_ADDRESS`
-     * when this release carries one, and otherwise trusts the builder `GET /agent/perps/config`
-     * reports the first time and holds every later build to that same address.
+     * and setup must approve exactly it. This deliberately replaces the release trust anchor and
+     * is shown as `preview.builderTrust.source: "override"`. Must be a nonzero EVM address; an
+     * invalid override refuses setup/signing. Unset uses the release pin, never `/perps/config`.
      */
     hyperliquidBuilder?: string;
     /** The Hyperliquid network this client trades on. Default mainnet; a build for another is refused. */
     hyperliquidNetwork?: HyperliquidNetwork;
+    /**
+     * The withdrawal pins every withdrawal is checked against before anything is signed: the
+     * perps-USDC `token`, `destinationDex`, Relay's depository allow-list and the amount's string
+     * form. Unset, this release's `CANDLE_PERPS_WITHDRAW_PINS` applies (the values V-A recorded on
+     * 2026-10-18). Pins of null would refuse every withdrawal with nothing signed.
+     */
+    perpsWithdrawPins?: PerpsWithdrawPins;
 }
 /** The bonding-curve terms of one (chain, quote asset, tier) cell. */
 export interface CurveTerms {
@@ -1799,12 +1811,29 @@ export interface PerpsOpenParams extends PerpsWalletRef {
     takeProfit?: string;
     /** Optional reduce-only stop-loss trigger price. */
     stopLoss?: string;
+    /**
+     * Optional client order id: `0x` and 32 hex digits, chosen by the caller and used as the order's
+     * cloid. A retry with the same id and the same request returns the original operation
+     * (`replayed: true`) instead of placing another order; the same id with a different request is
+     * refused (`PERPS_CLIENT_ID_CONFLICT`). It deduplicates, it does not resume: a retry never signs or
+     * submits, so a build-only first call stays unsubmitted. Use a new id for a genuinely new order.
+     */
+    clientId?: string;
 }
 export interface PerpsCloseParams extends PerpsWalletRef {
     coin: string;
     /** Part of the position to close; the whole position when omitted. */
     size?: string;
+    /**
+     * Phase 1 D (spec 2026-10-17 D, section 8): a percentage of the position instead of a size, a
+     * decimal string above 0 and at most 100 with at most four decimals. Sized by both the server and
+     * this client from a direct position read: `floor(|szi| * pct / 100)` at the market's size step,
+     * never rounded up. Exclusive with `size`.
+     */
+    pct?: string;
     slippageBps?: number;
+    /** Optional client order id, as on `PerpsOpenParams.clientId`. */
+    clientId?: string;
 }
 export interface PerpsCancelParams extends PerpsWalletRef {
     /** The cloid of an order Candle built (an open, or one of its take-profit / stop-loss legs). */
@@ -1818,7 +1847,12 @@ export interface PerpsModifyParams extends PerpsWalletRef {
 }
 export interface PerpsLeverageParams extends PerpsWalletRef {
     coin: string;
-    leverage: number;
+    /**
+     * Whole-number leverage. Phase 1 D (spec D, section 5): may be omitted when `mode` is named, and
+     * then the account's current leverage is kept (read from Hyperliquid), never defaulted to 1. A
+     * mode change needs no position and no resting order in the coin.
+     */
+    leverage?: number;
     mode?: "cross" | "isolated";
 }
 export interface PerpsMarginParams extends PerpsWalletRef {
@@ -1826,11 +1860,19 @@ export interface PerpsMarginParams extends PerpsWalletRef {
     /** USD, up to 6 decimals; negative removes isolated margin. */
     amount: string;
 }
+/** BE-1584: a scheduled cancel (spec D, section 7). `seconds` sets the venue's timer; `clear` disarms it. */
+export type PerpsScheduleCancelParams = PerpsWalletRef & ({
+    seconds: number;
+    clear?: undefined;
+} | {
+    clear: true;
+    seconds?: undefined;
+});
 /** What a perps build route returns: the plaintext action, its nonce, and the stamped typed data. */
 export interface PerpsBuild {
     success: true;
     perpOrderId: string;
-    kind: "open" | "close" | "modify" | "cancel" | "leverage" | "margin" | "setup";
+    kind: "open" | "close" | "modify" | "cancel" | "leverage" | "margin" | "setup" | "tpsl" | "scheduleCancel";
     network: HyperliquidNetwork;
     walletId: string;
     address: string;
@@ -1849,6 +1891,9 @@ export interface PerpsBuild {
         feeTenthsBps: number;
     } | null;
     exchangeUrl: string;
+    /** BE-1584: the key's reduce-only setting and policy version this build was judged under. Absent from an older API. */
+    perpsReduceOnly?: boolean;
+    perpsPolicyVersion?: number;
     preview: Record<string, unknown>;
 }
 /**
@@ -1858,11 +1903,150 @@ export interface PerpsBuild {
  * statuses for an order).
  */
 export interface PerpsActionResult {
+    replayed?: false;
     build: PerpsBuild;
     signature: string | null;
     submitted: boolean;
     exchange: unknown | null;
     submitError?: string;
+    /**
+     * BE-1584 (spec D, section 3): Hyperliquid's answer judged per leg. `confirmed` only when the venue
+     * said ok and no leg carries an error; HTTP 200 alone is not confirmation. Absent when nothing was
+     * submitted.
+     */
+    outcome?: HyperliquidSubmitOutcome;
+    /** A scheduled cancel: Candle recorded the venue's acknowledgement (not proof the timer will fire). */
+    acknowledged?: boolean;
+    /** A margin-mode change: the mode asked for, and the one Hyperliquid shows after the submit (null when unread). */
+    requestedMode?: "cross" | "isolated";
+    confirmedMode?: "cross" | "isolated" | null;
+}
+/** BE-1584 (spec D, section 9): the key's reduce-only setting. */
+export interface PerpsReduceOnlyResult {
+    success: true;
+    keyPrefix: string;
+    perpsReduceOnly: boolean;
+    perpsPolicyVersion: number;
+    changed?: boolean;
+    /** On enabling: what the setting does not do (no cancel, no revocation of signed actions, no other keys). */
+    limits?: string[];
+}
+/**
+ * The original operation a client order id already names, as `POST /perps/open` or `/perps/close`
+ * returns it for a retry (spec 2026-10-17 C, section 8). Nothing signable: `status` is Candle's
+ * record (`building` / `built` mean not yet seen on the venue), `venueStatus` what reconcile observed.
+ */
+export interface PerpsReplay {
+    success: true;
+    replayed: true;
+    perpOrderId: string;
+    kind: "open" | "close";
+    network: HyperliquidNetwork;
+    walletId: string;
+    address: string;
+    clientId: string;
+    cloid: string;
+    childCloids: string[];
+    nonce: number;
+    status: string;
+    venueStatus: string | null;
+    filledSz: string | null;
+    notionalUsdMicros: number | null;
+    builtAt: number;
+    settledAt: number | null;
+    preview: Record<string, unknown> | null;
+}
+/** A retry under a client order id: the original operation, and nothing signed, submitted or charged. */
+export interface PerpsReplayResult {
+    replayed: true;
+    replay: PerpsReplay;
+    build: null;
+    signature: null;
+    submitted: false;
+    exchange: null;
+}
+/** `POST /agent/perps/withdraw`: a quote for a withdrawal to this key's own Solana or Hood TEE wallet. */
+export interface PerpsWithdrawBuildRequest {
+    clientWithdrawalId: string;
+    /**
+     * USDC, a decimal string with at most 6 decimals, at least 10 USDC. The server refuses
+     * `PERPS_WITHDRAW_BELOW_MINIMUM` under 10 USDC (`limit: "minimumAmount"`), and when Relay guarantees
+     * under 5 USDC or its fees are above 5% of the amount (`limit: "minimum"`); Hyperliquid's one-time
+     * 1 USDC activation fee on the account's first withdrawal or transfer does not count toward the 5%.
+     */
+    amountUsdc: string;
+    to: "solana" | "hood";
+    /** The key's EVM TEE wallet row id; the key's only one when omitted. */
+    wallet?: string;
+}
+/** One withdrawal as the server records it, with Relay's live status on a read. */
+export interface PerpsWithdrawStatus {
+    success: true;
+    id: string;
+    status: "quoted" | "authorized" | "submitted" | "settled" | "refunded" | "failed";
+    from: {
+        walletId: string;
+        address: string;
+        network: string;
+    };
+    to: {
+        chain: "solana" | "hood";
+        walletId: string;
+        address: string;
+    };
+    amountUsdc: string;
+    feesUsdc: string;
+    netUsdc: string;
+    minimumOutUsdc: string;
+    relayRequestId: string;
+    nonce: number;
+    failureReason: string | null;
+    relay?: {
+        status: string | null;
+        txHashes: string[];
+    } | null;
+    [key: string]: unknown;
+}
+/** The four withdraw routes, one call each. No check runs here: `perpsWithdraw()` runs them. */
+export interface CandlePerpsWithdraw {
+    build(request: PerpsWithdrawBuildRequest): Promise<PerpsWithdrawBuild>;
+    authorize(request: {
+        clientWithdrawalId: string;
+        signature: string;
+    }): Promise<PerpsWithdrawAuthorization>;
+    reportSubmitted(request: {
+        clientWithdrawalId: string;
+        exchangeResponse: unknown;
+    }): Promise<PerpsWithdrawStatus>;
+    get(clientWithdrawalId: string): Promise<PerpsWithdrawStatus>;
+}
+export interface CandlePerps {
+    withdraw: CandlePerpsWithdraw;
+}
+export interface PerpsWithdrawParams extends Omit<PerpsWalletRef, "submit"> {
+    amountUsdc: string;
+    to: "solana" | "hood";
+    /** Reuse on retry. A new id is generated when omitted. */
+    clientWithdrawalId?: string;
+    /** This key's EVM TEE wallet address: the HyperCore account the USDC leaves. */
+    account: string;
+    /**
+     * This key's own wallet addresses on the chain asked for: its Solana TEE wallet for `solana`,
+     * the EVM TEE wallet itself for `hood`. A build landing anywhere else is refused.
+     */
+    ownDestinations: string[];
+}
+/**
+ * The outcome of `perpsWithdraw()`. `signature` is the SendAsset's, valid for resubmission until
+ * its nonce leaves Hyperliquid's two-day window; a failed submit keeps it.
+ */
+export interface PerpsWithdrawResult {
+    build: PerpsWithdrawBuild;
+    authorization: PerpsWithdrawAuthorization;
+    signature: string;
+    submitted: boolean;
+    exchange: unknown | null;
+    submitError?: string;
 }
 export interface PerpsAccountStatus {
     walletId: string;
@@ -1879,6 +2063,7 @@ export interface PerpsAccountStatus {
 export type PerpsSetupResult = PerpsAccountStatus & {
     ready: boolean;
     action?: PerpsActionResult;
+    preview?: Record<string, unknown>;
 };
 export interface PerpsConfig {
     success: true;
@@ -1900,7 +2085,34 @@ export interface PerpsPositions {
     account: Record<string, string>;
     withdrawable: string;
     positions: Record<string, unknown>[];
+    /**
+     * BE-1582 (spec A-3): the section 4 table, account line and risk report, from a direct read of
+     * Hyperliquid on this machine (the fields above are Candle's server read, unchanged). `rows` is
+     * empty and `accountLine` null when that read failed or no level could be computed, and `risk`
+     * then says why (`level: "unknown"`).
+     */
+    rows: PerpsPositionRow[];
+    accountLine: PerpsAccountLine | null;
+    risk: Omit<PerpsRiskReport, "positions">;
 }
+/** `GET /keys/self/limits`'s risk thresholds for the calling key (BE-1582, spec A-4). */
+export interface PerpsRiskSettingsResult {
+    /** What the key stores, or null. */
+    perpsRisk: PerpsRiskSettings | null;
+    /** What the engine applies, and where it came from (`defaults (server did not report)` on an older API). */
+    effective: PerpsRiskThresholdsReport;
+}
+/** `PUT /keys/self/perps-risk` or `/keys/:prefix/perps-risk`. */
+export interface PerpsRiskWriteResult {
+    success: true;
+    keyPrefix: string;
+    perpsRisk: PerpsRiskSettings | null;
+    effective: PerpsRiskThresholds;
+}
+/** A threshold write: each named field set (`null` clears that field), or `null` to clear them all. */
+export type PerpsRiskWrite = {
+    [K in keyof PerpsRiskThresholds]?: number | null;
+} | null;
 export interface PerpsOrderRecord {
     perpOrderId: string;
     kind: PerpsBuild["kind"];
@@ -1908,6 +2120,8 @@ export interface PerpsOrderRecord {
     coin: string | null;
     nonce: number;
     cloid: string | null;
+    /** The caller's client order id, on rows built with one (absent from an older API). */
+    clientId?: string | null;
     childCloids: string[];
     targetCloid: string | null;
     status: string;
@@ -2016,7 +2230,6 @@ export interface PerpsDepositResult {
     /** `/perps/deposit/submit`'s final answer: `status: "submitted"` and the chain hashes. */
     result: Record<string, unknown> | null;
 }
-/** Why a deposit build must not be signed, or null. */
 export declare function perpsDepositProblem(build: PerpsDepositBuild, params: PerpsDepositParams): string | null;
 /**
  * The base assets `swap()` converts between. Inlined rather than imported from `@candle/shared`'s
@@ -2537,7 +2750,14 @@ export declare class CandleClient {
     private readonly solanaRpcUrl?;
     private readonly evmRpcUrl?;
     private readonly hyperliquidNetwork;
+    private perpsMarketReader?;
     private hyperliquidBuilder?;
+    private readonly perpsWithdrawPins;
+    /**
+     * Hyperliquid withdrawals (spec 2026-10-17-hyperliquid-withdrawals-design.md): the routes, one call
+     * each. Needs `perps:withdraw` on the key. `perpsWithdraw()` is the checked flow.
+     */
+    readonly perps: CandlePerps;
     /** Reads scoped to what this key may spend: a one-shot swap's receipt, and spendable balances. */
     readonly wallets: CandleWallets;
     /** The creator fees this account's launched tokens can pay, and the claim (FE-438). */
@@ -3246,6 +3466,14 @@ export declare class CandleClient {
      */
     private signBroadcastAndWaitEvmLeg;
     private broadcastAndWaitEvmLeg;
+    /** Public Hyperliquid reads on this machine. A Candle key of any scope is required.
+     * The only Candle call is perpsConfig(), once per client; market data is cached for 5 seconds.
+     */
+    private marketReader;
+    perpsMarkets(opts?: PerpsMarketsOptions): Promise<PerpsMarketsResult>;
+    perpsMarket(coin: string): Promise<PerpsMarketResult>;
+    perpsBook(coin: string, opts?: PerpsBookOptions): Promise<PerpsBookResult>;
+    perpsCandles(coin: string, opts?: PerpsCandlesOptions): Promise<PerpsCandlesResult>;
     /** The server's perps settings: network, Candle's builder, this key's fee, and its limits. */
     perpsConfig(): Promise<PerpsConfig>;
     /**
@@ -3253,24 +3481,56 @@ export declare class CandleClient {
      * it, and reports the account's mode and balance. Idempotent.
      */
     perpsSetup(params: PerpsWalletRef): Promise<PerpsSetupResult>;
-    /** Open (or add to) a position: build, check, sign through the relay, submit to Hyperliquid. */
-    perpsOpen(params: PerpsOpenParams): Promise<PerpsActionResult>;
-    /** Close all or part of a position with a reduce-only IOC order. Reserves nothing. */
-    perpsClose(params: PerpsCloseParams): Promise<PerpsActionResult>;
+    /**
+     * Open (or add to) a position: build, check, sign through the relay, submit to Hyperliquid. With
+     * `clientId`, a retry of the same request returns the original operation (`replayed: true`).
+     */
+    perpsOpen(params: PerpsOpenParams & {
+        clientId?: undefined;
+    }): Promise<PerpsActionResult>;
+    perpsOpen(params: PerpsOpenParams): Promise<PerpsActionResult | PerpsReplayResult>;
+    /** Close all or part of a position with a reduce-only IOC order. Reserves nothing. Takes `clientId` as open does. */
+    perpsClose(params: PerpsCloseParams & {
+        clientId?: undefined;
+    }): Promise<PerpsActionResult>;
+    perpsClose(params: PerpsCloseParams): Promise<PerpsActionResult | PerpsReplayResult>;
     /** Cancel an order Candle built, by its cloid. */
     perpsCancel(params: PerpsCancelParams): Promise<PerpsActionResult>;
     /** Change a resting order's price or size. The replacement gets a new cloid. */
     perpsModify(params: PerpsModifyParams): Promise<PerpsActionResult>;
-    /** Set a market's leverage and margin mode on the account, within the key's maxLeverage. */
+    /**
+     * Set a market's leverage and margin mode on the account, within the key's maxLeverage. With
+     * `mode` and no `leverage`, the current leverage is kept (spec D, section 5); a mode change needs
+     * no position and no resting order in the coin. The answer reports the mode asked for and the one
+     * Hyperliquid shows after the submit, separately.
+     */
     perpsLeverage(params: PerpsLeverageParams): Promise<PerpsActionResult>;
     /** Add (positive) or remove (negative) isolated margin on an isolated position. */
     perpsMargin(params: PerpsMarginParams): Promise<PerpsActionResult>;
-    /** Positions and account value, read live from Hyperliquid by the wallet's address. */
+    /**
+     * Positions and account value, read live from Hyperliquid by the wallet's address. The server's
+     * fields are unchanged; `rows`, `accountLine` and `risk` (BE-1582, spec A-3) come from a direct
+     * read on this machine at the key's thresholds.
+     */
     perpsPositions(walletId: string): Promise<PerpsPositions>;
     /** Open orders on Hyperliquid, and Candle's record of every action it built, settled first. */
     perpsOrders(walletId: string, opts?: {
         limit?: number;
     }): Promise<PerpsOrders>;
+    /**
+     * One page of the wallet's fills, read directly from Hyperliquid's `/info` (spec 2026-10-17 C,
+     * sections 3 and 4). Candle resolves only the wallet's address; no Candle credential reaches
+     * Hyperliquid, and a read-capable key is enough. Default window: the last seven days, fixed on the
+     * first page; pass `nextCursor` back as `cursor` for the next one. Live venue data for this wallet,
+     * not Candle's ledger and not an all-time total: Hyperliquid serves only the 10,000 most recent
+     * fills. `closedPnl` is gross and `fee` already includes `builderFee`. Throws `PerpsHistoryError`.
+     */
+    perpsFillsPage(walletId: string, options?: PerpsHistoryOptions): Promise<PerpsFillsPage>;
+    /** One page of the wallet's funding payments, as `perpsFillsPage()` reads fills. `delta.usdc` is signed: negative was paid. */
+    perpsFundingPage(walletId: string, options?: PerpsHistoryOptions): Promise<PerpsFundingPage>;
+    private perpsHistoryPage;
+    /** The address of an EVM TEE wallet bound to this key, from Candle's own list of the key's wallets. */
+    private perpsWalletAddress;
     /** Fills, read live from Hyperliquid by the wallet's address. */
     perpsFills(walletId: string): Promise<{
         success: true;
@@ -3282,6 +3542,70 @@ export declare class CandleClient {
         startTime: number;
         funding: Record<string, unknown>[];
     }>;
+    /** The key's risk thresholds: stored and effective. An older API reports none: the defaults, sourced so. */
+    getPerpsRisk(): Promise<PerpsRiskSettingsResult>;
+    /**
+     * Tighten the calling key's own thresholds (`PUT /keys/self/perps-risk`). Anything looser than
+     * the effective set, including clearing a field stored stricter than its default, is refused with
+     * 403 LOOSEN_REQUIRES_SESSION: the owner loosens with `setKeyPerpsRisk()`.
+     */
+    setPerpsRisk(fields: PerpsRiskWrite): Promise<PerpsRiskWriteResult>;
+    /**
+     * The owner's write on any of the account's keys (`PUT /keys/:prefix/perps-risk`): may loosen or
+     * clear. Needs an owner credential, the CLI's device token or a Privy session token, sent as a
+     * bearer token; the client's API key is not sent and would be refused.
+     */
+    setKeyPerpsRisk(keyPrefix: string, fields: PerpsRiskWrite, owner: {
+        bearerToken: string;
+    }): Promise<PerpsRiskWriteResult>;
+    /**
+     * One-shot risk (spec A-8): `ok`, `warn` or `critical` with its drivers, from a direct read of
+     * Hyperliquid at the key's thresholds. `unknown` for a non-standard account mode or a stale read.
+     * A failed venue read throws `HyperliquidReadError` (`code: "PERPS_READ_FAILED"`). Stateless: no
+     * hysteresis (that is `watchPerpsRisk()`).
+     */
+    perpsRisk(params: {
+        walletId: string;
+        address?: string;
+    }): Promise<PerpsRiskReport>;
+    /**
+     * The account line (spec A-10): account value, margin, free margin, withdrawable, the margin
+     * ratio, and realized P&L, fees and funding over a recent window (`since`, epoch ms; default the
+     * last 24 hours, at most 30 days).
+     */
+    perpsAccount(params: {
+        walletId: string;
+        address?: string;
+        since?: number;
+    }): Promise<PerpsAccountReport>;
+    /**
+     * The loop `candle perps watch` runs (spec A-9): polls Hyperliquid every `intervalMs` (default
+     * 10 s), calls `onEvent` with a start event, one event per level change (rising immediately,
+     * falling past the clear band), heartbeats and errors, and resolves with the last level when
+     * `signal` aborts. Candle is asked for thresholds at start and every 5 minutes only.
+     */
+    watchPerpsRisk(params: {
+        walletId: string;
+        address?: string;
+        intervalMs?: number;
+        heartbeatMs?: number;
+        signal?: AbortSignal;
+        onceLevelChange?: boolean;
+        onEvent: (event: PerpsWatchEvent) => void | Promise<void>;
+    }): Promise<{
+        level: PerpsRiskReport["level"];
+    }>;
+    /**
+     * The portfolio's Hyperliquid section (spec A-11) for EVM TEE addresses: account value, unrealized
+     * P&L, positions and level at the default thresholds per account, and a subtotal. Live from
+     * Hyperliquid and never part of any portfolio total.
+     */
+    perpsPortfolioSection(wallets: readonly {
+        address: string;
+        label?: string;
+        walletId?: string;
+    }[]): Promise<PerpsPortfolioSection>;
+    private perpsThresholdsOrDefaults;
     /**
      * Deposit onto the key's Hyperliquid account through Relay (Perps C, HL-ED-8): build, check the
      * build names `account` on chain 1337 with no Candle fee, then sign through the relay and submit.
@@ -3298,11 +3622,65 @@ export declare class CandleClient {
     }>;
     /** The builder every perps build is checked against (see `hyperliquidBuilder` in the options). */
     private perpsBuilder;
+    private perpsBuilderTrust;
     /**
      * Check, sign, submit (HL-ED-2, HL-ED-5). The check runs before the relay is called; a build
-     * that fails it is refused with nothing signed.
+     * that fails it is refused with nothing signed. BE-1584: every method is checked against this
+     * machine's own read of Hyperliquid (`verifyPerpsBuildAgainstVenue`), and the venue's answer is
+     * judged per leg (`outcome`).
      */
     private perpsComplete;
+    /**
+     * Schedule Hyperliquid's cancel-all timer `seconds` from now (at least 5), or clear it. The timer
+     * is wallet-wide: it cancels every open order on the account, protection included, and no
+     * positions. Candle fixes the time at build and this client refuses to sign one less than five
+     * seconds ahead. An acknowledged set is recorded on Candle (`acknowledged`); no public read can
+     * confirm the timer, and Hyperliquid's 10 triggers per UTC day are never counted here.
+     */
+    perpsScheduleCancel(params: PerpsScheduleCancelParams): Promise<PerpsActionResult>;
+    /**
+     * Attach, change or remove the position's take-profit and stop-loss (spec D, section 6): each leg
+     * a reducing market trigger sized to the position now. A change cancels the old leg first (a
+     * protection gap, named in `warnings`), confirms it gone, re-reads, then places the new one; a
+     * partial result is reported as `complete: false`. Legs Candle did not build are listed in
+     * `unowned` and never touched. Calling this is the caller's intent; there is no prompt.
+     */
+    perpsTpsl(params: PerpsWalletRef & PerpsTpslParams): Promise<PerpsWorkflowResult>;
+    /**
+     * Cancel every open main-perp order on the wallet, then close every main-perp position (spec D,
+     * section 8). At most 100 signed steps per call; `complete` only when a final read shows nothing
+     * left. Spot, HIP-3 and vault exposure is out of scope (`scope: "main-perps"`).
+     */
+    perpsFlatten(params: PerpsWalletRef): Promise<PerpsWorkflowResult>;
+    private perpsWorkflowIo;
+    /** The calling key's perps reduce-only setting (`GET /keys/self/perps-reduce-only`). Throws on a failed read. */
+    getPerpsReduceOnly(): Promise<PerpsReduceOnlyResult>;
+    /**
+     * Turn the calling key's perps reduce-only on (`PUT /keys/self/perps-reduce-only`). The key can
+     * never turn it off (403 LOOSEN_REQUIRES_SESSION): the owner does that with `setKeyPerpsReduceOnly()`.
+     * It constrains future Candle builds only: resting orders stay, signed actions stay valid.
+     */
+    setPerpsReduceOnly(perpsReduceOnly: true): Promise<PerpsReduceOnlyResult>;
+    /**
+     * The owner's write on any of the account's keys (`PUT /keys/:prefix/perps-reduce-only`): on or
+     * off. Needs an owner credential (the CLI's device token or a Privy session token), sent as a
+     * bearer token; the client's API key is not sent and would be refused.
+     */
+    setKeyPerpsReduceOnly(keyPrefix: string, perpsReduceOnly: boolean, owner: {
+        bearerToken: string;
+    }): Promise<PerpsReduceOnlyResult>;
+    /**
+     * Withdraw USDC from the key's Hyperliquid account to the same key's own Solana or Hood TEE wallet
+     * through Relay (spec 2026-10-17, route A). MOVES REAL FUNDS. Needs `perps:withdraw`.
+     *
+     * Every signature is checked first, and a mismatch throws with nothing signed: the NonceMapping
+     * names this key's account and Relay's request, the build lands on one of `ownDestinations`, and
+     * Relay's own record of the request names that same recipient; then the SendAsset carries the
+     * mapping's nonce, the exact amount asked for, and the pinned token, dex and depository. The
+     * client posts the SendAsset to Hyperliquid itself and reports the answer. There is no
+     * confirmation gate here: the CLI has one (`candle perps withdraw`).
+     */
+    perpsWithdraw(params: PerpsWithdrawParams): Promise<PerpsWithdrawResult>;
     /**
      * Sign EIP-712 typed data with a linked EVM TEE wallet through the relay
      * (`eth_signTypedData_v4`). The relay signs only typed data a perps build stamped.
@@ -3351,7 +3729,7 @@ export declare function __setEvmReceiptWaitForTest(opts: {
     pollMs?: number;
 } | null): void;
 /** This build's own version. Kept in lockstep with package.json by the release-bump CI guard. */
-export declare const SDK_VERSION = "0.6.1";
+export declare const SDK_VERSION = "0.6.3";
 /** Test seam: the once-per-process latch would otherwise weld the suite's first case to the rest. */
 export declare function __resetSdkUpdateNoticeForTest(): void;
 //# sourceMappingURL=client.d.ts.map