# @lifi/composer-sdk

TypeScript SDK for building LI.FI Compose flows and compiling them into submit-ready transactions.

Full documentation: [docs.li.fi/composer](https://docs.li.fi/composer/overview). SDK API reference: [SDK API](https://docs.li.fi/composer/composer-api/reference/sdk-api.md).

## Install

`@lifi/compose-spec` is a peer dependency. Install it at exactly the same version as the SDK; the two are versioned in lockstep. Node.js 24 or later is required.

```bash
npm install @lifi/composer-sdk @lifi/compose-spec
```

`apiKey` is required (create one at [portal.li.fi](https://portal.li.fi)). A missing or blank key throws a `ComposeError` with code `VALIDATION_ERROR` when you call `createComposeSdk()`, including from plain JavaScript that skips the type check. It has been required since 0.3.0.

## Quick start

Swap WETH to USDC, then zap the USDC into an Aave lending position, in one transaction.

```ts
import {
  createComposeSdk,
  resources,
  guards,
  materialisers,
} from '@lifi/composer-sdk';

const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
const A_ETH_USDC = '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c'; // Aave aEthUSDC
const OWNER = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045';

const sdk = createComposeSdk({
  baseUrl: 'https://composer.li.quest',
  apiKey: process.env.LIFI_API_KEY!,
});

// A flow on Ethereum mainnet with one token input.
const builder = sdk.flow(1, {
  name: 'swap-and-zap-weth-to-aave',
  inputs: {
    amountIn: resources.erc20(WETH, 1),
  },
});

// Step 1: swap WETH to USDC via LI.FI.
const swapOutputs = builder.lifi.swap('swap', {
  bind: { amountIn: builder.inputs.amountIn },
  config: {
    resourceOut: resources.erc20(USDC, 1),
    slippage: 0.03,
  },
});

// Step 2: zap the swapped USDC into Aave. The swap's amountOut handle
// feeds the zap's amountIn directly.
builder.lifi.zap('zap', {
  bind: { amountIn: swapOutputs.amountOut },
  config: {
    resourceOut: resources.erc20(A_ETH_USDC, 1),
  },
  guards: [guards.slippage({ port: 'amountOut', bps: 100 })],
});

const flow = builder.build();

const request = sdk.request(flow, {
  signer: OWNER,
  inputs: {
    amountIn: materialisers.directDeposit({
      amount: '1000000000000000000',
    }),
  },
  sweepTo: builder.context.sender,
  // Opt into partial results. Under the default 'strict' policy a simulated
  // revert throws a ComposeError instead, and the `partial` branch is unreachable.
  simulationPolicy: 'allow-revert',
});

const result = await sdk.client.compile(request);

if (result.status === 'success') {
  // transactionRequest includes gasLimit.
  console.log(result.transactionRequest);

  // One entry per output port. Nothing downstream spends the zap's output, so
  // it is terminal and carries its owner. The swap's output is `consumed` by the zap.
  const position = result.outputs['zap.amountOut'];
  if (position?.role === 'terminal') {
    console.log(position.owner, position.amount.estimate?.value);
  }
} else {
  // status === 'partial': simulation reverted. The transaction is still
  // returned, without gasLimit.
  console.log(result.simulationRevert);
}
```

`builder.compile(run)` is shorthand for `sdk.client.compile(sdk.request(builder.build(), run))`.

## Core concepts

**Flows and operations**: a flow is an ordered list of on-chain operations. You declare inputs, chain operations, and the backend compiles everything into one transaction. Operations are namespaced, e.g. `builder.lifi.swap` and `builder.core.split`. Each call takes a node id that must be unique in the flow.

**Resources**: `resources.erc20(address, chainId)` and `resources.native(chainId)` describe the tokens flowing through the flow. A resource input must be on the flow's chain.

**Handles**: operations return typed output handles, e.g. `OutputHandle<'resource'>` or `OutputHandle<'uint256'>`, which you bind to downstream inputs. TypeScript enforces the port types. A resource handle fits a `uint256` slot (resources are amounts), but an `address` handle does not.

**Runtime inputs (materialisers)**: a materialiser tells the backend how to fund a flow input when the transaction executes.

- `directDeposit({ amount })` pulls exactly `amount`. For a token the compose token registry flags non-exact (stETH, Aave aTokens), a transfer credits a wei or two off, so the deposit instead pulls up to `amount` and asserts it received at least `amount` less 4 wei.
- `directDeposit({ amount, allowNonExact: true })` permits a capped ERC-20 deposit of up to `amount`; `directDeposit({ allowNonExact: true })` deposits with no on-chain cap (ERC-20 only).
- `balanceOf({ owner })` reads a current balance.
- `call({ target, calldata })` measures the balance delta after an arbitrary contract call.

**Preconditions**: on-chain state the backend assumes when it simulates, e.g. a balance the signer will hold at execution time. The factories are `erc20Balance`, `nativeBalance`, and `erc20Allowance`.

**Guards**: runtime checks on an operation's output, attached through its `guards` field. `guards.slippage({ port, bps })` floors an output at `bps` below its simulated amount. The `port` argument is typed against the ports a guard can protect. For example, `lifi.swap`'s `amountOut` already carries the aggregator's own floor, so it rejects a slippage guard at compile time.

**Outputs**: a compile result carries `outputs`, keyed `'<nodeId>.<portName>'`, with one entry per resource output, plus one entry per resource input no node consumes, keyed `'input.<name>'`. An entry is either:

- `role: 'terminal'`: delivered to `owner`. `delivery.when` says whether it lands with this transaction (`'now'`) or later (`'future'`).
- `role: 'consumed'`: spent by the node named in `consumedBy`.

Narrow on `role` before reading those fields. `amount.estimate` and `amount.minimum` are both optional. An absent minimum means no floor is enforced; there is no `0` default. `terminalOutputs(result.outputs)` keeps only the terminal entries.

## API surface

**SDK**

- `createComposeSdk({ baseUrl, apiKey, fetch? })`: `baseUrl` must be an HTTP(S) URL. A trailing slash is stripped.
- `sdk.flow(chainId, { inputs, name? })`: returns a `FlowBuilder`. `name` defaults to a random UUID.
- `builder.<namespace>.<operation>(nodeId, { bind, config, guards? })`: adds a node and returns one typed handle per output port.
- `builder.untypedOp(nodeId, op, { bind, config, guards? })`: escape hatch for ops without a typed method. Returns `void`; reference its outputs with `raw.ref<T>(path)`.
- `builder.build()`: returns the `Flow` document.
- `builder.compile(run)`: builds, then compiles.
- `sdk.request(flow, run)`: builds a `ComposeCompileRequest` from a flow and a `ComposeRunInput`.
- `sdk.route(request)`: compiles a token pair without authoring a flow. See [Routing a token pair](#routing-a-token-pair).
- `sdk.simulate(request)`: simulates a raw transaction. See [Simulating a raw transaction](#simulating-a-raw-transaction).
- `sdk.getSupportedChains()`: same as `sdk.client.getChains()`.

**`sdk.client` (HTTP)**

- `compile(request)`: `POST /compose`. Returns a `ComposeCompileResult` with `status: 'success'` or `status: 'partial'`.
- `route(request)`: `POST /compose/route`. Returns the same union.
- `getManifest()`: `GET /compose/manifest`, the live operation registry. From 0.10.2 the response also carries `routing` (`maxRouteHops`, `swapHops`), the deployment's `POST /compose/route` bounds; an older server omits it.
- `getChains()`: `GET /chains`. Returns `readonly ChainSummary[]` (`{ chainId, name }`), ascending by `chainId`.
  - A chain is listed once the VM contract is confirmed deployed on it. `compile`, `route`, and `simulate` validate against the same condition, so they reject an unlisted chain. A listed chain can still have no routing edge for a given pair.
  - `name` is a display label that can change, so key on `chainId`. A chain with no configured label reports `Chain <id>`.
- `getZapPacks(options?)`: `GET /compose/zap-packs`. Returns the routing edges grouped by protocol as `ZapPackOverview[]`. Filter with `{ protocols: 'aave' }` or an array. See [Discovering routable pairs](#discovering-routable-pairs).
- `simulate(request)`: `POST /simulate`.

The SDK caches none of these responses.

**Helpers**

- `resources.erc20(address, chainId)` / `resources.native(chainId)`.
- `guards.slippage`, `guards.coreNumericInvariant`, `guards.minAmount`.
- `materialisers.directDeposit`, `materialisers.balanceOf`, `materialisers.call`; experimental materialisers under `materialisers.experimental` (see [Experimental definitions](#experimental-definitions)).
- `preconditions.erc20Balance`, `preconditions.nativeBalance`, `preconditions.erc20Allowance`.
- `raw.ref<T>(path)`, `raw.literal(kind, value)`, `raw.guard(kind, config?)`, `raw.materialiser(kind, config?)`: low-level constructors for cases the typed helpers do not cover.
- `routeAmount.exact(amount)` / `routeAmount.all(simAmount)`: amount constructors for `route`.
- `buildReachability(packs, { maxHops?, allowAsyncRoutes? })`: the pairs `route` can connect (pure, no I/O).
- `buildSimulateRequest(...)`: turns a compile result into a `SimulateRequest` (pure, no I/O).
- `terminalOutputs(outputs)`.
- `isComposeError`, `isComposePreparationError`, `isComposeSdkOutdatedError`, `isComposeServerOutdatedError`: type guards. `ComposeError` is exported as a type only, so narrow with these rather than `instanceof`.

## Routing a token pair

`sdk.route(...)` is the shortcut for when the backend can choose the operations. You pass a from/to token pair on one chain, an amount, and a signer. It returns the same `ComposeCompileResult` that `compile()` does.

The backend plans the shortest chain of routing-catalog edges for the pair: entering or exiting a protocol position, a wrap or unwrap, a mint or burn. The route can be up to the server's hop ceiling (2 by default). The chain may open with one `lifi.swap` when the input has to be sold first; the swap counts as a hop, so at the default ceiling it precedes at most one catalog edge. That swap only targets a hub token or the underlying of the next deposit, so `route` is not a general swap aggregator.

- Node ids are `hop0`, `hop1`, … and the last node is always `zap`, so the delivered output is `result.outputs['zap.amountOut']`.
- Every intermediate step settles inside the proxy in the same transaction. Only the last step may pay out to a recipient, or land after settlement (only with `allowAsyncRoutes`).
- A route that opens with a swap requires `sweepTo`, because the swap can leave unspent input in the proxy. Omitting it fails with `validation_error`.

```ts
import { createComposeSdk, routeAmount } from '@lifi/composer-sdk';

const sdk = createComposeSdk({
  baseUrl: 'https://composer.li.quest',
  apiKey: process.env.LIFI_API_KEY!,
});

const result = await sdk.route({
  chainId: 1,
  fromToken: '0x0000000000000000000000000000000000000000', // native ETH
  toToken: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH, a `wrap` edge
  amount: routeAmount.exact(100_000_000_000_000_000n), // 0.1 ETH
  signer: '0xYourAddress...',
  slippageBps: 100,
});

if (result.status === 'success') {
  console.log(result.transactionRequest); // to, chainId, data, value, gasLimit
}
```

### Discovering routable pairs

The catalog changes as protocols, chains, and token blacklists move, so discover pairs instead of hardcoding them. `getZapPacks` lists single edges; `route` chains them. `buildReachability` computes the chained closure locally, using the planner's rule:

```ts
import { buildReachability } from '@lifi/composer-sdk';

const packs = await sdk.client.getZapPacks();
const reach = buildReachability(packs);

reach.canRoute(aUsdc, yvUsdc); // aUSDC -> USDC -> yvUSDC: true
for (const pair of reach.routableFrom(aUsdc)) {
  console.log(pair.in.address, '->', pair.out.address, `(${pair.hops} hops)`);
}
```

`pair.in` and `pair.out` are the `fromToken` and `toToken` of a `route` call on `pair.in.chainId`. The rule the helper applies, and the server enforces:

- Every edge except the last must leave its output in the proxy for the next edge to consume. An edge with `recipient: 'required'` or `availability: 'future'` can only be the last hop.
- The last edge must be synchronous, unless you pass `allowAsyncRoutes: true` to both `buildReachability` and `route`.
- A route never visits the same token twice and never exceeds `maxHops`.

The helper can overstate or miss what `route` accepts in a few ways:

- `maxHops` defaults to 2, the deployment default. The server reports its effective value in `no_route_error` `details.maxHops`; pass that value if it differs.
- The helper cannot check `inAmountMin` / `inAmountMax` on an intermediate hop without an amount. A reported pair is routable structurally, just as a listed edge is.
- The server drops blacklisted tokens as intermediates, so a reported pair can still return `no_route_error`.
- Routes that open with a `lifi.swap` depend on what the aggregator can sell, so the helper does not report them.

Two edge fields change how you call `route`:

- **`recipient: 'required'`**: the protocol mints to a named receiver. Set `sweepTo` when the output should not land with the signer.
- **`availability: 'future'`**: the output only exists once the transaction settles, and `route` uses such an edge only with `allowAsyncRoutes: true`. Once opted in:
  - `sweepTo` names the future output's owner.
  - No slippage floor applies.
  - You must track settlement.
  - A synchronous route still wins whenever one exists, so read each terminal output's `delivery.when`.

  A future output still reports `amount.estimate` (`basis: 'simulated'`, the in-transaction estimate). The catalog carries no settlement time. The compile result carries it as `delivery.etaSeconds` on a future terminal output; that field is absent when the protocol publishes no estimate, and absence means unknown, not zero.

### Amounts

- **`routeAmount.exact(amount)`**: spend exactly `amount` of `fromToken`, in its smallest unit.
- **`routeAmount.all(simAmount)`**: spend the signer's whole `fromToken` balance, read on-chain at execution time.
  - The quote, price impact, and returned approvals are computed against `simAmount`. The transaction moves the real balance, so pass a realistic estimate.
  - Not supported for a native `fromToken`: a gas coin arrives via `msg.value`, so there is no balance to sweep.

Both accept a `bigint` or a decimal string.

### Options

The SDK sends only the fields you set. The server applies the defaults.

- **`slippageBps`**: default `100` (1%). An end-to-end tolerance on the route's final output, not a per-hop one.
- **`maxPriceImpactBps`**: reject the route when its priced impact exceeds this. Default `500`; `0` disables the check.
- **`referrer`**: opaque tag forwarded to the underlying quote provider.
- **`sweepTo`**: owner of everything the route leaves behind. An address or `{ $ref: 'context.sender' }`; `context.executionAddress` is rejected. Defaults to the signer, except that a route with a swap requires it.
- **`checkOnChainAllowances`**: omit approvals that current allowances already cover. Default `false`.
- **`simulationPolicy`**: `'strict'` (default) or `'allow-revert'`. See [Simulation policy and partial results](#simulation-policy-and-partial-results).
- **`simulateUserProgram`**: also simulate the final user-facing transaction after the structured simulation succeeds. Default `false`.
- **`allowAsyncRoutes`**: accept a route whose output arrives after the transaction settles. Default `false`, which guarantees every terminal output is `delivery.when: 'now'`.

### When to author a flow instead

Use `sdk.flow(...)` for anything `route` cannot express:

- a chain you choose yourself, or one longer than the hop ceiling
- one input split across several destinations
- guards on intermediate outputs
- explicit preconditions or arithmetic
- funding from proxy-held balances
- combining an asynchronous position with other steps

For example, swapping WETH to USDC and depositing the USDC into Aave is a route when the planner can connect it, and a flow when you want to control the swap or add steps.

### Errors

`route` maps failures like `compile` does (see [Error handling](#error-handling)). Two outcomes are specific to it:

- **`NOT_FOUND`** with `kind: 'no_route_error'`: the planner cannot connect the pair within `details.maxHops` edges. `details.searchTruncated` reports whether the search hit its work bound.
- **`VALIDATION_ERROR`**: the pair connects but the request is rejected. Examples: price impact above `maxPriceImpactBps`, or a simulated revert under `'strict'`.

## Simulation policy and partial results

The backend simulates every compiled transaction. Under the default `simulationPolicy: 'strict'`, a revert throws a `ComposeError` with code `VALIDATION_ERROR` (HTTP 422). With `'allow-revert'` you get a **partial result** (HTTP 206) instead:

```ts
const result = await builder.compile({
  signer: OWNER,
  inputs: { amountIn: materialisers.balanceOf({ owner: OWNER }) },
  simulationPolicy: 'allow-revert',
});

if (result.status === 'success') {
  console.log(result.transactionRequest?.gasLimit); // string
} else {
  // status === 'partial': the transaction is returned without gasLimit;
  // estimate gas yourself.
  console.log(result.error.kind); // 'simulation_revert'
  console.log(result.error.message);

  const revert = result.simulationRevert;
  console.log(revert.code, revert.rawErrorBytes);
  for (const c of revert.decodeResult?.errorCandidates ?? []) {
    console.log(c.decodedErrorSignature, c.decodedParams, c.description);
  }

  const tx = result.transactionRequest;
  console.log(tx.to, tx.data, tx.value);
}
```

Pass `checkOnChainAllowances: true` to have the server drop entries from `approvals` that current on-chain allowances already cover.

## Simulating a raw transaction

`sdk.client.simulate(...)` (and `sdk.simulate(...)`) answers a question compile does not: if I send this exact transaction, how do specific balances change, and how much gas does it burn? It takes a pre-encoded transaction (`to`, hex `data`, optional `value`). It funds the sender as `requirements` describe, runs the transaction in one `eth_call`, and reports the watched balances before and after, their signed deltas, and the inner-call gas.

```ts
import { createComposeSdk } from '@lifi/composer-sdk';

const sdk = createComposeSdk({
  baseUrl: 'https://composer.li.quest',
  apiKey: process.env.LIFI_API_KEY!,
});

const result = await sdk.client.simulate({
  chainId: 1,
  from: '0x1111111111111111111111111111111111111111',
  to: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
  data: '0xa9059cbb...', // pre-encoded transfer calldata
  value: 0n,
  requirements: [
    {
      type: 'Erc20Balance',
      wallet: '0x1111111111111111111111111111111111111111',
      token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
      balance: 1_000_000n,
    },
  ],
  trackedBalances: [
    {
      token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
      owner: '0x1111111111111111111111111111111111111111',
    },
    {
      token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
      owner: '0x2222222222222222222222222222222222222222',
    },
  ],
});

switch (result.status) {
  case 'ok':
    console.log(result.gasUsed, result.deltas);
    break;
  case 'revert':
    // The simulation ran and the transaction reverted. Not an error.
    console.log(result.revertReason, result.decodeResult);
    break;
  case 'error':
    // Well-formed request, but the simulation could not be set up or run.
    console.log(result.message);
    break;
}
```

- `requirements` entries are `Erc20Balance`, `NativeBalance`, `Erc20Allowance`, or `Permit2Allowance`. Use the zero address as a `trackedBalances` token to watch the native balance.
- `Permit2Allowance` (`owner`, `token`, `spender`, `amount`) lets `spender` pull `token` from `owner` through Uniswap Permit2's `transferFrom`. The simulation also grants the ERC-20 allowance `owner` → Permit2, but not the owner's balance: fund it with an `Erc20Balance`. Only the canonical Permit2 address `0x000000000022D473030F116dDEE9F6B43aC78BA3` is supported; on a chain without it, `simulate` returns `status: 'error'` with a message that names Permit2 and the chain.
- Amount fields accept `bigint` or decimal strings.
- `ok` and `revert` results carry the `block` and `timestamp` the simulation ran against. Without a pinned `block`, resolving them costs the backend one extra block-header RPC; pass `reportBlockContext: false` to skip it, and the result then omits both. A pinned `block` is always reported. The field needs a backend that serves compose 0.18.0 or later: an older backend rejects it with HTTP 400, which `simulate` throws as a `ComposeError`.
- `SIMULATE_MAX_TRACKED_BALANCES` and `SIMULATE_MAX_REQUIREMENTS` (both `40`) are exported.
- A `revert` is returned, not thrown. Only transport failures and HTTP 400/401/403/404/429/5xx throw `ComposeError`.
- `gasUsed` is inner-call execution gas only; it excludes the 21000 base cost and calldata gas.
- EOA-only behaviour, such as `msg.sender == tx.origin` checks, is not simulated faithfully, because the call runs through injected VM bytecode rather than a real EOA.

To simulate a transaction you just compiled, `buildSimulateRequest(...)` fills in the transaction fields from the compile result. A compile result carries neither `chainId` nor `signer`, so pass both. Nothing in a flow says which balances to watch, so pass `trackedBalances` and any `requirements` too. It throws when the result has no single `transactionRequest` (a flow funded by an external action); submit that result's `actions` instead.

```ts
import { buildSimulateRequest } from '@lifi/composer-sdk';

const compiled = await builder.compile({ inputs: { ... }, signer: '0x1111...' });
const req = buildSimulateRequest({
  result: compiled,
  chainId: 1,
  signer: '0x1111111111111111111111111111111111111111',
  trackedBalances: [
    {
      token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
      owner: '0x1111111111111111111111111111111111111111',
    },
  ],
});
const sim = await sdk.client.simulate(req);
```

Runnable versions: [`src/examples/simulateRawTransaction.ts`](src/examples/simulateRawTransaction.ts) and [`src/examples/simulateCompiledSwap.ts`](src/examples/simulateCompiledSwap.ts).

## Deferred settlement (continuations)

`builder.continuation.settle(id, { bind: { input }, config })` escrows a resource and commits to the outcomes in `config.outcomes`, which an off-chain executor settles later by running the node's `continuationFlow` (the *leg*) from the escrow. The leg is an ordinary flow built with `sdk.flow(...)`, with one input, the funding resource, on the escrow chain:

```ts
// The leg supplies the escrowed WETH to Aave; the aBasWETH it mints stays in
// the leg's proxy, and the compiler's epilogue forwards it at commit.
const leg = sdk.flow(8453, { inputs: { funding: resources.erc20(WETH, 8453) } });
leg.lifi.zap('supply', {
  bind: { amountIn: leg.inputs.funding },
  config: { resourceOut: resources.erc20(A_BAS_WETH, 8453) },
  guards: [guards.slippage({ port: 'amountOut', bps: 50 })],
});

builder.continuation.settle('settle', {
  bind: { input: swap.amountOut },
  config: {
    outcomes: [{ token: A_BAS_WETH, destination: owner, chainId: 8453 }],
    continuationFlow: leg.build(),
    validity: { expiresAtMs: Date.now() + 60 * 60 * 1000 },
  },
});
```

Three rules decide whether a settlement can ever fill, and the compiler rejects a flow that breaks them:

- The leg leaves each outcome token in its own proxy: a leg that only delivers its funding has no nodes, and a node that needs a receiver binds `leg.context.executionAddress`. Never name `destination` or any payee. At commit the compiler writes the leg's epilogue, which forwards each outcome to the settlement contract (it verifies that outcome's committed floor and pays its `destination`) and the residual to `refund`. A leg that carries its own `epilogue` is rejected.
- The leg must not reference `context.sender`: inside the leg it is the solver's executor, not the user.
- The leg declares exactly one input, the funding resource.

One settle node may commit several outcomes, all on one chain and each token once; a token that goes to two destinations needs two settle nodes. The returned `settle.outcomes` holds one handle per entry of a literal `config.outcomes` (`settle.outcomes[0]`, `settle.outcomes[1]`). Only an exact settle may commit none (`outcomes: []`); it then has no output port.

The compile response carries the escrow terms in `settlements[id].escrow`, any `fundEscrow` action in `actions`, and each outcome as `outputs['<id>.outcomes.<i>']`, whose `amount.minimum` is that outcome's committed floor. The leg contract, funding modes (inline, external, bridge-delivered), expiry and refund, several outcomes, and monitoring are in [`docs/continuations.md`](docs/continuations.md).

## Error handling

HTTP and transport failures are thrown as a `ComposeError`. Builder mistakes (a duplicate node id, a missing output port) throw a plain `Error` at the call site. Narrow with `isComposeError`:

```ts
import { isComposeError } from '@lifi/composer-sdk';

try {
  const result = await sdk.client.compile(request);
} catch (err) {
  if (isComposeError(err)) {
    console.error(err.code, err.status, err.kind, err.message);
    console.error(err.path, err.port, err.fix); // when the server names a location or a fix
  }
}
```

| `code`             | HTTP status | Typical cause                                                   |
| ------------------ | ----------- | --------------------------------------------------------------- |
| `VALIDATION_ERROR` | 400, 422    | Malformed or rejected flow or request, simulated revert, guard  |
| `UNAUTHENTICATED`  | 401         | Missing or invalid API key                                      |
| `PAYMENT_REQUIRED` | 402         | Prepaid credit balance cannot cover the call; top up with `POST /credits/topup`. Use an x402-wrapped fetch (`@x402/fetch`) for the top-up only: the SDK's `fetch` option must be a plain fetch, because this 402 carries no `PAYMENT-REQUIRED` challenge and the wrapper turns it into a thrown error reported as `NETWORK_ERROR` |
| `FORBIDDEN`        | 403         | The server refuses the request                                  |
| `NOT_FOUND`        | 404         | `no_route_error`                                                |
| `RATE_LIMITED`     | 429         | Too many requests                                               |
| `SERVER_ERROR`     | 5xx         | Backend failure or a dependency temporarily unavailable        |
| `NETWORK_ERROR`    | none        | The request never got a response                                |
| `UNKNOWN_ERROR`    | other       | Unexpected status                                               |

`kind` is the backend's finer-grained classification, e.g. `simulation_revert`, `guard_error`, or `price_impact_exceeded`. When `kind` is `simulation_revert`, `err.details` has the same shape as `result.simulationRevert`.

A `preparation_error` (HTTP 422) means some prepared ops (ops that fetch external quotes at compile time, such as `lifi.swap`) failed while others succeeded, e.g. a mixed basket with one unroutable leg. A `failedOps` entry whose `kind` is `resolution_error` hit an upstream outage rather than a dead route, so keep that node when resubmitting. When every failed op hit an outage, the error is a 503 `resolution_error` instead: retry the same flow. Narrow with `isComposePreparationError`, drop the other failed node ids from the flow, and resubmit:

```ts
import { isComposePreparationError } from '@lifi/composer-sdk';

try {
  const result = await sdk.client.compile(request);
} catch (err) {
  if (isComposePreparationError(err)) {
    for (const op of err.failedOps) {
      console.error(op.callId, op.op, op.kind, op.message);
    }
    // Only the prepared ops that succeeded, not the rest of the flow. To retry,
    // remove the failedOps callIds from the original flow, keeping any whose
    // kind is 'resolution_error'.
    console.error('prepared ok:', err.succeededOps);
  }
}
```

**Version mismatch.** `compile` and `route` fail with `kind: 'sdk_outdated'` when this SDK is older than the oldest version the backend serves. They fail with `kind: 'server_outdated'` when the SDK is newer than the backend in any version component, which happens between an npm release and the backend rollout. Both come back as `VALIDATION_ERROR`. `isComposeSdkOutdatedError(err)` exposes `err.sdkOutdated.minimumSdkVersion`; `isComposeServerOutdatedError(err)` exposes `err.serverOutdated.serverVersion`. On `server_outdated`, pin both packages to the server's version or wait for the rollout.

## Examples

Each file in `src/examples/` is a complete flow:

- **lifiSwap**: single token swap (WETH to USDC)
- **lifiZap**: swap into a DeFi position
- **lifiZapAsync**: zap into a position whose output settles after the initiating transaction
- **swapAndZap**: swap, then deposit
- **splitAndZap**: split a resource and zap each part into a different vault
- **splitWithArithmetic**: split, then check with add/subtract/assertEqual
- **dustSweep**: split, use part of the tokens, sweep the rest back to the sender
- **depositFromProxy**: spend tokens already on the proxy via `balanceOf`, with a precondition
- **approveAndDeposit**: approve a vault, deposit, and turn the shares into a resource via `asResource`
- **consolidateToUsdc** / **consolidateToEth**: consolidate several tokens into one
- **swapToRecipient**: swap and send to another address
- **swapWithBalanceCheck**: swap with a balance precondition
- **swapWithOutputValidation**: swap with computed bounds via bpsDown/bpsUp/assertInRange
- **invariantChecks**: swap, then assert the output with `invariant.gte` and an allowance with `invariant.allowanceAtLeast`
- **payInvoiceWithMinAmount**: swap WETH to USDC on Base, split the invoice total off with `core.splitAt`, require it on `head` with `guards.minAmount`, and pay a Request Network invoice; a short swap fails the compile with the `shortfall`
- **rawCallWithArithmetic**: query a contract with pre-encoded calldata, then scale the result
- **readContractState**: compare `peek` (compile time), `staticCall` (execution time), and `balanceOf` (resource)
- **emitCustomEvent**: emit a custom event with `core.emitEvent2`; `bytes32` ports accept any static 32-byte handle
- **swapWithAllowRevert**: handle both branches of `ComposeCompileResult` under `'allow-revert'`
- **transferTokens**: transfer ERC-20 tokens from the proxy to any recipient
- **callContract**: call an arbitrary contract (ERC-4626 redeem, reward claim) without a typed op
- **flySwap**: on Base, exit a Pendle PT via `lifi.zap`, then swap all proceeds to WETH with `fly.swap`
- **aaveBorrow**: supply USDC to Aave v3, borrow USDC against it, and guard the health factor with `aave.getHealthFactor`
- **aaveHealthFactorExplode**: read the Aave v3 health factor and assert it stays above 1.0
- **aaveRepay**: repay Aave v3 variable debt and sweep the unspent residual to the sender
- **aaveRepayWithATokens**: repay Aave v3 debt by burning aTokens held by the proxy
- **aaveClaimRewards**: claim Aave rewards and forward them to a recipient
- **aaveSetEMode**: switch the proxy's Aave v3 eMode category
- **morphoBlueBorrow**: supply WETH collateral to a Morpho Blue market and borrow USDC
- **morphoBlueRepay**: open, repay and close a Morpho Blue position with `morphoBlue.repay` in `max` mode
- **uniswapV2AddLiquidity**: split USDC, swap half to WETH, and deposit both into the Uniswap V2 USDC/WETH pair with a `band` guard on the pool price
- **uniswapV3Mint**: mint a full-range Uniswap V3 USDC/WETH position with `band` and `slippage` guards
- **untypedOpWithTypedRef**: add a node with `untypedOp`, then use its output in typed ops via `raw.ref<T>()`
- **routeTokenPair**: `sdk.route(...)` with both the `exact` and `all` amount variants
- **supportedChains**: cache `sdk.getSupportedChains()`, then fail an unsupported chain locally with a message naming the alternatives
- **simulateRawTransaction** / **simulateCompiledSwap**: raw and compiled simulation
- **continuationSettle**: swap USDC to WETH on Base, then escrow the WETH for a deferred settlement whose leg supplies it to Aave and delivers the aBasWETH position
- **continuationBridgeSettle**: bridge USDC from Arbitrum into a settle escrow on Base; when the delivery lands, the leg supplies it to Aave and delivers the aBasUSDC position
- **continuationTwoOutcomes**: escrow 1,000 USDC on Base for one settle node with two outcomes; the leg partitions the USDC 50/50, swaps one half to DAI and supplies the other to Aave, and the settlement delivers both the DAI and the aBasUSDC position
- **continuationBuyWithChange**: swap WETH to USDC on Base, then escrow the USDC for one settle node with two outcomes and two destinations; the leg buys an exact EURC amount with `paraswap.buy`, and the settlement delivers the EURC to the payee and the unspent USDC to the owner
- **continuationExactInvoice**: escrow USDC on Base for an exact leg (`exact: true`) that pays a Request Network invoice through `core.call` and returns the surplus; a second builder funds the same leg from a WETH-to-USDC swap, and a third from Arbitrum ETH swapped to USDC and delivered by an exact-output `lifiIntents.order` (`exactAmountOut`) into the escrow at exactly the invoice total, with no outcome (`outcomes: []`)
- **experimental/flashloanRepay**: borrow USDC in an Aave v3 flashloan and earmark the principal and the fee top-up for repayment; a second builder swaps the loan to WETH and back first (experimental)
- **experimental/aaveToMorphoDebtMigration**: migrate an Aave v3 WETH/USDC position to Morpho Blue with two flashloans (experimental)
- **experimental/aaveToMorphoDebtMigrationWithSwap**: migrate an Aave v3 USDC debt into Morpho Blue WETH/EURC, swapping the EURC borrow to USDC (experimental)
- **experimental/aaveToMorphoDebtMigrationWithSwapExactOut**: the same migration with an exact-output swap that buys exactly the Aave debt (experimental)
- **experimental/aaveDebtRebalanceExactOut**: switch an Aave v3 debt from USDC to EURC with one flashloan and an exact-output swap (experimental)

## Experimental definitions

Some operations and materialisers run on the backend before their design is final. The SDK ships them in the default install, under an `experimental` namespace that keeps them apart from the stable surface:

```ts
// The calls only; src/examples/experimental/flashloanRepay.ts is the full
// flow, with the fee top-up an Aave v3 leg needs.
builder.experimental.lifi.flashloanRepay('repay', {
  bind: { funds: builder.inputs.borrowed },
});

const request = sdk.request(builder.build(), {
  signer,
  inputs: {
    borrowed: materialisers.experimental.flashloan({
      providerKind: 'aave-v3',
      amount: '10000000000',
    }),
  },
});
```

An experimental definition carries no compatibility guarantee. Any release, a patch included, can change its arguments, rename or remove it, or move it to its stable location (for example from `builder.experimental.lifi.flashloanRepay` to `builder.lifi.flashloanRepay`). A move leaves no alias, so code that calls the old name stops compiling. Pin the exact SDK version when you depend on an experimental definition.

A backend runs an experimental definition only when its deployment enables it. A backend that does not enable one rejects the flow with `validation_error`, for example `Unknown op: lifi.flashloanRepay` or `Unknown materialiser 'flashloan' for input 'borrowed'`. `sdk.client.getManifest()` lists the operations and materialisers a backend accepts.

The experimental definitions in this release:

- `builder.experimental.lifi.flashloanRepay`: earmarks funds of a flashloan-borrowed token, so the flashloan runtime repays the lender from them after the program.
- `materialisers.experimental.flashloan`: borrows a token from a flashloan provider into the proxy before the program runs. Its config type is `FlashloanMaterialiserConfig`.

The examples in `src/examples/experimental/` use them.

## License

Apache-2.0
