Skip to main content
Swaps exchange one cryptocurrency for another within the same blockchain network. Convert between stablecoins like USDC and USDT without bridging across chains.

​
How Swaps Work

Swaps execute immediately upon creation:
1

Create swap request

Specify source currency, destination currency, and amount to exchange.
2

Automatic execution

HIFI executes the swap at the current market rate.
3

Completion

Receive the swapped currency in the destination wallet.

​
Creating Swaps

Use the Create Swap endpoint to exchange currencies on the same chain. 
curl -X POST "https://sandbox.hifibridge.com/v2/wallets/swaps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "1ab3e6e0-4839-4dbe-89c3-b06d9645ae86",
    "source": {
      "userId": "usr_abc123",
      "chain": "POLYGON",
      "currency": "usdc",
      "amount": "100"
    },
    "destination": {
      "userId": "usr_abc123",
      "chain": "POLYGON",
      "currency": "usdt"
    }
  }'
The response contains the swap details and execution results: 
{
  "transferType": "WALLET.SWAP",
  "transferDetails": {
    "id": "swp_abc123",
    "requestId": "1ab3e6e0-4839-4dbe-89c3-b06d9645ae86",
    "status": "COMPLETED",
    "createdAt": "2025-08-20T03:55:29.437108+00:00",
    "updatedAt": "2025-08-20T03:55:31.837+00:00",
    "source": {
      "currency": "usdc",
      "amount": 100,
      "chain": "POLYGON",
      "userId": "usr_abc123"
    },
    "destination": {
      "currency": "usdt",
      "userId": "usr_abc123",
      "amount": 100,
      "chain": "POLYGON",
      "walletAddress": "0xe5727a4B1d93A26D6A7Adfaae145EFa41ED7f204"
    },
    "quoteInformation": {
      "sendGross": {
        "amount": "100",
        "currency": "usdc"
      },
      "sendNet": {
        "amount": "100",
        "currency": "usdc"
      },
      "receiveGross": {
        "amount": "100",
        "currency": "usdt"
      },
      "receiveNet": {
        "amount": "100",
        "currency": "usdt"
      },
      "rate": "1",
      "expiresAt": "2025-08-20T03:55:59.539+00:00"
    },
    "billingInformation": {
      "fees": [
        {
          "id": "fee_xyz789",
          "amount": 0.01,
          "currency": "USD",
          "type": "EXCHANGE_FEE",
          "timing": "ON_INVOICE"
        }
      ]
    },
    "error": null,
    "errorDetails": null
  }
}
​
transferDetails.id
string
Unique swap ID. Use this to check status using the Retrieve Swap endpoint.
​
transferDetails.status
string
Swap status. Swaps typically complete immediately. See Transaction Status for details.
​
transferDetails.source
object
Source wallet details including currency, amount, chain, and user information.
​
transferDetails.destination
object
Destination wallet details including currency, amount received, chain, and user information.
​
transferDetails.quoteInformation
object
Swap quote details including exchange rate, amounts sent and received.
​
transferDetails.billingInformation
object
Fee information for the swap. Contains an array of fees with their timing (ON_INVOICE or ON_TRANSACTION).
For detailed field documentation, see the Create Swap API reference.

​
Transaction Status

Swaps typically complete within seconds:
StatusDescription
PENDINGSwap request created and processing
COMPLETEDSwap successfully executed
FAILEDSwap failed (check error and errorDetails for specifics)
CANCELLEDSwap was cancelled before execution
Status Updates: Subscribe to SWAP.CREATE and SWAP.UPDATE webhook events to receive real-time status notifications. See Webhooks for setup instructions.

​
Tracking Swaps

Monitor swap status using the Retrieve Swap endpoint. Request: 
curl -X GET "https://sandbox.hifibridge.com/v2/wallets/swaps/swp_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
The retrieve response includes current swap status: 
{
  "transferType": "WALLET.SWAP",
  "transferDetails": {
    "id": "swp_abc123",
    "status": "COMPLETED",
    "quoteInformation": {
      "rate": "1",
      "receiveNet": {
        "amount": "100",
        "currency": "usdt"
      }
    }
  }
}
​
transferDetails.status
string
Current swap status. See Transaction Status for all possible statuses.

