@candledottv/agent-sdk 0.4.6 → 0.4.8

package/dist/client.d.ts

@@ -27,6 +27,8 @@
  *   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";
@@ -225,6 +227,8 @@ export interface ConfirmSelfLaunchResult extends LaunchResult {
 export interface DryRunResult {
     success: true;
     dryRun: true;
+    /** Wallet the real launch pays from; null when no wallet is available for the resolved chain. */
+    launchWallet: string | null;
     resolved: {
         chain: Chain;
         quoteAsset: string;
@@ -236,9 +240,36 @@ export interface DryRunResult {
     };
     checks: {
         image: string;
-        exclusiveEligible: boolean;
+        /** `"ok"` when a `bannerUrl` was sent and checked; absent otherwise. */
+        banner?: string;
+        /**
+         * Present only for an exclusive (or test-exclusive) mode, the modes that run the Believer
+         * check, and then `true`: an ineligible account gets EXCLUSIVE_NOT_ELIGIBLE instead. Absent in
+         * any other mode, where nothing was checked.
+         */
+        exclusiveEligible?: boolean;
     };
     matrixVersion: number;
+    /**
+     * Solana only: the assembled launch transaction's size. Absent on Hood, and when the size
+     * computation itself failed transiently. A body that would not fit fails the dry run with
+     * TRANSACTION_TOO_LARGE instead, so `fits` is always true when present.
+     */
+    size?: {
+        txBytes: number;
+        limit: number;
+        maxNameBytes: number;
+        fits: boolean;
+    };
+}
+/**
+ * POST /api/v1/launch/self/dry-run response: the headless dry run's shape, with `launchWallet` the
+ * linked or TEE wallet `buildSelfLaunch()` would pay from, and `launchWalletId` its id. Never
+ * checks that wallet's balance.
+ */
+export interface SelfLaunchDryRunResult extends Omit<DryRunResult, "launchWallet"> {
+    launchWallet: string;
+    launchWalletId: string;
 }
 /** POST /api/v1/launch/headless blocking (or replayed) success response. */
 export interface LaunchResult {
@@ -409,21 +440,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;
     /**
@@ -435,8 +475,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
@@ -453,6 +497,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`
@@ -487,22 +546,46 @@ export interface ImportWalletResult {
     privyWalletId: string;
 }
 /**
- * One row of `GET /api/v1/agent/wallets`'s `page` array: the linkedWallets Convex row minus
- * internal bookkeeping fields (userAddress/addressLower/privyWalletId/verifiedAt) a caller has
- * no use for. `privyPolicyId` present is what makes a row spend-capable (the import flow); its
- * absence means attribution-only (link-existing). `revokedAt` set means the row is a
- * tombstone -- `listWallets()` excludes these by default; pass `includeRevoked: true` to see
- * them.
+ * What a linked wallet can do, decided by the server (BE-860): `tee`, a TEE wallet bound to one
+ * key; `imported`, a spend-capable wallet from the import flow; `linked`, attribution-only, which
+ * cannot sign. Not `SelfWallet.kind`, whose `linked` covers both of the last two.
+ */
+export type WalletKind = "tee" | "imported" | "linked";
+/**
+ * One row of `GET /api/v1/agent/wallets`'s `page` array. The server returns the whole linkedWallets
+ * row, so a page also carries fields this type does not name (`userAddress`, `addressLower`,
+ * `verifiedAt` and others); the type names the ones a caller acts on. Branch on `walletKind` for
+ * what a row can do. `revokedAt` set means the row is a tombstone -- `listWallets()` excludes these
+ * by default; pass `includeRevoked: true` to see them.
  */
 export interface LinkedWalletRow {
     _id: string;
     chain: WalletChain;
     address: string;
+    /** The wallet's Privy id: what `selfLaunch()`, `trade()` and `launchAtomic()` sign a linked leg with. */
+    privyWalletId: string;
     label?: string;
     privyPolicyId?: string;
     signerQuorumId?: string;
     revokedAt?: number;
     addedVia: "agent" | "session";
+    /**
+     * What this wallet can do: `tee`, `imported` (spend-capable) or `linked` (attribution-only).
+     * Stable; derived by the server. Absent only from an API that predates it (before 2026-10), where
+     * `privyPolicyId` present meant spend-capable and its absence attribution-only.
+     */
+    walletKind?: WalletKind;
+    /**
+     * Served, but its values are internal code names and not promised (today `"ember-tee"`, or the
+     * legacy `"ember-hot"`, on a TEE wallet; absent on every other row). Use `walletKind`.
+     */
+    profile?: "ember-tee" | "ember-hot";
+    /**
+     * TEE wallets only: whether the account owner has allowed this wallet to pay for a launch.
+     * Absent reads as false. Only the owner can change it (`PUT /api/v1/agent/wallets/:id/capabilities`
+     * with a device token or session; the CLI's `candle wallets allow-launch`).
+     */
+    allowLaunch?: boolean;
 }
 /** GET /api/v1/agent/wallets response: one page of the account's linked wallets. */
 export interface ListWalletsResult {
@@ -548,13 +631,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;
@@ -575,7 +715,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;
 }
 /**
@@ -586,11 +726,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;
@@ -609,32 +765,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";
     /**
@@ -668,7 +843,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;
 }
 /**
@@ -775,8 +950,9 @@ export interface PortfolioHoodSection {
  *
  * `prices` keys a Solana mint by its address, Hood native ETH as `hood:native`, and a Hood token
  * as `hood:<lowercased contract>`, so lowercase a Hood `mint` before the lookup. Read `complete`
- * before quoting a total: it is false when the wallet list was cut off or any wallet's read failed
- * on either chain.
+ * before quoting a total: it is false when the wallet list was cut off, any wallet's read failed
+ * on either chain, or an LP position could not be read. `walletsComplete` is the list on its own.
+ * Absent on a server that predates it, in which case `complete: false` may be either cause.
  *
  * Not typed here: the `lp` section a deployment with LP enabled adds.
  */
@@ -790,6 +966,11 @@ export interface PortfolioResult {
     /** Solana addresses whose read failed. Hood's are in `hood.unavailable`. */
     unavailable: string[];
     complete: boolean;
+    /**
+     * Whether every wallet Candle knows was listed. False only when that list was cut off.
+     * Independent of `complete`. Absent on a server that predates the field.
+     */
+    walletsComplete?: boolean;
 }
 /**
  * One row of a profile's trade history: what was ordered, what actually filled, what it cost,
@@ -813,7 +994,26 @@ export interface ProfileTradeRow {
     filledAmount?: number;
     usdValue?: number;
     feeBps: number;
+    /**
+     * An estimate from the trade's size and rate, scaled by collected over planned fee. 0 when no fee
+     * was collected, including when the plan forgoes it.
+     */
     feeUsd?: number;
+    /**
+     * The fee the build planned, in raw units of `quoteAsset`: every venue pays its fee in the quote
+     * asset. Absent on a server before 2026-10-05.
+     */
+    feeRaw?: string;
+    /**
+     * What the treasury received, in raw units of `quoteAsset`. Confirmed rows only. Equal to
+     * `feeRaw` unless it was measured otherwise.
+     */
+    feeCollectedRaw?: string;
+    /**
+     * True for a `built` row that holds a signature: the trade is on chain but was not booked.
+     * `errorCode` says why. Absent on a server before 2026-10-05.
+     */
+    landedUnconfirmed?: boolean;
     payerWallet: string;
     venue?: "curve" | "jupiter" | "dex";
     signature?: string;
@@ -824,6 +1024,22 @@ export interface ProfileTradesResult {
     success: true;
     keyPrefix: string;
     trades: ProfileTradeRow[];
+    /**
+     * Pass back as `cursor` for the next, older page. Present whenever the page read a full `limit`,
+     * so a short or even empty page can still have one: only its absence means the end.
+     */
+    nextCursor?: string;
+}
+/** Options for `getProfileTrades`. */
+export interface ProfileTradesOptions {
+    /** Rows to read, 1 to 1,000. Default 200. */
+    limit?: number;
+    /** Inclusive lower bound on `createdAt`: an ISO 8601 string, epoch milliseconds, or a `Date`. */
+    since?: string | number | Date;
+    /** Exclusive upper bound on `createdAt`, in the same forms as `since`. */
+    until?: string | number | Date;
+    /** A previous page's `nextCursor`, verbatim. */
+    cursor?: string;
 }
 /** `GET /api/v1/agent/keys/{prefix}/wallets` response. */
 export interface ProfileWalletsResult {
@@ -845,6 +1061,27 @@ export type TradePayer = {
     type: "linked";
     linkedWalletId: string;
 };
+/**
+ * The Jupiter/DFlow race one Solana `jupiter`-venue build ran. Raw amounts and lamports are decimal
+ * strings. Present only while DFlow is enabled on the deployment, and never on paper or a replay.
+ */
+export interface TradeRace {
+    jupiterOutRaw: string;
+    /** DFlow's quoted output, when it gave an accepted quote. */
+    dflowOutRaw?: string;
+    /**
+     * Why DFlow did not build the transaction: `quote:<reason>`, `build:<reason>` (including
+     * `build:priority_fee_over_cap`), or `net:fee_exceeds_edge` when its larger output did not
+     * cover its larger priority fee.
+     */
+    dflowRefusal?: string;
+    /** The priority-fee ceiling both builds were given, in lamports. Absent from an older server. */
+    priorityFeeCapLamports?: string;
+    /** The priority fee decoded from Jupiter's built transaction. Absent when Jupiter built none. */
+    jupiterPriorityFeeLamports?: string;
+    /** The priority fee decoded from DFlow's built transaction. Absent when DFlow returned none. */
+    dflowPriorityFeeLamports?: string;
+}
 /** POST /api/v1/trade/agent/build request body. */
 export interface BuildTradeRequest {
     /** Idempotency key, unique per account; shared with the matching confirmTrade() call. */
@@ -856,6 +1093,18 @@ export interface BuildTradeRequest {
     payer: TradePayer;
     /** Bps, 0-10000. Server defaults to 100 (1%) when omitted. */
     maxSlippageBps?: number;
+    /**
+     * The most this build may bid as a Solana priority fee, in lamports: an integer from 0 to
+     * 10,000,000. Replaces the default ceiling of 25 bps of the trade's SOL leg (floored at 100,000,
+     * capped at 10,000,000), so it can raise the ceiling for a small trade that has to land as well
+     * as lower it. `0` asks for no priority fee, and is not the same as omitting the field.
+     *
+     * Applies to Solana `jupiter`-venue builds and is ignored everywhere else (Hood, the curve
+     * venue, paper). A hard limit on DFlow; a requested limit on Jupiter, whose paid figure is
+     * `race.jupiterPriorityFeeLamports` when the response carries `race`. A very low value may not
+     * land before its blockhash expires.
+     */
+    maxPriorityFeeLamports?: number;
     /**
      * What the wallet spends on a buy, or receives on a sell. Safe to pass straight through from a
      * `POST /trade/agent/quote` response: the two endpoints take the same ids.
@@ -906,6 +1155,17 @@ 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: net of each venue's priority fee when a leg is
+     * SOL, raw otherwise. 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?: TradeRace;
     transactionBase64: string;
     quoteAsset: string;
     quoteMint: string;
@@ -1062,6 +1322,12 @@ 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?: TradeRace;
 }
 /** 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;
@@ -1332,6 +1598,89 @@ export interface PerpsOrders {
         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
@@ -1762,6 +2111,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
@@ -1816,15 +2173,21 @@ export declare class CandleClient {
      * Includes FAILED trades, deliberately: a record that dropped them would misrepresent what the
      * agent did, and `errorCode` is how you find out why one did not go through. For a spreadsheet
      * instead of JSON, request the same path with `?format=csv`.
+     *
+     * Newest first. Narrow by `since` / `until` and page by passing `nextCursor` back as `cursor`
+     * until it is absent; a short page is not the end.
      */
-    getProfileTrades(keyPrefix: string, opts?: {
-        limit?: number;
-    }): Promise<ProfileTradesResult>;
+    getProfileTrades(keyPrefix: string, opts?: ProfileTradesOptions): Promise<ProfileTradesResult>;
     /**
      * One profile's realized P&L, fees, and open positions marked at current prices
      * (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.
@@ -1944,6 +2307,14 @@ export declare class CandleClient {
         signerPublicKey: string;
         label?: string;
     }): Promise<ImportWalletResult>;
+    /**
+     * Self-signed launch dry run: the same body as `buildSelfLaunch()`, the same checks (payer and
+     * TEE rules, plan, the key's caps), and the same refusals, without building, reserving or
+     * recording anything; the `clientLaunchId` stays unused. Does not check the payer's balance, the
+     * day cap, a `clientLaunchId` already used with another body or payer, or a Solana TEE wallet's
+     * USD spend window; `buildSelfLaunch()` can still refuse for those.
+     */
+    dryRunSelfLaunch(req: BuildSelfLaunchRequest): Promise<SelfLaunchDryRunResult>;
     /**
      * Self-signed launch build: returns an unsigned transaction for the agent to sign and
      * broadcast itself. Candle never signs and never holds the signer key. Signing a linked wallet
@@ -2124,8 +2495,9 @@ export declare class CandleClient {
      * Signs, broadcasts, and waits for its receipt, then -- when the build carried a `feeTransfer`
      * leg (a platform fee applies) -- does that leg next at `nonce + 1` and captures `feeTxHash`.
      * Requires `evmRpcUrl`; throws a clear error naming it when unset, before any signing. Does NOT
-     * send a dev buy: a Hood self-launch's dev buy runs out-of-band, server-side, after confirm --
-     * the build response never includes a dev-buy leg, and this method does not assemble one.
+     * send a dev buy: a Hood self-launch's dev buy is a separate transaction the caller sends itself
+     * and reports to `confirmSelfLaunch` as `devBuySignature`. The build response never includes a
+     * dev-buy leg, and this method does not assemble one.
      */
     selfLaunch(req: SelfLaunchRequest): Promise<ConfirmSelfLaunchResult>;
     /**
@@ -2190,8 +2562,13 @@ export declare class CandleClient {
      * transaction hash. Shared by trade()'s and selfLaunch()'s Hood branches, both of which must run
      * their legs strictly sequentially -- see trade()'s jsdoc for why a later leg's `estimateGas`
      * depends on an earlier leg already being mined.
+     *
+     * `surfaceLegOutcome` is the fee leg only. A receipt revert, a receipt read that fails, a
+     * receipt timeout, or a broadcast whose result is ambiguous then throws `EvmLegOutcome` with
+     * the hash once it is known. Every other caller gets the original error.
      */
     private signBroadcastAndWaitEvmLeg;
+    private broadcastAndWaitEvmLeg;
     /** The server's perps settings: network, Candle's builder, this key's fee, and its limits. */
     perpsConfig(): Promise<PerpsConfig>;
     /**
@@ -2228,6 +2605,20 @@ export declare class CandleClient {
         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;
     /**
@@ -2266,8 +2657,13 @@ export declare class CandleClient {
      */
     private jsonRpcCallRaw;
 }
+/** Test-only. Pass null to restore the production receipt wait. */
+export declare function __setEvmReceiptWaitForTest(opts: {
+    timeoutMs?: number;
+    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.4.6";
+export declare const SDK_VERSION = "0.4.8";
 /** 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