> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xentfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transfers & Swaps

> Transfers & Swaps enable you to move crypto assets between wallets and exchange one token for another, all through a unified API. Whether you need to consolidate funds across chains or convert assets, XentFi provides a seamless experience.

## Overview

XentFi's Transfer and Swap operations allow you to move assets between wallets and exchange tokens across multiple blockchains. The API provides real-time quotes, gas estimation, and execution capabilities for both transfers and swaps.

```mermaid theme={null}
flowchart TB
    subgraph Source["Source Wallet"]
        Wallet[Deposit Address or Master Wallet]
    end

    subgraph Operations["Operations"]
        Transfer[Transfer<br/>Send assets to recipient]
        Swap[Swap<br/>Exchange tokens]
    end

    subgraph Destination["Destination"]
        Recipient[Recipient Address]
        Output[Output Token]
    end

    Wallet --> Transfer --> Recipient
    Wallet --> Swap --> Output
```

## What's Possible?

<CardGroup cols={2}>
  <Card title="💰 Transfers" icon="send">
    Send assets from deposit addresses or master wallets to any blockchain address
  </Card>

  <Card title="🔄 Token Swaps" icon="exchange">
    Exchange tokens on the same blockchain using DEX aggregators
  </Card>

  <Card title="⚡ Quotes" icon="zap">
    Get real-time quotes with gas estimates before executing
  </Card>

  <Card title="⛽ Gas Estimation" icon="gas-pump">
    Estimate gas fees before executing transfers or swaps
  </Card>
</CardGroup>

## Transfer Operations

### Create Transfer Quote

Generate a quote for transferring assets from a deposit address:

```bash theme={null}
curl -X POST https://api.xentfi.com/v1/addresses/{addressId}/transfer \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [
      {
        "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
        "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f0b5b5",
        "amount": "0.001"
      }
    ]
  }'
```

**Request Parameters:**

| Parameter    | Type   | Required | Description                 |
| ------------ | ------ | -------- | --------------------------- |
| `assets`     | array  | ✅        | List of assets to transfer  |
| `assetId`    | string | ✅        | ID of the asset to transfer |
| `recipient`  | string | ✅        | Recipient wallet address    |
| `amount`     | string | ✅        | Amount in decimal format    |
| `feeAssetId` | string | ❌        | Asset ID for gas fees       |

**Response:**

```json theme={null}
{
    "quoteHash": "ASNFZ4mrze8gMkFGaW5hbGx5IHRoZSBkYXRhIGlzIGZ1bGx5IGVuY3J5cHRlZA==",
    "amount": "1.5",
    "value": "1500.00",
    "gasFee": "0.00021",
    "gasPrice": "284887648",
    "gasUsed": "35000",
    "fee": "0.01",
    "asset": {
        "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
        "symbol": "EURC",
        "decimals": 6
    },
    "blockchain": {
        "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
        "name": "Base",
        "symbol": "ETH"
    },
    "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0b5b5",
    "senderAddress": "0x123d35Cc6634C0532925a3b844Bc9e7595f0b5b5"
}
```

### Estimate Transfer Gas

Get gas estimates before executing a transfer:

```bash theme={null}
curl -X POST https://api.xentfi.com/v1/addresses/{addressId}/transfer/estimate-gas \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [
      {
        "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
        "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f0b5b5",
        "amount": "0.001"
      }
    ]
  }'
```

**Response:**

```json theme={null}
{
    "data": {
        "assets": [
            {
                "amount": "0.001",
                "asset": {
                    "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
                    "symbol": "EURC"
                },
                "blockchain": {
                    "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
                    "name": "Base"
                },
                "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0b5b5"
            }
        ],
        "estimatedFee": {
            "amount": "Estimated amount in token units",
            "value": "Estimated USD value",
            "callGasLimit": "callGasLimit fee in native token",
            "verificationGasLimit": "verificationGasLimit price in wei"
        }
    }
}
```

### Master Wallet Transfer

Transfer assets directly from a master wallet:

```bash theme={null}
curl -X POST https://api.xentfi.com/v1/master-wallets/{masterId}/transfer \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [
      {
        "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
        "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f0b5b5",
        "amount": "0.001"
      }
    ]
  }'
```

**Response:**

