@lifi/composer-sdk 0.2.0-staging.5 → 0.3.0

package/dist/sdk.d.ts

@@ -1,4 +1,4 @@
-import { ComposeCompileResult, ComposeCompileRequest } from '@lifi/compose-spec';
+import { ComposeCompileResult, ComposeCompileRequest, SimulateRequest, SimulateResult } from '@lifi/compose-spec';
 import { FlowOptions, FlowBuilderCore, TypedFlow } from './authoring/FlowBuilderCore.js';
 import { ComposeClient } from './client.js';
 import { GeneratedOps } from './generated/operations.generated.js';
@@ -46,8 +46,8 @@ interface ComposeSdkOptions {
     readonly baseUrl: string;
     /** Optional custom `fetch` implementation. Defaults to `globalThis.fetch`. */
     readonly fetch?: typeof globalThis.fetch;
-    /** Optional LI.FI API key for authenticated access. Sent as the `x-lifi-api-key` header on every request. */
-    readonly apiKey?: string;
+    /** LI.FI API key, sent as the `x-lifi-api-key` header on every request. Required — the Compose API rejects unauthenticated requests. */
+    readonly apiKey: string;
 }
 /**
  * The top-level Compose SDK interface.
@@ -59,7 +59,7 @@ interface ComposeSdkOptions {
  * ```ts
  * import { createComposeSdk, resources, materialisers } from '@lifi/composer-sdk';
  *
- * const sdk = createComposeSdk({ baseUrl: 'https://li.quest' });
+ * const sdk = createComposeSdk({ baseUrl: 'https://li.quest', apiKey: 'YOUR_API_KEY' });
  *
  * const builder = sdk.flow(1, {
  *   inputs: { usdc: resources.erc20('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', 1) },
@@ -95,16 +95,28 @@ interface ComposeSdk {
      * @returns A {@link ComposeCompileRequest} ready to send to the Compose API.
      */
     readonly request: <T extends InputSchema>(flow: TypedFlow<T>, run: ComposeRunInput<T>) => ComposeCompileRequest;
+    /**
+     * Simulates a raw, pre-encoded transaction. Thin pass-through to
+     * {@link ComposeClient.simulate}; see it for the `ok` / `revert` / `error`
+     * result discrimination and error behaviour. Pair with `buildSimulateRequest`
+     * to assemble the request from a compile result.
+     *
+     * @param request - The raw transaction plus funding `requirements` and
+     *   `trackedBalances`.
+     * @returns A {@link SimulateResult} (`ok` / `revert` / `error`).
+     * @throws {@link ComposeError} on network, validation, or server errors.
+     */
+    readonly simulate: (request: SimulateRequest) => Promise<SimulateResult>;
 }
 /**
  * Creates a new Compose SDK instance.
  *
- * @param options - SDK configuration including the API base URL and optional fetch implementation.
+ * @param options - SDK configuration including the API base URL, required API key, and optional fetch implementation.
  * @returns A {@link ComposeSdk} instance.
  *
  * @example
  * ```ts
- * const sdk = createComposeSdk({ baseUrl: 'https://li.quest' });
+ * const sdk = createComposeSdk({ baseUrl: 'https://li.quest', apiKey: 'YOUR_API_KEY' });
  * ```
  */
 declare const createComposeSdk: (options: ComposeSdkOptions) => ComposeSdk;

package/dist/sdk.js

@@ -33,7 +33,12 @@ const createComposeSdk = (options) => {
     };
     return Object.assign(builder, { compile });
   };
