Skip to main content
This guide covers flows that run on one chain. To bridge and then act on the destination chain, see Build a cross-chain flow.
This guide takes a flow from an empty builder to transactions the user has signed. It builds on the Quickstart; the SDK API reference lists every type.

Set up the SDK

Install the SDK and spec on the same version with npm install @lifi/composer-sdk @lifi/compose-spec; Before you start covers versions, Node.js and the API key. Create the SDK on your server:
Both options are required. A missing or blank apiKey, or a baseUrl that is not an http(s) URL, throws a ComposeError with code VALIDATION_ERROR. An optional fetch option replaces the transport, for example to add logging or retries.

Declare inputs

Inputs are a named record. Each entry is a resource declaration (a token) or a scalar type name such as 'address' or 'uint256':
The builder exposes a typed handle for each input as builder.inputs.<name>. Declare a scalar input only when a later op binds it, for example a recipient: 'address' bound into core.transfer. name is optional; without it the SDK generates a UUID for the Flow’s id. See Resource Model for how resources and handles behave.

Chain ops in your flow

The builder has one typed method per public op, grouped by namespace: builder.core, builder.lifi, builder.aave, builder.morphoBlue and so on. The op catalog lists every op with its ports and config. Each method returns the op’s output handles; bind one call’s output into the next call’s bind map:
Each bind slot is typed. A resource handle also fits a uint256 slot (a resource is an amount) and a bytes32 slot, but a handle of another scalar kind does not: an address handle in a uint256 slot is a TypeScript error. builder.context.sender and builder.context.executionAddress give you the signer and the execution proxy as address handles. For an op the typed methods do not cover yet, use builder.untypedOp with raw refs.

Wire runtime values

A flow declares what kind of value each input expects. You supply the concrete value in run.inputs when you call builder.compile(run) or sdk.request(flow, run). Every declared input must appear in run.inputs, and no other key may; a missing or unknown key fails with validation_error.

Input values by type

An integer amount on a resource input does not pull tokens. It states that the execution proxy already holds that amount, and the simulation reverts unless the proxy holds it or a precondition asserts it. To pull tokens from the signer, use materialisers.directDeposit.
This flow declares a scalar minOut next to the resource input and asserts the swap output against it onchain:

Materialisers

A materialiser tells Composer how to fund a resource input when the transaction runs: Tokens whose transfers credit a wei or two less than sent (stETH, Aave aTokens) are handled automatically: an exact directDeposit on them pulls up to amount and asserts that at least amount less 4 wei arrived. See the materialisers catalog for each kind’s config.

Assumptions for runtime amounts

When an input’s amount is known only at execution (a sweep directDeposit, balanceOf or call), Composer still needs a figure to plan routes, for example to quote a lifi.swap. Supply it in run.assumptions[name] as a bigint estimate:
With simAmount set, the result’s approvals asks the signer to approve simAmount to the execution proxy. Approve the amount you want swept: the deposit pulls what the approval allows. If Composer cannot resolve an amount it needs, the compile fails with subgraph_simulation_revert (HTTP 422), whose message names the port that needs an assumption. The REST API also accepts per-port keys ("<nodeId>.<port>") in run.assumptions; the SDK’s typed assumptions takes input names only.

Add safety: preconditions and guards

Preconditions describe state that must be true before the transaction runs. Guards are checks that run during the transaction.

Preconditions: state before execution

A precondition is a declarative assertion about onchain state. Three types exist: The SDK exposes typed factories. Amounts accept a bigint or a decimal string:
Pass them in run.preconditions. Materialisers add their own: directDeposit({ amount }) on an ERC-20 adds an Erc20Balance and an Erc20Allowance precondition, and only these materialiser-produced preconditions become approvals on the result. Add explicit preconditions when the inputs do not already capture what the flow expects, for example when balanceOf reads an amount that should already be on the proxy. The simulation evaluates the flow as if every precondition holds. Preconditions do not change live chain state, and a compile does not fail because live state differs from them. Wait until the real balances and allowances match before you submit.

Guards: invariants during execution

Attach guards with the guards option on an op call:
The SDK ships guards.slippage, guards.band and guards.coreNumericInvariant. port is typed against the op’s guardable outputs, so a guard on a port that provides its own minimum, or on a future output, is a TypeScript error. The enforced floor is reported at result.outputs['<nodeId>.<port>'].amount.minimum. See Guards for how guards work and where they can attach.

Preconditions or guards?

Use a precondition to say what must be true before the transaction runs. Use a guard to enforce what must stay true while it runs.

Wire in a signer

@lifi/composer-sdk does not sign or broadcast. Compile on your server, then submit every transaction in result.actions, in order, waiting for each to land before sending the next. In a browser app, send the actions to the client for the user’s wallet to sign; the API key stays on the server. This end-to-end example compiles a swap and zap with a guard and submits it with viem:
gasLimit is absent when Composer has no gas measurement for the chain; viem then estimates gas itself. See the compile response for every action and result field. builder.compile(run) builds the Flow, forms the request and sends it to POST /compose. To inspect or queue the request first, build it with sdk.request(builder.build(), run) and send it with sdk.client.compile(request). The signer in run determines the execution proxy, builder.context.sender, the account directDeposit pulls from, and the owner in every approval. The SDK does not check that you control the address: you can compile for any address, but only that address can execute the result.

Run options

Besides inputs, signer, preconditions, assumptions and sweepTo, the run takes these options: sweepTo moves the whole balance of every token the flow leaves on the proxy. Some balances cannot move, such as aTokens that back an open debt, and sweeping them reverts the whole transaction; see Non-transferable terminal resources.

Read the outputs

result.outputs reports every token output with its owner, its expected amount and its guaranteed minimum. terminalOutputs keeps what the flow delivers:
See Amounts on the response for what each amount means.

Compile a token pair without authoring

For a single-chain token pair, such as USDC into an Aave position, sdk.route plans and compiles the route on the server and returns the same ComposeCompileResult. Build amount with routeAmount.exact(...) or routeAmount.all(...) (the signer’s whole balance at execution). sweepTo is required whenever the planned route includes an aggregator swap, so pass it by default:
See the server-planned route recipe.

Errors you might see

Every failure throws. HTTP, transport and setup failures throw a ComposeError; builder mistakes, such as a duplicate node id or an unknown port, throw a plain Error. Narrow with isComposeError and branch on err.kind:
The kinds you are most likely to meet, and what to do: Under simulationPolicy: 'allow-revert', a simulated revert returns the calldata and the revert diagnostics as a partial result (HTTP 206) instead of throwing. Use it to show the revert reason to the user; never submit a partial result. Error codes lists every kind, including the continuation-specific ones.

Next steps

Build a cross-chain flow

Add a bridge and a destination flow.

Recipes

Runnable flows for common tasks.