企业官网建设流程全解析

wagmi Tempo DEX 卖出报价 Hook 完全指南：dex.useSellQuote的用法、参数与实现原理

【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi

dex.useSellQuote是 wagmi Tempo 模块为 DEX（去中心化交易所）交易场景提供的 React Hook，用于在卖出指定数量代币时，从链上订单簿实时获取可收到的tokenOut数量报价。本文以 site/tempo/hooks/dex.useSellQuote.md 为核心骨架，结合底层 Actiondex.getSellQuote、React 侧实现与测试用例，完整讲解该 Hook 的调用方式、参数语义、返回结构与缓存行为，帮助你在以太坊应用中快速集成"卖出前询价"能力。

一、dex.useSellQuote是什么

dex.useSellQuote是一个只读查询型（query）Hook，对应底层 Actiondex.getSellQuote，其职责是：给定要卖出的代币地址（tokenIn）、目标收到代币地址（tokenOut）以及卖出数量（amountIn），返回卖出后预期获得的tokenOut数量。

它与购买方向的dex.useBuyQuote（详见 site/tempo/hooks/dex.useBuyQuote.md）互为镜像：

• useBuyQuote：指定amountOut，问"买入这么多需要投入多少tokenIn"；
• useSellQuote：指定amountIn，问"卖出这么多能换回多少tokenOut"。

两者都不会发起交易、不消耗 Gas，只读取订单簿价格状态，适合用于交易界面的报价展示、滑点预估与下单前的用户确认。

二、前置准备：Tempo 链配置

使用该 Hook 前，需要先创建连接到 Tempo 链的 wagmi Config。文档引用的完整配置模板位于 site/snippets/react/config-tempo.ts：

import { createConfig, http } from 'wagmi' import { tempo } from 'wagmi/chains' import { tempoWallet } from 'wagmi/tempo' export const config = createConfig({ connectors: [tempoWallet()], chains: [tempo], multiInjectedProviderDiscovery: false, transports: { [tempo.id]: http(), }, })

要点说明：

• tempoWallet是 Tempo 链的钱包连接器（wagmi/tempo导出），负责提供签名账户与连接状态；
• chains: [tempo]声明应用只使用 Tempo 链，后续报价查询默认落在该链上；
• multiInjectedProviderDiscovery: false关闭多注入钱包自动发现，避免与tempoWallet冲突；
• transports中为tempo.id配置http()作为 RPC 传输层，所有只读查询（包括报价）都经由该 transport 发往链上节点。

三、基本用法

文档给出的最小调用示例如下：

import { Hooks } from 'wagmi/tempo' import { parseUnits } from 'viem' const { data: quote } = Hooks.dex.useSellQuote({ amountIn: parseUnits('100', 6), tokenIn: '0x20c0000000000000000000000000000000000001', tokenOut: '0x20c0000000000000000000000000000000000002', }) console.log('Amount received:', quote) // @log: Amount received: 99700000n

几个关键点：

• 导入路径：Hooks从wagmi/tempo导出，dex.useSellQuote是Hooks.dex命名空间下的成员；
• 数量精度：amountIn必须使用bigint，示例用 viem 的parseUnits('100', 6)将 100 个 6 位小数代币转为整数100000000n，不要直接传字符串或 number；
• 返回值：data是bigint，上例中卖出100000000n后获得99700000n，即约 99.7 个代币——差额来自订单簿价差与流动性结构，这正是"实时报价"而非"按面值兑换"的体现。

在 React 组件中，更完整的形态是利用 TanStack Query 提供的isLoading/isSuccess/error等状态字段：

import { Hooks } from 'wagmi/tempo' import { parseUnits } from 'viem' function SellQuote() { const { data, isLoading, isError, error } = Hooks.dex.useSellQuote({ amountIn: parseUnits('100', 6), tokenIn: '0x20c0000000000000000000000000000000000001', tokenOut: '0x20c0000000000000000000000000000000000002', }) if (isLoading) return <div>Loading...</div> if (isError) return <div>Quote failed: {error.message}</div> return <div>Expected Output: {data?.toString()}</div> }

四、参数详解（Parameters）

useSellQuote的参数类型定义在 packages/react/src/tempo/hooks/dex.ts（useSellQuote.Parameters，约第 885–896 行），其语义与底层 Actiondex.getSellQuote的参数一一对应，完整字段说明见 site/tempo/actions/dex.getSellQuote.md：

源码层面的补充细节：