```json theme={null}
{
    "data": {
        "hash": "0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
        "assets": [
            {
                "amount": "0.001",
                "asset": {
                    "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
                    "symbol": "EURC"
                },
                "blockchain": {
                    "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
                    "name": "Base"
                },
                "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0b5b5"
            }
        ],
        "gasFee": "0.00021",
        "gasPrice": "284887648",
        "gasUsed": "35000"
    }
}
```

### Estimate Master Transfer Gas

```bash theme={null}
curl -X POST https://api.xentfi.com/v1/master-wallets/{masterId}/transfer/estimate-gas \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [
      {
        "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
        "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f0b5b5",
        "amount": "0.001"
      }
    ]
  }'
```

## Swap Operations

### Create Address Swap Quote

Generate a quote for swapping tokens from a deposit address:

```bash theme={null}
curl -X POST https://api.xentfi.com/v1/addresses/quotes/swap \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "srcAssetId": "asset_eth_123",
    "dstAssetId": "asset_usdc_456",
    "amount": "1000000000000000000",
    "masterId": "master_123456789",
    "srcBlockchainId": "eth_mainnet",
    "dstBlockchainId": "base_mainnet",
    "slippageTolerance": "0.5",
    "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0b5b5"
  }'
```

**Request Parameters:**

| Parameter            | Type   | Required | Description                                  |
| -------------------- | ------ | -------- | -------------------------------------------- |
| `srcAssetId`         | string | ✅        | Source asset ID                              |
| `dstAssetId`         | string | ✅        | Destination asset ID                         |
| `amount`             | string | ✅        | Amount of source asset to swap               |
| `masterId`           | string | ✅        | Master wallet ID                             |
| `addressId`          | string | ❌        | Deposit address ID (alternative to masterId) |
| `srcBlockchainId`    | string | ✅        | Source blockchain ID                         |
| `dstBlockchainId`    | string | ✅        | Destination blockchain ID                    |
| `slippageTolerance`  | string | ✅        | Maximum slippage percentage                  |
| `destinationAddress` | string | ❌        | Custom destination address                   |
| `feeAssetId`         | string | ❌        | Asset ID for gas fees                        |

**Response:**

```json theme={null}
{
    "quote": {
        // Quote object containing swap details
    }
}
```

### Execute Address Swap

Execute a swap using a quote:

```bash theme={null}
curl -X POST https://api.xentfi.com/v1/addresses/quotes/swap/execute \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "quote": { ... },
    "walletId": "wallet_123456789"
  }'
```

**Response:**

```json theme={null}
{
    "hash": "0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb"
}
```

### Create Master Swap Quote

Generate a swap quote from a master wallet:

```bash theme={null}
curl -X POST https://api.xentfi.com/v1/master-wallets/quotes/swap \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "srcAssetId": "asset_eth_123",
    "dstAssetId": "asset_usdc_456",
    "amount": "1000000000000000000",
    "masterId": "master_123456789",
    "srcBlockchainId": "eth_mainnet",
    "dstBlockchainId": "base_mainnet",
    "slippageTolerance": "0.5"
  }'
```

### Execute Master Swap

```bash theme={null}
curl -X POST https://api.xentfi.com/v1/master-wallets/quotes/swap/execute \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "quote": { ... },
    "walletId": "master_123456789"
  }'
```

## Address vs Master Wallet Operations

| Operation                 | Address Endpoint                                  | Master Wallet Endpoint                                |
| ------------------------- | ------------------------------------------------- | ----------------------------------------------------- |
| **Transfer Quote**        | `/v1/addresses/{addressId}/transfer`              | `/v1/master-wallets/{masterId}/transfer`              |
| **Transfer Gas Estimate** | `/v1/addresses/{addressId}/transfer/estimate-gas` | `/v1/master-wallets/{masterId}/transfer/estimate-gas` |
| **Swap Quote**            | `/v1/addresses/quotes/swap`                       | `/v1/master-wallets/quotes/swap`                      |
| **Swap Execute**          | `/v1/addresses/quotes/swap/execute`               | `/v1/master-wallets/quotes/swap/execute`              |

## Gas Estimation Fields

| Field                  | Description                        |
| ---------------------- | ---------------------------------- |
| `callGasLimit`         | Gas limit for the transaction call |
| `verificationGasLimit` | Gas limit for verification         |
| `amount`               | Estimated amount in token units    |
| `value`                | Estimated USD value                |

