Skip to main content
@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

Install both packages on the same version. For the supported version, runtime and API key, see Before you start.
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)

Later snippets on this page use this 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 under simulationPolicy: 'allow-revert' when the simulation reverted. It carries error: { kind, message } and simulationRevert: { 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:
A raw response keeps amounts as decimal strings. Send the request with 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:
The SDK caches nothing; cache discovery results as your refresh needs dictate. See the routing edges catalog for the rendered live view.

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, from builder.inputs.<name>.
  • ResourceInputHandle: an InputHandle<'resource'> that also carries its resource.
  • OutputHandle<T>: a node’s output port, from an op method’s return value.
  • TypedRef<T>: a ref built with raw.ref<T>(path) or read from builder.context.
A typed bind slot accepts a handle or 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:
Every successful compile of a flow with a settle node registers a new escrow. Compile it only when you intend to fund it, and fund only the escrow named in that compile’s settlements[<nodeId>].escrow.
The settle node returns one handle, 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 a ComposeError. 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.
The SDK also checks versions itself on 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