# @1inch/cross-chain-sdk 中文文档

规范地址：https://npmcn.com/package/%401inch/cross-chain-sdk/

版本：2\.2\.4
npm 元数据更新时间：2026-10-09T15:43:12.906Z
中文译文更新时间：2026-11-05T18:59:42.544Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%401inch/cross-chain-sdk
原文对照：https://npmcn.com/package/%401inch/cross-chain-sdk/?lang=original
项目主页：https://github.com/1inch/cross-chain-sdk#readme
源码仓库：https://github.com/1inch/cross-chain-sdk

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

- 包体积（解压后）：2 MB，726 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.16\.0
- 运行依赖：13 个
- peer 依赖：assert ^2\.0\.0
- 首次发布：2024-09-21T09:29:46.722Z
- 最新版本发布：2026-09-11T13:19:54.766Z
- 近 30 天下载量：49449（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：125（近 12 个月 36 个）

## 中文简介

通过 1英寸 创建原子交换的 Sdk

## 安装

```sh
npm install @1inch/cross-chain-sdk
```

也可以使用：`pnpm add @1inch/cross-chain-sdk`、`yarn add @1inch/cross-chain-sdk`、`bun add @1inch/cross-chain-sdk`

## README

# 跨链 SDK

通过 1英寸 创建原子交换的 Sdk

## 资源

