@candledottv/agent-sdk 0.6.7 → 0.6.8

package/README.md

@@ -52,7 +52,7 @@ The API key is attached as `x-api-key` on every request when configured. The key
 (`launch`, `launchAsync`, `dryRunLaunch`, `getLaunchJob`, `reportActivity`, `uploadImage`)
 refuse to fetch without one and throw a plain `Error` locally instead of a server 401.
 
-## Launching with built-in idempotent retries
+## Embedded launches with built-in idempotent retries
 
 `launch()` fills in a `clientLaunchId` (`"sdk-" + crypto.randomUUID()`) when you omit one, and
 retries transient failures by re-sending the SAME id, which the server's idempotency ledger
@@ -73,7 +73,7 @@ try {
     symbol: "TREND",
     imageUrl: "https://example.com/logo.png",
     chain: "solana",
-    buyAmount: 100_000_000, // lamports
+    buy: "0.1", // SOL
   })
   console.log("minted", result.mint, "explorer:", result.links.explorer, "id:", result.clientLaunchId)
 } catch (error) {
@@ -100,16 +100,56 @@ else console.error("failed:", job.errorCode)
 Need a hosted image first? `uploadImage(bytes, contentType)` posts raw bytes to
 `/api/v1/uploads/agent-image` and returns `{ imageUrl }`, ready for the launch body.
 
-`launch()` works on every plan, Free included: it launches from the account's embedded wallet,
-and `buyAmount` adds an optional dev buy: in the launch transaction on Solana (up to 0.5 SOL by default), a best-effort follow-up transaction on Hood.
+`launch()` with an embedded wallet works on every plan, Free included. `buy` adds an optional
+first buy: atomic on Solana (up to 0.5 SOL by default), a best-effort follow-up on Hood.
 
-Two more paths need the Pro or Max plan. `selfLaunch()` launches from a linked or TEE wallet the
-agent signs for locally. `launchAtomic()` lands the launch and 1 to 4 first buys in one Jito bundle: several
+A TEE wallet passed to `launch()` needs Pro or Max and the agent signs locally; the deprecated
+`selfLaunch()` follows the same path. `launchAtomic()` lands the launch and 1 to 4 first buys in one Jito bundle: several
 transactions in the same block, all or none. Each buy is paid by the embedded wallet or a linked
 wallet; the same payer may fund more than one leg. A TEE wallet can be the creator or a buyer, and
-`selfLaunch()` from a TEE wallet can carry a `buyAmount`, only where the server has
+A TEE `launch()` can carry `buy`, only where the server has
 `TEE_LAUNCH_BUYS_ENABLED` on. It is off by default, and a TEE wallet is refused there until it is.
 
+## One launch method
+
+`launch()` and `dryRunLaunch()` take the shared generated launch fields. Omit `wallet` or use
+`wallet: "embedded"` to pay from the account's embedded wallet. Name a TEE wallet by label, id or
+address, or pass `{ linkedWalletId, privyWalletId }` for an existing SDK integration. A named
+wallet's chain is inferred; supply `chain: "hood"` for an explicit Hood wallet object. Conflicting
+chains or quote assets are refused before building. The SDK uses your configured `privyAppId`
+and `secretStore` for TEE signing, and `solanaRpcUrl` / `evmRpcUrl` for caller broadcasts.
+
+```ts
+await candle.launch({
+  wallet: "spider-01",
+  name: "Trend Coin",
+  symbol: "TREND",
+  imageUrl: "https://example.com/logo.png",
+  buy: "0.1", // optional, whole units of the quote asset (SOL by default)
+})
+```
+
+`buy` is a decimal string: SOL has 9 decimals, USDC/CNDL/USDG 6, ETH 18. Empty or zero means no
+first buy. Excess precision and passing both `buy` and deprecated raw `buyAmount` are refused
+locally. `socials` accepts only `website`, `twitter`, `telegram` and `discord`, each an http(s) URL.
+The remaining limits, defaults and field help come from the shared launch definition; the server
+validates ranges and eligibility.
+
+Embedded launches use `/launch/headless` with or without a buy. TEE launches use `/launch/self/build`
+and the existing sign/broadcast/confirm flow; a Solana TEE buy signs the returned bundle and sends
+it to `/launch/atomic/submit`. Dry runs use the selected family's `/dry-run`. Existing server
+gates still apply: embedded-wallet allowance, launch availability, and TEE tier, `allowLaunch`
+and first-buy switches. No server switch is enabled by this SDK release. `launchAsync()` remains
+embedded-only.
+
+Migration for this release: replace `selfLaunch({ linkedWalletId, privyWalletId, ...fields })`
+with `launch({ wallet: { linkedWalletId, privyWalletId }, ...fields })`. Replace raw `buyAmount`
+with whole-unit `buy`. `selfLaunch()`, `buildSelfLaunch()` and `dryRunSelfLaunch()` are deprecated
+for one release; existing calls still work. `confirmSelfLaunch()` remains the recovery method.
+TEE `launch()` preserves `SelfLaunchOutcomeError` on Hood: after a create-curve broadcast,
+recover by confirming its original id and hashes, never by starting another launch. Embedded
+launch retries and Solana same-id recovery retain their existing behavior.
+
 ## Trading, swaps and account reads
 
 ```ts
@@ -223,7 +263,7 @@ safe for a main payer.
 | `failed`, other | not confirmed. A row with broadcast evidence may still be on chain, and a same-id call answers `stage: "unconfirmed"` for it. The same-id call is the check | call again with the same id |
 | `built` | in flight or unresolved | a same-id `trade()` answers `IDEMPOTENCY_CONFLICT`. If it carries `stage: "unconfirmed"` and `retryable: false`, check its `signature` on chain and do not retry |
 
-### `launch()`, `launchAsync()`
+### Embedded `launch()`, `launchAsync()`
 
 Retry with the same `clientLaunchId` and body, or read `getLaunchJob(id)` (`waitForLaunch(id)`
 polls it). The rules are the ones under "Idempotency" in
@@ -440,28 +480,35 @@ read the existing `GET /api/v1/agent/keys/{prefix}/pnl`. The answer adds an opti
 `hyperliquid` section, and the CLI prints it under **Hyperliquid**. The existing read
 authentication applies; on an older API the section is simply absent. No additional signing, deposit or setup is needed for this read.
 
-The section reports main-exchange perp `realizedGrossUsd` (venue `closedPnl`), signed
-`fundingUsd` (received positive, paid negative), `feesUsd` (venue fees including builder fees;
-rebates are negative), and `realizedNetUsd = realizedGrossUsd + fundingUsd - feesUsd`.
-Builder fees are already included in the venue fee and are not subtracted again. These figures
-stay separate from spot and LP totals and exclude unrealized perps, deposits and withdrawals.
-
-Coverage is **currently bound EVM TEE wallets since the current TEE binding**,
-shown in `byWallet` with `startTime` in epoch milliseconds. That start is the latest rebind
-onto this key, or the wallet's creation time when it was bound then and never rebound. A
-rebound wallet does not bring its previous key's history. A wallet-set row is not required,
-and an older one cannot move the start earlier than the binding. Revoked and previous
-bindings, spot and HIP-3 fills are excluded. This is a binding-period read, not lifetime or
-order-level attribution.
-
-Reads use the venue client's two-second cache. `userFills` is capped at 2,000 recent rows;
-`userFunding` at 500 rows from `startTime`, and this response covers at most 20 bound
-wallets. `truncated` flags any reached history cap or remaining wallet page; `byWallet` names
-`fillsTruncated` and `fundingTruncated`. Funding and fills can cover different time spans when
-capped: a partial net must not be quoted as a lifetime figure. On upstream, wallet-discovery or
-malformed-data failure the section is `{ read: false, reason }`, without amounts; spot PnL still
-answers. An empty successful read is `{ read: true, ... }` with zero amounts. `--json` preserves
-the section and its coverage fields. Agent boards are outside this slice.
+The section reports main-exchange perps for **every EVM TEE wallet bound to the key's profile,
+per binding period** (`coverage: "profile"`; revoked, swept and rebound wallets included for the
+time they were the profile's). `realizedGrossUsd` is the venue `closedPnl`, `fundingUsd` is
+signed (received positive, paid negative), `feesUsd` is venue fees including builder fees
+(rebates are negative), and `realizedNetUsd = realizedGrossUsd + fundingUsd - feesUsd`. Builder
+fees are already included in the venue fee and are not subtracted again. `unrealizedUsd` is the
+open positions' unrealized at each wallet's cutoff, `netUsd = realizedNetUsd + unrealizedUsd`
+(both USD decimal strings), and `positions` lists the open positions, each with
+`fundingNetUsd` positive when earned. Deposits and withdrawals are not P&L.
+
+Facts and unrealized stop at the same cutoff per wallet. For a wallet still bound to the
+profile, the cutoff is Hyperliquid's position time at this read: the fills and funding since the
+wallet's last stored snapshot are read through that time and must reconcile with the positions
+(each fill continues the previous position, the positions match, and every open hour has its
+funding row). That wallet's `byWallet` entries say `reconciliation: "live"`, and the CLI prints
+"(live, not yet settled)". A wallet whose binding to the profile ended before its last stored
+snapshot is `settled`. `markedAt` is the oldest wallet cutoff, `completeThroughMs` the lowest
+completeness watermark, and `perpsSnapshotId` identifies the cutoff vector. "Reconciled" is not
+"complete": a round opened and closed between two fills Hyperliquid never returned cannot be
+seen.
+
+The net is **also counted in the total**: when `read` is true, `pnl.totalUsd` includes `netUsd`
+and the answer's `perpsInTotal` is `true`; the CLI's `Total` line says it includes Hyperliquid.
+When the section cannot be read or reconciled within the request's Hyperliquid budget, it is
+`{ read: false, code, reason }` without amounts, `pnl.totalUsd` is the spot total,
+`perpsInTotal` is `false`, and the CLI says the total excludes perps and why. Never a zero.
+`historyPartial` (and `partialReasons`) flags history the stored record does not cover;
+`truncated` repeats it for older CLIs. At most 20 wallets are read. `--json` preserves the
+section and its coverage fields. Agent boards are outside this slice.
 
 
 ## CNDL staking

package/dist/client.d.ts

@@ -19,7 +19,7 @@
  *   endpoints (launch, dry run, jobs, activity, uploads) refuse to fetch at all without one,
  *   throwing a plain `Error` that names the missing option, so a misconfigured agent fails
  *   fast and locally instead of with a server 401.
- * - Idempotent launch retries: `launch()` fills in `clientLaunchId` ("sdk-" + UUID) when the
+ * - Embedded launch retries: `launch()` fills in `clientLaunchId` ("sdk-" + UUID) when the
  *   caller omits one and re-sends the SAME id on network errors, non-envelope 5xx responses,
  *   retryable envelopes with 5xx status, and the retryable in-flight 409. It never retries a
  *   non-retryable envelope (IDEMPOTENCY_CONFLICT with a different body, LAUNCH_DISABLED, every
@@ -45,6 +45,7 @@ import { type PerpsBookOptions, type PerpsBookResult, type PerpsCandlesOptions,
 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 { GeneratedLaunchFields } from "./launch-definition";
 import { type PerpsFillsPage, type PerpsFundingPage, type PerpsHistoryOptions } from "./perps-history";
 import type { AgentPlansResult, PlanPrice, PlanTable } from "./plans";
 import type { SecretStore } from "./secret-store";
@@ -230,57 +231,18 @@ export interface LaunchCurve {
     /** G: the quote the curve raises before it graduates. */
     threshold: string;
 }
-/** POST /api/v1/launch/headless request body. The server is the authoritative validator. */
-export interface LaunchRequest {
-    /** Idempotency key, unique per account. launch() generates "sdk-" + UUID when absent. */
-    clientLaunchId?: string;
-    chain?: Chain;
-    quoteAsset?: string;
-    mode?: LaunchTier;
-    /** `mode: "exp-custom"` only, and required there. Dry-run first: the API checks the limits. */
-    curve?: LaunchCurve;
-    /**
-     * An `exp-` mode only: an extra creator fee of 100 or 200 basis points on top of the curve's 1%
-     * and the pool's 0.5%, paid to the creator in full. 0 is the same as leaving it out.
-     */
-    creatorFeeBps?: 0 | 100 | 200;
-    stakerAllocationBps?: number;
-    /** Solana only: the graduated pool's fee. Omitted keeps the flat 50 bps pool. */
-    poolFee?: PoolFee;
-    /**
-     * Solana preset tiers only: "curve_price" opens the pool at the curve's last price and burns the rest.
-     * Omitted defaults to "curve_price" when stakerAllocationBps plus the team allocation fit the tier's
-     * limit (dry-run graduation.maxStakerCarveBps), otherwise falls back to "legacy" without refusal.
-     * Set "legacy" explicitly to opt out. Explicit "curve_price" is refused above the limit.
-     */
-    poolOpen?: "legacy" | "curve_price";
-    /** Solana exp- curves only: "full_range" opens the pool across the whole price range. Omitted is "floor". */
-    expPoolShape?: "floor" | "full_range";
-    /** Hood only, required there: which Uniswap version the curve graduates through. */
-    dexVersion?: "v3" | "v4";
-    /** Initial dev buy. Solana: JSON number in the pair's base units. Hood: decimal string in wei. */
-    buyAmount?: number | string;
-    name: string;
-    symbol: string;
-    /** Roughly SQUARE (at most 1.5:1): this is the avatar. Wider is rejected as IMAGE_WRONG_SHAPE. */
-    imageUrl: string;
-    /**
-     * Optional WIDE artwork (wider than 1.5:1, e.g. 1200x630) for the token page's banner strip.
-     * Where a share card or OG image belongs; a square image here is rejected as
-     * BANNER_WRONG_SHAPE. Omitted, the strip falls back to `imageUrl`.
-     */
-    bannerUrl?: string;
-    description?: string;
-    socials?: {
-        twitter?: string;
-        telegram?: string;
-        website?: string;
-        discord?: string;
+/** Shared launch fields, plus SDK wallet identifiers and the legacy raw first buy. */
+export interface LaunchRequest extends Omit<GeneratedLaunchFields, "wallet" | "dryRun"> {
+    /** Omitted means embedded. A TEE wallet may be named by label, address or id. */
+    wallet?: string | {
+        linkedWalletId: string;
+        privyWalletId: string;
     };
-    visibility?: "production" | "test" | "local" | "hidden";
+    /** @deprecated Use buy, a decimal string in whole quote units, for one release. */
+    buyAmount?: number | string;
 }
 /** POST /api/v1/launch/self/build request body. Extends LaunchRequest with linkedWalletId. */
-export interface BuildSelfLaunchRequest extends LaunchRequest {
+export interface BuildSelfLaunchRequest extends Omit<LaunchRequest, "wallet" | "buy"> {
     linkedWalletId: string;
 }
 /** POST /api/v1/launch/self/build response for Solana (unsigned transaction). */
@@ -1210,8 +1172,18 @@ export interface ProfileChainPnl extends ProfilePnlEngineFields {
 export interface ProfilePnlResult {
     /** Public board figures including fee income; independent of pnl.totalUsd and its coverage. */
     board?: ProfileBoardPnl;
-    /** Optional while Hyperliquid is enabled; separate from spot totals. */
+    /**
+     * The key's profile on Hyperliquid, every binding period: its own heading and net, also counted
+     * in `pnl.totalUsd` when `read` is true (see `perpsInTotal`). Unrealized is at each wallet's live
+     * cutoff, and facts stop at that same cutoff. A `read: false` section is never a zero.
+     */
     hyperliquid?: HyperliquidPnlSection;
+    /**
+     * True when `pnl.totalUsd` includes `hyperliquid.netUsd`. False when the section was not read,
+     * and then `pnl.totalUsd` is the spot total. Absent from servers that predate it: their
+     * `pnl.totalUsd` never included perps.
+     */
+    perpsInTotal?: boolean;
     success: true;
     keyPrefix: string;
     pnl: ProfilePnlEngineFields & {
@@ -2888,7 +2860,7 @@ export interface AtomicFirstBuyRequest {
  * buy via `firstBuys` instead, so it lands as bundle leg 1 against a still-virgin curve) plus the
  * creator's own payer and 1-4 first-buy legs.
  */
-export interface BuildAtomicLaunchRequest extends Omit<LaunchRequest, "buyAmount"> {
+export interface BuildAtomicLaunchRequest extends Omit<LaunchRequest, "buyAmount" | "buy" | "wallet"> {
     payer: AtomicLaunchPayer;
     /** 1 to 4 buy legs, sharing the launch transaction's own recent blockhash and landing atomically with it (Jito's 5-transaction bundle cap: 1 launch + up to 4 buys). */
     firstBuys: AtomicFirstBuyRequest[];
@@ -3156,9 +3128,14 @@ export declare class CandleClient {
      * 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
+    dryRunLaunch(req: LaunchRequest): Promise<DryRunResult | SelfLaunchDryRunResult>;
+    /** Resolve only wallets explicitly named by this caller; server gates remain authoritative. */
+    private prepareLaunch;
+    /**
+     * Launch from the named wallet (embedded by default), optionally with a whole-unit `buy`.
+     * TEE wallets use selfLaunch()'s signing and recovery flow, including SelfLaunchOutcomeError
+     * on Hood. Embedded launches use the idempotent retries described below.
+     * Generates `clientLaunchId` when absent and
      * re-sends the SAME id on retryable failures; see the module doc for the exact policy.
      *
      * The id this call sent, yours or the generated one, is on the result
@@ -3236,9 +3213,10 @@ export declare class CandleClient {
      * `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.
+     * cent (`pnl.totalUsd` is the console's P&L, plus the Hyperliquid net when `perpsInTotal`).
+     * 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
@@ -3386,6 +3364,8 @@ export declare class CandleClient {
      * 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.
+     *
+     * @deprecated Use dryRunLaunch({ ...fields, wallet }) for one release.
      */
     dryRunSelfLaunch(req: BuildSelfLaunchRequest): Promise<SelfLaunchDryRunResult>;
     /**
@@ -3400,6 +3380,8 @@ export declare class CandleClient {
      * round trip (build -> sign -> broadcast -> confirm) in one call for both Solana and Hood; call
      * this method directly only to drive the steps yourself. See "Self-signed launches" in
      * docs/headless-launch.md.
+     *
+     * @deprecated Use launch({ ...fields, wallet }) for one release.
      */
     buildSelfLaunch(req: BuildSelfLaunchRequest): Promise<BuildSelfLaunchResult>;
     /** buildSelfLaunch()'s request; selfLaunch() passes its `op` so its exits can expose the id. */
@@ -3669,6 +3651,8 @@ export declare class CandleClient {
      * error's doc describes for each `feeOutcome`. This method sends nothing a second time and
      * does not pay a fee again. An error from before the create-curve receipt is unchanged,
      * including a create-curve broadcast whose answer was lost: that case keeps no hash.
+     *
+     * @deprecated Use launch({ ...fields, wallet }) for one release.
      */
     selfLaunch(req: SelfLaunchRequest): Promise<ConfirmSelfLaunchResult>;
     /** selfLaunch()'s steps. Every error leaves through selfLaunch()'s runOperation(), which adds the id. */
@@ -4103,7 +4087,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.7";
+export declare const SDK_VERSION = "0.6.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