• Hook 内部通过useConfig获取全局 config，并通过useChainId({ config })取得当前链 ID，在未显式传入chainId时自动补全（见 packages/react/src/tempo/hooks/dex.ts 第 870–883 行的useSellQuote实现）；
• Action 侧（packages/core/src/tempo/actions/dex.ts 第 992–998 行的getSellQuote）会从参数中剥离chainId，通过config.getClient({ chainId })拿到对应链的 viem client，再调用 viem Tempo 的Actions.dex.getSellQuote(client, rest)完成链上读取；
• 也就是说，从 Hook 到链上读数的完整调用链为：useSellQuote→getSellQuote.queryOptions→Actions.dex.getSellQuote(config, params)→config.getClient({ chainId })→ viemActions.dex.getSellQuote。

关于query子参数

query选项直接透传给 TanStack Query v5 的useQuery，因此支持其全部标准字段（enabled、retry、refetchInterval、staleTime、select、placeholderData等），官方说明见 TanStack Query 的useQuery文档。

值得一提的源码行为：getSellQuote.queryOptions在 packages/core/src/tempo/actions/dex.ts 第 1019–1038 行中，会自动将enabled与参数完整性绑定——只有tokenIn、tokenOut、amountIn三者都非空时查询才会执行，避免在参数缺失时发起无效的链上请求。

五、返回类型（Return Type）

useSellQuote的返回值是一个 TanStack Query 查询结果对象，核心字段如下：

data

• 类型：bigint
• 语义：卖出amountIn数量的tokenIn后，预期收到的tokenOut数量（Actions.dex.getSellQuote.ReturnValue）。

在底层 Action 的类型定义中，返回值被明确标注为bigint：

type ReturnType = bigint

查询状态字段

Hook 返回的是标准UseQueryReturnType，包含isPending/isLoading/isSuccess/isError、error、refetch、fetchStatus、dataUpdatedAt等全部 TanStack Query 状态，可用于渲染加载态、错误态与数据刷新。关于 Hook 返回类型的通用说明，可参考 TanStack Query v5 的useQuery文档。

六、测试用例与实战注意事项

仓库在 packages/react/src/tempo/hooks/dex.test.ts（第 548–594 行）为useSellQuote提供了两组测试，可以作为集成时的行为参照：

场景一：正常报价（有流动性）

// Place bid orders to create liquidity await Actions.dex.placeSync(config, { token: base, amount: parseUnits('500', 6), type: 'buy', tick: Tick.fromPrice('0.999'), }) const { result } = await renderHook(() => dex.useSellQuote({ tokenIn: base, tokenOut: quote, amountIn: parseUnits('100', 6), }), ) await vi.waitFor(() => expect(result.current.isSuccess).toBeTruthy()) expect(result.current.data).toBeGreaterThan(0n) // Should be approximately 100 * 0.999 = 99.9 expect(result.current.data).toBeLessThan(parseUnits('100', 6))

要点：报价依赖订单簿流动性——测试先以Tick.fromPrice('0.999')挂入买单价，卖出 100 个base后所得应小于 100（约 99.9），验证了报价会随订单簿价格收敛。

场景二：无流动性时报错

const { result } = await renderHook(() => dex.useSellQuote({ tokenIn: base, tokenOut: quote, amountIn: parseUnits('100', 6), query: { retry: false }, }), ) await vi.waitUntil(() => result.current.isError, { timeout: 2_000 }) expect(result.current.error?.message).toContain('InsufficientLiquidity')

要点：若交易对没有流动性，查询会以InsufficientLiquidity错误失败。生产代码中应做好isError分支处理，并可通过query.retry控制重试次数（测试中设为false以快速失败）。

实战建议：

1. 善用enabled自动门控：queryOptions已内置参数完整性检查，无需手动传enabled；
2. 与usePlace/useBuy组合：报价仅用于展示，真正下单请使用Hooks.dex.usePlace、Hooks.dex.useBuy等 mutation Hook（参考 packages/react/src/tempo/hooks/dex.ts 中的usePlace、useBuy实现）；
3. 数量统一用bigint：从parseUnits到data全程保持bigint，避免浮点精度问题。

七、相关资源

• 底层 Action 文档：site/tempo/actions/dex.getSellQuote.md
• 购买方向报价 Hook：site/tempo/hooks/dex.useBuyQuote.md
• Hooks 索引：site/tempo/hooks/index.md
• Actions 索引：site/tempo/actions/index.md
• React Hook 源码实现：packages/react/src/tempo/hooks/dex.ts
• Core Action 源码实现：packages/core/src/tempo/actions/dex.ts
• 行为测试用例：packages/react/src/tempo/hooks/dex.test.ts
• Tempo 配置示例：site/snippets/react/config-tempo.ts

【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi