nexus-sdk-swap-flows

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Swap Flows

交换流程

Call swapWithExactIn(input, options?)

调用swapWithExactIn(input, options?)

Use when input amount is fixed and sources are known.

Signature:

sdk.swapWithExactIn(input, { onEvent? })

Params (

ExactInSwapInput

from: { chainId: number; amount: bigint; tokenAddress: Hex }[]

```
toChainId: number
```
```
toTokenAddress: Hex
```

Notes:
- Ensure
```
from
```
  amounts are in smallest units.
- Use chain-specific token addresses (see
```
TOKEN_CONTRACT_ADDRESSES
```
  ).

Result (

SwapResult

{ success: true; result: SuccessfulSwapResult }

适用于输入金额固定且来源已知的场景。

签名：

sdk.swapWithExactIn(input, { onEvent? })

参数 (

ExactInSwapInput

)：

from: { chainId: number; amount: bigint; tokenAddress: Hex }[]

```
toChainId: number
```
```
toTokenAddress: Hex
```

注意事项：
- 确保
```
from
```
  字段内的金额以最小单位填写。
- 使用对应链的代币地址（参考
```
TOKEN_CONTRACT_ADDRESSES
```
  ）。

返回值 (

SwapResult

)：

{ success: true; result: SuccessfulSwapResult }

Call swapWithExactOut(input, options?)

调用swapWithExactOut(input, options?)

Use when desired output amount is fixed.

Signature:

sdk.swapWithExactOut(input, { onEvent? })

Params (

ExactOutSwapInput

```
toChainId: number
```
```
toTokenAddress: Hex
```
```
toAmount: bigint
```
```
toNativeAmount?: bigint
```
(optional native token output)

fromSources?: { chainId: number; tokenAddress: Hex }[]

(optional)

Notes:
- If
```
fromSources
```
  is omitted, SDK auto-selects sources.

适用于预期输出金额固定的场景。

签名：

sdk.swapWithExactOut(input, { onEvent? })

参数 (

ExactOutSwapInput

)：

```
toChainId: number
```
```
toTokenAddress: Hex
```
```
toAmount: bigint
```
```
toNativeAmount?: bigint
```
（可选，原生代币输出）

fromSources?: { chainId: number; tokenAddress: Hex }[]

（可选）

注意事项：
- 如果省略
```
fromSources
```
  ，SDK会自动选择来源。

Call swapAndExecute(input, options?)

调用swapAndExecute(input, options?)

Use to perform swap (if needed) and then execute a contract call.
Signature:
- ```
sdk.swapAndExecute(input, { onEvent? })
```

Params (

SwapAndExecuteParams

```
toChainId: number
```
```
toTokenAddress: Hex
```
```
toAmount: bigint
```

fromSources?: { chainId: number; tokenAddress: Hex }[]

```
execute: SwapExecuteParams
```

SwapExecuteParams

```
to: Hex
```
```
data?: Hex
```
```
value?: bigint
```
```
gas: bigint
```
```
gasPrice?: 'low' | 'medium' | 'high'
```

tokenApproval?: { token: Hex; amount: bigint; spender: Hex }

Result (

SwapAndExecuteResult

```
swapResult: SuccessfulSwapResult | null
```
(null if swap skipped)

用于执行必要的交换后再调用合约的场景。
签名：
- ```
sdk.swapAndExecute(input, { onEvent? })
```

参数 (

SwapAndExecuteParams

)：

```
toChainId: number
```
```
toTokenAddress: Hex
```
```
toAmount: bigint
```

fromSources?: { chainId: number; tokenAddress: Hex }[]

```
execute: SwapExecuteParams
```

SwapExecuteParams

说明：

```
to: Hex
```
```
data?: Hex
```
```
value?: bigint
```
```
gas: bigint
```
```
gasPrice?: 'low' | 'medium' | 'high'
```

tokenApproval?: { token: Hex; amount: bigint; spender: Hex }

返回值 (

SwapAndExecuteResult

)：

```
swapResult: SuccessfulSwapResult | null
```
（跳过交换时为null）

Use token addresses and chains

代币地址与链使用

Use SDK constants for addresses and chain IDs:
- ```
SUPPORTED_CHAINS
```
- ```
TOKEN_CONTRACT_ADDRESSES
```

使用SDK提供的常量获取地址和链ID：
- ```
SUPPORTED_CHAINS
```
- ```
TOKEN_CONTRACT_ADDRESSES
```

Attach swap intent hook

绑定交换意图钩子

Set
```
sdk.setOnSwapIntentHook(...)
```
and call
```
allow()
```
to proceed.
If the hook is not set, the SDK auto-approves.

设置
```
sdk.setOnSwapIntentHook(...)
```
并调用
```
allow()
```
即可继续执行。
如果未设置钩子，SDK会自动批准。

Stream swap events

流式获取交换事件

Listen for
```
NEXUS_EVENTS.SWAP_STEP_COMPLETE
```
.
Handle special cases like swap skipped (e.g., already on destination token).

监听
```
NEXUS_EVENTS.SWAP_STEP_COMPLETE
```
事件。
处理特殊情况，比如跳过交换（例如已经持有目标代币）。

Convert amounts to bigint

金额转换为bigint格式

Use
```
sdk.utils.parseUnits(value, decimals)
```
or

sdk.convertTokenReadableAmountToBigInt(value, tokenSymbol, chainId)

when decimals vary by chain.

使用
```
sdk.utils.parseUnits(value, decimals)
```
方法，或

当不同链的代币小数位数不同时，使用

sdk.convertTokenReadableAmountToBigInt(value, tokenSymbol, chainId)

方法。