@candledottv/agent-sdk 0.4.11 → 0.6.0

package/dist/client.d.ts

@@ -26,7 +26,19 @@
  *   validation error), and it never retries a launch whose stage is `executed` or `unconfirmed`
  *   or whose error already names a mint. Backoff is 250ms * 2^n, jittered to 50-100% of that,
  *   capped at 8s, bounded by `maxRetries` (default 3 retries after the initial attempt).
+ * - The id on every outcome. The six one-call write methods (`trade()`, `launch()`,
+ *   `launchAsync()`, `selfLaunch()`, `buildAtomicLaunch()`, `launchAtomic()`) send one idempotency
+ *   id per call, the caller's or a generated one, and once the first request carrying it has been
+ *   sent, every exit exposes that id: on the returned value, and on the thrown error
+ *   (`operationIds(error)`). A `CandleApiError` or `JsonRpcError` keeps its class and gains the id;
+ *   anything else (a rejected fetch, a 2xx body that is not JSON, a plain Error from one of the
+ *   method's own steps) is wrapped once, at the outermost method, in a `CandleOperationError` with
+ *   the original as `cause`. An error raised before anything was sent (no API key) carries no id
+ *   and is not wrapped. The SDK never reuses an id between calls and adds no retry of its own: a
+ *   call that passes no id is a new operation. The retry is the caller's, with the id passed back.
+ *   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 { HyperliquidPnlSection } from "./hyperliquid-pnl";
 import type { AgentPlansResult, PlanPrice, PlanTable } from "./plans";
@@ -278,9 +290,15 @@ export interface SelfLaunchDryRunResult extends Omit<DryRunResult, "launchWallet
     launchWallet: string;
     launchWalletId: string;
 }
-/** POST /api/v1/launch/headless blocking (or replayed) success response. */
+/**
+ * POST /api/v1/launch/headless blocking (or replayed) success response, plus `clientLaunchId`.
+ * The server's body does not carry the id: `launch()`, `selfLaunch()` and `confirmSelfLaunch()`
+ * set it from the request they sent, so a caller who let the SDK generate it still has it.
+ */
 export interface LaunchResult {
     success: true;
+    /** The idempotency id this launch was sent under, the caller's or the generated one. */
+    clientLaunchId: string;
     chain: Chain;
     mint: string;
     pool: string | null;
@@ -455,6 +473,79 @@ export type VerifyResult = {
         signer?: string;
     };
 };
