LI.FI Messaging Flow Documentation

Overview

LI.FI Messaging Flow enables seamless interactions with centralized and hybrid exchanges that use message-based APIs (such as Hyperliquid) instead of traditional on-chain transactions. This flow delivers gasless, approval-free operations for cross-chain transfers involving protocols that operate with off-chain signed messages. Traditional DeFi operations require users to send on-chain transactions, manage gas fees, and approve token spending for each interaction. Messaging flow eliminates these friction points by using off-chain signed messages (EIP-712) that are relayed to destination protocols through LI.FI’s backend infrastructure.

Key Benefits of Messaging Flow

No Token Approvals Required: Unlike transaction-based flows, messaging flow doesn’t require users to approve token spending
Gasless Operations: Users sign messages off-chain without paying gas fees for the message itself (some operation might require fee payments, not gas)
Asynchronous Execution: Messages are relayed and processed asynchronously, with status tracking via taskId
Seamless Integration: Works out-of-the-box with LI.FI API, SDK, and Widget

How Messaging Flow Works

The messaging flow operates through a multi-step process that replaces traditional on-chain transactions with off-chain signed messages:

Quote/Route Generation: User requests a quote or route with executionType=message (will generate ONLY message-based routes) or executionType=all (both transaction and messages options)
Message Creation: LI.FI generates an EIP-712 typed message containing the operation details
User Signature: User signs the message off-chain in their wallet (no gas required)
Message Relay: Signed message is submitted to LI.FI’s /v1/advanced/relay endpoint
Backend Processing: LI.FI backend validates and forwards the message to the destination protocol (e.g., Hyperliquid)
Task Tracking: Backend returns a taskId for tracking the asynchronous operation
Status Monitoring: Status can be checked via /v1/status endpoint using the taskId parameter

Flow Diagram

User Wallet → Sign EIP-712 Message (off-chain, no gas)
     ↓
LI.FI SDK/API → POST /v1/advanced/relay
     ↓
LI.FI Backend → Validates & relays to protocol
     ↓
Returns taskId → Track via GET /v1/status?taskId=...
     ↓
Protocol Execution → (e.g., Hyperliquid withdrawal)

Key Differences from Transaction Flow

Aspect	Transaction Flow	Messaging Flow
Execution Type	On-chain transaction	Off-chain signed message
Gas Fees	User pays gas for each transaction	No gas for signing messages
Token Approvals	Required (separate transaction)	Not required (`skipApproval: true`)
Status Tracking	`txHash`	`taskId`
User Action	Send transaction	Sign typed message

Important Parameters

estimate.skipApproval: Automatically set to true for messaging flows, indicating no approval transaction is needed
estimate.executionType: Set to "message" to identify steps that use messaging flow
typedData: Contains the EIP-712 message structure that users need to sign

The executionType Parameter

The executionType parameter controls which types of routes are returned by the LI.FI API. This optional parameter is available in:

GET /v1/quote
POST /v1/advanced/routes

Values

transaction (default): Returns only routes using traditional on-chain transactions, excluding messaging flow routes
message: Returns only routes that use messaging flow
all: Returns both transaction-based and message-based routes

Example Usage

Get only message-based routes:

curl -X GET 'https://li.quest/v1/quote?fromChain=1337&toChain=999&fromToken=0x8F254b963e8468305d409b33aA137C6700000000&toToken=0x9FDBdA0A5e284c32744D2f17Ee5c74B284993463&fromAddress=0x552008c0f6870c2f77e5cC1d2eb9bdff03e30Ea0&fromAmount=1000000&executionType=message'

Get all available routes (both types):

curl -X GET 'https://li.quest/v1/quote?fromChain=1337&toChain=999&fromToken=0x8F254b963e8468305d409b33aA137C6700000000&toToken=0x9FDBdA0A5e284c32744D2f17Ee5c74B284993463&fromAddress=0x552008c0f6870c2f77e5cC1d2eb9bdff03e30Ea0&fromAmount=1000000&executionType=all'

The /relay Endpoint

POST /v1/advanced/relay

Purpose: Submit signed EIP-712 messages for relaying to destination protocols. Endpoint: https://li.quest/v1/advanced/relay

Request Body

The request body is a RelayRequest object containing:

Step Information: Standard LI.FI step data (tool, action, estimate)
Typed Data: Array of signed EIP-712 messages
Signature: User’s signature for each message

Request Schema

