# 0xtrails 中文文档

规范地址：https://npmcn.com/package/0xtrails/

版本：0\.20\.0
npm 元数据更新时间：2026-10-22T15:27:29.568Z
中文译文更新时间：2026-11-06T00:19:43.364Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/0xtrails
原文对照：https://npmcn.com/package/0xtrails/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：6.3 MB，32 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：14 个
- peer 依赖：viem ^2\.56\.7，react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，@tanstack/react-query ^5\.101\.0
- 首次发布：2025-07-14T17:54:55.277Z
- 最新版本发布：2026-10-22T15:27:29.379Z
- 近 30 天下载量：8234（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：99（近 12 个月 68 个）

## 中文简介

拖车的 SDK

## 安装

```sh
npm install 0xtrails
```

也可以使用：`pnpm add 0xtrails`、`yarn add 0xtrails`、`bun add 0xtrails`

## README

# 0x拖车

在 React apps中嵌入部件并调用拖车钩的Trails SDK.

## 安装

```bash
npm install 0xtrails @tanstack/react-query viem
```

如果您想要拖车使用您现有的 wagmi 设置, 请同时安装 `@0xtrails/adapter-wagmi` 财务报告和审定财务报表 `wagmi`。 。 。 .

## 独立部件

仅供部件使用, `TrailsWidget` 无需 `QueryClientProvider` 或者说 `TrailsProvider`。 。 。 .

```tsx
import { TrailsWidget } from '0xtrails'

const apiKey = 'YOUR_TRAILS_API_KEY'

export function App() {
  return <TrailsWidget apiKey={apiKey} renderInline />
}
```

当没有父钱包上下文和没有时 `adapters`,部件使用其内置的 EVM 运行时间.

## 钩子 `TrailsProvider`

使用 `TrailsProvider` 当你想直接拨打拖车钩时.

```tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { TrailsProvider, useAccountTotalBalanceUsd } from '0xtrails'

const apiKey = 'YOUR_TRAILS_API_KEY'
const queryClient = new QueryClient()

function BalancePreview() {
  const address = '0x0000000000000000000000000000000000000000'
  const totalBalance = useAccountTotalBalanceUsd(address)

  return <pre>{JSON.stringify(totalBalance.data, null, 2)}</pre>
}

export function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <TrailsProvider config={{ trailsApiKey: apiKey }}>
        <BalancePreview />
      </TrailsProvider>
    </QueryClientProvider>
  )
}
```

### 钩子

虎克是用于定制的UI. 将您的应用程序与您已有的 wagmi 和 React 查询提供者包装, 然后添加 `TrailsProvider`。 。 。 .

```tsx
import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
import { WagmiProvider } from "wagmi"
import { TrailsProvider } from "0xtrails"
import { wagmiConfig } from "./wagmi"

const queryClient = new QueryClient()

export function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <TrailsProvider config={{ trailsApiKey: "<YOUR_TRAILS_API_KEY>" }}>
          <YourRoutes />
        </TrailsProvider>
      </QueryClientProvider>
    </WagmiProvider>
  )
}
```

## 部件模式

从 `0xtrails/widget`。 。 。 .

### 支付

使用 `Pay` 当你的应用程序知道 准确的接收者, 目的地标志, 链, 和数量.

```tsx
import { Pay } from "0xtrails/widget"

export function PayInvoice() {
  return (
    <Pay
      apiKey="<YOUR_TRAILS_API_KEY>"
      to={{
        recipient: "0xMerchantAddress",
        chain: "base",
        token: "USDC",
        amount: "49.99",
      }}
      from={{ chain: "arbitrum", token: "ETH" }}
      paymentMethod="CONNECTED_WALLET"
      payMessage="Invoice #INV-1001"
      buttonText="Pay now"
    />
  )
}
```

### 基金

使用 `Fund` 允许用户在钱包或目的账户中添加资金。 您可以允许不同的支付方法, 使用连接的钱包, qr 代码传输, 交换, 或在斜坡上 fiat .

用户在部件 UI 中选择支付方法

