快速开始 - LI.FI

本文会带你从一个空项目走到下出一笔订单。全程使用 Hyperliquid；切换交易场所只需替换对应的 provider 插件和 provider 参数，代码结构的其余部分不变。

Perps 运行在一个受限访问的接口上，而不是公共 API 主机，因此下面的调用需要先为你的集成商开通访问权限才会返回数据。参见访问权限。

1. 安装

安装核心 SDK，以及你所需的每个交易场所对应的插件。

npm install @lifi/perps-sdk @lifi/perps-sdk-provider-hyperliquid

2. 创建客户端

import { createPerpsClient } from '@lifi/perps-sdk'
import { hyperliquidProvider } from '@lifi/perps-sdk-provider-hyperliquid'

const client = createPerpsClient({
  integrator: 'my-app',
  apiKey: process.env.LIFI_API_KEY!,
  providers: [hyperliquidProvider()],
})

integrator 标识你的应用，apiKey 来自 Partner Portal。注册一个 provider 会将该交易场所的读取接口绑定到客户端，之后你可以通过键名查找它。有一个选项值得提前了解：retry 用于控制 HTTP 重试行为，可以为所有交易场所设置统一策略，也可以按交易场所分别设置。这个 client 是行情数据和账户查询所使用的读取接口。设置和交易请改用 PerpsClient——一个构建在其之上的独立类，参见第 4 步。在那里，用户的钱包是通过 setUserWallet 提供的，而不是作为构造函数选项，因为它可以在客户端创建之后再设置或更换。

3. 读取行情数据

行情数据既不需要用户，也不需要设置，因此这是确认客户端配置是否正确的最快方式。

import { getMarkets } from '@lifi/perps-sdk'

const { markets } = await getMarkets(client, { provider: 'hyperliquid' })
console.log(markets.slice(0, 5))

如果这里能返回市场数据，说明你的密钥、集成商标识和访问权限都是正常的。如果不能，请先解决这个问题，再涉及钱包相关的操作。

4. 完成账户设置

交易前需要针对每个用户、每个交易场所完成一次性设置。具体内容因交易场所而异，SDK 会替你统一协调，而不需要你为每种方案分别编写脚本。在调用之前先给 PerpsClient 传入用户的钱包，因为设置阶段正是首次需要捕获用户签名的地方。

import { PerpsClient } from '@lifi/perps-sdk'
import { hyperliquidProvider } from '@lifi/perps-sdk-provider-hyperliquid'

const perps = new PerpsClient({
  integrator: 'my-app',
  apiKey: process.env.LIFI_API_KEY!,
  providers: [hyperliquidProvider()],
})
perps.setUserWallet(userWallet)

const setup = await perps.checkSetup({ provider: 'hyperliquid', address: userAddress })

for (const step of setup.setup) {
  await perps.executeProviderSetupAction({
    provider: 'hyperliquid',
    address: userAddress,
    step,
  })
}

checkSetup 会返回该账户仍待完成的设置项；一旦返回为空，isReady 即为 true，此时无需再签署任何内容。在 Hyperliquid 上，这一步会批准一个代理钱包；在 Lighter 上，会在链上注册一个签名密钥；在 Ondo 上，会建立一个会话。用户只需在此处签名一次，这也是之后每笔订单都不再弹出钱包的原因。

5. 下单

import { OrderSide, OrderType, getMarketsContext } from '@lifi/perps-sdk'

const [market] = markets // 来自第 3 步

const { prices } = await getMarketsContext(client, {
  provider: 'hyperliquid',
  marketIds: [market.id],
})

const result = await perps.placeOrder({
  provider: 'hyperliquid',
  address: userAddress,
  market: { marketId: market.id, categoryId: market.categoryId },
  side: OrderSide.BUY,
  type: OrderType.MARKET,
  size: '0.1',
  price: prices[0].midPrice, // 每笔订单都必填，包括市价单
})

成功的结果会携带该交易场所的订单标识符，如果该操作涉及链上交互，还会携带交易哈希和区块浏览器链接。失败的结果会携带一个错误，通常还带有结构化错误码——应以此作为分支判断依据，而不是错误消息文本。其他交易方法遵循相同的结构：placeTriggerOrder 用于独立的止盈止损单，placeTwapOrder 和 cancelTwapOrder 用于时间加权订单，cancelOrders 用于取消订单，modifyOrders 用于原地修改订单而无需先取消再重新下单。

附加在入场订单上的止盈止损属于订单本身的一部分，而不是单独的调用。只有在没有可附加的订单时，才需要使用独立的触发单方法。

6. 推送数据

轮询获取成交信息是可行的，但会浪费你的速率限制额度和用户的耐心。WebSocket 客户端按通道订阅，并返回一个用于取消订阅的函数。

import { PerpsWsClient } from '@lifi/perps-sdk'
import { hyperliquidWsProvider } from '@lifi/perps-sdk-provider-hyperliquid'

const ws = new PerpsWsClient(client, {
  wsProviders: { hyperliquid: hyperliquidWsProvider() },
})

const unsubscribe = await ws.subscribe(
  { channel: 'orderbook', dex: 'hyperliquid', marketId: 'ETH' },
  (event) => console.log(event.data),
)

同一通道上的多个监听者共享同一条到交易场所的连接，因此按组件分别订阅并不会像你担心的那样造成浪费。

后续步骤

概念

一次交易调用内部发生了什么，以及凭证保存在哪里。

交易场所

各交易场所的设置、存款和提款。

可运行的示例

行情数据、账户数据、代理交易、错误处理和推送数据。

方法参考

每个方法、参数和错误码。

​1. 安装

​2. 创建客户端

​3. 读取行情数据

​4. 完成账户设置

​5. 下单

​6. 推送数据

​后续步骤

概念

交易场所

可运行的示例

方法参考

1. 安装

2. 创建客户端

3. 读取行情数据

4. 完成账户设置

5. 下单

6. 推送数据

后续步骤