Skip to main content
POST /compose takes a JSON body with two objects: flow, the Flow that describes what to execute, and run, the per-request values (signer, input amounts, options). Neither accepts unknown keys: an unknown run key fails the request schema and an unknown Flow key fails with decode_error, both HTTP 400. This page lists the request fields and the 200 and 206 responses. Error bodies are on Errors. The authoritative schema is FlowSchema in @lifi/compose-spec; GET /compose/manifest publishes it as JSON Schema under flowSchema. When this page conflicts with the schema, the schema wins.

Top-level: Flow

FlowInput

A resource input or a handle input.

ResourceInput

A resource input’s amount is supplied per request in run.inputs. Funds that end up on another chain (a bridge, a cross-chain flow) are expressed by the op that moves them, not by an input on a foreign chain.

HandleInput

Call (node)

Node ids

A node id must satisfy these rules, in the top-level flow and in every embedded continuationFlow:
  • Not empty and not "__proto__". Both are rejected at decode with decode_error.
  • Not a reserved ref scope: input, context or literal. Rejected with validation_error.
  • Unique within its flow. A duplicate is a validation_error.
Any other string is a valid id, including constructor.

BindValue

bind entries are a ref or a literal.

Ref

$ref is a dotpath. The parser splits it at the first dot and reads the part before the dot as the scope. See References:
  • input.<name>: a flow input.
  • context.sender or context.executionAddress: the signer, or the execution proxy. Any other context. key is rejected.
  • <nodeId>.<port>: an output port of an earlier node. There is no output. prefix.
  • <nodeId>.<family>.<index>: one instance of an output family. Because the split is at the first dot, p.parts.1 addresses port parts.1 of node p. core.partition with config: { bps: [5000, 3000, 2000] } produces parts.0, parts.1 and parts.2. A ref past the last instance is an unresolved ref.
The schema only checks that the string contains a dot after its first character. Any prefix other than input or context is read as a node id, so a typo such as inptu.amountIn becomes an output ref and fails as unresolved. The SDK’s builder.inputs and builder.context handles avoid hand-typed paths.

LiteralBinding

AppliedGuard

Resource

Tempo and Arc express their native coin as an ERC-20, and the server rewrites every native resource on them to that token when it decodes the Flow: Write the ERC-20 form on these chains so the Flow you send matches the Flow that runs.

SolType

Literal union of supported Solidity scalar types: uint8, uint16, uint32, uint64, uint128, uint256, int128, int256, address, bool, bytes, bytes4, bytes32, string.

Epilogue

The epilogue is a list of transfers the execution proxy makes after the last node runs. A named forward moves the proxy’s whole balance of one resource to one address. The remainder moves every other resource the proxy still holds to one address.
At least one of forwards and remainder is required. ForwardTo is an EVM address or { "$ref": "context.sender" }; the compiler admits no other ref. run.sweepTo: X is shorthand for epilogue: { remainder: X }. A request that sets both run.sweepTo and flow.epilogue fails with a 400 validation_error at run.sweepTo. The SDK builder does not author epilogue; use run.sweepTo, or send a hand-built flow through sdk.client.compile() for named forwards. See Sweeping and amounts.

Lineage

lineage links the parts of one non-atomic flow. The server writes it into every flow it hands back for a later compile, such as a committed destination flow. Post such a flow back unchanged. Never author or edit lineage: a flow without it starts a new journey. Both fields are lowercase UUIDs.

continuation.settle node

A continuation.settle node, the settle node, ends a source flow. The compile registers an escrow, and LI.FI’s settlement service later runs the settle node’s destination flow, the continuationFlow, from it. The escrow lives on the destination chain of a bridge or order that funds it, or on the flow’s own chain for a same-chain continuation. See Cross-chain flows for the model and continuation.settle for the op.
In this example the source flow runs on Arbitrum (42161), and an earlier bridge node (lifi.bridge with no destination) delivers USDC to Base, so the escrow sits on Base. The destination flow deposits that USDC into Aave, and the outcome, aBasUSDC, goes to destination. The funding resource is bound through bind.input, never through config. The node has one output port, output, which is delivered in the future. There is no top-level continuation field on the Flow. config (ContinuationIntent): The destination flow follows its own rules: it must not reference context.sender, must not set an epilogue, and must not nest another settle node. The op reference lists them, and its Errors section lists every violation.