{
  id: string                    // Step ID
  type: 'lifi'                  // Step type
  tool: string                  // Bridge tool (e.g., 'hyperliquidSA')
  toolDetails: {                // Tool metadata
    key: string
    name: string
    logoURI: string
  }
  action: {                     // Transfer action details
    fromChainId: number
    toChainId: number
    fromToken: Token
    toToken: Token
    fromAmount: string
    fromAddress: string
    toAddress: string
    slippage?: number
  }
  estimate: {                   // Estimated results
    fromAmount: string
    toAmount: string
    toAmountMin: string
    tool: string
    executionDuration: number
    approvalAddress: string
    skipApproval: true          // Always true for messaging flow
    feeCosts: FeeCost[]
    gasCosts: GasCost[]
    executionType: string
  }
  includedSteps: Step[]         // Nested steps
  typedData: TypedData[]        // EIP-712 messages with signatures
}

Response

Success Response (200 OK):

{
  "status": "ok",
  "data": {
    "taskId": "0x3078316542363633386445386335373163373837443762433234463938624641373335343235373331437c313735393438383039323538347c65646461643630632d373730392d346165312d623431652d3834643834333064306135623a30"
  }
}

Error Response (400 Bad Request):

{
  "status": "error",
  "data": {
    "code": 400,
    "message": "Invalid request"
  }
}

Response Fields

status: Either "ok" or "error"
data.taskId: Unique hex-encoded identifier for tracking the message relay operation
data.code: Error code (only present when status is “error”)
data.message: Error message (only present when status is “error”)

Status Tracking with taskId

After relaying a message, you receive a taskId that uniquely identifies the operation. Use this to track the message processing status.

GET /v1/status

Endpoint: https://li.quest/v1/status Query Parameters:

taskId (optional): The task ID returned from /relay endpoint
txHash (optional): Transaction hash (for traditional transactions)
toChain (optional): Destination chain ID or key
bridge (optional): Bridge tool identifier
fromChain (optional): Source chain ID or key

Note: You must provide either taskId or txHash. For messaging flow, use taskId.

Example Request

curl -X GET 'https://li.quest/v1/status?taskId=0x3078316542363633386445386335373163373837443762433234463938624641373335343235373331437c313735393438383039323538347c65646461643630632d373730392d346165312d623431652d3834643834333064306135623a30'

Response Format

The status endpoint returns the current state of the transfer:

{
  "status": "DONE",
  "substatus": "COMPLETED",
  "sending": {
    "txHash": "0x...",
    "amount": "1000000",
    "token": {
      /* token details */
    },
    "chainId": 1337,
    "timestamp": 1234567890
  },
  "receiving": {
    "txHash": "0x...",
    "amount": "1000000",
    "token": {
      /* token details */
    },
    "chainId": 999,
    "timestamp": 1234567890
  }
}

Current Usage & Supported Protocols

Messaging flow is currently used for interactions with the following protocols:

1. Hyperliquid (Primary Use Case)

Protocol: Hyperliquid Operation: Withdrawals from Hyperliquid to EVM chains Bridge Tool: hyperliquidSA Message Type: SendAsset, “ How it works:

User has tokens on Hyperliquid spot account
Signs a SendAsset message to withdraw to an EVM chain
LI.FI relays the message to Hyperliquid’s API
Hyperliquid processes the withdrawal and sends tokens to destination chain

2. Unit Protocol

Protocol: Unit Protocol Operation: Withdrawals to Hyperliquid via Unit bridge Bridge Tool: unit Message Type: SpotSend Chain IDs:

From: 1337 (Hyperliquid/Hypercore)
To: EVM chains, Bitcoin, Solana

Supported Message Types

Hyperliquid

LI.FI Messaging Flow supports three EIP-712 message types for Hyperliquid operations. Each message type follows a specific structure and is used for different operations.

1. SpotSend

Purpose: Spot token transfers Use Case: Used by Unit protocol for deposits to Hyperliquid Bridge Tool: unit Message Structure:

{
  type: 'spotSend',
  signatureChainId: '0x1',
  hyperliquidChain: 'Mainnet',
  destination: '0x...',           // Recipient address
  token: 'USOL:0x49b67c39...',   // Token identifier
  amount: '1.0',                  // Amount to transfer
  time: 1234567890                // Timestamp in milliseconds
}

2. SendAsset

Purpose: Asset transfers between DEXs (spot accounts) Use Case: Used for Hyperliquid withdrawals to EVM chains Bridge Tool: hyperliquidSA Message Structure:

{
  type: 'sendAsset',
  signatureChainId: '0x1',
  hyperliquidChain: 'Mainnet',
  destination: '0x2000...00fe',        // System address
  sourceDex: 'spot',                    // Source DEX type
  destinationDex: 'spot',               // Destination DEX type
  token: 'USOL:0x49b67c39...',         // Token identifier
  amount: '1.0',                        // Amount to transfer
  fromSubAccount: '',                   // Agent wallet address (if used)
  nonce: 1757944034747                  // Timestamp/nonce
}