```tsx
import { Fund } from "0xtrails/widget"

export function FundWallet() {
  return (
    <Fund
      apiKey="<YOUR_TRAILS_API_KEY>"
      to={{
        recipient: "0xUserWallet",
        chain: "base",
        token: "USDC",
      }}
      onFundingSuccess={(data) => console.log("Funded", data.sessionId)}
    />
  )
}
```

主机应用预选支付款Method为信用卡,以100美元进行融资加密.

```tsx
import { Fund } from "0xtrails/widget"

export function FundWallet() {
  return (
    <Fund
      apiKey="<YOUR_TRAILS_API_KEY>"
      paymentMethod="CREDIT_DEBIT_CARD"
      from={{
        currency="USD",
        amount="100"
      }}
      to={{
        recipient: "0xUserWallet",
        chain: "base",
        token: "USDC",
      }}
      onFundingSuccess={(data) => console.log("Funded", data.sessionId)}
    />
  )
}
```

### 交换

使用 `Swap` 同链和跨链的代币互换.

```tsx
import { Swap } from "0xtrails/widget"

export function SwapToBaseUsdc() {
  return (
    <Swap
      apiKey="<YOUR_TRAILS_API_KEY>"
      onSwapSuccess={(data) => console.log("Swap complete", data.sessionId)}
    />
  )
}
```

### 赚

使用 `Earn` 内置的UI跨链体验,以赚取收益.

```tsx
import { Earn } from "0xtrails/widget"

export function EarnUsdc() {
  return (
    <Earn
      apiKey="<YOUR_TRAILS_API_KEY>"
      buttonText="Deposit into a protocol"
      onEarnSuccess={(data) => console.log("Earn deposit", data.sessionId)}
    />
  )
}
```

### 撤销

使用 `Withdraw` 用于加密提取流量。 让用户退出,并将其资产交换给任何链条上的任何令牌.

```tsx
import { Withdraw } from "0xtrails/widget"

export function WithdrawToBase() {
  return (
    <Withdraw
      apiKey="<YOUR_TRAILS_API_KEY>"
      onWithdrawSuccess={(data) => console.log("Withdrawn", data.sessionId)}
    />
  )
}
```

### 自定义标签

每个模式都接受 `labels` 重命名部件本身副本的对象。 每个 字段是可选的,并倒回内置字符串,这样您就可以覆盖 一个字或四个都行 空白字符串计算为没有覆盖 字段直接输入文字输入,在清除框时做正确的事情。 例如,捐款流动是基金模式,用于: 资金词汇交换:

```tsx
import { Fund } from "0xtrails/widget"

export function Donate() {
  return (
    <Fund
      apiKey="<YOUR_TRAILS_API_KEY>"
      to={{ recipient: "0xReliefFund", chain: "polygon", token: "USDC" }}
      labels={{
        confirmButton: "Donate",
        formTitle: "Donate",
        methodsTitle: "Choose a donation method",
        tokensTitle: "Donate with any token",
      }}
    />
  )
}
```

| 外地 | 重命名 | 默认 |
| --- | --- | --- |
| `confirmButton` | 主窗体按钮 | `"Fund"`, (中文(简体) ), `"Pay"`, (中文(简体) ), `"Swap"`, (中文(简体) ), `"Deposit"`, (中文(简体) ), `"Withdraw"`,按模式 |
| `formTitle` | 金额屏幕的标题, 以及继续它的加密传输屏幕 | `"Fund"`, (中文(简体) ), `"Pay"`, (中文(简体) ), `"Swap"`, (中文(简体) ), `"Withdraw"`, (中文(简体) ), `"Earn"` 按模式; `"Deposit"` 在传输屏幕上 |
| `methodsTitle` | 支付方法的取名 | `"Choose a funding method"`, (中文(简体) ), `"Choose a payment method"` 报酬和报酬, `"Payment methods"` 在工资流的 自己拾取器 |
| `tokensTitle` | 每个"用这个付费"的代号列表的标题 | 按模式和屏幕排列的变数—— `"Fund with any token"`, (中文(简体) ), `"Select From Token"`, (中文(简体) ), `"Select Token to Withdraw"`,, , , , , , , , |

