@candledottv/agent-sdk 0.6.2 → 0.6.4

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 {
@@ -1718,7 +1730,7 @@ export interface EvmSignTransactionParams {
  *
  * A TEE payer (Ember Phase 4c) may also start from USDC, and needs `clientTradeId`: the server
  * then resolves the destination to this key's own TEE wallet on Hood (`toWalletId` names one when
- * the key has several), requires a raw cap on the origin asset, and charges no fee. That bridge is
+ * the key has several), honours any cap on the origin asset (none is required), and charges no fee. That bridge is
  * gated by the server's `TEE_BRIDGE_ENABLED`; with it off the build answers `PAIR_UNSUPPORTED`.
  * A Hood-origin bridge signs one leg at a time and is not this call; `candle swap` runs it.
  */
@@ -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,152 @@ 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;
+    /** Relay `protocol.v2.orderId`, when the quote stored one. Status reads still use `relayRequestId`. */
+    relayOrderId?: 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 +2065,7 @@ export interface PerpsAccountStatus {
 export type PerpsSetupResult = PerpsAccountStatus & {
     ready: boolean;
     action?: PerpsActionResult;
+    preview?: Record<string, unknown>;
 };
 export interface PerpsConfig {
     success: true;
@@ -1900,7 +2087,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 +2122,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;
@@ -1939,7 +2155,7 @@ export interface PerpsOrders {
  * Perps C (BE-647, HL-ED-8): `perpsDeposit()`. Relay moves funds from the key's Hood or Solana TEE
  * wallet onto Hyperliquid perps USDC at the key's EVM TEE wallet's own address. The asset decides
  * the paying chain: SOL or USDC from the Solana TEE wallet, ETH or USDG from the Hood one. Needs
- * `swap:write` and a raw cap on the asset. There is no withdrawal yet.
+ * `swap:write`; any cap on the asset still applies. There is no withdrawal yet.
  */
 export interface PerpsDepositParams {
     /** Idempotency id, 1 to 128 of `A-Za-z0-9._:-`. Rebuilding under the same id answers its job. */
@@ -1957,15 +2173,25 @@ export interface PerpsDepositParams {
     perpsWalletId?: string;
     /** Relay slippage, 1 to 1000 bps (default 100). */
     maxSlippageBps?: number;
-    /** Sign and submit (default), or stop after the build and its check. */
+    /**
+     * Sign and submit (default), or `false` for a dry run: the API previews the deposit (`preview:
+     * true`), locking no wallet, reserving no USD window and recording no id, and nothing is signed.
+     */
     submit?: boolean;
 }
-/** What `POST /agent/perps/deposit` builds. A Hood build also carries the first sequenced leg. */
+/**
+ * What `POST /agent/perps/deposit` builds. A Hood build also carries the first sequenced leg. A
+ * preview (`status: "preview"`, from `submit: false`) has no `depositId`, `expiresAt` or sequenced
+ * leg; from Hood it carries `plannedLegs` instead.
+ */
 export interface PerpsDepositBuild {
     success: true;
-    status: "built";
+    status: "built" | "preview";
+    /** A dry run: nothing is held, and the same id still builds a new deposit. */
+    preview?: true;
     clientDepositId: string;
-    depositId: string;
+    /** Absent on a preview. */
+    depositId?: string;
     chain: "solana" | "hood";
     venue: "relay";
     network: HyperliquidNetwork;
@@ -1991,9 +2217,17 @@ export interface PerpsDepositBuild {
     };
     statusChecks: string[];
     requestId: string | null;
-    expiresAt: number;
+    /** Absent on a preview. */
+    expiresAt?: number;
     /** Solana: the one unsigned deposit. */
     transactionsBase64?: string[];
+    /** A Hood preview: the legs' calldata, nothing sequenced. */
+    plannedLegs?: Array<{
+        kind: string;
+        to: string;
+        data: string;
+        value: string;
+    }>;
     /** Hood: the sequenced leg protocol's first body. */
     mode?: "sequenced";
     operationId?: string;
@@ -2016,7 +2250,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
@@ -2256,11 +2489,18 @@ export interface SkippedEmptyTokenAccount extends EmptyTokenAccount {
 export interface PreviewCloseEmptyAccountsRequest {
     /** Mints whose empty accounts stay open, e.g. the pair token a held holder-reward coin pays in. */
     keep?: string[];
+    /**
+     * A Solana TEE wallet's linked-wallet id, to preview that wallet instead of the embedded one
+     * (BE-1687). Any key bound to the wallet may preview it.
+     */
+    wallet?: string;
 }
 /** previewCloseEmptyAccounts()'s result. Nothing was built, signed or written to produce it. */
 export interface CloseEmptyAccountsPreview {
     success: true;
     wallet: string;
+    /** The TEE wallet's linked-wallet id, on a TEE wallet's preview. */
+    linkedWalletId?: string;
     keep: string[];
     accounts: EmptyTokenAccount[];
     accountCount: number;
@@ -2284,9 +2524,18 @@ export interface CloseEmptyAccountsRequest {
     keep?: string[];
     /** The preview's `accounts[].account`, to close only what was shown. Omit to close every qualifying account. */
     accounts?: string[];
+    /**
+     * A Solana TEE wallet's linked-wallet id, to close that wallet's accounts instead of the embedded
+     * wallet's (BE-1687). Needs `swap:write`, `privyWalletId`, and the wallet's signer in `secretStore`.
+     */
+    wallet?: string;
+    /** The TEE wallet's Privy wallet id, which signLinkedTransaction() signs for. Required with `wallet`. */
+    privyWalletId?: string;
 }
 /** A close transaction that landed. */
 export interface CloseEmptyAccountsBatch {
+    /** The transaction's place in a TEE wallet's built batch. */
+    index?: number;
     signature: string;
     accounts: string[];
     lamports: string;
@@ -2297,18 +2546,37 @@ export interface CloseEmptyAccountsBatch {
  * re-preview before re-running.
  */
 export interface CloseEmptyAccountsFailure {
+    /** The transaction's place in a TEE wallet's built batch. */
+    index?: number;
     accounts: string[];
     code: string;
     message: string;
     signature?: string;
 }
+/**
+ * A TEE wallet's close transaction the chain has not settled yet (BE-1687). Its rent is not counted,
+ * and the operation stays `recovering` until every one is settled.
+ */
+export interface CloseEmptyAccountsUnresolved {
+    index: number;
+    accounts: string[];
+    /** Known once the transaction was signed and recorded. */
+    signature?: string;
+    reason: string;
+}
 /** closeEmptyAccounts()'s result. A run in which nothing landed throws a CandleApiError instead. */
 export interface CloseEmptyAccountsResult {
     success: true;
-    /** `partial`: some batch failed, or more accounts remain than one call closes. */
-    status: "completed" | "partial" | "nothing_to_close";
+    /**
+     * `partial`: some batch failed, or more accounts remain than one call closes. `recovering`, a TEE
+     * wallet's close only: a transaction may still land. Nothing is sent again; read
+     * getCloseEmptyAccountsJob(clientTradeId, { wallet }) until it settles.
+     */
+    status: "completed" | "partial" | "nothing_to_close" | "recovering";
     clientTradeId: string;
     wallet: string;
+    /** The TEE wallet's linked-wallet id, on a TEE wallet's close. */
+    linkedWalletId?: string;
     keep: string[];
     closed: EmptyTokenAccount[];
     transactions: CloseEmptyAccountsBatch[];
@@ -2317,8 +2585,11 @@ export interface CloseEmptyAccountsResult {
     solRecovered: string;
     /** The base network fee of the transactions that landed, reverted ones included, 5,000 lamports each. */
     feeLamports: string;
-    netLamports: string;
-    netSol: string;
+    /** Absent while `status` is `recovering`: no net is final until every transaction settles. */
+    netLamports?: string;
+    netSol?: string;
+    /** A TEE close that landed before its fee could be read: `feeLamports` does not count it yet. */
+    feeUnresolved?: true;
     failed: CloseEmptyAccountsFailure[];
     /** Accounts in batches never sent, after a failure that stops the run. */
     unattempted: string[];
@@ -2331,15 +2602,35 @@ export interface CloseEmptyAccountsResult {
     remaining: number;
     /** Present when this is the stored report of an earlier call under the same id. */
     replayed?: true;
+    /** `recovering` only: what the server says to do next. */
+    message?: string;
+    /** `recovering` only: the TEE close transactions not settled yet. */
+    unresolved?: CloseEmptyAccountsUnresolved[];
+}
+/** Which wallet getCloseEmptyAccountsJob() reads: the embedded wallet's runs, or a TEE wallet's. */
+export interface CloseEmptyAccountsJobOptions {
+    /** A Solana TEE wallet's linked-wallet id (BE-1687). Omit for the embedded wallet. */
+    wallet?: string;
 }
 export interface CloseEmptyAccountsJob {
     clientTradeId: string;
     kind: "close-empty";
-    status: "running" | "completed" | "failed";
+    /** `built`, a TEE wallet's only: the transactions await their signatures, or are being sent or recovered. */
+    status: "running" | "built" | "completed" | "failed";
+    /** On a TEE wallet's job. */
+    walletKind?: "tee";
+    linkedWalletId?: string;
+    /** A TEE wallet's send state: `idle` before submit, then `submitting`, `recovering` or `done`. */
+    submitState?: "idle" | "submitting" | "recovering" | "done";
+    /** On a TEE wallet's job: whether this read reconciled the row against the chain. */
+    reconciled?: boolean;
     createdAt: number;
     finishedAt?: number;
     httpStatus?: number;
-    /** The report the close call returned, once it finished. */
+    /**
+     * The report the close call returned, once it finished. On a TEE wallet's job, the build while
+     * its signatures are awaited, the report (`recovering` until the chain settles), or the stored error.
+     */
     result?: CloseEmptyAccountsResult | Record<string, unknown>;
 }
 /** trade()'s one-call request: mirrors BuildTradeRequest minus clientTradeId/payer, plus who signs. */
@@ -2537,7 +2828,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). */
@@ -2791,6 +3089,10 @@ export declare class CandleClient {
      * Lists the embedded Solana wallet's empty token accounts that a close would reclaim, on both
      * token programs, and the SOL their rent returns (BE-418). Read-only: nothing is built, signed or
      * written, and any key scope may call it.
+     *
+     * With `wallet` (a Solana TEE wallet's linked-wallet id, BE-1687), the same preview for that TEE
+     * wallet, by any key bound to it. Off on a deployment until it is enabled
+     * (`AGENT_TEE_CLOSE_EMPTY_ENABLED`): until then it throws LAUNCH_DISABLED.
      */
     previewCloseEmptyAccounts(req?: PreviewCloseEmptyAccountsRequest): Promise<CloseEmptyAccountsPreview>;
     /**
@@ -2803,10 +3105,27 @@ export declare class CandleClient {
      * returns its stored report (`replayed: true`), a repeat while it runs throws CLOSE_IN_PROGRESS,
      * and the same id with a different request throws IDEMPOTENCY_CONFLICT. So a retry under the
      * same id is safe, and this method still never retries on its own.
+     *
+     * With `wallet` (a Solana TEE wallet's linked-wallet id bound to this key, BE-1687), the TEE
+     * wallet's close instead. Needs `swap:write`, `privyWalletId`, and that wallet's signer in
+     * `secretStore`. Three steps: `POST /agent/wallets/:id/close-empty/build` (the server builds
+     * the close transactions, every one CloseAccount with the TEE wallet as fee payer, rent
+     * destination and owner, and stamps them for the relay), `signLinkedTransaction()` per
+     * transaction, then `POST .../close-empty/submit` with the whole signed batch, which the server
+     * checks against the build before it sends anything. A build with nothing to close returns
+     * `nothing_to_close` without signing. A `recovering` result means a transaction may still land:
+     * nothing is sent again, and getCloseEmptyAccountsJob(clientTradeId, { wallet }) reads it until
+     * it settles. A TEE wallet's build is signable once: after a lost answer, read the job rather
+     * than calling this again. Off on a deployment until it is enabled
+     * (`AGENT_TEE_CLOSE_EMPTY_ENABLED`): until then it throws LAUNCH_DISABLED.
      */
     closeEmptyAccounts(req: CloseEmptyAccountsRequest): Promise<CloseEmptyAccountsResult>;
-    /** Reads a closeEmptyAccounts() run by its clientTradeId, without sending anything (BE-418). */
-    getCloseEmptyAccountsJob(clientTradeId: string): Promise<CloseEmptyAccountsJob>;
+    /**
+     * Reads a closeEmptyAccounts() run by its clientTradeId, without sending anything (BE-418). With
+     * `wallet`, a TEE wallet's run (BE-1687, `swap:write`): that read also reconciles the run against
+     * the chain, so a `recovering` close settles by reading it again. It never signs or sends.
+     */
+    getCloseEmptyAccountsJob(clientTradeId: string, opts?: CloseEmptyAccountsJobOptions): Promise<CloseEmptyAccountsJob>;
     /**
      * Imports an existing wallet via Candle's ciphertext-only flow (PR3): calls
      * `/agent/wallets/import/init` for Privy's HPKE receiver public key, encrypts `privateKey`
@@ -3246,6 +3565,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 +3580,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 +3641,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 +3721,66 @@ 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 the build's Relay order id (`relayOrderId`, never the step
+     * `relayRequestId`), and the build lands on one of `ownDestinations` (the recipient check: Relay's
+     * own record of the request is not read, BE-1777); 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 +3829,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.2";
+export declare const SDK_VERSION = "0.6.4";
 /** 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