> ## Documentation Index
> Fetch the complete documentation index at: https://docs.li.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速开始

> 安装 SDK、创建客户端、读取行情数据，并下出你的第一笔订单。

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

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

## 1. 安装

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

```bash theme={"system"}
npm install @lifi/perps-sdk @lifi/perps-sdk-provider-hyperliquid
```

## 2. 创建客户端

```typescript theme={"system"}
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](https://portal.li.fi/)。注册一个 provider 会将该交易场所的读取接口绑定到客户端，之后你可以通过键名查找它。

有一个选项值得提前了解：`retry` 用于控制 HTTP 重试行为，可以为所有交易场所设置统一策略，也可以按交易场所分别设置。

这个 `client` 是行情数据和账户查询所使用的读取接口。设置和交易请改用 `PerpsClient`——一个构建在其之上的独立类，参见第 4 步。在那里，用户的钱包是通过 `setUserWallet` 提供的，而不是作为构造函数选项，因为它可以在客户端创建之后再设置或更换。

## 3. 读取行情数据

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

```typescript theme={"system"}
import { getMarkets } from '@lifi/perps-sdk'

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

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

## 4. 完成账户设置

交易前需要针对每个用户、每个交易场所完成一次性设置。具体内容因交易场所而异，SDK 会替你统一协调，而不需要你为每种方案分别编写脚本。

在调用之前先给 `PerpsClient` 传入用户的钱包，因为设置阶段正是首次需要捕获用户签名的地方。

```typescript theme={"system"}
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. 下单

```typescript theme={"system"}
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` 用于原地修改订单而无需先取消再重新下单。

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

## 6. 推送数据

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

```typescript theme={"system"}
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),
)
```

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

## 后续步骤

<CardGroup cols={2}>
  <Card title="概念" icon="diagram-project" href="/perps/concepts" horizontal>
    一次交易调用内部发生了什么，以及凭证保存在哪里。
  </Card>

  <Card title="交易场所" icon="building-columns" href="/perps/venues" horizontal>
    各交易场所的设置、存款和提款。
  </Card>

  <Card title="可运行的示例" icon="code" href="https://github.com/lifinance/perps-sdk/tree/main/examples" horizontal>
    行情数据、账户数据、代理交易、错误处理和推送数据。
  </Card>

  <Card title="方法参考" icon="book" href="https://public-perps-docs.mintlify.app/" horizontal>
    每个方法、参数和错误码。
  </Card>
</CardGroup>