@lifi/composer-sdk builds a Flow in TypeScript, sends it to the Composer API and returns typed results. This page lists its public surface for version 0.14.0. The authoritative types are the package’s type declarations and the wire types in @lifi/compose-spec.
Install
There is no
sdk.compile(). Compile lives on the builder: builder.compile(run). sdk.request(flow, run) builds the same request without sending it.createComposeSdk(options)
sdk and add their own imports.
ComposeSdkOptions
createComposeSdk throws a ComposeError with code VALIDATION_ERROR when baseUrl is not an HTTP(S) URL or apiKey is empty. Every request also sends the SDK version in x-lifi-composer-sdk for the version check.
ComposeSdk
sdk.flow(chainId, options)
FlowOptions<T>
sdk.flow throws when a resource input’s chainId differs from the flow’s chainId. The type T carries through to typed handles at builder.inputs.<name> and to the run.inputs keys compile accepts.
FlowBuilder<T>
A FlowBuilder combines the core members below, one typed method per op, and compile.
build() never emits epilogue or lineage. Use run.sweepTo for the remainder; for named forwards, add epilogue to the built Flow and send it with sdk.client.compile(). See Flow Schema: Epilogue.
Op methods
Each op method takes(id, { bind, config, guards? }) and returns the node’s output handles, keyed by port name: const { amountOut } = builder.lifi.swap('swap', …). An op with no config takes no config key. Every op in the op catalog is a method named after its id: lifi.swap is builder.lifi.swap, core.splitAt is builder.core.splitAt. Config types are exported by name, for example LifiSwapConfig and ContinuationSettleConfig.
builder.compile(run)
compile sends the Flow to POST /compose and returns a ComposeCompileResult.
compile throws a ComposeError on a network failure or any error response. See Errors.
ComposeRunInput<T>
ComposeCompileResult
The result is a union on status. Check it before you read shape-specific fields.
status: 'success': the compile and its simulation succeeded.status: 'partial': returned only undersimulationPolicy: 'allow-revert'when the simulation reverted. It carrieserror: { kind, message }andsimulationRevert: { code, rawErrorBytes, decodeResult? }. Never submit it, and never fund an escrow it registered.
terminalOutputs(result.outputs) keeps only the entries nothing in the flow spends: what the caller actually receives. The wire-only fields producedHandles and producedResources are not part of this type; see Flow Schema: 200 response.
sdk.request(flow, run)
sdk.request returns the exact { flow, run } body compile would send. Use it to queue a request, send it through your own backend, or inspect it in tests.
bigint values have no JSON form, so a plain JSON.stringify(request) throws a TypeError. Serialise them as decimal strings, as the SDK does. Continuing with the builder above:
sdk.client.compile(request) instead to get the typed result with bigint amounts.
sdk.route(request)
sdk.route compiles a token pair on one chain without a Flow. The server plans a short chain of catalog edges (a position entry or exit, a wrap or unwrap), optionally opened by a lifi.swap, and compiles it through the same pipeline as compile. Its node ids are hop0, hop1, …, and the last node is zap.
ComposeRouteRequest
A pair the planner cannot connect throws a
ComposeError with kind: 'no_route_error' (HTTP 404). To check reachability without a request, fetch the edges with sdk.client.getZapPacks() and pass them to buildReachability(packs, { maxHops?, allowAsyncRoutes? }), which returns { canRoute(from, to), routableFrom(from), pairs() }.
sdk.simulate(request)
sdk.simulate runs a raw transaction against POST /simulate and reports balance changes. buildSimulateRequest({ result, chainId, signer, trackedBalances, requirements?, block?, value? }) builds the request from a compile result; it throws when the result has no transactionRequest.
The result is a union on status: 'ok' (with balancesBefore, balancesAfter, deltas, gasUsed), 'revert' (with revertReason?, code?, rawErrorBytes?, decodeResult?) or 'error' (the simulation could not run). A revert is returned, not thrown.
sdk.client
The low-level client behind every member above. Reach for it to send a request you built with sdk.request(), or for discovery.
Discover which tokens route into Aave positions:
Helper namespaces
Handles
An op method binds handles, not ref strings. A handle points at a flow input or a node’s output port, and the SDK turns it into a{ "$ref": … } when it builds the Flow.
InputHandle<T>: a flow input, frombuilder.inputs.<name>.ResourceInputHandle: anInputHandle<'resource'>that also carries itsresource.OutputHandle<T>: a node’s output port, from an op method’s return value.TypedRef<T>: a ref built withraw.ref<T>(path)or read frombuilder.context.
TypedRef of the matching kind; a uint256 slot also accepts a resource handle. isInputHandle and isOutputHandle narrow an AnyHandle.
An output family returns several handles from one port name. core.partition returns parts, one handle per bps entry; with a literal array the handles are a tuple, so indexing past the last one is a type error:
raw.ref('split.parts.1') addresses the same port as parts[1]. Here the unspent third part is swept to the signer by sweepTo.
Continuations
builder.continuation.settle adds a settle node: the compile registers an escrow, and LI.FI’s settlement service later runs the node’s destination flow (continuationFlow) from it. The escrow lives on a bridge’s or order’s destination chain when one funds it, and on the flow’s own chain otherwise. Build the destination flow as an ordinary flow with exactly one resource input and pass destFlow.build(). Here a bridge from Arbitrum funds the escrow on Base:
output, delivered in the future. Its compile result adds settlements, a fundEscrow action for external funding, and fill. Exported types: ContinuationSettleConfig, ContinuationIntent, ContinuationOutcome, SettlementWire, SettlementEscrowWire, SettlementBindingWire, ComposeAction and ComposeFill. Concepts and rules: Cross-chain flows, Build a cross-chain flow and continuation.settle.
Errors
Every SDK failure is aComposeError. The package exports ComposeError as a type only, so instanceof ComposeError does not compile: narrow with the guards below.
code maps from the HTTP status: 400 and 422 → VALIDATION_ERROR, 401 → UNAUTHENTICATED, 403 → FORBIDDEN, 404 → NOT_FOUND, 429 → RATE_LIMITED, 5xx → SERVER_ERROR, a transport failure → NETWORK_ERROR, anything else → UNKNOWN_ERROR.
compile and route. It reads the API’s version from the x-lifi-composer-version response header. When the SDK is newer than the API, it throws server_outdated; pin the SDK to the API’s version or wait for the rollout. When the SDK is older than the API’s major.minor.0, it throws sdk_outdated; upgrade both packages.
See also
- Quickstart — a first flow in five minutes.
- Build a same-chain flow — inputs, ops, materialisers, guards, preconditions and submission.
- Flow Schema — the JSON the SDK sends and receives.
- Errors — every error kind and its HTTP status.