-   [Dev 门户网站](https://portal.1inch.dev/documentation/apis/swap/fusion-plus/introduction)

## 文档

-   [网络安全套](https://github.com/1inch/cross-chain-sdk/tree/master/src/ws-api)
-   [v2.0 移徙指南](https://npmcn.com/package/%401inch/cross-chain-sdk/docs/v2-migration-guide.md)

# 安装

`npm install @1inch/cross-chain-sdk`

# 设置

```typescript
const privateKey =  '0x'
const rpc = 'https://ethereum-rpc.publicnode.com'
const authKey = 'auth-key'
const source = 'sdk-tutorial'

const web3 = new Web3(rpc)
const walletAddress = web3.eth.accounts.privateKeyToAccount(privateKey).address

const sdk = new SDK({
    url: 'https://api.1inch.com/fusion-plus',
    authKey,
    blockchainProvider: new PrivateKeyProviderConnector(privateKey, web3) // only required for order creation
})
```

# 顺序创建

要创建命令,钱包必须有足够的备忘 `srcTokenAddress` 页:1 `Limit Order Protocol` 源链

```typescript
// 10 USDT (Polygon) -> BNB (BSC)

// estimate
const quote = await sdk.getQuote({
    amount: '10000000',
    srcChainId: NetworkEnum.POLYGON,
    dstChainId: NetworkEnum.BINANCE,
    enableEstimate: true,
    srcTokenAddress: '0xc2132d05d31c914a87c6611c10748aeb04b58e8f', // USDT
    dstTokenAddress: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee', // BNB
    walletAddress
})

const preset = PresetEnum.fast

// generate secrets
const secrets = Array.from({
    length: quote.presets[preset].secretsCount
}).map(() => '0x' + randomBytes(32).toString('hex'))

const hashLock =
    secrets.length === 1
        ? HashLock.forSingleFill(secrets[0])
        : HashLock.forMultipleFills(HashLock.getMerkleLeaves(secrets))

const secretHashes = secrets.map((s) => HashLock.hashSecret(s))

// create order
const {hash, quoteId, order} = await sdk.createOrder(quote, {
    walletAddress,
    hashLock,
    preset,
    source,
    secretHashes
})
console.log({hash}, 'order created')
```

# 提交顺序

```typescript
// submit order
const _orderInfo = await sdk.submitOrder(
    quote.srcChainId,
    order,
    quoteId,
    secretHashes
)
console.log({hash}, 'order submitted')
```

# 秘密提交书

解析器每次部署源和目的地代管时 - 用户必须提交适当的秘密,因此解析器可以完成互换

```typescript
 // submit secrets for deployed escrows
while (true) {
    const secretsToShare = await sdk.getReadyToAcceptSecretFills(hash)

    if (secretsToShare.fills.length) {
        for (const {idx} of secretsToShare.fills) {
            await sdk.submitSecret(hash, secrets[idx])

            console.log({idx}, 'shared secret')
        }
    }

    // check if order finished
    const {status} = await sdk.getOrderStatus(hash)

    if (
        status === OrderStatus.Executed ||
        status === OrderStatus.Expired ||
        status === OrderStatus.Refunded
    ) {
        break
    }

    await sleep(1000)
}

const statusResponse = await sdk.getOrderStatus(hash)

console.log(statusResponse)
```

# 完整实例

```typescript
import {
    HashLock,
    NetworkEnum,
    OrderStatus,
    PresetEnum,
    PrivateKeyProviderConnector,
    SDK
} from '@1inch/cross-chain-sdk'
import Web3 from 'web3'
import {randomBytes} from 'node:crypto'

const privateKey =  '0x'
const rpc = 'https://ethereum-rpc.publicnode.com'
const authKey = 'auth-key'
const source = 'sdk-tutorial'

const web3 = new Web3(rpc)
const walletAddress = web3.eth.accounts.privateKeyToAccount(privateKey).address

const sdk = new SDK({
    url: 'https://api.1inch.com/fusion-plus',
    authKey,
    blockchainProvider: new PrivateKeyProviderConnector(privateKey, web3) // only required for order creation
})

async function sleep(ms: number): Promise<void> {
    return new Promise((resolve) => setTimeout(resolve, ms))
}

async function main(): Promise<void> {
    // 10 USDT (Polygon) -> BNB (BSC)

    // estimate
    const quote = await sdk.getQuote({
        amount: '10000000',
        srcChainId: NetworkEnum.POLYGON,
        dstChainId: NetworkEnum.BINANCE,
        enableEstimate: true,
        srcTokenAddress: '0xc2132d05d31c914a87c6611c10748aeb04b58e8f', // USDT
        dstTokenAddress: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee', // BNB
        walletAddress
    })

    const preset = PresetEnum.fast

    // generate secrets
    const secrets = Array.from({
        length: quote.presets[preset].secretsCount
    }).map(() => '0x' + randomBytes(32).toString('hex'))

    const hashLock =
        secrets.length === 1
            ? HashLock.forSingleFill(secrets[0])
            : HashLock.forMultipleFills(HashLock.getMerkleLeaves(secrets))

    const secretHashes = secrets.map((s) => HashLock.hashSecret(s))

    // create order
    const {hash, quoteId, order} = await sdk.createOrder(quote, {
        walletAddress,
        hashLock,
        preset,
        source,
        secretHashes
    })
    console.log({hash}, 'order created')

    // submit order
    const _orderInfo = await sdk.submitOrder(
        quote.srcChainId,
        order,
        quoteId,
        secretHashes
    )
    console.log({hash}, 'order submitted')

    // submit secrets for deployed escrows
    while (true) {
        const secretsToShare = await sdk.getReadyToAcceptSecretFills(hash)

        if (secretsToShare.fills.length) {
            for (const {idx} of secretsToShare.fills) {

                // it is responsibility of the client to check whether is safe to share secret (check escrow addresses and so on)
                await sdk.submitSecret(hash, secrets[idx])

                console.log({idx}, 'shared secret')
            }
        }

        // check if order finished
        const {status} = await sdk.getOrderStatus(hash)

        if (
            status === OrderStatus.Executed ||
            status === OrderStatus.Expired ||
            status === OrderStatus.Refunded
        ) {
            break
        }

        await sleep(1000)
    }

    const statusResponse = await sdk.getOrderStatus(hash)

    console.log(statusResponse)
}

main()
```

## 收费合并费

以综合者身份收费,通过 `integratorFee` 字段改为 `sdk.getQuote`。收费在基点(1% = 100 bps)中规定,需要有一个接收地址来收取收费.

```diff
const quote = await sdk.getQuote({
    amount: '10000000',
    srcChainId: NetworkEnum.POLYGON,
    dstChainId: NetworkEnum.BINANCE,
    enableEstimate: true,
    srcTokenAddress: '0xc2132d05d31c914a87c6611c10748aeb04b58e8f', // USDT
    dstTokenAddress: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee', // BNB
    walletAddress,
+    integratorFee: {
+        receiver: integratorFeeReceiver, // address to receive the fee
+        value: new Bps(100n) // 1% fee (100 basis points)
+    }
})
```

## 完整实例 土著资产交叉交换

```typescript
import {
    EvmCrossChainOrder,
    HashLock,
    NetworkEnum,
    OrderStatus,
    PrivateKeyProviderConnector,
    SDK,
    EvmAddress,
    NativeOrdersFactory,
    Address
} from '@1inch/cross-chain-sdk'
import {JsonRpcProvider, Wallet} from 'ethers'
import {randomBytes} from 'node:crypto'
import assert from "node:assert";

const PRIVATE_KEY =  '0x'
const WEB3_NODE_URL = 'https://'
const AUTH_KEY = 'auth-key'

const ethersRpcProvider = new JsonRpcProvider(WEB3_NODE_URL)

const ethersProviderConnector = {
    eth: {
        call(transactionConfig): Promise<string> {
            return ethersRpcProvider.call(transactionConfig)
        }
    },
    extend(): void {}
}

const connector = new PrivateKeyProviderConnector(
    PRIVATE_KEY,
    ethersProviderConnector
)

const wallet = new Wallet(PRIVATE_KEY, ethersRpcProvider)

const sdk = new SDK({
    url: 'https://api.1inch.com/fusion-plus',
    authKey: AUTH_KEY,
    blockchainProvider: connector,
})

async function sleep(ms: number): Promise<void> {
    return new Promise((resolve) => setTimeout(resolve, ms))
}

async function main(): Promise<void> {
    // estimate
    const quote = await sdk.getQuote({
        amount: '400000000000000000',
        srcChainId: NetworkEnum.AVALANCHE,
        dstChainId: NetworkEnum.BINANCE,
        enableEstimate: true,
        srcTokenAddress: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee', // AVAX
        dstTokenAddress: '0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d', // USDC
        walletAddress: wallet.address
    })

    const preset = quote.recommendedPreset

    // generate secrets
    const secrets = Array.from({
        length: quote.presets[preset].secretsCount
    }).map(() => '0x' + randomBytes(32).toString('hex'))

    const hashLock =
        secrets.length === 1
            ? HashLock.forSingleFill(secrets[0])
            : HashLock.forMultipleFills(HashLock.getMerkleLeaves(secrets))

    const secretHashes = secrets.map((s) => HashLock.hashSecret(s))

    // create order
    const {hash, quoteId, order} = sdk.createOrder(quote, {
        walletAddress: wallet.address,
        hashLock,
        preset,
        source: 'sdk-tutorial',
        secretHashes
    })

    assert(order instanceof EvmCrossChainOrder)

    console.log({hash}, 'order created')

    // submit order
    const orderInfo = await sdk.submitNativeOrder(
        quote.srcChainId,
        order,
        EvmAddress.fromString(wallet.address),
        quoteId,
        secretHashes
    )
    console.log({hash}, 'order submitted')

    const factory = NativeOrdersFactory.default(NetworkEnum.AVALANCHE)
    const call = factory.create(new Address(wallet.address), orderInfo.order)

    const txRes = await wallet.sendTransaction({
        to: call.to.toString(),
        data: call.data,
        value: call.value
    })

    console.log({txHash: txRes.hash}, 'transaction broadcasted')

    await wallet.provider.waitForTransaction(txRes.hash, 3)

    // submit secrets for deployed escrows
    while (true) {
        const secretsToShare = await sdk.getReadyToAcceptSecretFills(hash)

        if (secretsToShare.fills.length) {
            for (const {idx} of secretsToShare.fills) {

                // it is responsibility of the client to check whether is safe to share secret (check escrow addresses and so on)
                await sdk.submitSecret(hash, secrets[idx])

                console.log({idx}, 'shared secret')
            }
        }

        // check if order finished
        const {status} = await sdk.getOrderStatus(hash)

        if (
            status === OrderStatus.Executed ||
            status === OrderStatus.Expired ||
            status === OrderStatus.Refunded
        ) {
            break
        }

        await sleep(1000)
    }

    const statusResponse = await sdk.getOrderStatus(hash)

    console.log(statusResponse)
}

main()
```

# 索拉纳

交换到/从 solana 进行类似于 evm 到 evm 互换, 除了地址格式, 还必须在链上和中继器上发布 solana 的命令

## 索拉纳 - > EVM( 视频)

这个例子表明索拉纳公司与EVM公司之间完全的跨链互换,包括:

-   建立SDK
-   获得USDT(索拉那)到USDT(Ethereum)互换的报价
-   创建并向中继器宣布命令
-   使用索拉纳交易发布链上订单
-   管理代管部署的秘密分享
-   监测订单状况直至完成

点击以扩展代码示例

```typescript
/* eslint-disable max-depth */
import {
  NetworkEnum,
  SDK,
  SolanaAddress,
  HashLock,
  EvmAddress,
  SvmSrcEscrowFactory,
  OrderStatus
} from '@1inch/cross-chain-sdk'
import { utils, web3 } from '@coral-xyz/anchor'
import assert from 'node:assert'
import { randomBytes } from 'node:crypto'
import { setTimeout } from 'node:timers/promises'

const authKey = process.env.DEV_PORTAL_API_TOKEN
assert(authKey, 'please provide auth key in DEV_PORTAL_API_TOKEN env. You can grab it at https://portal.1inch.dev')

const signerPrivateKey = process.env.SOLANA_PRIVATE_KEY
assert(signerPrivateKey, 'please provide solana private key of the maker wallet in SOLANA_PRIVATE_KEY')
const makerSigner = web3.Keypair.fromSecretKey(utils.bytes.bs58.decode(signerPrivateKey))

const SOLANA_RPC = 'https://api.mainnet-beta.solana.com'
const sdk = new SDK({
  url: 'https://api.1inch.com/fusion-plus',
  authKey
})

const USDT_SOL = 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB'
const USDT_ETHEREUM = '0xdac17f958d2ee523a2206206994597c13d831ec7'

const maker = makerSigner.publicKey.toBase58()
const receiver = '0x962a836519109e162754161000D65d9Dc027Fa0F'

const srcToken = SolanaAddress.fromString(USDT_SOL)
const dstToken = EvmAddress.fromString(USDT_ETHEREUM) // use EvmAddress.NATIVE for native token
const amount = 10_000_000n // 10 USDT

const srcChainId = NetworkEnum.SOLANA
const dstChainId = NetworkEnum.ETHEREUM

async function main(): Promise<void> {
  console.log(
    `creating order from wallet ${maker} for [${srcChainId}] ${amount} ${srcToken} -> ${dstToken} [${dstChainId}]`
  )

  const quote = await sdk.getQuote({
    amount: amount.toString(),
    srcChainId,
    dstChainId,
    srcTokenAddress: srcToken.toString(),
    dstTokenAddress: dstToken.toString(),
    enableEstimate: true,
    walletAddress: maker
  })

  console.log('got quote', quote)

  const preset = quote.getPreset(quote.recommendedPreset)
  assert(quote.quoteId)

  const secrets = Array.from({ length: preset.secretsCount }).map(getSecret)
  const secretHashes = secrets.map(HashLock.hashSecret)
  const leaves = HashLock.getMerkleLeaves(secrets)

  const hashLock = secrets.length > 1 ? HashLock.forMultipleFills(leaves) : HashLock.forSingleFill(secrets[0])

  const order = quote.createSolanaOrder({
    hashLock,
    receiver: EvmAddress.fromString(receiver),
    preset: quote.recommendedPreset
  })
  const orderHash = await sdk.announceOrder(order, quote.quoteId, secretHashes)

  console.log('announced order to relayer', orderHash)

  const ix = SvmSrcEscrowFactory.DEFAULT.createOrder(order, {
    srcTokenProgramId: SolanaAddress.TOKEN_PROGRAM_ID
  })

  const tx = new web3.Transaction().add({
    data: ix.data,
    programId: new web3.PublicKey(ix.programId.toBuffer()),
    keys: ix.accounts.map((a) => ({
      isSigner: a.isSigner,
      isWritable: a.isWritable,
      pubkey: new web3.PublicKey(a.pubkey.toBuffer())
    }))
  })

  const connection = new web3.Connection(SOLANA_RPC)

  const result = await connection.sendTransaction(tx, [makerSigner])

  console.log('submitted order', result)
  await setTimeout(5000) // wait for tx lending

  const alreadyShared = new Set<number>()

  while (true) {
    const readyToAcceptSecretes = await sdk.getReadyToAcceptSecretFills(orderHash)
    const idxes = readyToAcceptSecretes.fills.map((f) => f.idx)

    for (const idx of idxes) {
      if (!alreadyShared.has(idx)) {
        // it is responsibility of the client to check whether is safe to share secret (check escrow addresses and so on)
        await sdk.submitSecret(orderHash, secrets[idx])
        alreadyShared.add(idx)

        console.log('submitted secret', secrets[idx])
      }
    }

    // check if order finished
    const { status } = await sdk.getOrderStatus(orderHash)

    if (status === OrderStatus.Executed || status === OrderStatus.Expired || status === OrderStatus.Refunded) {
      break
    }

    await setTimeout(5000)
  }

  const statusResponse = await sdk.getOrderStatus(orderHash)
  console.log(statusResponse)
}

function getSecret(): string {
  return '0x' + randomBytes(32).toString('hex')
}

main()
```

## EVM - > 索拉纳

这一例子表明,EVM公司与索拉纳公司之间完全互换,包括:

-   建立SDK
-   获得USDT(Ethereum)到USDT(索拉那)互换的报价
-   创建并向中继器提交命令
-   管理代管部署的秘密分享
-   监测订单状况直至完成

点击以扩展代码示例

```typescript
import {
  NetworkEnum,
  SDK,
  SolanaAddress,
  HashLock,
  EvmAddress,
  PrivateKeyProviderConnector,
  OrderStatus
} from '@1inch/cross-chain-sdk-solana'
import { JsonRpcProvider, TransactionRequest, computeAddress } from 'ethers'
import assert from 'node:assert'
import { randomBytes } from 'node:crypto'
import { setTimeout } from 'node:timers/promises'
import 'dotenv/config'

const authKey = process.env.DEV_PORTAL_API_TOKEN
assert(authKey, 'please provide auth key in DEV_PORTAL_API_TOKEN env. You can grab it at https://portal.1inch.dev')

const signerPrivateKey = process.env.EVM_PRIVATE_KEY
assert(signerPrivateKey, 'please provide evm private key of the maker wallet in EVM_PRIVATE_KEY env')

const NODE_URL = 'https://web3.1inch.io/1'
const ethersRpcProvider = new JsonRpcProvider(NODE_URL)

const ethersProviderConnector = {
  eth: {
    call(transactionConfig: TransactionRequest): Promise<string> {
      return ethersRpcProvider.call(transactionConfig)
    }
  },
  extend(): void {}
}

const connector = new PrivateKeyProviderConnector(signerPrivateKey, ethersProviderConnector)

const sdk = new SDK({
  url: 'https://api.1inch.com/fusion-plus',
  authKey: process.env.DEV_PORTAL_API_TOKEN,
  blockchainProvider: connector
})

const maker = computeAddress(signerPrivateKey)
const receiver = '93FP8NG2JrScb9xzNsJrzAze8gJJtr1TgQWUCHDgP3BW'

const USDT_SOL = 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB'
const USDT_ETHEREUM = '0xdac17f958d2ee523a2206206994597c13d831ec7'
const amount = 10_000_000n // 10 USDT
const srcToken = EvmAddress.fromString(USDT_ETHEREUM)
const dstToken = SolanaAddress.fromString(USDT_SOL) // use SolanaAddress.NATIVE for native token
const srcChainId = NetworkEnum.ETHEREUM
const dstChainId = NetworkEnum.SOLANA

async function main(): Promise<void> {
  const quote = await sdk.getQuote({
    amount: amount.toString(),
    srcChainId,
    dstChainId,
    srcTokenAddress: srcToken.toString(),
    dstTokenAddress: dstToken.toString(),
    enableEstimate: true,
    walletAddress: maker
  })

  const preset = quote.getPreset(quote.recommendedPreset)
  assert(quote.quoteId)
  console.log('got preset', preset)

  const secrets = Array.from({ length: preset.secretsCount }).map(getSecret)
  const secretHashes = secrets.map(HashLock.hashSecret)
  const leaves = HashLock.getMerkleLeaves(secrets)

  const hashLock = secrets.length > 1 ? HashLock.forMultipleFills(leaves) : HashLock.forSingleFill(secrets[0])

  const order = quote.createEvmOrder({
    hashLock,
    receiver: SolanaAddress.fromString(receiver),
    preset: quote.recommendedPreset
  })

  const { orderHash } = await sdk.submitOrder(srcChainId, order, quote.quoteId, secretHashes)

  console.log('submit order to relayer', orderHash)

  const alreadyShared = new Set<number>()

  while (true) {
    const readyToAcceptSecretes = await sdk.getReadyToAcceptSecretFills(orderHash)

    const idxes = readyToAcceptSecretes.fills.map((f) => f.idx)

    for (const idx of idxes) {
      if (!alreadyShared.has(idx)) {
        // it is responsibility of the client to check whether is safe to share secret (check escrow addresses and so on)
        await sdk.submitSecret(orderHash, secrets[idx]).catch((err) => console.error('failed to submit secret', err))
        alreadyShared.add(idx)

        console.log('submitted secret', secrets[idx])
      }
    }

    // check if order finished
    const { status } = await sdk.getOrderStatus(orderHash)

    if (status === OrderStatus.Executed || status === OrderStatus.Expired || status === OrderStatus.Refunded) {
      break
    }

    await setTimeout(5000)
  }

  const statusResponse = await sdk.getOrderStatus(orderHash)
  console.log(statusResponse)
}

function getSecret(): string {
  return '0x' + randomBytes(32).toString('hex')
}

main()
```

## 常见问题

### @1inch/cross-chain-sdk 是什么？

通过 1英寸 创建原子交换的 Sdk

### 如何安装 @1inch/cross-chain-sdk？

在项目目录运行 npm install @1inch/cross-chain-sdk，或使用 pnpm add / yarn add / bun add。

### @1inch/cross-chain-sdk 支持 TypeScript 吗？

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

### @1inch/cross-chain-sdk 支持 ESM 还是 CommonJS？

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

### @1inch/cross-chain-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.16\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @1inch/cross-chain-sdk 可以商用吗？

@1inch/cross-chain-sdk 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @1inch/cross-chain-sdk 的下载量有多少？

根据 npm 官方下载统计，@1inch/cross-chain-sdk 在 2026/10/05 – 2026/11/03 这 30 天内被下载 49,449 次，日均约 1,648 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @1inch/cross-chain-sdk 还在维护吗？

最新版本 2\.2\.4 发布于 2026/09/11（1 个月前）；至今共发布 125 个版本，其中过去 12 个月发布了 36 个；首次发布于 2024/09/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。