-  return { client: composeClient, flow, request };
+  return {
+    client: composeClient,
+    flow,
+    request,
+    simulate: composeClient.simulate
+  };
 };
 export {
   createComposeSdk

package/dist/sdk.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/sdk.ts"],"sourcesContent":["import type {\n  ComposeCompileRequest,\n  ComposeCompileResult,\n  InputSpec,\n} from '@lifi/compose-spec';\n\nimport {\n  createFlowBuilderCore,\n  type FlowBuilderCore,\n  type FlowOptions,\n  type TypedFlow,\n} from './authoring/FlowBuilderCore.js';\nimport { type ComposeClient, createComposeClient } from './client.js';\nimport {\n  bindGeneratedOps,\n  type GeneratedOps,\n} from './generated/operations.generated.js';\nimport { buildRun, type ComposeRunInput } from './run/inputs.js';\nimport type { InputSchema } from './types.js';\n\nexport type { ComposeRunInput };\n\n/**\n * A flow builder augmented with generated operation methods and a `compile` method\n * that submits the flow to the Compose backend for compilation.\n *\n * Created via {@link ComposeSdk.flow}.\n *\n * @typeParam T - The input schema describing the flow's required inputs.\n */\nexport type FlowBuilder<T extends InputSchema = InputSchema> =\n  FlowBuilderCore<T> &\n    GeneratedOps & {\n      /**\n       * Builds the flow document from the current builder state and submits it\n       * to the Compose API for compilation.\n       *\n       * @param run - Runtime inputs, preconditions, and signer address.\n       * @returns The compiled transaction calldata and metadata.\n       * @throws {@link ComposeError} on network, validation, or server errors.\n       *\n       * @example\n       * ```ts\n       * const result = await builder.compile({\n       *   inputs: { token: materialisers.balanceOf({}) },\n       *   signer: '0xYourAddress...',\n       * });\n       * console.log(result.calldata);\n       * ```\n       */\n      readonly compile: (\n        run: ComposeRunInput<T>,\n      ) => Promise<ComposeCompileResult>;\n    };\n\n/**\n * Configuration for creating a Compose SDK instance.\n */\nexport interface ComposeSdkOptions {\n  /** Base URL of the Compose API (e.g. `\"https://li.quest\"`). */\n  readonly baseUrl: string;\n  /** Optional custom `fetch` implementation. Defaults to `globalThis.fetch`. */\n  readonly fetch?: typeof globalThis.fetch;\n  /** Optional LI.FI API key for authenticated access. Sent as the `x-lifi-api-key` header on every request. */\n  readonly apiKey?: string;\n}\n\n/**\n * The top-level Compose SDK interface.\n *\n * Provides methods to build flows, compile them into executable calldata, and\n * interact with the Compose API directly.\n *\n * @example\n * ```ts\n * import { createComposeSdk, resources, materialisers } from '@lifi/composer-sdk';\n *\n * const sdk = createComposeSdk({ baseUrl: 'https://li.quest' });\n *\n * const builder = sdk.flow(1, {\n *   inputs: { usdc: resources.erc20('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', 1) },\n * });\n *\n * builder.lifi.swap('swap1', {\n *   bind: { amountIn: builder.inputs.usdc },\n *   config: { resourceOut: resources.native(1) },\n * });\n *\n * const result = await builder.compile({\n *   inputs: { usdc: materialisers.balanceOf({}) },\n *   signer: '0xYourAddress...',\n * });\n * ```\n */\nexport interface ComposeSdk {\n  /** Low-level HTTP client for the Compose API. */\n  readonly client: ComposeClient;\n  /**\n   * Creates a new flow builder targeting the given chain.\n   * @param chainId - The EVM chain ID (e.g. `1` for Ethereum mainnet).\n   * @param options - Flow configuration including input declarations.\n   * @returns A {@link FlowBuilder} with generated operation methods and a `compile` method.\n   * @throws Error if any resource input's `chainId` doesn't match the flow's `chainId`.\n   */\n  readonly flow: <T extends InputSchema>(\n    chainId: number,\n    options: FlowOptions<T>,\n  ) => FlowBuilder<T>;\n  /**\n   * Builds a raw compile request without sending it. Useful for inspecting the\n   * request payload or submitting it through a custom transport.\n   * @param flow - A built flow document (from `builder.build()`).\n   * @param run - Runtime inputs, preconditions, and signer address.\n   * @returns A {@link ComposeCompileRequest} ready to send to the Compose API.\n   */\n  readonly request: <T extends InputSchema>(\n    flow: TypedFlow<T>,\n    run: ComposeRunInput<T>,\n  ) => ComposeCompileRequest;\n}\n\n/**\n * Creates a new Compose SDK instance.\n *\n * @param options - SDK configuration including the API base URL and optional fetch implementation.\n * @returns A {@link ComposeSdk} instance.\n *\n * @example\n * ```ts\n * const sdk = createComposeSdk({ baseUrl: 'https://li.quest' });\n * ```\n */\nexport const createComposeSdk = (options: ComposeSdkOptions): ComposeSdk => {\n  const composeClient = createComposeClient(options);\n\n  const request = <T extends InputSchema>(\n    flowDoc: TypedFlow<T>,\n    run: ComposeRunInput<T>,\n  ): ComposeCompileRequest => ({\n    flow: flowDoc,\n    run: buildRun({\n      inputs: run.inputs as Record<string, InputSpec>,\n      preconditions: run.preconditions,\n      signer: run.signer,\n      assumptions: run.assumptions as Record<string, bigint> | undefined,\n      referrer: run.referrer,\n      integratorFeeBps: run.integratorFeeBps,\n      maxPriceImpactBps: run.maxPriceImpactBps,\n      sweepTo: run.sweepTo,\n      simulationPolicy: run.simulationPolicy,\n      checkOnChainAllowances: run.checkOnChainAllowances,\n    }),\n  });\n\n  const flow = <T extends InputSchema>(\n    chainId: number,\n    opts: FlowOptions<T>,\n  ): FlowBuilder<T> => {\n    const core = createFlowBuilderCore(chainId, opts);\n    const builder = Object.assign(core, bindGeneratedOps(core));\n\n    const compile = async (\n      run: ComposeRunInput<T>,\n    ): Promise<ComposeCompileResult> => {\n      const flowDoc = builder.build();\n      const req = request(flowDoc, run);\n      return composeClient.compile(req);\n    };\n\n    return Object.assign(builder, { compile });\n  };\n\n  return { client: composeClient, flow, request };\n};\n"],"mappings":"AAMA;AAAA,EACE;AAAA,OAIK;AACP,SAA6B,2BAA2B;AACxD;AAAA,EACE;AAAA,OAEK;AACP,SAAS,gBAAsC;AAmHxC,MAAM,mBAAmB,CAAC,YAA2C;AAC1E,QAAM,gBAAgB,oBAAoB,OAAO;AAEjD,QAAM,UAAU,CACd,SACA,SAC2B;AAAA,IAC3B,MAAM;AAAA,IACN,KAAK,SAAS;AAAA,MACZ,QAAQ,IAAI;AAAA,MACZ,eAAe,IAAI;AAAA,MACnB,QAAQ,IAAI;AAAA,MACZ,aAAa,IAAI;AAAA,MACjB,UAAU,IAAI;AAAA,MACd,kBAAkB,IAAI;AAAA,MACtB,mBAAmB,IAAI;AAAA,MACvB,SAAS,IAAI;AAAA,MACb,kBAAkB,IAAI;AAAA,MACtB,wBAAwB,IAAI;AAAA,IAC9B,CAAC;AAAA,EACH;AAEA,QAAM,OAAO,CACX,SACA,SACmB;AACnB,UAAM,OAAO,sBAAsB,SAAS,IAAI;AAChD,UAAM,UAAU,OAAO,OAAO,MAAM,iBAAiB,IAAI,CAAC;AAE1D,UAAM,UAAU,OACd,QACkC;AAClC,YAAM,UAAU,QAAQ,MAAM;AAC9B,YAAM,MAAM,QAAQ,SAAS,GAAG;AAChC,aAAO,cAAc,QAAQ,GAAG;AAAA,IAClC;AAEA,WAAO,OAAO,OAAO,SAAS,EAAE,QAAQ,CAAC;AAAA,EAC3C;AAEA,SAAO,EAAE,QAAQ,eAAe,MAAM,QAAQ;AAChD;","names":[]}
+{"version":3,"sources":["../src/sdk.ts"],"sourcesContent":["import type {\n  ComposeCompileRequest,\n  ComposeCompileResult,\n  InputSpec,\n  SimulateRequest,\n  SimulateResult,\n} from '@lifi/compose-spec';\n\nimport {\n  createFlowBuilderCore,\n  type FlowBuilderCore,\n  type FlowOptions,\n  type TypedFlow,\n} from './authoring/FlowBuilderCore.js';\nimport { type ComposeClient, createComposeClient } from './client.js';\nimport {\n  bindGeneratedOps,\n  type GeneratedOps,\n} from './generated/operations.generated.js';\nimport { buildRun, type ComposeRunInput } from './run/inputs.js';\nimport type { InputSchema } from './types.js';\n\nexport type { ComposeRunInput };\n\n/**\n * A flow builder augmented with generated operation methods and a `compile` method\n * that submits the flow to the Compose backend for compilation.\n *\n * Created via {@link ComposeSdk.flow}.\n *\n * @typeParam T - The input schema describing the flow's required inputs.\n */\nexport type FlowBuilder<T extends InputSchema = InputSchema> =\n  FlowBuilderCore<T> &\n    GeneratedOps & {\n      /**\n       * Builds the flow document from the current builder state and submits it\n       * to the Compose API for compilation.\n       *\n       * @param run - Runtime inputs, preconditions, and signer address.\n       * @returns The compiled transaction calldata and metadata.\n       * @throws {@link ComposeError} on network, validation, or server errors.\n       *\n       * @example\n       * ```ts\n       * const result = await builder.compile({\n       *   inputs: { token: materialisers.balanceOf({}) },\n       *   signer: '0xYourAddress...',\n       * });\n       * console.log(result.calldata);\n       * ```\n       */\n      readonly compile: (\n        run: ComposeRunInput<T>,\n      ) => Promise<ComposeCompileResult>;\n    };\n\n/**\n * Configuration for creating a Compose SDK instance.\n */\nexport interface ComposeSdkOptions {\n  /** Base URL of the Compose API (e.g. `\"https://li.quest\"`). */\n  readonly baseUrl: string;\n  /** Optional custom `fetch` implementation. Defaults to `globalThis.fetch`. */\n  readonly fetch?: typeof globalThis.fetch;\n  /** LI.FI API key, sent as the `x-lifi-api-key` header on every request. Required — the Compose API rejects unauthenticated requests. */\n  readonly apiKey: string;\n}\n\n/**\n * The top-level Compose SDK interface.\n *\n * Provides methods to build flows, compile them into executable calldata, and\n * interact with the Compose API directly.\n *\n * @example\n * ```ts\n * import { createComposeSdk, resources, materialisers } from '@lifi/composer-sdk';\n *\n * const sdk = createComposeSdk({ baseUrl: 'https://li.quest', apiKey: 'YOUR_API_KEY' });\n *\n * const builder = sdk.flow(1, {\n *   inputs: { usdc: resources.erc20('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', 1) },\n * });\n *\n * builder.lifi.swap('swap1', {\n *   bind: { amountIn: builder.inputs.usdc },\n *   config: { resourceOut: resources.native(1) },\n * });\n *\n * const result = await builder.compile({\n *   inputs: { usdc: materialisers.balanceOf({}) },\n *   signer: '0xYourAddress...',\n * });\n * ```\n */\nexport interface ComposeSdk {\n  /** Low-level HTTP client for the Compose API. */\n  readonly client: ComposeClient;\n  /**\n   * Creates a new flow builder targeting the given chain.\n   * @param chainId - The EVM chain ID (e.g. `1` for Ethereum mainnet).\n   * @param options - Flow configuration including input declarations.\n   * @returns A {@link FlowBuilder} with generated operation methods and a `compile` method.\n   * @throws Error if any resource input's `chainId` doesn't match the flow's `chainId`.\n   */\n  readonly flow: <T extends InputSchema>(\n    chainId: number,\n    options: FlowOptions<T>,\n  ) => FlowBuilder<T>;\n  /**\n   * Builds a raw compile request without sending it. Useful for inspecting the\n   * request payload or submitting it through a custom transport.\n   * @param flow - A built flow document (from `builder.build()`).\n   * @param run - Runtime inputs, preconditions, and signer address.\n   * @returns A {@link ComposeCompileRequest} ready to send to the Compose API.\n   */\n  readonly request: <T extends InputSchema>(\n    flow: TypedFlow<T>,\n    run: ComposeRunInput<T>,\n  ) => ComposeCompileRequest;\n  /**\n   * Simulates a raw, pre-encoded transaction. Thin pass-through to\n   * {@link ComposeClient.simulate}; see it for the `ok` / `revert` / `error`\n   * result discrimination and error behaviour. Pair with `buildSimulateRequest`\n   * to assemble the request from a compile result.\n   *\n   * @param request - The raw transaction plus funding `requirements` and\n   *   `trackedBalances`.\n   * @returns A {@link SimulateResult} (`ok` / `revert` / `error`).\n   * @throws {@link ComposeError} on network, validation, or server errors.\n   */\n  readonly simulate: (request: SimulateRequest) => Promise<SimulateResult>;\n}\n\n/**\n * Creates a new Compose SDK instance.\n *\n * @param options - SDK configuration including the API base URL, required API key, and optional fetch implementation.\n * @returns A {@link ComposeSdk} instance.\n *\n * @example\n * ```ts\n * const sdk = createComposeSdk({ baseUrl: 'https://li.quest', apiKey: 'YOUR_API_KEY' });\n * ```\n */\nexport const createComposeSdk = (options: ComposeSdkOptions): ComposeSdk => {\n  const composeClient = createComposeClient(options);\n\n  const request = <T extends InputSchema>(\n    flowDoc: TypedFlow<T>,\n    run: ComposeRunInput<T>,\n  ): ComposeCompileRequest => ({\n    flow: flowDoc,\n    run: buildRun({\n      inputs: run.inputs as Record<string, InputSpec>,\n      preconditions: run.preconditions,\n      signer: run.signer,\n      assumptions: run.assumptions as Record<string, bigint> | undefined,\n      referrer: run.referrer,\n      integratorFeeBps: run.integratorFeeBps,\n      maxPriceImpactBps: run.maxPriceImpactBps,\n      sweepTo: run.sweepTo,\n      simulationPolicy: run.simulationPolicy,\n      checkOnChainAllowances: run.checkOnChainAllowances,\n    }),\n  });\n\n  const flow = <T extends InputSchema>(\n    chainId: number,\n    opts: FlowOptions<T>,\n  ): FlowBuilder<T> => {\n    const core = createFlowBuilderCore(chainId, opts);\n    const builder = Object.assign(core, bindGeneratedOps(core));\n\n    const compile = async (\n      run: ComposeRunInput<T>,\n    ): Promise<ComposeCompileResult> => {\n      const flowDoc = builder.build();\n      const req = request(flowDoc, run);\n      return composeClient.compile(req);\n    };\n\n    return Object.assign(builder, { compile });\n  };\n\n  return {\n    client: composeClient,\n    flow,\n    request,\n    simulate: composeClient.simulate,\n  };\n};\n"],"mappings":"AAQA;AAAA,EACE;AAAA,OAIK;AACP,SAA6B,2BAA2B;AACxD;AAAA,EACE;AAAA,OAEK;AACP,SAAS,gBAAsC;AA+HxC,MAAM,mBAAmB,CAAC,YAA2C;AAC1E,QAAM,gBAAgB,oBAAoB,OAAO;AAEjD,QAAM,UAAU,CACd,SACA,SAC2B;AAAA,IAC3B,MAAM;AAAA,IACN,KAAK,SAAS;AAAA,MACZ,QAAQ,IAAI;AAAA,MACZ,eAAe,IAAI;AAAA,MACnB,QAAQ,IAAI;AAAA,MACZ,aAAa,IAAI;AAAA,MACjB,UAAU,IAAI;AAAA,MACd,kBAAkB,IAAI;AAAA,MACtB,mBAAmB,IAAI;AAAA,MACvB,SAAS,IAAI;AAAA,MACb,kBAAkB,IAAI;AAAA,MACtB,wBAAwB,IAAI;AAAA,IAC9B,CAAC;AAAA,EACH;AAEA,QAAM,OAAO,CACX,SACA,SACmB;AACnB,UAAM,OAAO,sBAAsB,SAAS,IAAI;AAChD,UAAM,UAAU,OAAO,OAAO,MAAM,iBAAiB,IAAI,CAAC;AAE1D,UAAM,UAAU,OACd,QACkC;AAClC,YAAM,UAAU,QAAQ,MAAM;AAC9B,YAAM,MAAM,QAAQ,SAAS,GAAG;AAChC,aAAO,cAAc,QAAQ,GAAG;AAAA,IAClC;AAEA,WAAO,OAAO,OAAO,SAAS,EAAE,QAAQ,CAAC;AAAA,EAC3C;AAEA,SAAO;AAAA,IACL,QAAQ;AAAA,IACR;AAAA,IACA;AAAA,IACA,UAAU,cAAc;AAAA,EAC1B;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/composer-sdk",
-  "version": "0.2.0-staging.5",
+  "version": "0.3.0",
   "description": "Public Composer SDK for building and submitting flows",
   "license": "Apache-2.0",
   "repository": {
@@ -23,7 +23,7 @@
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=24"
   },
   "publishConfig": {
     "access": "public"
@@ -51,11 +51,12 @@
     "example:staged": "tsx src/examples/run.ts --staged"
   },
   "peerDependencies": {
-    "@lifi/compose-spec": "0.2.0-staging.5"
+    "@lifi/compose-spec": "0.3.0"
   },
   "dependencies": {
     "abitype": "^1.2.3",
-    "effect": "^3.21.0"
+    "effect": "^3.21.0",
+    "zod": "^4.1.11"
   },
   "devDependencies": {
     "@eslint/compat": "^1.4.0",
@@ -70,7 +71,7 @@
     "eslint-plugin-require-extensions": "^0.1.3",
     "json-schema-to-typescript": "^15.0.4",
     "npm-run-all": "^4.1.5",
-    "prettier": "^3.0.0",
+    "prettier": "^3.9.4",
     "tsup": "^8.5.1",
     "tsx": "^4.20.4",
     "typescript": "^5.9.2",
@@ -84,6 +85,7 @@
     "!src/**/*.test.ts",
     "!src/**/*.mock.ts",
     "!src/**/*.typecheck.ts",
-    "!dist/**/*.typecheck.*"
+    "!dist/**/*.typecheck.*",
+    "!src/examples/staged/**"
   ]
 }

package/src/client.ts

@@ -4,10 +4,16 @@ import type {
   ComposeCompileResult,
   ComposeCompileSuccessData,
   ComposeManifest,
+  SimulateRequest,
+  SimulateResult,
 } from '@lifi/compose-spec';
 
 import type { GetZapPacksOptions, ZapPackOverview } from './discovery.js';
 import { ComposeError, errorFromHttpResponse } from './errors.js';
+import {
+  parseCompilePartialEnvelope,
+  parseSimulateResult,
+} from './responseSchemas.js';
 
 // __SDK_VERSION__ is a compile-time constant injected by tsup (via `define` in tsup.config.ts)
 // and by vitest (via `define` in vitest.config.ts). Both read the version from package.json
@@ -27,8 +33,8 @@ export interface ComposeClientOptions {
   readonly baseUrl: string;
   /** Optional custom `fetch` implementation. Defaults to `globalThis.fetch`. */
   readonly fetch?: typeof globalThis.fetch;
-  /** Optional LI.FI API key. When set, sent as the `x-lifi-api-key` header on every request. */
-  readonly apiKey?: string;
+  /** LI.FI API key, sent as the `x-lifi-api-key` header on every request. Required — the Compose API rejects unauthenticated requests. */
+  readonly apiKey: string;
 }
 
 /**
@@ -78,6 +84,30 @@ export interface ComposeClient {
   readonly getZapPacks: (
     options?: GetZapPacksOptions,
   ) => Promise<readonly ZapPackOverview[]>;
+  /**
+   * Simulates a raw, pre-encoded transaction against `POST /simulate` and
+   * reports how the watched balances change and how much inner-call gas it
+   * burns.
+   *
+   * The result is a discriminated union on `status`:
+   * - `'ok'` — the simulation ran successfully; `deltas`/`gasUsed` are populated.
+   * - `'revert'` — the simulation ran but the transaction reverted on-chain. A
+   *   revert is a *successful simulation*, not a transport error, so it is
+   *   returned (HTTP 200) rather than thrown — mirroring how {@link compile}
+   *   returns `status: 'partial'` on a simulated revert.
+   * - `'error'` — the request was well-formed but the simulation could not be
+   *   set up or run (HTTP 422); `message` is intentionally generic.
+   *
+   * `bigint` amounts in the request (`value`, requirement `balance`/`allowance`)
+   * are serialised to decimal strings automatically.
+   *
+   * @param request - The raw transaction plus funding `requirements` and the
+   *   `trackedBalances` to watch.
+   * @returns A {@link SimulateResult} (`ok` / `revert` / `error`).
+   * @throws {@link ComposeError} on network failures, HTTP 400 (malformed
+   *   input), 401/403 (auth), 404, 429, and 5xx.
+   */
+  readonly simulate: (request: SimulateRequest) => Promise<SimulateResult>;
 }
 
 const bigintReplacer = (_key: string, value: unknown): unknown =>
