{ "$ref": "…" }. It binds an input port of a Call to a value produced elsewhere in the Flow: a declared input, an earlier call’s output, or a runtime context value. The SDK writes refs for you from typed handles; you write them by hand only for raw wire Flows and the raw.ref escape hatch.
The three ref scopes
1. input.<name>
References an input declared in flow.inputs:
2. context.<key>
References a runtime context value. Two keys exist, and any other key under context.* is rejected:
See Write the destination flow for the other destination flow rules.
3. <nodeId>.<port>
Any ref whose prefix is not input or context references another call’s output port. <nodeId> is the id you gave the node, so builder.lifi.swap('swap', …) produces refs of the form swap.<port>:
- The ref must point to an earlier node in
nodes. - A ref splits at the first dot. Everything after it is the port name, so
p.parts.1addresses portparts.1of nodep. That is how you reference one instance of an output family such ascore.partition’sparts(see Output families). A ref past the last instance fails as an unresolved ref. - A misspelled prefix becomes an output ref.
inputs.amountInorcontxt.senderreads as an output of a node calledinputsorcontxt, then fails with avalidation_errorbecause no such node exists. The SDK’sbuilder.inputsandbuilder.contexthandles avoid hand-typing these paths.
Reserved prefixes
input, context and literal cannot be used as node ids. The empty string and __proto__ are rejected as node ids with a decode_error, including inside a continuation.settle node’s destination flow.
literal is not a ref scope. A literal value in bind is a LiteralBinding:
How SDK handles become refs
The SDK gives you typed handles and converts them to refs when it serialises the Flow:Raw refs (escape hatch)
builder.untypedOp(id, op, { bind, config }) adds a node for an op or config field the typed builder methods do not cover yet. It returns nothing and takes raw Ref values in bind, with no type checks. To feed its output into a typed call, wrap the path with raw.ref<T>(path), which is accepted by any Bindable<T> slot:
some.op stands for whichever manifest op you call untyped. raw.ref does no runtime validation: you choose the type parameter, and the validator rejects the flow at compile time if it does not match the port. Prefer typed builder methods whenever they exist.
Refs in forward targets
Theto of an epilogue forward, the epilogue remainder and run.sweepTo accept only a literal address or { "$ref": "context.sender" }. See The flow epilogue.
See also
- Resources and ports: what each port carries.
- Flow wire format: refs on the wire.
- Build a same-chain flow: typed handles in the SDK.

