@candledottv/agent-sdk 0.4.5 → 0.4.7

package/dist/client.d.ts

@@ -26,6 +26,9 @@
  *   validation error). Backoff is 250ms * 2^n, jittered to 50-100% of that, capped at 8s,
  *   bounded by `maxRetries` (default 3 retries after the initial attempt).
  */
+import { type HyperliquidNetwork, type HyperliquidTypedData } from "./hyperliquid";
+import type { HyperliquidPnlSection } from "./hyperliquid-pnl";
+import type { AgentPlansResult, PlanPrice, PlanTable } from "./plans";
 import type { SecretStore } from "./secret-store";
 import { type WalletChain } from "./wallet-import";
 export type Chain = "solana" | "hood";
@@ -83,6 +86,16 @@ export interface CandleClientOptions {
      * is unset, before any signing.
      */
     evmRpcUrl?: string;
+    /**
+     * 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.
+     */
+    hyperliquidBuilder?: string;
+    /** The Hyperliquid network this client trades on. Default mainnet; a build for another is refused. */
+    hyperliquidNetwork?: HyperliquidNetwork;
 }
 /** The bonding-curve terms of one (chain, quote asset, tier) cell. */
 export interface CurveTerms {
@@ -398,21 +411,30 @@ export interface AgentProfile {
  */
 export interface AgentTierInfo {
     success: true;
-    /** Display tier: max > pro > believer > free. */
+    /**
+     * Display tier: max > pro > believer > free. From the three-plan launch the server sends only
+     * `free`, `pro` or `max`; `believer` stays in this type for one release after it, then goes.
+     */
     tier: "free" | "believer" | "pro" | "max";
     /** Live-evaluated tier, independent of the Believer key-issuance label. */
     liveTier: "free" | "pro" | "max";
     stakedCndl: number;
     heldCndl: number;
+    /** `graceMs` is 0 from the three-plan launch: Pro through CNDL then has no grace window. */
     thresholds: {
         minStakedCndl: number;
         minHeldCndl: number;
         graceMs: number;
     };
-    /** `startedAt` is null unless `active` (see the endpoint's own doc for why). */
+    /**
+     * `startedAt` is null unless `active` (see the endpoint's own doc for why). `endsAt` is the
+     * server's deadline for an open window; absent from an older server. Never active from the
+     * three-plan launch.
+     */
     grace: {
         active: boolean;
         startedAt: number | null;
+        endsAt?: number | null;
     };
     maxTierExpiresAt: number | null;
     /**
@@ -424,8 +446,12 @@ export interface AgentTierInfo {
     maxExpired: boolean;
     /** When the lapsed grant ended (ms). Present only when `maxExpired`. */
     maxExpiredAt?: number;
-    /** Which kind of grant lapsed. Present only when `maxExpired`. */
-    maxExpiredSource?: "subscription" | "trial" | "team";
+    /**
+     * Which kind of grant lapsed. Present only when `maxExpired`. `"promo"` is the Max that came free
+     * with a first Pro purchase; while the account still pays for Pro, that lapse is not reported.
+     * Treat an unknown value as a generic Max expiry.
+     */
+    maxExpiredSource?: "subscription" | "trial" | "team" | "promo";
     /**
      * The server's own sentence about the lapse, dated, with the renewal link. Relay it verbatim:
      * it is the same copy the CLI doctor row, the MCP notice, and the tier refusals use, so every
@@ -442,6 +468,21 @@ export interface AgentTierInfo {
         feeRawSum: string;
         count: number;
     }>;
+    /** The live tier's cap floors. Absent from an older server. */
+    tierCaps?: {
+        rateLimitPerMin: number;
+        dailyLaunchCap: number;
+        uploadsPerMin: number;
+        linkedWallets: number;
+    };
+    /** When the tier was evaluated (ms), so a caller can say how fresh it is. Absent from an older server. */
+    checkedAt?: number;
+    /** Max's price. Kept beside `planTable` for compatibility; read `planTable` for every plan. */
+    maxPricing?: PlanPrice;
+    /** Pro's price, null while Pro is not sold. Absent from a server before the plan table. */
+    proPricing?: PlanPrice | null;
+    /** The plan table in force, the same one `getPlans()` returns. Absent from an older server. */
+    planTable?: PlanTable;
 }
 /**
  * One per-transaction spend cap, mirroring `SpendLimit` in `apps/api/src/lib/agent-policy.ts`
@@ -537,13 +578,70 @@ export interface ProfileOpenPosition {
     unrealizedUsd?: number;
     /** The chain this position was traded on. Optional: a server that predates it omits it. */
     chain?: Chain;
+    /**
+     * The wallet holding it: positions live in wallets, so one token held in two wallets is two
+     * positions. `unknown:solana` or `unknown:hood` names the pool for fills no record places in a
+     * wallet, which is not an address. Optional: a server that predates 2026-10-02 omits it.
+     */
+    wallet?: string;
+    /**
+     * The key this position belongs to, by prefix: the wallet's bound key, else the key whose buy
+     * opened it; null for Manual (web-app trades). Optional: a server that predates 2026-10-02 omits it.
+     */
+    agent?: string | null;
+    /** When the round behind this position opened, epoch ms. Optional, as `wallet`. */
+    openedTs?: number;
+    /** Why there is no mark. Present exactly when `markPriceUsd` is absent, on a server that sends it. */
+    unpricedReason?: "no-market-row" | "unusable-price";
+    /**
+     * Worth under one cent at its mark. Still listed and still counted; `openPositionsExDust` leaves it
+     * out. An unpriced position is never dust. Optional: a server that predates 2026-10-02 omits it.
+     */
+    dust?: true;
+}
+/**
+ * Closed positions as one equation (P&L spec PNL-ED-8): `madeUsd + lostUsd + partialSellsUsd`
+ * equals the scope's `realizedNetUsd`. A position is closed when its wallet's quantity returns to
+ * zero through a sale.
+ */
+export interface ProfileClosedSummary {
+    /** Closed positions, those with unknown cost included. */
+    closed: number;
+    /** Sum of the closed positions that made money, USD. */
+    madeUsd: number;
+    /** Sum of the closed positions that lost money, USD: zero or negative. */
+    lostUsd: number;
+    /**
+     * The rest of the realized net: partial sells of positions still open, and fees not in a closed
+     * position (a buy fee on an open position, a sell with nothing open).
+     */
+    partialSellsUsd: number;
+    /** Closed positions won and lost, leaving out those with unknown cost. */
+    wins: number;
+    losses: number;
+    /** Closed positions with unknown cost: listed in `closed`, left out of `wins` and `losses`. */
+    costUnknown: number;
+}
+/**
+ * Fields every scope of `ProfilePnlResult` gained on 2026-10-02 (the total, each `byChain` entry
+ * and each `byWallet` row). Each is optional: a server that predates it omits it.
+ */
+export interface ProfilePnlEngineFields {
+    /** Realized net plus unrealized: the figure the console labels P&L, to the cent. */
+    totalUsd?: number;
+    /** Open positions that are not dust. */
+    openPositionsExDust?: number;
+    /** Closed positions this scope's sales closed. */
+    closedRounds?: number;
+    /** Money made, minus money lost, plus partial sells, equals `realizedNetUsd`. */
+    closed?: ProfileClosedSummary;
 }
 /**
  * One chain's share of a profile's P&L (`ProfilePnlResult.pnl.byChain`): the total's figures over
  * that chain's fills alone. `openPositions` is a COUNT here; the positions themselves are in
  * `pnl.openPositions`, each carrying its `chain`.
  */
-export interface ProfileChainPnl {
+export interface ProfileChainPnl extends ProfilePnlEngineFields {
     realizedGrossUsd: number;
     feesUsd: number;
     realizedNetUsd: number;
@@ -564,7 +662,7 @@ export interface ProfileChainPnl {
         measured: number;
         unmeasured: number;
     };
-    /** Confirmed trades on this chain in the window. */
+    /** This key's ledger fills on this chain in the window. */
     tradesConsidered: number;
 }
 /**
@@ -575,11 +673,27 @@ export interface ProfileChainPnl {
  * that could be marked. A position with no price is counted in `unmarkedPositions` rather than
  * valued at zero, and `oldestMarkAt` says how old the marks are, so a stale figure is visible.
  * Deposits and withdrawals are excluded entirely: funding a wallet is not trading profit.
+ *
+ * Since 2026-10-02 (P&L spec R2) the figures are this key's share of the account's one P&L read,
+ * the read the console, the dashboard, `/books` and `/keys/pnl` share, so they agree with the
+ * console to the cent for the same moment:
+ * - realized and fees are on the fills this key placed; an open position belongs to the wallet's
+ *   bound key, else to the key whose buy opened it; a closed position to the key whose sale closed it;
+ * - each wallet is its own average-cost pool, and the total is the sum of `byWallet`
+ *   (it used to pool every wallet of the key);
+ * - a recorded move between two of the account's wallets carries its cost and realizes nothing;
+ *   tokens that arrive with no cost anyone can state realize nothing when sold;
+ * - `openPositions` counts one per wallet and token, dust included;
+ * - `tradesConsidered` counts this key's ledger fills, and `lookback` / `truncated` are the
+ *   account's activity bound, not 500 of this key's trades.
+ * Every account's realized figure can move on the day a server ships this.
  */
 export interface ProfilePnlResult {
+    /** Optional while Hyperliquid is enabled; separate from spot totals. */
+    hyperliquid?: HyperliquidPnlSection;
     success: true;
     keyPrefix: string;
-    pnl: {
+    pnl: ProfilePnlEngineFields & {
         realizedGrossUsd: number;
         /** Candle fees over the counted fills. Reported separately, netted only into realizedNetUsd. */
         feesUsd: number;
@@ -598,32 +712,51 @@ export interface ProfilePnlResult {
         /** Fills counted, and fills that had no trusted USD price and so were left out entirely. */
         counted: number;
         unvalued: number;
+        /** Fills held out because their token has a fill of unknown size. Part of `unvalued`. Optional. */
+        unresolved?: number;
+        /** The tokens those fills belong to: their P&L is unknown, not zero. Optional. */
+        unresolvedMints?: string[];
+        /** Fees and measured slippage, reported and never netted a second time. Optional. */
+        friction?: {
+            feesUsd: number;
+            slippageUsd: number;
+            slippageBpsAvg?: number;
+            measured: number;
+            unmeasured: number;
+        };
+        /** This key's ledger fills in the window. */
         tradesConsidered: number;
+        /** The account's activity bound, shared by every private P&L read (it was 500 of this key's trades). */
         lookback: number;
         /** True when the lookback window was full, so this is not a lifetime figure. */
         truncated: boolean;
         /**
-         * The same fills divided by the wallet that paid for each trade, ordered by
-         * `tradesConsidered` then address. Optional: a server that predates it omits it.
+         * The same figures divided by wallet, ordered by `tradesConsidered` then address. Optional: a
+         * server that predates it omits it.
          *
-         * Each row is an independent average-cost pool over its own fills, so the rows need not sum to
-         * the total above, which pools all fills and stays correct. A token bought in one wallet and
-         * sold from another leaves the buyer holding it and the seller with a sale that realizes
-         * nothing; and even with no transfer, A buying 100 X for $100, B buying 100 X for $200 and A
-         * selling 100 X for $300 realizes $150 in total but $200 summed over the wallets.
+         * Each wallet is its own average-cost pool, and the total above is the sum of its wallets: A
+         * buying 100 X for $100, B buying 100 X for $200 and A selling 100 X for $300 realizes $200.
+         * (Before 2026-10-02 the total pooled every wallet and realized $150 here.) A token moved
+         * between two of the account's wallets carries its cost once the move is recorded; until then
+         * the buyer still holds it and the seller's sale realizes nothing.
          */
         byWallet?: ProfileWalletPnl[];
         /**
-         * The same figures split by the chain each trade was on, both chains always present. Each is
-         * its own average-cost pool, so the two need not sum exactly to the total above, for the
-         * reason `byWallet` rows need not. Optional: a server that predates it omits it.
+         * The same figures split by chain, both chains always present. A token lives on one chain, so
+         * the two sum to the total above. Optional: a server that predates it omits it.
          */
         byChain?: Record<Chain, ProfileChainPnl>;
     };
 }
-/** One row of `ProfilePnlResult.pnl.byWallet`: one paying wallet's share of a profile's P&L. */
-export interface ProfileWalletPnl {
-    /** The paying wallet's address as stored: base58, or EIP-55 on Hood. */
+/**
+ * One row of `ProfilePnlResult.pnl.byWallet`: one wallet's share of a profile's P&L. A wallet two
+ * keys trade carries this key's share only.
+ */
+export interface ProfileWalletPnl extends ProfilePnlEngineFields {
+    /**
+     * The wallet's address as stored: base58, or EIP-55 on Hood. `unknown:solana` or `unknown:hood`
+     * is the pool for fills no record places in a wallet: a row, not an address.
+     */
     wallet: string;
     payerType: "main" | "linked";
     /**
@@ -657,7 +790,7 @@ export interface ProfileWalletPnl {
         measured: number;
         unmeasured: number;
     };
-    /** Confirmed trades in the window this wallet paid for. */
+    /** This key's ledger fills in the window from this wallet. */
     tradesConsidered: number;
 }
 /**
@@ -895,6 +1028,20 @@ export interface TradeFee {
 /** Solana "built" artifacts: one unsigned transaction, the fee (if any) already embedded inside it. */
 export interface SolanaTradeArtifacts {
     venue: "curve" | "jupiter";
+    /**
+     * Which quoter built the transaction. On the `jupiter` venue Candle also asks DFlow for a quote and
+     * uses it only when its output is strictly larger; otherwise this is `jupiter`. `curve` on the curve venue.
+     */
+    quoteSource?: "curve" | "jupiter" | "dflow";
+    /**
+     * The Jupiter/DFlow race on a `jupiter` venue build: Jupiter's quoted output, DFlow's when it gave an
+     * accepted quote, and why DFlow did not build the transaction when it did not. Absent on the curve venue.
+     */
+    race?: {
+        jupiterOutRaw: string;
+        dflowOutRaw?: string;
+        dflowRefusal?: string;
+    };
     transactionBase64: string;
     quoteAsset: string;
     quoteMint: string;
@@ -1051,6 +1198,16 @@ export interface ExecutedTradeResult {
      * server had already read. Present on the executed response since 2026-09-04.
      */
     route?: TradeRoute;
+    /**
+     * Solana `jupiter` venue only: which quoter built the transaction that executed (`jupiter` or `dflow`),
+     * and the Jupiter/DFlow race behind it. Absent on the curve venue, on Hood, and on an idempotent replay.
+     */
+    quoteSource?: "jupiter" | "dflow";
+    race?: {
+        jupiterOutRaw: string;
+        dflowOutRaw?: string;
+        dflowRefusal?: string;
+    };
 }
 /** POST /api/v1/trade/agent/build response: "built" for a linked payer, "executed" for a main payer (or an idempotent replay of an already-confirmed trade under the same clientTradeId). */
 export type BuildTradeResult = BuildTradeBuiltResult | ExecutedTradeResult;
@@ -1161,6 +1318,249 @@ export interface SignLinkedTransactionResult {
     signedTransaction: string;
     encoding: string;
 }
+/** The EVM TEE wallet a perps action signs from: its row id and its Privy wallet id. */
+export interface PerpsWalletRef {
+    /** The linked wallet's row id (the relay's :id, and the secretStore key). */
+    walletId: string;
+    /** The same wallet's Privy wallet id, the authorization signature's URL target. */
+    privyWalletId: string;
+    /** Sign and submit (default), or stop after the build and its check and return the build. */
+    submit?: boolean;
+}
+export type PerpsSide = "long" | "short";
+export interface PerpsOpenParams extends PerpsWalletRef {
+    coin: string;
+    side: PerpsSide;
+    /** Size in the coin, a decimal string. */
+    size: string;
+    /** `market` (IOC at the mid moved by the slippage) or `limit`. Default: limit when `price` is set. */
+    type?: "market" | "limit";
+    price?: string;
+    tif?: "Gtc" | "Alo" | "Ioc";
+    slippageBps?: number;
+    /** Optional reduce-only take-profit trigger price. */
+    takeProfit?: string;
+    /** Optional reduce-only stop-loss trigger price. */
+    stopLoss?: string;
+}
+export interface PerpsCloseParams extends PerpsWalletRef {
+    coin: string;
+    /** Part of the position to close; the whole position when omitted. */
+    size?: string;
+    slippageBps?: number;
+}
+export interface PerpsCancelParams extends PerpsWalletRef {
+    /** The cloid of an order Candle built (an open, or one of its take-profit / stop-loss legs). */
+    cloid: string;
+}
+export interface PerpsModifyParams extends PerpsWalletRef {
+    cloid: string;
+    price?: string;
+    size?: string;
+    slippageBps?: number;
+}
+export interface PerpsLeverageParams extends PerpsWalletRef {
+    coin: string;
+    leverage: number;
+    mode?: "cross" | "isolated";
+}
+export interface PerpsMarginParams extends PerpsWalletRef {
+    coin: string;
+    /** USD, up to 6 decimals; negative removes isolated margin. */
+    amount: string;
+}
+/** 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";
+    network: HyperliquidNetwork;
+    walletId: string;
+    address: string;
+    nonce: number;
+    action: Record<string, unknown>;
+    typedData: HyperliquidTypedData;
+    claimHash: string;
+    cloid?: string;
+    childCloids?: string[];
+    targetCloid?: string;
+    notionalUsdMicros: number | null;
+    reservedUsdMicros: number;
+    windowKey: string | null;
+    builder: {
+        address: string;
+        feeTenthsBps: number;
+    } | null;
+    exchangeUrl: string;
+    preview: Record<string, unknown>;
+}
+/**
+ * The outcome of one perps action. `signature` is present once the relay signed; it stays valid
+ * for resubmission until the nonce leaves Hyperliquid's two-day window, so a failed submit keeps
+ * it. `exchange` is Hyperliquid's own answer, unchanged (`status: "ok"` or `"err"`, and per-order
+ * statuses for an order).
+ */
+export interface PerpsActionResult {
+    build: PerpsBuild;
+    signature: string | null;
+    submitted: boolean;
+    exchange: unknown | null;
+    submitError?: string;
+}
+export interface PerpsAccountStatus {
+    walletId: string;
+    address: string;
+    network: HyperliquidNetwork;
+    mode: string;
+    standardMode: boolean;
+    accountValue: string;
+    withdrawable: string;
+    builder: string;
+    approvedFeeTenthsBps: number;
+}
+/** `ready: true` when the builder approval is already on Hyperliquid; otherwise the setup action's outcome. */
+export type PerpsSetupResult = PerpsAccountStatus & {
+    ready: boolean;
+    action?: PerpsActionResult;
+};
+export interface PerpsConfig {
+    success: true;
+    network: HyperliquidNetwork;
+    exchangeUrl: string;
+    builder: string | null;
+    builderFeeTenthsBps: number;
+    maxBuilderFeeRate: string;
+    allowedActionTypes: string[];
+    limits: Record<string, unknown>;
+}
+export interface PerpsPositions {
+    success: true;
+    walletId: string;
+    address: string;
+    network: HyperliquidNetwork;
+    mode: string;
+    standardMode: boolean;
+    account: Record<string, string>;
+    withdrawable: string;
+    positions: Record<string, unknown>[];
+}
+export interface PerpsOrderRecord {
+    perpOrderId: string;
+    kind: PerpsBuild["kind"];
+    actionType: string;
+    coin: string | null;
+    nonce: number;
+    cloid: string | null;
+    childCloids: string[];
+    targetCloid: string | null;
+    status: string;
+    venueStatus: string | null;
+    filledSz: string | null;
+    notionalUsdMicros: number | null;
+    reservedUsdMicros: number;
+    releasedUsdMicros: number;
+    windowKey: string | null;
+    builtAt: number;
+    settledAt: number | null;
+}
+export interface PerpsOrders {
+    success: true;
+    walletId: string;
+    address: string;
+    network: HyperliquidNetwork;
+    /** Hyperliquid's open orders for the wallet's address. */
+    open: Record<string, unknown>[];
+    /** Candle's record of every action it built for this wallet, newest first. */
+    recorded: PerpsOrderRecord[];
+    settled: {
+        perpOrderId: string;
+        status: string;
+        releasedUsdMicros: number;
+    }[];
+}
+/**
+ * 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.
+ */
+export interface PerpsDepositParams {
+    /** Idempotency id, 1 to 128 of `A-Za-z0-9._:-`. Rebuilding under the same id answers its job. */
+    clientDepositId: string;
+    asset: "SOL" | "USDC" | "ETH" | "USDG";
+    /** Raw base units of `asset`, as a decimal string. */
+    amountRaw: string;
+    /** The paying TEE wallet's row id (the relay's :id, and the secretStore key). */
+    walletId: string;
+    /** The paying wallet's Privy wallet id. */
+    privyWalletId: string;
+    /** The Hyperliquid account: the EVM TEE wallet's address. The build is refused if it names another. */
+    account: string;
+    /** From Solana only: the EVM TEE wallet whose Hyperliquid account receives. Omit from Hood. */
+    perpsWalletId?: string;
+    /** Relay slippage, 1 to 1000 bps (default 100). */
+    maxSlippageBps?: number;
+    /** Sign and submit (default), or stop after the build and its check. */
+    submit?: boolean;
+}
+/** What `POST /agent/perps/deposit` builds. A Hood build also carries the first sequenced leg. */
+export interface PerpsDepositBuild {
+    success: true;
+    status: "built";
+    clientDepositId: string;
+    depositId: string;
+    chain: "solana" | "hood";
+    venue: "relay";
+    network: HyperliquidNetwork;
+    asset: PerpsDepositParams["asset"];
+    amountRaw: string;
+    walletId: string;
+    walletAddress: string;
+    destination: {
+        walletId: string;
+        address: string;
+        chainId: number;
+        currency: string;
+    };
+    firstDeposit: boolean;
+    expectedOutRaw: string;
+    minimumOutRaw: string;
+    outDecimals: number;
+    floorUsdcMicros: string;
+    minimumCreditUsdcMicros: string;
+    fee: {
+        bps: number;
+        feeRaw: string;
+    };
+    statusChecks: string[];
+    requestId: string | null;
+    expiresAt: number;
+    /** Solana: the one unsigned deposit. */
+    transactionsBase64?: string[];
+    /** Hood: the sequenced leg protocol's first body. */
+    mode?: "sequenced";
+    operationId?: string;
+    legKind?: string;
+    plannedLegCount?: number;
+    nextLeg?: {
+        chainId: number;
+        nonce: number;
+        gas: string;
+        maxFeePerGas: string;
+        maxPriorityFeePerGas: string;
+        to: string;
+        data: string;
+        value: string;
+    };
+}
+export interface PerpsDepositResult {
+    build: PerpsDepositBuild;
+    submitted: boolean;
+    /** `/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
  * `BaseAssetKey`, for the same reason `packages/mcp` inlines its curve constants: this SDK is
@@ -1560,6 +1960,8 @@ export declare class CandleClient {
     private readonly secretStore?;
     private readonly solanaRpcUrl?;
     private readonly evmRpcUrl?;
+    private readonly hyperliquidNetwork;
+    private hyperliquidBuilder?;
     /** Reads scoped to what this key may spend: a one-shot swap's receipt, and spendable balances. */
     readonly wallets: CandleWallets;
     constructor(opts: CandleClientOptions);
@@ -1589,6 +1991,14 @@ export declare class CandleClient {
      * with (possibly none) and lets the server's own auth middleware decide.
      */
     getAgentTier(): Promise<AgentTierInfo>;
+    /**
+     * The plan table in force on this deployment (`GET /api/v1/agent/plans`, no credential): each
+     * plan's price, agent fee, perps builder fee, the limits a new key gets, what it can do
+     * (`capabilities`), and `promoMaxDays`. Quote prices and fees from here rather than hard-coding
+     * them: they differ by deployment and change at the three-plan launch. `planTableRows()` renders
+     * it. A server that predates the table answers 404 (`CandleApiError`).
+     */
+    getPlans(): Promise<AgentPlansResult>;
     dryRunLaunch(req: LaunchRequest): Promise<DryRunResult>;
     /**
      * Blocking launch with idempotent retries. Generates `clientLaunchId` when absent and
@@ -1652,6 +2062,11 @@ export declare class CandleClient {
      * (GET /api/v1/agent/keys/{prefix}/pnl). Read `unrealizedUsd` with `unmarkedPositions` and
      * `oldestMarkAt`: an unpriced position is counted there, never valued at zero.
      *
+     * The figures are the key's share of the account's one P&L read, the console's figures to the
+     * cent (`pnl.totalUsd` is the console's P&L). Since 2026-10-02 the total is the sum of the key's
+     * wallets, not one pool across them, and `lookback` is the account's activity bound; see
+     * `ProfilePnlResult` for every meaning that changed.
+     *
      * Check `unvalued` and `truncated` before quoting the number: the first counts fills that had
      * no trusted USD price and were left out rather than counted as zero, the second says the
      * lookback window was full and this is not a lifetime figure.
@@ -2019,6 +2434,68 @@ export declare class CandleClient {
      * depends on an earlier leg already being mined.
      */
     private signBroadcastAndWaitEvmLeg;
+    /** The server's perps settings: network, Candle's builder, this key's fee, and its limits. */
+    perpsConfig(): Promise<PerpsConfig>;
+    /**
+     * One-time setup (R1): approves Candle's builder fee at 0.1% unless Hyperliquid already shows
+     * 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>;
+    /** 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. */
+    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. */
+    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>;
+    /** Fills, read live from Hyperliquid by the wallet's address. */
+    perpsFills(walletId: string): Promise<{
+        success: true;
+        fills: Record<string, unknown>[];
+    }>;
+    /** Funding payments since `startTime` (epoch ms; default the last 7 days). */
+    perpsFunding(walletId: string, startTime?: number): Promise<{
+        success: true;
+        startTime: number;
+        funding: Record<string, unknown>[];
+    }>;
+    /**
+     * 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.
+     * From Solana that is one deposit transaction; from Hood each sequenced leg (approve, then the
+     * deposit) is signed and submitted in turn. The fill is Relay's, after the deposit lands: read it
+     * with `perpsDepositStatus()`. Candle checks Relay's steps before it stamps them; `candle perps
+     * deposit` additionally decodes them on the caller's machine.
+     */
+    perpsDeposit(params: PerpsDepositParams): Promise<PerpsDepositResult>;
+    /** A deposit's job: what was built and submitted, the Hood operation, and Relay's fill status. */
+    perpsDepositStatus(clientDepositId: string): Promise<{
+        success: true;
+        job: Record<string, unknown>;
+    }>;
+    /** The builder every perps build is checked against (see `hyperliquidBuilder` in the options). */
+    private perpsBuilder;
+    /**
+     * 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.
+     */
+    private perpsComplete;
+    /**
+     * 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.
+     */
+    private signLinkedTypedData;
     private requireKey;
     private headers;
     private requestJson;
@@ -2046,7 +2523,7 @@ export declare class CandleClient {
     private jsonRpcCallRaw;
 }
 /** This build's own version. Kept in lockstep with package.json by the release-bump CI guard. */
-export declare const SDK_VERSION = "0.4.5";
+export declare const SDK_VERSION = "0.4.7";
 /** 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