@@ -109,22 +139,39 @@ const parsePartialBody = async (
   url: string,
 ): Promise<ComposeCompileResult> => {
   const body = await res.json().catch((_) => null);
-  if (
-    !isNonNullObject(body) ||
-    !('data' in body) ||
-    !isNonNullObject(body.data) ||
-    !('error' in body) ||
-    !isNonNullObject(body.error)
-  ) {
+  const envelope = parseCompilePartialEnvelope(body);
+  if (envelope === null) {
     throw new ComposeError(
       'UNKNOWN_ERROR',
       'Unexpected partial response format',
       { url },
     );
   }
-  const data = body.data as unknown as ComposeCompilePartialData;
-  const error = body.error as unknown as { kind: string; message: string };
-  return { ...data, status: 'partial' as const, error };
+  // `data` is validated as an object by the schema; compose-spec owns its full
+  // shape as a hand-authored type, so we narrow it here rather than re-declaring
+  // that type as a schema. `error` is fully validated — no cast needed.
+  const data = envelope.data as unknown as ComposeCompilePartialData;
+  return { ...data, status: 'partial' as const, error: envelope.error };
+};
+
+// `/simulate` is un-enveloped: the discriminated body (`{ status, ... }`) is at
+// the top level, NOT wrapped in `{ data }` like `/compose`. So this reads the
+// body directly and validates it against the simulate union rather than reusing
+// `parseBody`.
+const parseSimulateBody = async (
+  res: Response,
+  url: string,
+): Promise<SimulateResult> => {
+  const body = await res.json().catch((_) => null);
+  const result = parseSimulateResult(body);
+  if (result === null) {
+    throw new ComposeError(
+      'UNKNOWN_ERROR',
+      'Unexpected simulate response format',
+      { url },
+    );
+  }
+  return result;
 };
 
 /**
@@ -142,15 +189,20 @@ export const createComposeClient = (
       `Invalid baseUrl: expected an HTTP(S) URL, got "${options.baseUrl}"`,
     );
   }
+  const trimmedApiKey = options.apiKey?.trim() || undefined;
+  if (!trimmedApiKey) {
+    throw new ComposeError(
+      'VALIDATION_ERROR',
+      'apiKey is required: pass a LI.FI API key to createComposeSdk().',
+    );
+  }
   const fetchFn = options.fetch ?? globalThis.fetch;
   const base = options.baseUrl.replace(/\/$/, '');
 
-  const trimmedApiKey = options.apiKey?.trim() || undefined;
-
   const baseHeaders: Record<string, string> = {
     Accept: 'application/json',
     'x-lifi-composer-sdk': SDK_VERSION,
-    ...(trimmedApiKey ? { 'x-lifi-api-key': trimmedApiKey } : {}),
+    'x-lifi-api-key': trimmedApiKey,
   };
 
   const getManifest = async (): Promise<ComposeManifest> => {
@@ -226,5 +278,33 @@ export const createComposeClient = (
     return await parseBody<readonly ZapPackOverview[]>(res, url);
   };
 
-  return { getManifest, compile, getZapPacks };
+  const simulate = async (
+    request: SimulateRequest,
+  ): Promise<SimulateResult> => {
+    const url = `${base}/simulate`;
+    let res: Response;
+    try {
+      res = await fetchFn(url, {
+        method: 'POST',
+        headers: { ...baseHeaders, 'Content-Type': 'application/json' },
+        body: JSON.stringify(request, bigintReplacer),
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new ComposeError('NETWORK_ERROR', message, { cause: err });
+    }
+    // Only 200 (carries `ok`/`revert`) and 422 (carries the `error` member of
+    // the union) have a discriminated body. 422 is deliberately intercepted
+    // here (not thrown as VALIDATION_ERROR) so callers get one exhaustive
+    // `switch (result.status)`. Every other status is a transport error and is
+    // thrown — including HTTP 400 (malformed input, no `status` body) and any
+    // unexpected 2xx.
+    if (res.status === 200 || res.status === 422) {
+      return await parseSimulateBody(res, url);
+    }
+    const body = await res.text();
+    throw errorFromHttpResponse(res.status, body, url);
+  };
+
+  return { getManifest, compile, getZapPacks, simulate };
 };

package/src/errors.ts

@@ -1,5 +1,10 @@
 import type { ComposeErrorKind, SimulationRevert } from '@lifi/compose-spec';
 
+import {
+  parseServerErrorBody,
+  type ServerErrorBody,
+} from './responseSchemas.js';
+
 /**
  * Machine-readable error codes returned by the SDK.
  *
@@ -101,21 +106,14 @@ const STATUS_TO_CODE: ReadonlyMap<number, ComposeErrorCode> = new Map<
   [429, 'RATE_LIMITED'],
 ]);
 
-interface ServerErrorBody {
-  readonly error?: {
-    readonly kind?: string;
-    readonly message?: string;
-    readonly path?: string;
-    readonly details?: SimulationRevert;
-  };
-}
-
 const tryParseErrorBody = (body: string): ServerErrorBody | null => {
+  let json: unknown;
   try {
-    return JSON.parse(body) as ServerErrorBody;
+    json = JSON.parse(body);
   } catch {
     return null;
   }
+  return parseServerErrorBody(json);
 };
 
 /**

package/src/examples/aaveClaimRewards.ts

@@ -3,7 +3,7 @@ import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 import { createComposeSdk } from '../index.js';
 import type { Address } from '../types.js';
 
-import { BASE_URL } from './config.js';
+import { API_KEY, BASE_URL } from './config.js';
 
 // Aave v3 incentives contracts on Ethereum mainnet.
 const REWARDS_CONTROLLER = '0x8164Cc65827dcFe994AB23944CBC90e0aa80bFcb';
@@ -37,7 +37,7 @@ export const buildAaveClaimRewards = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'aave-claim-rewards',

package/src/examples/aaveRepay.ts

@@ -3,7 +3,7 @@ import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 import { createComposeSdk, materialisers, resources } from '../index.js';
 import type { Address } from '../types.js';
 
-import { BASE_URL } from './config.js';
+import { API_KEY, BASE_URL } from './config.js';
 
 // Aave v3 contracts on Ethereum mainnet.
 const AAVE_V3_POOL = '0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2';
@@ -49,7 +49,7 @@ export const buildAaveRepay = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'aave-repay-weth',

package/src/examples/aaveRepayWithATokens.ts

@@ -3,7 +3,7 @@ import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 import { createComposeSdk, materialisers, resources } from '../index.js';
 import type { Address } from '../types.js';
 
-import { BASE_URL } from './config.js';
+import { API_KEY, BASE_URL } from './config.js';
 
 // Aave v3 contracts on Ethereum mainnet.
 const AAVE_V3_POOL = '0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2';
@@ -39,7 +39,7 @@ export const buildAaveRepayWithATokens = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'aave-repay-with-atokens',

package/src/examples/aaveSetEMode.ts

@@ -3,7 +3,7 @@ import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 import { createComposeSdk } from '../index.js';
 import type { Address } from '../types.js';
 
-import { BASE_URL } from './config.js';
+import { API_KEY, BASE_URL } from './config.js';
 
 // Aave v3 contracts on Ethereum mainnet.
 const AAVE_V3_POOL = '0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2';
@@ -41,7 +41,7 @@ export const buildAaveSetEMode = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'aave-set-emode',

package/src/examples/approveAndDeposit.ts

@@ -3,7 +3,7 @@ import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 import { createComposeSdk, materialisers, resources } from '../index.js';
 import type { Address } from '../types.js';
 
-import { BASE_URL } from './config.js';
+import { API_KEY, BASE_URL } from './config.js';
 
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
 // Example ERC-4626 vault address (Steakhouse USDC on Ethereum mainnet)
@@ -30,7 +30,7 @@ export const buildApproveAndDeposit = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'approve-and-deposit',

package/src/examples/callContract.ts

@@ -3,7 +3,7 @@ import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 import { createComposeSdk, materialisers, resources } from '../index.js';
 import type { Address } from '../types.js';
 
-import { BASE_URL } from './config.js';
+import { API_KEY, BASE_URL } from './config.js';
 
 // Example ERC-4626 vault address (Steakhouse USDC on Ethereum mainnet)
 const VAULT = '0xBEEF01735c132Ada46AA9aA4c54623cAA92A64CB';
@@ -31,7 +31,7 @@ export const buildRedeemFromVault = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'redeem-from-vault',
@@ -103,7 +103,7 @@ export const buildClaimRewards = ({
   const REWARDS_CONTRACT = '0x1111111111111111111111111111111111111111';
   const REWARD_TOKEN = '0x2222222222222222222222222222222222222222';
 
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'claim-rewards',
@@ -154,7 +154,7 @@ export const buildWrapEth = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'wrap-eth',

package/src/examples/config.ts

@@ -2,7 +2,10 @@
 // built-in process.env.BASE_URL (set to "/" from the `base` config option).
 export const BASE_URL: string =
   process.env['COMPOSER_BASE_URL'] ?? 'https://composer.li.quest';
-export const API_KEY: string | undefined = process.env['LIFI_API_KEY'];
+// `apiKey` is required by `createComposeSdk`/`createComposeClient`; fall back to a
+// placeholder so the examples remain runnable (against a backend that accepts it)
+// without every contributor needing a real LI.FI API key set locally.
+export const API_KEY: string = process.env['LIFI_API_KEY'] ?? 'YOUR_API_KEY';
 
 export const OWNER = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045';
 export const RECIPIENT = '0x1234567890abcdef1234567890abcdef12345678';

package/src/examples/consolidateToEth.ts

@@ -3,7 +3,7 @@ import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 import { createComposeSdk, materialisers, resources } from '../index.js';
 import type { Address } from '../types.js';
 
-import { BASE_URL } from './config.js';
+import { API_KEY, BASE_URL } from './config.js';
 
 export interface ConsolidateToEthInput {
   readonly owner: Address;
@@ -38,7 +38,7 @@ export const buildConsolidateToEth = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
   const erc20 = (token: Address) => resources.erc20(token, CHAIN_ID);
 
   // Declare the flow with one input per ERC-20 token on Ethereum mainnet.

package/src/examples/consolidateToUsdc.ts

@@ -3,7 +3,7 @@ import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 import { createComposeSdk, materialisers, resources } from '../index.js';
 import type { Address } from '../types.js';
 
-import { BASE_URL } from './config.js';
+import { API_KEY, BASE_URL } from './config.js';
 
 export interface ConsolidateStablesToUsdcInput {
   readonly owner: Address;
@@ -39,7 +39,7 @@ export const buildConsolidateStablesToUsdc = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
   const erc20 = (token: Address) => resources.erc20(token, CHAIN_ID);
 
   // Declare the flow with one input per stablecoin on Ethereum mainnet.

package/src/examples/depositFromProxy.ts

@@ -9,7 +9,7 @@ import {
 } from '../index.js';
 import type { Address } from '../types.js';
 
-import { BASE_URL } from './config.js';
+import { API_KEY, BASE_URL } from './config.js';
 
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
 // Aave v3 aEthUSDC receipt token on Ethereum mainnet
@@ -45,7 +45,7 @@ export const buildDepositFromProxy = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'deposit-from-proxy',

package/src/examples/dustSweep.ts

@@ -2,7 +2,7 @@ import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 
 import { createComposeSdk, materialisers, resources } from '../index.js';
 
-import { BASE_URL, OWNER } from './config.js';
+import { API_KEY, BASE_URL, OWNER } from './config.js';
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
 const USDT = '0xdAC17F958D2ee523a2206206994597C13D831ec7';
 
@@ -23,7 +23,7 @@ export const buildDustSweepExample = (): {
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'dust-sweep',

package/src/examples/emitCustomEvent.ts

@@ -3,7 +3,7 @@ import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 import { createComposeSdk } from '../index.js';
 import type { Address } from '../types.js';
 
-import { BASE_URL } from './config.js';
+import { API_KEY, BASE_URL } from './config.js';
 
 // Example ERC-4626 vault address (Steakhouse USDC on Ethereum mainnet)
 const VAULT = '0xBEEF01735c132Ada46AA9aA4c54623cAA92A64CB';
@@ -33,7 +33,7 @@ export const buildEmitCustomEvent = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'emit-custom-event',

package/src/examples/invariantChecks.ts

@@ -3,7 +3,7 @@ import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 import { createComposeSdk, materialisers, resources } from '../index.js';
 import type { Address } from '../types.js';
 
-import { BASE_URL } from './config.js';
+import { API_KEY, BASE_URL } from './config.js';
 
 const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
@@ -41,7 +41,7 @@ export const buildInvariantChecks = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   // One WETH resource input plus a scalar spender address.
   const builder = sdk.flow(1, {

package/src/examples/lifiSwap.ts

@@ -2,7 +2,7 @@ import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 
 import { createComposeSdk, materialisers, resources } from '../index.js';
 
-import { BASE_URL, OWNER } from './config.js';
+import { API_KEY, BASE_URL, OWNER } from './config.js';
 
 const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
@@ -19,7 +19,7 @@ export const buildLifiSwapExample = (): {
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   // Declare the flow with a single WETH input on Ethereum mainnet.
   const builder = sdk.flow(1, {

package/src/examples/lifiZap.ts

@@ -7,7 +7,7 @@ import {
   resources,
 } from '../index.js';
 
-import { BASE_URL, OWNER } from './config.js';
+import { API_KEY, BASE_URL, OWNER } from './config.js';
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
 // Aave aEthUSDC receipt token on Ethereum mainnet
 const A_ETH_USDC = '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c';
@@ -24,7 +24,7 @@ export const buildLifiZapExample = (): {
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   // Declare the flow with a single USDC input on Ethereum mainnet.
   const builder = sdk.flow(1, {