SDK 参考

@stablechain/sdk 的完整概览。有关详细介绍，请参阅 SDK 快速入门。

安装

npm install @stablechain/sdk viem

added 2 packages, audited 3 packages in 2s

viem >= 2.0.0 是对等依赖。

`createStable(config)`

构造一个 StableClient。返回一个包含 StableClient 中列出的方法的对象。

import { createStable, Network } from "@stablechain/sdk";
 
const stable = createStable({ network: Network.Mainnet, account });

StableClient { transfer, quoteBridge, bridge, quoteSwap, swap }

`StableConfig`

字段	类型	默认值	描述
`network`	`Network`	`Network.Mainnet`	目标网络。
`rpc`	`string`	`network` 的公共 RPC	RPC 覆盖。
`account`	`viem.Account`		服务器端签名器（例如 `privateKeyToAccount`）。
`transport`	`viem.Transport`		浏览器钱包传输（例如 `custom(window.ethereum)`）。
`walletClient`	`viem.WalletClient`		预构建的钱包客户端。优先于 `account` 和 `transport`。

请提供 account、transport 或 walletClient 中的一个。

`StableClient`

`transfer(params)`

在 Stable 上发送原生 USDT0 或任何 ERC-20。切换钱包到 Stable 链，在缺失时链上获取代币小数位数，并等待回执。

const { txHash } = await stable.transfer({
  from: "0xYourAddress",
  to: "0xRecipient",
  amount: 10,
});

{ txHash: "0x8f3a...2d41" }

参数	类型	描述
`from`	`string`	发送方地址。
`to`	`string`	接收方地址。
`amount`	`number`	人类可读金额。
`token`	`string?`	ERC-20 合约地址。原生 USDT0 则省略。
`tokenDecimals`	`number?`	小数位数。省略时从链上获取。

返回 OperationResult ({ txHash, toAmount? })。

`quoteBridge(params)`

桥接预览。只读。无签名，无 gas。

const quote = await stable.quoteBridge({
  fromChain: Chain.Ethereum,
  toChain: Chain.Stable,
  fromToken: "0x6C96dE32CEa08842dcc4058c14d3aaAD7Fa41dee",
  toToken: "0x779Ded0c9e1022225f8E0630b35a9b54bE713736",
  amount: 100,
});

{ toAmount: 99.94 }

返回 BridgeQuote。

`bridge(params)`

跨链桥接代币。SDK 选择路由：USDT0 → USDT0 使用 LayerZero，其他使用 LI.FI。传入预取的 quote 可跳过内部引用调用。

const { txHash } = await stable.bridge({ ...bridgeParams, quote });

{ txHash: "0xabcd...7890" }

参数	类型	描述
`fromChain`	`Chain`	源链。
`toChain`	`Chain`	目标链。
`fromToken`	`string`	源代币合约地址。
`toToken`	`string`	目标代币合约地址。
`amount`	`number`	人类可读金额。
`fromDecimals`	`number?`	源代币小数位数。默认为 `6`。
`recipient`	`string?`	目标地址。默认为签名者。
`quote`	`BridgeQuote?`	预取的报价。跳过内部报价调用。

`quoteSwap(params)`

获取 Stable 上的 LI.FI 交换报价。返回预构建的交易请求和批准地址。

const quote = await stable.quoteSwap({
  fromToken: "0x8a2B28364102Bea189D99A475C494330Ef2bDD0B",
  toToken: "0x779Ded0c9e1022225f8E0630b35a9b54bE713736",
  amount: 100,
  fromDecimals: 6,
});

{ toAmount: 99.81, fromAmount: 100000000n, fromToken: "0x8a2B...", approvalAddress: "0x...", transactionRequest: { ... } }

`swap(params)`

通过 LI.FI 在 Stable 上交换代币。自动处理 ERC-20 批准，并在需要时切换钱包的链。

const { txHash, toAmount } = await stable.swap({ ...swapParams, quote });

{ txHash: "0xabcd...", toAmount: 99.81 }

参数	类型	默认值	描述
`fromToken`	`string`		源代币地址。
`toToken`	`string`		目标代币地址。
`amount`	`number`		人类可读金额。
`fromDecimals`	`number?`	`6`	源代币小数位数。
`toAddress`	`string?`	signer	接收方地址。
`quote`	`SwapQuote?`		预取的报价。跳过 LI.FI 调用。

枚举

`Network`

值	链 ID
`Network.Mainnet`	988
`Network.Testnet`	2201

`Chain`

由 quoteBridge 和 bridge 使用。每个条目都有相应的 CHAIN_CONFIGS 条目。

枚举	网络	链 ID
`Chain.Sepolia`	Ethereum Sepolia	11155111
`Chain.StableTestnet`	Stable Testnet	2201
`Chain.Stable`	Stable Mainnet	988
`Chain.Ethereum`	Ethereum	1
`Chain.Arbitrum`	Arbitrum One	42161
`Chain.Ink`	Ink	57073
`Chain.Bera`	Berachain	80094
`Chain.MegaETH`	MegaETH	4326
`Chain.Base`	Base	8453
`Chain.BSC`	BNB Smart Chain	56
`Chain.HyperEVM`	HyperEVM	999

`CHAIN_CONFIGS`

由 Chain 枚举键入的 Partial<Record<Chain, ChainConfig>>。每个条目都公开 id、rpc、usdt 和 decimals。当您需要支持链上的规范 USDT 地址而无需硬编码时使用。

import { CHAIN_CONFIGS, Chain } from "@stablechain/sdk";
 
console.log(CHAIN_CONFIGS[Chain.Stable]);

{ id: 988, rpc: "https://rpc.stable.xyz", usdt: "0x779Ded0c9e1022225f8E0630b35a9b54bE713736", decimals: 6 }

错误

所有 SDK 错误都扩展了 StableError，后者又扩展了 viem 的 BaseError。错误携带结构化元数据，因此您可以根据 error.name 或 instanceof 进行分支。

类	抛出条件	有用字段
`StableValidationError`	参数验证失败（地址错误、非有限金额、不支持的链）。	`field`, `value`
`StableQuoteError`	向 LI.FI 发出的报价请求失败。	`provider`, `httpStatus`, `providerCode`, `body`
`StableTransactionError`	链上步骤失败：链切换、批准、发送或回滚。	`phase`, `txHash`, `chainId`, `revertReason`
`StableNetworkError`	底层 HTTP/RPC 调用失败。	`url`

import { StableTransactionError } from "@stablechain/sdk";
 
try {
  await stable.transfer({ from, to, amount: 1 });
} catch (err) {
  if (err instanceof StableTransactionError && err.phase === "switch_chain") {
    // 用户拒绝了链切换
  }
  throw err;
}

StableTransactionError: transfer: wallet rejected or failed to switch to chain 988
  Phase: switch_chain
  Chain ID: 988

建议下一步

SDK 快速入门：安装 SDK 并在测试网上运行您的首次传输。
与 viem 结合使用：在私钥、浏览器钱包和预构建的签名器之间切换。
与 wagmi 结合使用：使用挂钩将 SDK 连接到 React 应用程序。