## Best Practices

<AccordionGroup>
  <Accordion title="Always Get a Quote First">
    * Never execute blind transfers or swaps
    * Quotes provide gas estimates and expected outcomes
    * Quotes include slippage protection details
    * Check `quoteHash` for encrypted execution data
  </Accordion>

  <Accordion title="Set Appropriate Slippage">
    * Use `0.5%` for stable pairs (USDC/USDT)
    * Use `1.0%` for volatile pairs (ETH/USDC)
    * Consider network congestion when setting tolerance
    * Higher slippage = higher success rate
  </Accordion>

  <Accordion title="Monitor Gas Fees">
    * Use `estimate-gas` endpoints before execution
    * Check `callGasLimit` and `verificationGasLimit`
    * Compare gas costs across blockchains
    * Consider L2 networks for lower fees
  </Accordion>

  <Accordion title="Handle Errors Gracefully">
    * Implement retry logic with exponential backoff
    * Handle network timeout errors
    * Log all transaction hashes for audit
    * Set up webhook monitoring for transfer status
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Transfer quote fails">
    **Possible causes:**

    * Insufficient balance
    * Invalid asset ID
    * Invalid recipient address

    **Solutions:**

    * Check wallet balance using `/balance` endpoint
    * Verify asset ID from `/assets/tokens` endpoint
    * Validate recipient address format
  </Accordion>

  <Accordion title="Swap quote fails">
    **Possible causes:**

    * Insufficient liquidity
    * Invalid asset pair
    * Slippage too low

    **Solutions:**

    * Increase slippage tolerance
    * Try different asset pairs
    * Check asset availability on destination blockchain
  </Accordion>

  <Accordion title="Transaction not completing">
    **Possible causes:**

    * Network congestion
    * Insufficient gas
    * Blockchain issues

    **Solutions:**

    * Check transaction status via hash
    * Increase gas limit
    * Monitor blockchain status
  </Accordion>

  <Accordion title="Gas estimation too high">
    **Possible causes:**

    * Network congestion
    * Complex transaction path

    **Solutions:**

    * Wait for lower network traffic
    * Use L2 networks
    * Batch transactions when possible
  </Accordion>
</AccordionGroup>

## Webhook Events

| Event               | Description                     | Trigger                   |
| ------------------- | ------------------------------- | ------------------------- |
| `TRANSFER_EXECUTED` | Transfer completed successfully | After successful transfer |
| `TRANFER_FAILED`    | Transfer failed                 | When transfer fails       |
| `SWAP_EXECUTED`     | Swap completed successfully     | After successful swap     |
| `SWAP_FAILED`       | Swap failed                     | When swap fails           |

## API Reference

| Endpoint                                              | Method | Description                   |
| ----------------------------------------------------- | ------ | ----------------------------- |
| `/v1/addresses/{addressId}/transfer`                  | POST   | Create address transfer quote |
| `/v1/addresses/{addressId}/transfer/estimate-gas`     | POST   | Estimate transfer gas         |
| `/v1/master-wallets/{masterId}/transfer`              | POST   | Execute master transfer       |
| `/v1/master-wallets/{masterId}/transfer/estimate-gas` | POST   | Estimate master transfer gas  |
| `/v1/addresses/quotes/swap`                           | POST   | Create swap quote             |
| `/v1/addresses/quotes/swap/execute`                   | POST   | Execute swap                  |
| `/v1/master-wallets/quotes/swap`                      | POST   | Create master swap quote      |
| `/v1/master-wallets/quotes/swap/execute`              | POST   | Execute master swap           |

## Related Products

<CardGroup cols={3}>
  <Card title="Master Wallets" icon="wallet" href="/products/master-wallets">
    Source and destination wallets
  </Card>

  <Card title="Deposit Addresses" icon="address-card" href="/products/deposit-addresses">
    Address management and monitoring
  </Card>

  <Card title="Webhooks" icon="webhook" href="/products/webhooks">
    Transfer and swap notifications
  </Card>
</CardGroup>

## Next Steps

* [Get a transfer quote](/api-reference) using the API Reference
* [Execute your first swap](/api-reference) with detailed examples
* [Set up webhooks](/products/webhooks) for real-time notifications