> For the complete documentation index, see [llms.txt](https://docs.zofinance.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zofinance.io/building-on-zo/zo-sdk/swap-examples.md).

# Swap Examples

This guide covers how to integrate swaps using the ZO SDK. Swaps are supported on **ZLP**, **SLP**, and **USDZ** via `api.swap()`, `api.swapV2Ptb()`, and fee estimation via `dataAPI.calculateSwapFeeBreakdown()`.

### Overview

A swap flow typically involves:

1. **Estimate fees** – Get the expected fee breakdown for the swap.
2. **Set slippage protection** – Compute `minAmountOut` based on expected output and slippage tolerance.
3. **Build transaction** – Call `api.swap()` to construct the transaction.
4. **Sign and send** – Sign with the wallet and submit to the network.

### Amounts and units

* `fromAmount` is in **atomic units** (raw token units), e.g. `1_000_000` for 1 USDC (6 decimals).
* `minAmountOut` is in **atomic units** of the destination token.
* `calculateSwapFeeBreakdown(fromAmount)` expects atomic units for the source token.

```typescript
// Example: swap 100 USDC (6 decimals) for SUI
const fromAmount = BigInt(100 * 1e6)  // 100_000_000 atomic units
```

### Estimate swap fees

Before building the swap transaction, you can estimate the fee breakdown to display to the user or compute a safe `minAmountOut`.

```typescript
import { SDK, LPToken, Network } from '@zofai/zo-sdk'
import { SuiClient } from '@mysten/sui/client'

const provider = new SuiClient({ url: 'https://fullnode.mainnet.sui.io' })
const network = Network.MAINNET
const apiEndpoint = 'https://api.zofinance.io'
const connectionURL = 'https://hermes.pyth.network'

const slpDataAPI = SDK.createSLPDataAPI(network, provider, apiEndpoint, connectionURL)

// fromAmount in atomic units (e.g. 100 USDC = 100 * 1e6)
const fromToken = 'usdc'
const toToken = 'sui'
const fromAmount = 100 * 1e6

const feeBreakdown = await slpDataAPI.calculateSwapFeeBreakdown(fromToken, toToken, fromAmount)

// feeBreakdown contains:
// - swapValue: notional in USD
// - totalVaultsValue: total vault value in USD
// - rebaseFeeInRate, rebaseFeeOutRate: rates for swap-in and swap-out
// - rebaseFeeInValue, rebaseFeeOutValue: rebase fee amounts in USD
// - swapImpactFeeValue: swap impact fee in USD
// - emaVolatilityFeeValue: EMA volatility fee in USD
// - totalFeeValue: sum of all fee components
// - totalFeeRate: totalFeeValue / swapValue

console.log(`Total fee: ${feeBreakdown.totalFeeValue.toFixed(4)} USD`)
console.log(`Fee rate: ${(feeBreakdown.totalFeeRate * 100).toFixed(2)}%`)
```

### Build and submit swap transaction

Use the **API** instance to build the swap transaction. You need:

* `fromToken`, `toToken` – token identifiers (e.g. `'usdc'`, `'sui'`).
* `fromAmount` – amount in atomic units (bigint).
* `fromCoinObjects` – owned coin object IDs for the source token.
* `minAmountOut` – optional; minimum output amount in atomic units (slippage protection).

```typescript
const slpAPI = SDK.createSLPAPI(network, provider, apiEndpoint, connectionURL)

const fromAmount = BigInt(100 * 1e6)  // 100 USDC
const fromCoinObjects = ['0x...']     // user's USDC coin IDs

// Optional: set minAmountOut to protect against slippage
// e.g. 1% slippage: minAmountOut = expectedOut * 0.99
const minAmountOut = 0  // or compute from oracle + slippage

const tx = await slpAPI.swap(
  'usdc',
  'sui',
  fromAmount,
  fromCoinObjects,
  minAmountOut
)

// Sign with wallet and execute
// const signed = await signAndExecuteTransaction({ transaction: tx })
```

### Swap and return coin to user (swapV2Ptb)

Use `swapV2Ptb()` when you need the output coin returned as a `TransactionObjectArgument`—for example, to pass into another move call or to transfer it within the same transaction. Unlike `swap()`, which consumes the output internally, `swapV2Ptb()` returns the output coin so you can compose it into larger transactions.

Pass an optional `tx` to compose into an existing transaction; otherwise a new transaction is created (you must sign and execute it via your wallet).

```typescript
const slpAPI = SDK.createSLPAPI(network, provider, apiEndpoint, connectionURL)

// Option 1: Standalone swap (tx created internally)
const tx = new Transaction()
const outputCoin = await slpAPI.swapV2Ptb(
  'usdc',
  'sui',
  BigInt(100 * 1e6),
  fromCoinObjects,
  minAmountOut,
  tx
)
// tx is modified in place; sign and execute tx

// Option 2: Compose with other move calls
const composedTx = new Transaction()
const swapCoin = await slpAPI.swapV2Ptb('usdc', 'sui', BigInt(100 * 1e6), fromCoinObjects, minAmountOut, composedTx)
composedTx.transferObjects([swapCoin], composedTx.pure.address(recipientAddress))
```

### Complete integration example

```typescript
import { SDK, LPToken, Network } from '@zofai/zo-sdk'
import { SuiClient } from '@mysten/sui/client'

async function swapWithFeeEstimate(
  fromToken: string,
  toToken: string,
  fromAmountAtomic: number,
  fromCoinObjects: string[],
  slippageBps: number = 50,  // 0.5%
) {
  const provider = new SuiClient({ url: 'https://fullnode.mainnet.sui.io' })
  const api = SDK.createSLPAPI(
    Network.MAINNET,
    provider,
    'https://api.zofinance.io',
    'https://hermes.zofinance.io'
  )

  // 1. Estimate fees
  const feeBreakdown = await api.dataAPI.calculateSwapFeeBreakdown(
    fromToken,
    toToken,
    fromAmountAtomic
  )

  // 2. Compute minAmountOut from fee breakdown (net value after fees) and slippage
  const toPrice = (await api.getOraclePrice(toToken)).getPriceUnchecked().getPriceAsNumberUnchecked()
  const toDecimals = 9  // use deployment consts or lookup
  const netValueUsd = feeBreakdown.swapValue - feeBreakdown.totalFeeValue
  const expectedOutAtomic = (netValueUsd * (10 ** toDecimals)) / toPrice
  const minAmountOut = Math.floor(expectedOutAtomic * (1 - slippageBps / 10000))

  // 3. Build transaction
  const tx = await api.swap(
    fromToken,
    toToken,
    BigInt(fromAmountAtomic),
    fromCoinObjects,
    minAmountOut
  )

  return {
    transaction: tx,
    feeBreakdown,
  }
}
```

### Fee components

| Component              | Description                                                               |
| ---------------------- | ------------------------------------------------------------------------- |
| **Rebase fee (in)**    | Fee on the source token when swapping in; depends on vault utilization.   |
| **Rebase fee (out)**   | Fee on the destination token when swapping out.                           |
| **Swap impact fee**    | Fee from `SwapImpactConfig`; scales with `swapValue / totalVaultsValue`.  |
| **EMA volatility fee** | Fee from `EmaVolatilityFeeConfig`; scales with price divergence from EMA. |

Use `calculateSwapFeeBreakdown` to get the USD value of each component and the total fee before executing the swap.

### Token identifiers

Tokens are identified by their symbol in the deployment config, e.g. `'sui'`, `'usdc'`, `'usdt'`, `'eth'`, `'btc'`. Ensure the `fromToken` and `toToken` values match those in the LP’s supported tokens.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zofinance.io/building-on-zo/zo-sdk/swap-examples.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.