run

200 response

Amounts are decimal strings on the wire. The SDK decodes outputs and epilogue amounts to bigint. The response may also carry producedResources, a legacy field. Read outputs instead.

outputs

Each entry has resource and amount, and a role:
  • { "role": "consumed", "consumedBy": "<nodeId>" }: a later node spends it.
  • { "role": "terminal", "owner": "0x…", "delivery": … }: nothing spends it. owner receives it. delivery is { "when": "now" }, or { "when": "future", "etaSeconds"?, "provider"?, "trackingId"? } for an output that lands after the transaction, such as a settle node’s output.
amount is { estimate?, minimum? }. estimate is { basis: "simulated" | "quoted", value }, the expected outcome. minimum is { basis: "guard" | "op" | "input" | "declared", value }, a floor. For a settle node’s output, minimum is the minimum received, the only amount enforced on chain, and estimate is never enforced.

actions

actions is the ordered to-do list: approvals, then the execution transaction, then one escrow funding transfer per externally funded settle node. Each action has kind: "transaction", a purpose, a submitter (signer: only the signer may send it; anyone: any wallet may) and a transactionRequest. Submit the actions in order, each on its transactionRequest.chainId.

settlements

Record<settleNodeId, { escrow?, binding? }>. It describes the escrow behind each settle node and contains nothing to sign or submit. (escrow.chainId, escrow.address) identifies the escrow: track it with Escrow status. Every compile registers a fresh escrow; never reuse one. binding is present only for exact destination flows. It discloses what the escrow will run: A settle node also shapes these fields:
  • outputs['<settle id>.output']. owner is the outcome’s destination, and delivery.when is 'future'. amount.minimum is the minimum received, the only amount enforced on chain. amount.estimate (basis: 'quoted') is the expected outcome: what the destination flow delivered at the minimum funding, scaled up to the expected funding by at most 100 bps. Nothing enforces it. A zero-outcome exact destination flow has no such entry.
  • outputs['<producer id>.amountOut']. For bridge or order funding, role: 'consumed' with consumedBy set to the settle node: the funds go into the escrow, not to the user.
  • actions. Each fundEscrow carries the settle nodeId and submitter: 'anyone'.
  • fill.validUntilMs. Submit the user’s transaction before this time, or the funds can land in an expired escrow. It is never later than the escrow’s expiry. Nothing on chain enforces it.

206 response

With run.simulationPolicy: "allow-revert", a simulation revert returns HTTP 206 instead of a 422 simulation_revert. The same applies when the run.simulateUserProgram simulation reverts.
data carries outputs, transactionRequest (always present), userProxy, simulationRevert: { code, rawErrorBytes, decodeResult? }, producedHandles (always {}; REST only, the SDK result type does not expose it), and optionally approvals, actions, settlements, warnings and the legacy producedResources. It has no epilogue, fill, priceImpact, verificationByNode or userProgramSimulation. What outputs holds depends on which simulation reverted. When the main simulation reverts, nothing was measured: estimates are quoted or absent, and minimums are op, input, declared or absent. When the main simulation succeeds and only the run.simulateUserProgram simulation reverts, outputs keeps the simulated amounts.
A 206 can carry a registered escrow in settlements and a fundEscrow action. Never fund an escrow from a partial result: the balance stays locked until expiry, then returns to refund. Fix the revert and recompile.

Complete request

A same-chain swap of 1 WETH to USDC, then a deposit into Aave v3, with leftovers returned to the signer:

See also