`formTitle` 刻意跟踪用户进入加密传输屏幕( QR代码和存款地址步骤,所以捐款流总是说"捐赠" 而不是在中途切换到“ 保存” 。 刷卡显示屏是 独自一人——他们向第三方交接,通过设计阅读.

`tokensTitle` 仅覆盖采源者。 取地者("收取","收取","收取","收取","收取","收取","收取","收取","收取","收取","收取","收取","收取","收","收","收","收","收","收","收","收"等","收"等, "选择目的地令牌")保留自己的标题,因为令牌使用者 发送和收件人得到的信号是不同的问题.

有两件事情是故意的:

-   **即时按钮状态.** "输入一个数量","得到引用...","连接" 您的钱包和“ 不足余额” 报告部件正在做什么, 不是 按钮是做什么的,所以他们保留自己的副本.
-   **从另一个模式借来的屏幕 .** 覆盖仅适用于 配置模式 。 从基金部件头部和按钮打开交换标签 仍然说"扫地"——一个"捐赠"的标签会出现错误.

对于模式触发按钮, `buttonText` 仍然胜过 `labels.confirmButton`。 。 。 .

### 同意复选框

`consentCheckbox` 将同意线直接放在主按钮上方,并加一个 链接用户可以在他们承诺之前打开。 设置道具是使 勾选为强制性——没有单独的旗帜,因为可选同意 复选框不是别人想要的.

```tsx
import { Fund } from "0xtrails/widget"

export function DonateWithTerms() {
  return (
    <Fund
      apiKey="<YOUR_TRAILS_API_KEY>"
      to={{ recipient: "0xReliefFund", chain: "polygon", token: "USDC" }}
      labels={{ confirmButton: "Donate" }}
      consentCheckbox={{
        label:
          "I've read and agree to the " +
          '<a href="https://example.org/terms">Terms &amp; Conditions</a>',
        requiredMessage: "Please accept the Terms & Conditions to donate.",
      }}
    />
  )
}
```

| 外地 | 目的 | 默认 |
| --- | --- | --- |
| `label` | 同意行, 如内置 HTML 。 要求. | —— 说 |
| `requiredMessage` | 新闻界就一个无线盒子提出的长期通知 | 无——见下文 |

> **一个空白 `label` 取出出出门.** 设置道具是什么使勾选 强制,所以只使用白空间标签意味着没有复选框使 _编辑 确认按钮没有门_ ——流动始终在同意步骤下发挥作用 默然去来. 这是刻意的(没有什么可以解释的) 绑定时无法查看模式 `label` 到 CMS 字段或 i18n 键 可能不会解决。 SDK一旦发生就会记录一个警告.

**按钮保持活性.** 当盒子解开时,确认按钮会保留 正常的外形,所以一个已准备好的引文 仍然可以读到。 按着它 不提交:行会摇动,会起子,焦点会移动到复选框.

**`requiredMessage` 决定一个失败的媒体留下什么.** 设置它和 信件站在复选框下直到选中该框, 所以一个用户错过了 摇动在屏幕上还有原因 放下它,摇摆和锡是 整个反应——轻而易举,它永远不会改变休息布局,但一秒钟 媒体教的是什么 第一个没有。 无论哪种方式, 失败的媒体移动 聚焦到复选框中,因此辅助技术宣布了未锁定的控制.

**`label` 已经消毒.** 它是作为 HTML 提供的一种道具,对一固定 允许列表 :

-   保留 : `a`, (中文(简体) ), `b`, (中文(简体) ), `strong`, (中文(简体) ), `i`, (中文(简体) ), `em`, (中文(简体) ), `span`, (中文(简体) ), `br`。所有其它标记被丢弃 而不是逃脱,所以一个不支持的标记会变成干净的文本.
-   每个属性都被剥去. 一个锚保持它的 `href` 如果那个赫雷夫 决定: `http(s)` 或者说 `mailto` 包括亲属(`/terms`和 协议关系(`//host/path`表格,按书面形式公布。 任何东西 其他(无)`javascript:`, (中文(简体) ), `data:`) 被打开为纯文本,所以没有惰性 看起来可以点击.
-   幸存锚重写为 `target="_blank" rel="noopener noreferrer"`,因此读取术语从来不会让用户花费填充的引文.

此允许列表保留了标签, 避免断开部件或插入元素 . 没错 **没有** 您从其它地方插入的 URL 验证符 — 如果 红外线来自 CMS 、 查询字符串或用户输入, 你自己检查 在它来之前.

打开链接从不勾选盒子——两者是故意分开的行为. 如果您希望链接打开自己的页面模式, 请添加授权 点击听众并拨打 `preventDefault()`;部件在阴影内 根,但是它的事件是由组成的,所以 `composedPath()` 见起锚.

**同意是每届会议的,而且从未坚持过.** 重新装入又问,即 是什么使滴滴的证据 同意而不是被记住的偏好.

喜欢 `labels`,复选框属于已配置模式的屏幕。 打开 从基金部件头部取出互换标签, 它没有遵循 .

## `useQuote`

`useQuote` 给你一个引用和一个可执行文件 `send` 函数用于完全自定义 UI 。 应提供一笔金额: `from.amount` 或者说 `from.amountRaw` 准确输入,或 `to.amount` 或者说 `to.amountRaw` 准确的输出。 您可以使用“ 收费选项” 来允许在稳定币中支付气体 .

```tsx
import { useQuote, QuoteError } from "0xtrails"
import { useAccount, useWalletClient } from "wagmi"

export function CustomSwap() {
  const { address } = useAccount()
  const { data: walletClient } = useWalletClient()

  const {
    quote,
    send,
    isLoadingQuote,
    quoteError,
    quoteErrorPrettified,
    feeOptions,
    refetchQuote,
    abort,
  } = useQuote({
    from: {
      chain: "base",
      token: "USDC",
      amount: "10",
    },
    to: {
      chain: "arbitrum",
      token: "ETH",
      recipient: address,
    },
    onStatusUpdate: (states) => console.log("status", states),
  })

  if (quoteError instanceof QuoteError) {
    console.log("Quote failed with code", quoteError.code)
  }

  return (
    <section>
      {isLoadingQuote && <p>Loading quote...</p>}
      {quoteErrorPrettified && <p>{quoteErrorPrettified}</p>}

      {quote && (
        <>
          <p>
            Spend {quote.originAmountDisplay} for{" "}
            {quote.destinationAmountDisplay}
          </p>
          <p>Estimated time: {quote.completionEstimateDisplay}</p>
          <p>Fee options: {feeOptions.length}</p>
        </>
      )}

      <button disabled={!send} onClick={() => send?.()}>
        Send
      </button>
      <button onClick={() => refetchQuote()}>Refresh</button>
      <button onClick={() => abort()}>Abort</button>
    </section>
  )
}
```

预览引用时, 不需要连接的钱包, 即可通过 `walletAddress`。 。 。 .

## `useTrailsSendTransaction`

`useTrailsSendTransaction` 是一个目的地第一交易钩 与有轨电车路线。 镜子 `useQuote`是因为 `from`编号 :`to` 形状和可以打开 Trails 部件模式,当用户需要选择原产地链、令牌或数量,所以不需要构建此步骤.

渲染器 `TrailsHookModal` 一次进去 `TrailsProvider` 所以模式驱动的发送 有地方上载.

说明收款人应通过下列方式得到什么: `to` 并让用户选择如何支付。 设定 `to.amount` 用于精确输出发送(该模式仅需要源代码选择).

```tsx
import { useTrailsSendTransaction } from "0xtrails"

export function RequestUsdcPayment() {
  const { sendTransaction, isPending } = useTrailsSendTransaction({
    receiptActionButtonText: "Back to app",
  })

  return (
    <>
      <button
        disabled={isPending}
        onClick={() =>
          sendTransaction({
            to: {
              chain: "polygon",
              token: "USDC", // or a contract address
              recipient: "0xMerchantAddress",
              amount: "25",
            },
          })
        }
      >
        Pay 25 USDC
      </button>
    </>
  )
}
```

提供 `from` (单位:千美元)`{ chain, token, amount }`当您的应用程序已经知道要跳过模式的来源资产时 。 使用 `from.amountRaw`编号 :`to.amountRaw` 当您已经拥有最小单位金额时.

## 可编译动作

可编译的行动描述了资金到达目的地后应当发生的情况。 由SDK解决进入目的地的电话,可以从两者中调用 `useQuote` 财务报告和审定财务报表 `useTrailsSendTransaction`。 。 。 .

现有的行动构建者包括:

-   `swap` 交换目的地链.
-   `lend` 财务报告和审定财务报表 `deposit` 支持创收市场.
-   `custom` 让你自己行动起来.
-   `assertCondition` 用于运行时间检查.
-   `dynamic()` 以在未知值时使用意图钱包的运行时余额.

### 引用和执行动作

```tsx
import {
  assertCondition,
  dynamic,
  lend,
  swap,
  useQuote,
} from "0xtrails"
import { useAccount, useWalletClient } from "wagmi"

export function QuoteActions() {
  const { address } = useAccount()
  const { data: walletClient } = useWalletClient()

  const actions = [
    // Check if we received enough USDC on the destination chain
    assertCondition({
      erc20Balance: { token: "USDC", gte: "100" },
    }),
    // Swap 100 USDC in WETH (defaults to Uniswap V3)
    swap({
      tokenIn: "USDC",
      tokenOut: "WETH",
      amountIn: "100",
      fee: "0.05"
    }),
    // Lend all WETH received from the swap 
    lend({
      marketId: "base-weth-aave-v3-lending",
      amount: dynamic(),
      receiverAddress: address,
    }),
  ]

  const { quote, send, isLoadingQuote } = useQuote({
    from: { chain: "base", token: "USDC" },
    to: { chain: "base", token: "USDC", amount: "100" },
    actions,
  })

  return (
    <button disabled={!send || isLoadingQuote} onClick={() => send?.()}>
      {quote ? "Execute recipe" : "Get quote"}
    </button>
  )
}
```

`actions` 两者相互排斥 `to.calls` 和已贬值 `to.calldata`。 。 。 .

### 执行使用部件 Modal 的动作

```tsx
import { dynamic, erc20Utils, lend, swap, useTrailsSendTransaction } from "0xtrails"

export function WidgetActionRecipe({ userAddress }: { userAddress: `0x${string}` }) {
  const actions = [
    swap({
      tokenIn: "USDC",
      tokenOut: "USDT",
      amountIn: dynamic(),
      fee: "0.05",
    }),
    lend({
      marketId: "polygon-usdt-fluid-lending",
      amount: dynamic(),
      receiverAddress: userAddress,
    }),
  ]

  const { sendTransaction, isPending } = useTrailsSendTransaction({
    actions,
    receiptActionButtonText: "Done",
  })

  return (
    <>
      <button
        disabled={isPending}
        onClick={() =>
          sendTransaction({
            to: {
              chain: "polygon",
              token: erc20Utils.USDC.addressOn("polygon"),
              recipient: userAddress,
              amount: "50"
            },
          })
        }
      >
        Choose payment token
      </button>
    </>
  )
}
```

### 原始目标呼叫

使用 `to.calls` 当您需要低级别ABI编码的呼叫而不是动作构建器时.

```tsx
import { buildApproveAndCall, buildCall, erc20Utils, useQuote } from "0xtrails"
import { useAccount } from "wagmi"
import { stakingAbi } from "./stakingAbi"

export function RawCallsQuote() {
  const { address } = useAccount()

  const stakingCall = buildCall({
    to: "0xStakingContract",
    data: {
      abi: stakingAbi,
      functionName: "stake",
      args: [1_000_000n],
    },
  })

  const calls = buildApproveAndCall({
    token: erc20Utils.USDC.addressOn("base"),
    call: stakingCall,
  })

  const { quote, send } = useQuote({
    from: { chain: "base", token: "USDC" },
    to: {
      chain: "base",
      token: "USDC",
      amount: "1",
      calls,
    },
  })

  return (
    <button disabled={!send} onClick={() => send?.()}>
      {quote ? "Stake USDC" : "Loading quote"}
    </button>
  )
}
```

## 公用事业

共同出口 `0xtrails`数字 :

-   `getSupportedChains`, (中文(简体) ), `useSupportedChains`,以及 `resolveChainId`。 。 。 .
-   `getChainInfo`, (中文(简体) ), `getAllChains`,以及 `attemptSwitchChain`。 。 。 .
-   `useTokenList`, (中文(简体) ), `useSupportedTokens`, (中文(简体) ), `useTokenBalances`, (中文(简体) ), `useTokenBalancesForMultipleAccounts`, (中文(简体) ), `useAccountTotalBalanceUsd`, (中文(简体) ), `useHasSufficientBalanceToken`,以及 `useHasSufficientBalanceUsd`。 。 。 .
-   `getTokenPrice`, (中文(简体) ), `getTokenPrices`, (中文(简体) ), `useTokenPrice`, (中文(简体) ), `useTokenPrices`
-   `erc20Utils`, (中文(简体) ), `buildCall`, (中文(简体) ), `buildApproveAndCall`, (中文(简体) ), `buildErc20Approve`,以及 `getAmountWithSlippage` 对于符号元数据,ERC-20调用,批准,以及自定义调用数据.
-   `uniswapV3` 财务报告和审定财务报表 `sushiswapV3` 用于自定义 Uniswap V3 / SushiSwap V3 池的查询、引用和交换呼叫构建.
-   `useEarnProviders`, (中文(简体) ), `useEarnMarkets`, (中文(简体) ), `useEarnBalances`, (中文(简体) ), `getEarnProviders`, (中文(简体) ), `getEarnMarkets`,以及 `getEarnBalances`。 。 。 .
-   `useResolveActions`, (中文(简体) ), `encodeDestinationForIntentProtocol`, (中文(简体) ), `createHydratePayload`,以及 `encodeMulticallHydrateExecute` 用于高级目的地呼叫和水合物流动.
-   `prepareSend`, (中文(简体) ), `commitIntent`, (中文(简体) ), `quoteIntent`, (中文(简体) ), `sendOriginTransaction`, (中文(简体) ), `getIntent`, (中文(简体) ), `useGetIntent`, (中文(简体) ), `pollIntentReceipt`,以及 `useIntentReceiptMonitor`。 。 。 .
-   `getAccountTransactionHistory`, (中文(简体) ), `useAccountTransactionHistory`, (中文(简体) ), `useIntentTransactionHistory`,以及 `getTxTimeDiff`。 。 。 .
-   `useFiatCurrencyList`, (中文(简体) ), `useExchangeRate`, (中文(简体) ), `getCurrencyInfo`
-   `getTrailsClient`, (中文(简体) ), `useTrailsClient`, (中文(简体) ), `TrailsClient`
-   `useIntentRecover`, (中文(简体) ), `useIntentRecoverWithAddress`, (中文(简体) ), `buildRefundTransactionWithSignature`,以及 `signPayload`。 。 。 .

`TrailsProvider` 默认情况下挂载内置钱包运行时间。 添加 `config.adapters` 当拖车使用明确的钱包运行时间适配器时.

## 使用带有 wagmi 的拖车

如果您的应用程序已经使用 wagmi, 请添加 `@0xtrails/adapter-wagmi` 这样拖车就可以分享你的钱包设置. Wagmi 3是首要的集成目标;wagmi 2仍然通过相同的适配器对等范围支持.

更多选项和wagmi 2/3 例见 `packages/wallet/adapters/wagmi/README.md`, (中文(简体) ), `apps/examples/wagmi3`,以及 `apps/examples/wagmi2`。 。 。 .

```tsx
import { TrailsProvider, TrailsWidget } from '0xtrails'
import { wagmiAdapter } from '@0xtrails/adapter-wagmi'
import { WagmiProvider } from 'wagmi'

const apiKey = 'YOUR_TRAILS_API_KEY'
// Create wagmiConfig with your chains, transports, and connectors.
const adapters = [wagmiAdapter({ wagmiConfig })]

export function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <TrailsProvider config={{ trailsApiKey: apiKey, adapters }}>
        <TrailsWidget renderInline />
      </TrailsProvider>
    </WagmiProvider>
  )
}
```

用同样的 `wagmiConfig` 例如,两者均 `WagmiProvider` 财务报告和审定财务报表 `wagmiAdapter(...)` 当有轨电车在主机的 wagmi 运行时间中连接。 如果周围没有匹配 `WagmiProvider`,适配器用提供的配置来挂载自己的运行时间.

## 运行时间所有权

适配器运行时间选择和生命周期所有权是分开的:

-   wagmi 运行时间选择基于 `wagmiConfig` 身份
    -   与周围的配置实例相同 `WagmiProvider` \* 连接主机运行时间
    -   没有匹配周围提供者 ~ 挂载适配器自有的运行时间
-   `managedBy` 用于复合适配器列表,控制有轨电车的生命周期所有权
    -   `managedBy: 'host'` 意味着拖车可以使用钱包, 但不应该拥有像断开这样的主机生命周期动作
    -   `managedBy: 'trails'` 指有轨电车拥有适配器的钱包生命周期

```tsx
const adapters = [
  { adapter: wagmiAdapter({ wagmiConfig: hostWagmiConfig }), managedBy: 'host' },
  { adapter: wagmiAdapter({ wagmiConfig: trailsWagmiConfig }), managedBy: 'trails' },
]
```

## 发展

从原始 SVG 文件夹中复制部件 SVG 组件 `pnpm --dir packages/0xtrails icons:generate <source-dir>`。 。 。 .

## 规则

-   `wagmi` wagmi 3是首要目标, wagmi 2 仍然支持兼容性
-   钩子需要两个 `QueryClientProvider` 财务报告和审定财务报表 `TrailsProvider`
-   `adapters` 还能活下去 `TrailsProvider config.adapters` 或者说 `TrailsWidget adapters`
-   不同时在两地提供适配器
-   `TrailsWidget adapters` 无法在现有父钱包上下文中使用, 包括默认运行时间 `TrailsProvider`

## 使用带索拉纳的拖车

安装 `@0xtrails/svm` ——用户从索拉纳钱包和任何EVM链的支付地获得资金.

```bash
npm install @0xtrails/svm
```

过 `svmAdapter` 与您的 EVM 适配器。 没有 `wallet` 选项,它自动检测钱包标准索拉纳钱包,如幽灵和索尔夫拉尔:

```tsx
import { TrailsWidget, evmAdapter } from '0xtrails'
import { svmAdapter } from '@0xtrails/svm'

const adapters = [
  evmAdapter({ wallets: [{ id: 'injected', name: 'MetaMask' }] }),
  svmAdapter({ rpcUrls: ['https://api.mainnet-beta.solana.com'] }),
]

export function App() {
  return (
    <TrailsWidget
      apiKey="YOUR_TRAILS_API_KEY"
      adapters={adapters}
      fundOptions={{ fundMethodsList: ['connected-wallet'] }}
      renderInline
    />
  )
}
```

在配置索拉纳适配器时,可通过连接-Wallet供资路径获得索拉纳资金。 支持的原产地代币有SOL、USDC、USDT和PYUSD等.

### 和华克米

组合 `wagmiAdapter` 财务报告和审定财务报表 `svmAdapter` 当您的应用程序同时使用 EVM 和 Solana 钱包时 :

```tsx
import { wagmiAdapter } from '@0xtrails/adapter-wagmi'
import { svmAdapter } from '@0xtrails/svm'

const adapters = [
  wagmiAdapter({ wagmiConfig }),
  svmAdapter({ rpcUrls: ['https://api.mainnet-beta.solana.com'] }),
]
```

更多选项和实例见 `packages/0xtrails-svm/README.md`。 。 。 .

## 许可证

阿帕奇 - 2.0

## 常见问题

### 0xtrails 是什么？

拖车的 SDK

### 如何安装 0xtrails？

在项目目录运行 npm install 0xtrails，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：viem（^2\.56\.7）、react（^18\.0\.0 \|\| ^19\.0\.0）、react-dom（^18\.0\.0 \|\| ^19\.0\.0）、@tanstack/react-query（^5\.101\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### 0xtrails 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### 0xtrails 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### 0xtrails 可以商用吗？

0xtrails 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### 0xtrails 的下载量有多少？

根据 npm 官方下载统计，0xtrails 在 2026/10/04 – 2026/11/02 这 30 天内被下载 8,234 次，日均约 274 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### 0xtrails 还在维护吗？

最新版本 0\.20\.0 发布于 2026/10/22（16 天前）；至今共发布 99 个版本，其中过去 12 个月发布了 68 个；首次发布于 2025/07/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。