| name | liquidity-hub-integration |
| description | Integration guide for @orbs-network/liquidity-hub-sdk into a DEX. Enables DEXes to offer better swap prices by routing through Orbs Liquidity Hub — a decentralized optimization layer that sources liquidity from on-chain and off-chain solvers. Covers SDK setup, quote fetching, price comparison, swap execution, and analytics. |
Liquidity Hub Integration
Use this skill to integrate @orbs-network/liquidity-hub-sdk into any DEX. Liquidity Hub is a decentralized optimization layer that finds better swap prices by sourcing liquidity from multiple on-chain and off-chain solvers. When Liquidity Hub offers a better price than the DEX's own router, the swap is executed through Liquidity Hub instead — giving users better rates at no extra cost.
How It Works
- User initiates a swap on the DEX.
- DEX fetches a quote from its own router and from Liquidity Hub in parallel.
- If the Liquidity Hub quote is better (higher output amount), execute through Liquidity Hub.
- If the DEX quote is better, fall back to the normal DEX swap.
- The user always gets the best available price.
Distribution
This skill lives in skills/liquidity-hub-integration/ of the orbs-network/spot-ui repository.
Workflow
- Read references/01-quickstart.md for install, supported chains, and the minimum integration steps.
- Read references/02-sdk.md for SDK initialization, quote fetching, price comparison, and swap execution.
- Read references/03-swap-flow.md for the complete swap flow including approval, wrapping, signing, and analytics callbacks.
- Read references/04-best-practices.md for error handling, quote freshness, native token wrapping, and debugging.
- Use assets/liquidity-hub-example.ts as a starting template.
Guardrails
- Set the
partner field to the DEX name (lowercase, e.g. "myDex").
- Only install
@orbs-network/liquidity-hub-sdk. No other Orbs packages needed.
- Never skip the price comparison — always compare Liquidity Hub quote against the DEX quote and use whichever is better.
- Always check quote freshness with
isFreshQuote before executing a swap.
- Native tokens (ETH, BNB, MATIC, etc.) must be wrapped before swapping through Liquidity Hub.
- Report analytics callbacks for all stages (quote, approval, wrap, signature, swap) so the protocol can optimize for your DEX.