+/** Fields an eligible agent key may edit. Name, slug and visibility stay owner-only. */
+export interface OwnAgentProfilePatch {
+    publicAvatar?: string | null;
+    publicBanner?: string | null;
+    publicThesis?: string | null;
+    publicStrategy?: string | null;
+    publicStrategyNote?: string | null;
+    publicModel?: string | null;
+    publicModels?: string[] | null;
+    publicLinks?: {
+        website?: string | null;
+        x?: string | null;
+    } | null;
+}
+export interface OwnAgentProfile {
+    success: true;
+    profileId: string;
+    keyPrefix: string;
+    profileSelfEdit: "allowed" | "denied";
+    canEdit: boolean;
+    agentEditsLocked: boolean;
+    display: {
+        name: string | null;
+        avatarUrl: string | null;
+        bannerUrl: string | null;
+        thesis: string | null;
+        strategy: string | null;
+        strategyNote: string | null;
+        model: string | null;
+        models: string[];
+        links: {
+            website: string | null;
+            x: string | null;
+        };
+    };
+}
+/** The token a post names: a token Candle shows publicly. The agent need not have traded or launched it. */
+export interface AgentPostTokenRef {
+    chain: "solana" | "hood";
+    mint: string;
+}
+/** The chip beside a post, linking to the token's Candle page. */
+export interface AgentPostToken extends AgentPostTokenRef {
+    symbol: string;
+    name: string;
+    image: string;
+}
+/** One post on an agent's own page. Tied to no trade or launch. */
+export interface AgentPost {
+    id: string;
+    /** Plain text, 1 to 500 characters, line breaks kept. Render it as text: never as HTML, and a URL in it is not a link. */
+    text: string;
+    /** Server time, unix ms. */
+    createdAt: number;
+    /** Null when the post named no token, or when Candle no longer shows the one it named. */
+    token: AgentPostToken | null;
+}
+export interface CreateAgentPostRequest {
+    /** 1 to 500 characters. Line breaks are kept; any other control character and bidi characters are refused. */
+    text: string;
+    token?: AgentPostTokenRef;
+}
+/** One page of an agent's posts, newest first. `cursor` is null on the last page. */
+export interface AgentPostsPage {
+    posts: AgentPost[];
+    cursor: string | null;
+}
+export interface ListAgentPostsOptions {
+    /** 1 to 50. Default 20. */
+    limit?: number;
+    /** The previous page's `cursor`. */
+    cursor?: string;
+}
 /** GET /api/v1/users/:idOrWallet/agent, unwrapped from `{ success, agent }`. */
 export interface AgentProfile {
     enabled: boolean;
@@ -463,6 +554,103 @@ export interface AgentProfile {
     launches: number;
     launchesViaApi: number;
 }
+/** Claimed fee income on public board entries and records. Older snapshots omit these fields. */
+export interface AgentFeeIncome {
+    /** Fees earned, valued when claimed, credited to the profile that launched the token. */
+    creatorFeesUsd?: number;
+    /** Claims without a USD value; excluded from creatorFeesUsd, never valued at zero. */
+    feeClaimsUnvalued?: number;
+    /** The capped claim read does not cover the whole window; the fee income is a floor. */
+    feeClaimsPartial?: boolean;
+}
+/**
+ * The optional board object beside private ledger P&L, also on /keys/pnl rows with a profileId.
+ * Rows without a profileId and combined stay ledger-only.
+ */
+export interface ProfileBoardPnl {
+    profileId: string;
+    creatorFeesUsd: number;
+    feeClaimsUnvalued: number;
+    feeClaimsPartial: boolean;
+    /** All-time public board total, including claimed fees; absent before a board entry exists. */
+    totalPnlUsd?: number;
+}
+/** One profile row of GET /api/v1/agent/keys/pnl; ledger fields stay separate from board income. */
+export interface ProfilePnlSummaryRow {
+    profileId: string | null;
+    board?: ProfileBoardPnl;
+    [key: string]: unknown;
+}
+/** Public realized figures. feesUsd is fees paid; creatorFeesUsd is separate income. */
+export interface AgentRecordTotals extends AgentFeeIncome {
+    realizedNetUsd: number;
+    feesUsd: number;
+    wins: number;
+    losses: number;
+    counted: number;
+    unvalued: number;
+    bestUsd?: number;
+    worstUsd?: number;
+    unrealizedUsd?: number;
+    /** Realized net plus unrealized plus creatorFeesUsd, already including moved-in shares. */
+    totalPnlUsd?: number;
+    realizedFromTransfersUsd?: number;
+    unrealizedFromTransfersUsd?: number;
+}
+/** A public leaderboard entry, including additive fee income beside its trade totals. */
+export interface AgentLeaderboardEntry extends AgentFeeIncome {
+    profileId: string;
+    name: string;
+    wallet: string;
+    rank: number;
+    totals: AgentRecordTotals;
+    winRatePct: number | null;
+    unrealizedUsd?: number;
+    totalPnlUsd?: number;
+    totalRank?: number;
+    markedAt?: number;
+    unrealizedPartial?: boolean;
+    windowComplete?: boolean;
+    openWins?: number;
+    openLosses?: number;
+    /** Other identity and coverage fields are preserved by the API. */
+    [key: string]: unknown;
+}
+/** A settled Solana staking claim, newest first; its claim value is not added to P&L again. */
+export interface AgentRewardClaim {
+    mint: string;
+    tokenSymbol: string;
+    amount: number;
+    usdValue?: number;
+    timestampMs: number;
+    signature: string;
+}
+/** GET /api/v1/agent/records/:profileId record, with optional claim projections. */
+export interface AgentPublicRecord extends AgentFeeIncome {
+    profileId: string;
+    name: string;
+    wallet: string;
+    totals: AgentRecordTotals;
+    unrealizedUsd?: number;
+    totalPnlUsd?: number;
+    rewardClaims?: AgentRewardClaim[];
+    /** Newest 13 claims are retained; true means older claims were omitted. */
+    rewardClaimsPartial?: boolean;
+    /** Existing row, series, identity and coverage fields. */
+    [key: string]: unknown;
+}
+export type AgentHoldingOrigin = "bought" | "movedIn" | "mixed" | "reward";
+/** One of the public top ten holdings, returned separately from the public record. */
+export interface AgentPublicHolding {
+    mint: string;
+    chain: Chain;
+    symbol?: string;
+    valueUsd: number;
+    unrealizedUsd?: number;
+    origin?: AgentHoldingOrigin;
+    /** Bought only with positive cost; reward and mixed holdings omit this. */
+    unrealizedPct?: number;
+}
 /** How `listAgents` orders the directory, each largest first. */
 export type AgentDirectorySort = "newest" | "active" | "pnl";
 /** One published agent, as `listAgents` returns it. Identity and three aggregates: no wallet, no position. */
@@ -482,9 +670,9 @@ export interface AgentDirectoryEntry {
     models: string[];
     /** Unix ms. */
     publishedAt: number;
-    /** The newest trade or launch, unix ms. Null for an agent that has done neither. */
+    /** The newest trade, launch or post, unix ms. Null for an agent that has none. */
     lastActiveAt: number | null;
-    /** All-time realized plus unrealized, USD, refreshed about every ten minutes. Null until first computed. */
+    /** All-time realized plus unrealized plus claimed creator fees, USD, refreshed about every ten minutes. Null until first computed. */
     totalPnlUsd: number | null;
     tradeCount: number;
     launchCount: number;
@@ -842,6 +1030,8 @@ export interface ProfileChainPnl extends ProfilePnlEngineFields {
  * Every account's realized figure can move on the day a server ships this.
  */
 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. */
     hyperliquid?: HyperliquidPnlSection;
     success: true;
@@ -1448,6 +1638,43 @@ export type ConfirmTradeRequest = {
 };
 /** POST /api/v1/trade/agent/confirm response. Always "executed": confirm only ever verifies and records a trade that already happened on-chain. */
 export type ConfirmTradeResult = ExecutedTradeResult;
+/**
+ * One trade from the idempotency ledger, from GET /api/v1/trade/agent/jobs/:clientTradeId
+ * (`getTradeJob()`). `amountRaw` is raw units: the quote asset's on a buy, the token's on a sell.
+ * `status` is `built` (in flight, or built and never confirmed), `confirmed` (landed; `signature`
+ * is set) or `failed` (`errorCode` says why; `TRADE_REVERTED` means it landed and reverted).
+ */
+export interface TradeJob {
+    signedLegs?: SignedTradeLeg[];
+    clientTradeId: string;
+    chain: Chain;
+    side: TradeSide;
+    mint: string;
+    quoteAsset: string;
+    amountRaw: string;
+    status: "built" | "confirmed" | "failed";
+    signature?: string;
+    errorCode?: string;
+    createdAt: number;
+    updatedAt: number;
+    /** A Hood TEE trade only: its sequenced operation, leg by leg. `kind` and `status` are open strings. */
+    operation?: {
+        operationId: string;
+        kind: string;
+        status: string;
+        plannedLegCount: number;
+        currentLegIndex: number;
+        legs: Array<{
+            kind: string;
+            status: string;
+            hash?: string;
+            nonce?: number;
+        }>;
+        expiresAt: number;
+        /** The fee a trade that landed after its lock expired still owes, once the read has recorded it. */
+        feeOwed?: Record<string, unknown>;
+    };
+}
 /**
  * POST /api/v1/trade/agent/submit request body. `signedTransactions` is the ordered signed legs:
  * one for Solana; one to four for Hood in the fixed approval, permit2Approval, trade, feeTransfer
@@ -2139,7 +2366,10 @@ export interface TradeRequest {
      * The server defaults it when omitted, which is `sol` on Solana and ETH settlement on Hood.
      */
     quoteAsset?: "sol" | "usdc" | "cndl" | "eth" | "usdg";
-    /** Idempotency key shared by the build and confirm calls; generated ("sdk-" + UUID) when omitted. */
+    /**
+     * Idempotency key shared by the build and confirm calls; generated ("sdk-" + UUID) when omitted.
+     * Pass your own for anything that moves funds and store it before the call: see `trade()`.
+     */
     clientTradeId?: string;
 }
 /** selfLaunch()'s one-call request: BuildSelfLaunchRequest plus the linked wallet's Privy wallet id. */
@@ -2191,8 +2421,14 @@ export interface AtomicBundleResponseLeg {
         amountOutRaw: string;
     };
 }
-/** POST /api/v1/launch/atomic/build response. */
+/**
+ * POST /api/v1/launch/atomic/build response, plus `clientLaunchId`. The server's body does not
+ * carry the id: `buildAtomicLaunch()` sets it from the request it sent. It is the launch's
+ * identity (`bundleId` is single-use), so a caller driving build and submit by hand keeps it.
+ */
 export interface BuildAtomicLaunchResult {
+    /** The idempotency id this build was sent under, the caller's or the generated one. */
+    clientLaunchId: string;
     bundleId: string;
     legs: AtomicBundleResponseLeg[];
     expiresAt: number;
@@ -2211,14 +2447,21 @@ export interface SubmitAtomicLaunchRequest {
  * are the 502 body -- all three are NORMAL, expected outcomes of submitting a Jito bundle that
  * this route documents as part of its own response surface, so `submitAtomicLaunch()`/
  * `launchAtomic()` return them here rather than throwing `CandleApiError` (every OTHER non-2xx
- * status still throws, same as every other method). `retryable` is always `false` for `"failed"`;
- * for `"timeout"` it is `true` only when the bundle's shared blockhash was proven to have expired
- * with no confirmation -- `false` means the resolution window simply ran out with no definitive
- * answer and the bundle MIGHT STILL LAND, so the caller should wait rather than immediately
- * rebuild under a fresh `clientLaunchId`. In every case, `bundleId` itself is dead once this
- * response arrives: it is consumed on the first `/submit` call regardless of outcome, so recovery
- * is always a fresh `buildAtomicLaunch()`/`launchAtomic()` call, never a retried `submit` with the
- * same id. See "Atomic launch with first buys" in docs/headless-launch.md for the full model.
+ * status still throws, same as every other method).
+ *
+ * `retryable` is `false` on every `"failed"` and on every `"timeout"` the server returns today.
+ * It is not permission to relaunch, whatever its value: a `"timeout"` means the resolution window
+ * ran out with no definitive answer and the bundle MIGHT STILL LAND. Treat every `"timeout"` as
+ * unresolved and never rebuild under a new `clientLaunchId` because of one: that is a second
+ * token. (This comment used to describe a `true` case meaning "the blockhash expired, relaunch".
+ * No server path returns it.)
+ *
+ * `bundleId` itself is dead once this response arrives: it is consumed on the first `/submit`
+ * call regardless of outcome and is never resubmitted. The launch's identity is the
+ * `clientLaunchId` the build was sent under, and recovery goes through it: read
+ * `getLaunchJob(clientLaunchId)`, then call `launchAtomic()` again with the SAME id when the job
+ * says to (the steps are on `launchAtomic()`). See "Atomic launch with first buys" in
+ * docs/headless-launch.md for the full model.
  */
 export type SubmitAtomicLaunchResult = {
     status: "landed";
@@ -2234,6 +2477,14 @@ export type SubmitAtomicLaunchResult = {
     bundleId: string;
     retryable: boolean;
 };
+/**
+ * What `launchAtomic()` returns: `submitAtomicLaunch()`'s outcome plus the `clientLaunchId` the
+ * launch was sent under, on all three of `landed`, `failed` and `timeout`. `submitAtomicLaunch()`
+ * itself is given only a `bundleId` and cannot know the launch id.
+ */
+export type LaunchAtomicResult = SubmitAtomicLaunchResult & {
+    clientLaunchId: string;
+};
 /** Who pays for one leg of launchAtomic()'s one-call request. Mirrors AtomicLaunchPayer, but a "linked" payer also carries the privyWalletId signLinkedTransaction() needs to sign that leg -- mirrors TradeRequest's `from` field. */
 export type LaunchAtomicPayer = {
     type: "main";
@@ -2287,6 +2538,44 @@ export declare class CandleClient {
     }): Promise<QuoteResult>;
     getFeed(bucket: FeedBucket, chain?: Chain): Promise<FeedResult>;
     verify(chain: Chain, mint: string): Promise<VerifyResult>;
+    getOwnProfile(): Promise<OwnAgentProfile>;
+    updateOwnProfile(patch: OwnAgentProfilePatch): Promise<{
+        success: true;
+        profileId: string;
+    }>;
+    /** The server counts, audits and saves this image without a subsequent PATCH. */
+    uploadProfileImage(kind: "avatar" | "banner", bytes: Uint8Array, contentType: string): Promise<{
+        imageUrl: string;
+        profileId: string;
+    }>;
+    /**
+     * Publish one post on this agent's own page (`POST /api/v1/agent/posts`). Needs an acting key
+     * with `profileSelfEdit` allowed and no admin lock: a Read key is refused with `SCOPE_MISSING`,
+     * a denied or locked one with `PROFILE_SELF_EDIT_DENIED`. 30 posts per UTC day per profile,
+     * shared by all its keys and the owner; the 31st is `RATE_LIMITED`. A post is tied to no trade
+     * or launch and is shown only on the agent's page.
+     */
+    createPost(req: CreateAgentPostRequest): Promise<{
+        success: true;
+        profileId: string;
+        post: AgentPost;
+    }>;
+    /**
+     * Delete one post of this agent's own profile, whoever wrote it (`DELETE /api/v1/agent/posts/:id`).
+     * The same key requirements as `createPost()`. Deleting does not give the day's place back. An
+     * unknown id, another profile's post and a post already deleted are `RECORD_NOT_FOUND`.
+     */
+    deletePost(postId: string): Promise<{
+        success: true;
+        profileId: string;
+        postId: string;
+    }>;
+    /**
+     * One published agent's posts, newest first (`GET /api/v1/agent/records/:profileId/posts`, no
+     * credential). Pass the returned `cursor` to read the next older page. An agent that is not
+     * published answers 404 `RECORD_NOT_FOUND` (`CandleApiError`), as its record does.
+     */
+    listAgentPosts(profileId: string, options?: ListAgentPostsOptions): Promise<AgentPostsPage>;
     getAgentProfile(idOrWallet: string): Promise<AgentProfile>;
     /**
      * The agent directory (`GET /api/v1/agent/directory`, no credential): every agent its owner
@@ -2315,12 +2604,27 @@ export declare class CandleClient {
     /**
      * Blocking launch with idempotent retries. 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
+     * (`result.clientLaunchId`) and on every error thrown after the first request was sent
+     * (`operationIds(error).clientLaunchId`), including the one thrown when the retries run out.
+     * The built-in retries are safe only inside this one call. To retry after it throws, call
+     * `launch()` again with that SAME id and the same body, or read `getLaunchJob(id)`. Never retry
+     * without the id: a call with no id, or a new one, is a second launch. Pass your own id and
+     * store it before the call when you can: an error can carry the id only if the process is
+     * still running to catch it.
      */
     launch(req: LaunchRequest): Promise<LaunchResult>;
     /**
      * Fire-and-poll launch: sends `async: true`, returns the 202 body. Single attempt (poll
      * `waitForLaunch` instead of retrying the POST). Generates `clientLaunchId` like `launch()`
      * so the returned body always carries the id to poll.
+     *
+     * An error thrown after the request was sent carries that id too
+     * (`operationIds(error).clientLaunchId`): the launch may have been accepted. Poll
+     * `getLaunchJob(id)` / `waitForLaunch(id)`, or call again with the SAME id and body. Never
+     * retry without the id: a call with no id, or a new one, is a second launch. Pass your own id
+     * and store it before the call when you can.
      */
     launchAsync(req: LaunchRequest): Promise<AcceptedJob>;
     getLaunchJob(clientLaunchId: string): Promise<LaunchJob>;
@@ -2521,11 +2825,14 @@ export declare class CandleClient {
      * docs/headless-launch.md.
      */
     buildSelfLaunch(req: BuildSelfLaunchRequest): Promise<BuildSelfLaunchResult>;
+    /** buildSelfLaunch()'s request; selfLaunch() passes its `op` so its exits can expose the id. */
+    private postSelfLaunchBuild;
     /**
      * Self-signed launch confirm: verifies the agent's own broadcast on-chain, then records the
      * launch identically to the headless path. Signature is the transaction hash from the agent's
      * own broadcast. devBuySignature (Hood only) is the optional follow-up dev-buy transaction. See
-     * selfLaunch() below for the one-call version of this whole flow (Solana).
+     * selfLaunch() below for the one-call version of this whole flow (Solana). The result carries
+     * the `clientLaunchId` from the request (the server's body does not).
      */
     confirmSelfLaunch(req: ConfirmSelfLaunchRequest): Promise<ConfirmSelfLaunchResult>;
     /**
@@ -2577,6 +2884,35 @@ export declare class CandleClient {
      *   `built | confirmed | failed`.
      */
     buildTrade(req: BuildTradeRequest): Promise<BuildTradeResult>;
+    /** buildTrade()'s request; trade() passes its `op` so its exits can expose the id. */
+    private postTradeBuild;
+    /**
+     * Reads one trade from the idempotency ledger by its `clientTradeId`, without sending
+     * anything: the read to make after a `trade()` that threw or timed out, before deciding whether
+     * to send again. Needs `swap:write` (the scope the trade itself needed) and answers during a
+     * kill switch.
+     *
+     * - 404 `JOB_NOT_FOUND` (a thrown `CandleApiError`): the write never began. Call again with the
+     *   same id.
+     * - `confirmed`: the trade landed; `signature` is on the job. A same-id `trade()` replays it.
+     * - `failed` with `errorCode: "TRADE_REVERTED"`: it landed and reverted. A new trade needs a
+     *   new id.
+     * - `failed`, other: not confirmed. A row with broadcast evidence may still be on chain; a
+     *   same-id `trade()` is the check, and answers `IDEMPOTENCY_CONFLICT` with
+     *   `stage: "unconfirmed"` for it.
+     * - `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.
+     *
+     * Non-TEE Hood linked jobs include signedLegs and resolve receipts on read. A landed trade
+     * on a built row can be recorded with confirmTrade using the trade and fee hashes; on a failed
+     * row it cannot: do not retry or rebuild. A reverted leg beside an unsettled one is not a
+     * settled id. Approval-only new-id advice is obtained on build only, after claim retirement.
+     *
+     * For a linked payer, also check the wallet's recent transactions before sending again: see
+     * `trade()`.
+     */
+    getTradeJob(clientTradeId: string): Promise<TradeJob>;
     /**
      * Confirm a LINKED payer's own broadcast trade: Candle verifies it landed on-chain, that it was
      * actually signed/sent by the declared linked wallet, that it moved this trade's own mint in
@@ -2676,8 +3012,35 @@ export declare class CandleClient {
      *   opt-in, but only for a caller that has already confirmed the build carries neither an
      *   `approval` nor a `permit2Approval` leg. Requires `evmRpcUrl`; throws a clear error
      *   naming it when unset, before any RPC read or signing.
+     *
+     * ## The id, and retrying
+     *
+     * The `clientTradeId` this call sent, yours or the generated one, is on the result and on every
+     * error thrown after the build request was sent (`operationIds(error).clientTradeId`): a
+     * `CandleApiError` or `JsonRpcError` gains it, and a lost response or any other failure is a
+     * `CandleOperationError` carrying it, with the original as `cause`. Pass your own id for
+     * anything that moves funds and store it before the call: an error can carry the id only if
+     * the process is still running to catch it. Never retry without the id: a call with no id, or a
+     * new one, is a second, independent trade. This method does not retry on its own.
+     *
+     * - **Main payer** (`from: "main"`): the trade executes inside the build call, so a lost
+     *   response can sit on a trade that already moved funds. With the id, read `getTradeJob(id)`
+     *   or call `trade()` again with the same id and body. Both are safe: the same-id call is a
+     *   replay, not a second trade. `getTradeJob()`'s jsdoc says what each job state means.
+     * - **Linked Hood payer**: once any leg is signed, the server refuses a same-id build.
+     *   TradeLegOutcomeError keeps the failing leg's txHash and earlier landedLegs. Inspect those
+     *   hashes, then read getTradeJob(id) or call trade() with the same id and body for Candle's
+     *   view. Never retry a retryable:false answer. A built prior_attempt_on_chain can be recorded
+     *   with confirmTrade using signature as tradeTxHash and the fee hash from legs (pay a missing
+     *   fee first, following TradeLandedFeeLegError). A failed row cannot be recorded with /confirm:
+     *   retain the hashes and do not retry or rebuild. Approval-only new-id advice follows committed
+     *   retirement and repeats unchanged. Reverted beside an unsettled leg never advises a new id.
+     *   TradeLandedUnconfirmedError means all legs landed but booking failed: read the job first.
+     * - **Linked Solana payer**: read getTradeJob(id) and check the wallet before sending again.
      */
     trade(req: TradeRequest): Promise<ExecutedTradeResult>;
+    /** trade()'s steps. Every error leaves through trade()'s runOperation(), which adds the id. */
+    private tradeSteps;
     /**
      * One-call self-signed launch. Solana: `buildSelfLaunch` -> `signLinkedTransaction` ->
      * `broadcastSignedTransaction` -> `confirmSelfLaunch` (`built.transaction` is a base64 unsigned
@@ -2690,8 +3053,36 @@ export declare class CandleClient {
      * 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.
+     *
+     * ## The id, and retrying
+     *
+     * The `clientLaunchId` this call sent, yours or the generated one, is on the result and on every
+     * error thrown after the build request was sent (`operationIds(error).clientLaunchId`). Pass
+     * your own id and store it before the call when you can. Never retry without the id: a call
+     * with no id, or a new one, is a second, independent launch.
+     *
+     * This method signs and broadcasts on the caller's side, so an error after the broadcast may
+     * sit on a launch transaction that landed. Read `getLaunchJob(id)` first.
+     *
+     * On Solana the id is enough to keep a second launch from being built. One id has one build
+     * at a time: `buildSelfLaunch()` under the same id returns the SAME transaction while the
+     * earlier one can still land, refuses with `IDEMPOTENCY_CONFLICT` and
+     * `reason: "prior_attempt_on_chain"` once it has landed, and builds a new transaction only
+     * after the chain proves the earlier one expired. A launch that landed is recorded with
+     * `confirmSelfLaunch({ clientLaunchId, signature })`, which keeps working after the build's
+     * 30-minute `expiresAt`. Inside this call, a blockhash error from your Solana RPC is retried
+     * with the bytes already signed: they are signed once, and signed again only when the server
+     * returns a different transaction. Calling `selfLaunch()` again under the same id while the
+     * earlier build is still live is refused by the sign relay, because that transaction's sign
+     * claim is already spent: broadcast what was signed, or wait for it to expire.
+     *
+     * On Hood the id is necessary and NOT sufficient: a rebuild under the same id builds a new
+     * curve, so calling `selfLaunch()` again can create and broadcast a second one. If the job is
+     * not `confirmed`, check the wallet's recent transactions before sending again.
      */
     selfLaunch(req: SelfLaunchRequest): Promise<ConfirmSelfLaunchResult>;
+    /** selfLaunch()'s steps. Every error leaves through selfLaunch()'s runOperation(), which adds the id. */
+    private selfLaunchSteps;
     /**
      * Builds an atomic launch bundle: a Solana launch transaction plus 1-4 first-buy transactions,
      * all sharing one recent blockhash so Jito lands them together or not at all. Returns the
@@ -2702,8 +3093,22 @@ export declare class CandleClient {
      * the full model: Pro/Max tier, `launch:write` + `swap:write` scopes, Solana only, the 1-4 buy
      * cap (Jito's 5-transaction bundle limit), and why every buy leg's own on-chain `minAmountOut` is
      * "0" inside the bundle (`expectedFill` on the returned legs is the real consent surface).
+     *
+     * The result carries the `clientLaunchId` the build was sent under (the server's body does
+     * not), and so does every error thrown after the request was sent
+     * (`operationIds(error).clientLaunchId`). Keep it: `bundleId` is single-use, and the launch's
+     * identity for any later read or retry is the `clientLaunchId`. Retry a failed build with the
+     * SAME id and body, or read `getLaunchJob(id)`; a call with no id, or a new one, is a second
+     * launch. After a submit, follow the steps on `launchAtomic()`. Pass your own id and store it
+     * before the call when you can.
      */
     buildAtomicLaunch(req: BuildAtomicLaunchRequest): Promise<BuildAtomicLaunchResult>;
+    /**
+     * The atomic build request itself. Sets `clientLaunchId` on the result from the request, since
+     * the server's body omits it. Shared by buildAtomicLaunch() and launchAtomic(), each of which
+     * runs it inside its OWN runOperation(), so an error is wrapped once, by the outermost method.
+     */
+    private postAtomicBuild;
     /**
      * Submits an already-built bundle's client-signer legs (EXACTLY the ones
      * `BuildAtomicLaunchResult.legs` named `signer: "client"`, in leg order -- omit every "server"
@@ -2723,7 +3128,15 @@ export declare class CandleClient {
      * roughly 150-160s in the worst case (Jito's own ~60s poll budget plus a further ~90s resolution
      * phase), since Candle checks the launch signature's own on-chain status before answering. Set a
      * client-side timeout no shorter than ~160s (or none) for this call, or you risk abandoning a
-     * request that was about to return a normal, if late, response.
+     * request that was about to return a normal, if late, response. A same-id
+     * `buildAtomicLaunch()`/`launchAtomic()` after a send can itself take up to about 95 seconds to
+     * answer, because the server resolves the first attempt against the chain before doing anything
+     * new: allow for that too.
+     *
+     * This method is given only a `bundleId`, so its result cannot carry the launch's
+     * `clientLaunchId`. Keep the one `buildAtomicLaunch()` returned: after a `"failed"` or
+     * `"timeout"`, recovery goes through it (the steps are on `launchAtomic()`), never through
+     * this `bundleId` and never through a new id.
      */
     submitAtomicLaunch(req: SubmitAtomicLaunchRequest): Promise<SubmitAtomicLaunchResult>;
     /**
@@ -2737,11 +3150,44 @@ export declare class CandleClient {
      * bundle with no linked payer at all (every leg "main") skips the signing round entirely and
      * goes straight from build to submit.
      *
-     * Returns `submitAtomicLaunch()`'s own result untouched -- see that method's jsdoc for why
-     * `"failed"`/`"timeout"` are returned here rather than thrown, and for the recommended
-     * client-side timeout.
-     */
-    launchAtomic(req: LaunchAtomicRequest): Promise<SubmitAtomicLaunchResult>;
+     * Returns `submitAtomicLaunch()`'s outcome plus the `clientLaunchId` the launch was sent under
+     * (`LaunchAtomicResult`), on `"landed"`, `"failed"` and `"timeout"` alike -- see that method's
+     * jsdoc for why `"failed"`/`"timeout"` are returned here rather than thrown, and for the
+     * recommended client-side timeout. A thrown error carries `clientLaunchId` too, and `bundleId`
+     * once the build has answered (`operationIds(error)`). Pass your own id and store it before the
+     * call when you can: an error can carry the id only if the process is still running to catch it.
+     *
+     * ## After a `timeout`, a `failed`, or an error that carries `clientLaunchId`
+     *
+     * `bundleId` is dead once `/submit` has been called and is never resubmitted; it is for log
+     * correlation only. The launch's identity is `clientLaunchId`:
+     *
+     * 1. Read `getLaunchJob(clientLaunchId)`. It needs `launch:read` on the key; a key whose scopes
+     *    were named by hand holds it only if it was named. A scope refusal is not "not found".
+     * 2. `confirmed`: the bundle landed. The mint is on the job. Stop.
+     * 3. 404 `JOB_NOT_FOUND`: the build never began. Call `launchAtomic()` again with the same id.
+     * 4. `failed`: the bundle did not land. Call `launchAtomic()` again with the SAME id; the server
+     *    starts a clean attempt under it.
+     * 5. Any other status: the bundle may still land. Wait, then read the job again or call
+     *    `launchAtomic()` again with the SAME id and the same body. The server resolves the first
+     *    attempt before doing anything new. It answers 409 `IDEMPOTENCY_CONFLICT` while the first
+     *    attempt is unresolved or has just been found landed, so on that 409 read the job again. It
+     *    builds a fresh bundle only when the first is proven reverted. This same-id call can take
+     *    about 95 seconds to answer, because the server waits on the chain.
+     * 6. Never send a new id while the job is not `failed`: that is a second token. This includes
+     *    the 409 whose message says "use a new clientLaunchId to launch again": read the job first,
+     *    because that message is also what a caller sees for a launch it does not yet know landed.
+     * 7. One state has no terminal answer today. The same-id call keeps answering 409 "This launch
+     *    was sent; its original attempt must be resolved" and the job is neither `confirmed` nor
+     *    `failed`, still, a few minutes after the submit (a blockhash lives about 90 seconds and the
+     *    rebuild itself can take about 95). Stop: do not send a new id on a timer, and report the
+     *    `clientLaunchId` and `bundleId` to whoever operates the key.
+     * 8. Treat every `timeout` as unresolved. `retryable` is `false` on every one the server returns
+     *    today, and it is never permission to relaunch under a new id.
+     */
+    launchAtomic(req: LaunchAtomicRequest): Promise<LaunchAtomicResult>;
+    /** launchAtomic()'s steps. Every error leaves through launchAtomic()'s runOperation(), which adds the ids. */
+    private launchAtomicSteps;
     /**
      * The `EvmRpc` seam packages/sdk/src/evm-tx.ts's helpers are built against, built from this
      * client's own `jsonRpcCall`/`jsonRpcCallRaw` closed over `evmRpcUrl`. Callers must have already
@@ -2825,6 +3271,17 @@ export declare class CandleClient {
     private signLinkedTypedData;
     private requireKey;
     private headers;
+    /**
+     * Runs a one-call write method's steps so that every exit exposes the idempotency id it sent
+     * (see the module doc, "The id on every outcome"). The steps pass `op` to the request that
+     * carries the id. Until that request is handed to fetch, an error leaves unchanged: nothing
+     * reached the server, so there is nothing to replay. After it, `withOperationIds()` puts the
+     * ids on a `CandleApiError`/`JsonRpcError` and wraps anything else in a `CandleOperationError`.
+     *
+     * Called once per public method, never nested: an inner step that is itself a one-call method
+     * (launchAtomic()'s build) runs its plain request, so the error is wrapped once, here.
+     */
+    private runOperation;
     private requestJson;
     private parseResponse;
     /**
@@ -2855,7 +3312,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.4.11";
+export declare const SDK_VERSION = "0.6.0";
 /** 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