Note: All messages follow the EIP-712 typed data standard and include domain information:

{
  domain: {
    name: 'HyperliquidSignTransaction',
    version: '1',
    chainId: 999,
    verifyingContract: '0x0000000000000000000000000000000000000000'
  },
  types: { /* EIP712Domain and message types */ },
  primaryType: 'HyperliquidTransaction:SendAsset',
  message: { /* message content */ }
}

Integration Guide

Using the API Directly

Step 1: Get a Quote/Route Request a quote with executionType=message or executionType=all:

curl -X GET 'https://li.quest/v1/quote?fromChain=1337&toChain=999&fromToken=0x8F254b963e8468305d409b33aA137C6700000000&toToken=0x9FDBdA0A5e284c32744D2f17Ee5c74B284993463&fromAddress=0x552008c0f6870c2f77e5cC1d2eb9bdff03e30Ea0&fromAmount=1000000&executionType=all'

Step 2: Identify Message Steps Check the route for steps with estimate.executionType === "message" and estimate.skipApproval === true. Step 3: Sign the Message Use the typedData from the route to request a signature from the user’s wallet:

const signature = await walletClient.signTypedData({
  domain: typedData.domain,
  types: typedData.types,
  primaryType: typedData.primaryType,
  message: typedData.message,
})

Step 4: Relay the Message Submit the signed message to the /relay endpoint:

curl -X POST 'https://li.quest/v1/advanced/relay' \
  -H 'Content-Type: application/json' \
  -H 'x-lifi-api-key: YOUR_API_KEY' \
  -d '{
    "id": "step-id",
    "typedData": [{
      ...typedData,
      "signature": "0x..."
    }],
    ...stepData
  }'

Step 5: Track Status Use the returned taskId to check status:

curl -X GET 'https://li.quest/v1/status?taskId=RETURNED_TASK_ID'

Best Practices

Always check estimate.skipApproval: If true, skip approval transaction
Validate signatures: Ensure the message is signed correctly before relaying
Store taskId: Save the taskId returned from /relay for status tracking
Poll status endpoint: Check status periodically until completion

Limitations & Considerations

Current Limitations

Supported Protocols: Currently limited to Hyperliquid and Unit protocol

Future Enhancements

As the messaging flow matures, additional protocols and chains may be supported. Protocol teams interested in integration can contact the LI.FI team.

FAQ

Q: Do I need to do anything special to use messaging flow? A: No. If you’re using the LI.FI SDK or Widget, messaging routes are automatically included and handled. For direct API usage, set executionType=all to see message routes. Q: Why does my route have skipApproval: true? A: This indicates the route uses messaging flow and doesn’t require a token approval transaction. Q: How long does it take for a message to be processed? A: Processing time varies by protocol. For Hyperliquid, withdrawals typically complete within a few seconds. Q: Can I cancel a message after relaying? A: Once a message is relayed and accepted by the protocol, it cannot be cancelled through LI.FI. Check with the specific protocol for their cancellation policies. Q: How do I know if a route uses messaging flow? A: Check the estimate.executionType field. If it’s "message", the route uses messaging flow.

Next Steps

Integrate: Use the LI.FI SDK, Widget, or API to access messaging flow routes
Test: Try a small withdrawal from Hyperliquid using the messaging flow
Monitor: Use the taskId to track your operations via the status endpoint
Contact: Reach out to the LI.FI team for protocol integration requests

For more information, visit the LI.FI Documentation.

Learn About LI.FI

Supported Systems

LI.FI Architecture

User Flows and Examples

Learn More

​LI.FI Messaging Flow Documentation

​Overview

​Key Benefits of Messaging Flow

​How Messaging Flow Works

​Flow Diagram

​Key Differences from Transaction Flow

​Important Parameters

​The executionType Parameter

​Values

​Example Usage

​The /relay Endpoint

​POST /v1/advanced/relay

​Request Body

​Request Schema

​Response

​Response Fields

​Status Tracking with taskId

​GET /v1/status

​Example Request

​Response Format

​Current Usage & Supported Protocols

​1. Hyperliquid (Primary Use Case)

​2. Unit Protocol

​Supported Message Types

​Hyperliquid

​1. SpotSend

​2. SendAsset

​Integration Guide

​Using the API Directly

​Best Practices

​Limitations & Considerations

​Current Limitations

​Future Enhancements

​FAQ

​Next Steps