Transfers & Swaps - XentFi API Documentation

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.

What’s Possible?

💰 Transfers

Send assets from deposit addresses or master wallets to any blockchain address

🔄 Token Swaps

Exchange tokens on the same blockchain using DEX aggregators

⚡ Quotes

Get real-time quotes with gas estimates before executing

⛽ Gas Estimation

Estimate gas fees before executing transfers or swaps

Transfer Operations

Create Transfer Quote

Generate a quote for transferring assets from a deposit address:

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:

{
    "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:

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:

{
    "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:

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:

{
    "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

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:

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:

{
    "quote": {
        // Quote object containing swap details
    }
}

Execute Address Swap

Execute a swap using a quote:

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:

{
    "hash": "0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb"
}

Create Master Swap Quote

Generate a swap quote from a master wallet:

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

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

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

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

Monitor Gas Fees

Use estimate-gas endpoints before execution
Check callGasLimit and verificationGasLimit
Compare gas costs across blockchains
Consider L2 networks for lower fees

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

Troubleshooting

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

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

Transaction not completing

Possible causes:

Network congestion
Insufficient gas
Blockchain issues

Solutions:

Check transaction status via hash
Increase gas limit
Monitor blockchain status

Gas estimation too high

Possible causes:

Network congestion
Complex transaction path

Solutions:

Wait for lower network traffic
Use L2 networks
Batch transactions when possible

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

Master Wallets

Source and destination wallets

Deposit Addresses

Address management and monitoring

Webhooks

Transfer and swap notifications

Next Steps

Get a transfer quote using the API Reference
Execute your first swap with detailed examples
Set up webhooks for real-time notifications

​Overview

​What’s Possible?

💰 Transfers

🔄 Token Swaps

⚡ Quotes

⛽ Gas Estimation

​Transfer Operations

​Create Transfer Quote

​Estimate Transfer Gas

​Master Wallet Transfer

​Estimate Master Transfer Gas

​Swap Operations

​Create Address Swap Quote

​Execute Address Swap

​Create Master Swap Quote

​Execute Master Swap

​Address vs Master Wallet Operations

​Gas Estimation Fields

​Best Practices

​Troubleshooting

​Webhook Events

​API Reference

​Related Products

Master Wallets

Deposit Addresses

Webhooks

​Next Steps

Overview

What’s Possible?

Transfer Operations

Create Transfer Quote

Estimate Transfer Gas

Master Wallet Transfer

Estimate Master Transfer Gas

Swap Operations

Create Address Swap Quote

Execute Address Swap

Create Master Swap Quote

Execute Master Swap

Address vs Master Wallet Operations

Gas Estimation Fields

Best Practices

Troubleshooting

Webhook Events

API Reference

Related Products

Next Steps