​
Supported Swap Pairs

Currently supported swap combinations:
ChainSupported Pairs
PolygonUSDC ↔ USDT, USDC ↔ USDG, USDT ↔ USDG
EthereumUSDC ↔ USDT, USDC ↔ USDG, USDT ↔ USDG
SolanaUSDC ↔ USDT
Coming Soon: Additional chains and token pairs will be added. Contact support if you need specific swap pairs.

​
Key Concepts

You can specify the amount in either source or destination:Source amount (you send exactly 100 USDC):
{
  "source": {
    "currency": "usdc",
    "amount": "100"
  },
  "destination": {
    "currency": "usdt"
  }
}
Destination amount (you receive exactly 100 USDT):
{
  "source": {
    "currency": "usdc"
  },
  "destination": {
    "currency": "usdt",
    "amount": "100"
  }
}
Provide amount in only one side - the system calculates the other based on the current rate.
The quoteInformation.rate shows the exchange rate between currencies:
  • 1:1 stablecoins (USDC ↔ USDT): Rate is typically “1”
  • Market rates: Rates may vary slightly based on liquidity
Always verify receiveNet to see the exact amount you’ll receive after any fees.
The billingInformation.fees array shows all applicable fees:EXCHANGE_FEE: Conversion fee for the swap
  • timing: ON_INVOICE: Billed on your monthly invoice (not deducted from swap)
  • timing: ON_TRANSACTION: Deducted from the swap amount
GAS_FEE: Blockchain transaction fees (if applicable)Check timing to understand when fees are charged.
Swap to external wallets (not managed by HIFI) by providing externalWalletId or walletAddress:
{
  "destination": {
    "chain": "POLYGON",
    "currency": "usdt",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
  }
}
Or use a registered external wallet:
{
  "destination": {
    "chain": "POLYGON",
    "currency": "usdt",
    "externalWalletId": "ext_xyz789"
  }
}
External wallet swaps may require gas sponsorship enrollment. Use userId for HIFI wallets when possible.
Understanding the differences:Swaps: Exchange currencies on the same chain (USDC → USDT on Polygon)Bridges: Move same currency across chains (USDC on Polygon → USDC on Ethereum)Transfers: Move same currency to another wallet on same chain (USDC wallet A → USDC wallet B on Polygon)

​
Sample Code

​
Basic swap flow

1

Create swap

curl -X POST "https://sandbox.hifibridge.com/v2/wallets/swaps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "1ab3e6e0-4839-4dbe-89c3-b06d9645ae86",
    "source": {
      "userId": "usr_abc123",
      "chain": "POLYGON",
      "currency": "usdc",
      "amount": "100"
    },
    "destination": {
      "userId": "usr_abc123",
      "chain": "POLYGON",
      "currency": "usdt"
    }
  }'
2

Verify completion

The response will show status COMPLETED for successful swaps. Check:
  • destination.amount - Amount received
  • quoteInformation.rate - Exchange rate used
  • billingInformation.fees - Any applicable fees
3

Handle errors

If status is FAILED:
  • Check error field for error type
  • Review errorDetails for specific failure reason
  • Common issues: insufficient balance, unsupported pair, network congestion

​
Swap with exact output amount

1

Specify destination amount

When you need to receive an exact amount:
curl -X POST "https://sandbox.hifibridge.com/v2/wallets/swaps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "1ab3e6e0-4839-4dbe-89c3-b06d9645ae86",
    "source": {
      "userId": "usr_abc123",
      "chain": "POLYGON",
      "currency": "usdc"
    },
    "destination": {
      "userId": "usr_abc123",
      "chain": "POLYGON",
      "currency": "usdt",
      "amount": "100"
    }
  }'
2

Check source amount used

The response shows how much source currency was needed:
  • source.amount - Amount deducted from source wallet
  • quoteInformation.sendNet - Net amount sent after fees

​
Getting Help