This guide covers flows that run on one chain. To bridge and then act on the destination chain, see Build a cross-chain flow.
Set up the SDK
Install the SDK and spec on the same version withnpm install @lifi/composer-sdk @lifi/compose-spec; Before you start covers versions, Node.js and the API key. Create the SDK on your server:
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':
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:
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 inrun.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
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 sweepdirectDeposit, 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:
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:
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 theguards option on an op call:
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
Besidesinputs, 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:
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:
Errors you might see
Every failure throws. HTTP, transport and setup failures throw aComposeError; builder mistakes, such as a duplicate node id or an unknown port, throw a plain Error. Narrow with isComposeError and branch on err.kind:
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.

