HIFI Docs

Overview

Create swap request

Specify source currency, destination currency, and amount to exchange. The swap is created with OPEN_QUOTE status.

Accept the swap

Accept the swap using the Accept Swap endpoint to execute the exchange.

Completion

Receive the swapped currency in the destination wallet once the swap is accepted and executed.

Supported Pairs

Source	Destination
Polygon - USDC	Polygon (USDT), Ethereum (USDT, USDG), Solana (USDT, USDG)
Polygon - USDT	Polygon (USDC), Ethereum (USDC, USDG), Solana (USDC, USDG)
Ethereum - USDC	Polygon (USDT), Ethereum (USDT, USDG), Solana (USDT, USDG)
Ethereum - USDT	Polygon (USDC), Ethereum (USDC, USDG), Solana (USDC, USDG)
Ethereum - USDG	Polygon (USDC, USDT), Ethereum (USDC, USDT), Solana (USDC, USDT)
Solana - USDC	Polygon (USDT), Ethereum (USDT, USDG), Solana (USDT, USDG)
Solana - USDT	Polygon (USDC), Ethereum (USDC, USDG), Solana (USDC, USDG)
Solana - USDG	Polygon (USDC, USDT), Ethereum (USDC, USDT), Solana (USDC, USDT)

USDG swapping is available upon request. Please contact support to get access.

Fees

The Swap endpoint uses a two-part billing model:

Market quote fees: Fees are included in the swap quote response. Check the quoteInformation fields (sendNet, receiveNet) to see the amounts after market fees are applied.
Gas fees: Network gas fees are charged separately on your invoice and are not included in the quote response.

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. Swaps are created in PENDING status and require acceptance:

Response

{
  "transferType": "WALLET.SWAP",
  "transferDetails": {
    "id": "swp_abc123",
    "requestId": "1ab3e6e0-4839-4dbe-89c3-b06d9645ae86",
    "status": "OPEN_QUOTE",
    "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"
    },
    "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 are created with OPEN_QUOTE status and must be accepted before execution. 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.

Show properties

sendGross

object

Total source currency amount sent.

sendNet

object

Net source currency amount after fees (if any).

receiveGross

object

Total destination currency amount received before fees.

receiveNet

object

Actual destination currency amount received. This is the amount that will be in your destination wallet.

rate

string

Exchange rate between source and destination currencies.

expiresAt

string

Quote expiration timestamp (if applicable).

For detailed field documentation, see the Create Swap API reference.

Accepting Swaps

All swaps are created in PENDING status and require explicit acceptance before execution. Use the Accept Swap endpoint to accept and execute a swap. Request:

curl -X POST "https://sandbox.hifibridge.com/v2/wallets/swaps/swp_abc123/accept" \
  -H "Authorization: Bearer YOUR_API_KEY"

The accept endpoint returns the same swap details structure as the create endpoint, with updated status:

Response

{
  "transferType": "WALLET.SWAP",
  "transferDetails": {
    "id": "swp_abc123",
    "requestId": "1ab3e6e0-4839-4dbe-89c3-b06d9645ae86",
    "status": "CRAETED",
    "createdAt": "2025-08-20T03:55:29.437108+00:00",
    "updatedAt": "2025-08-20T04:08:10.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"
    },
    "error": null,
    "errorDetails": null
  }
}

transferDetails.status

string

Swap status after acceptance. Transitions from PENDING to COMPLETED upon successful acceptance. See Transaction Status for details.

Required Step: All swaps must be accepted before execution. After creating a swap, always call the accept endpoint to execute the exchange.

Transaction Status

Swaps progress through the following statuses:

Status	Description
OPEN_QUOTE	Swap quote requested and waiting for acceptance
CREATED	Swap request accepted
PENDING	Swap processing
COMPLETED	Swap successfully executed
FAILED	Swap failed (check `error` and `errorDetails` for specifics)
QUOTE_FAILED	Swap quote is expired or invalid

Status Updates: Subscribe to SWAP.TRANSACTION.CREATE and SWAP.STATUS.* 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:

Response

{
  "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"
    },
    "error": null,
    "errorDetails": null
  }
}

transferDetails.status

string

Current swap status. See Transaction Status for all possible statuses.

Listing Swaps

Retrieve a list of all swaps associated with users under your organization using the List Swaps endpoint. Swaps are returned sorted by creation date, with the most recent swaps appearing first. Request:

curl -X GET "https://sandbox.hifibridge.com/v2/wallets/swaps?userId=usr_abc123&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters:

userId

string

required

Filter swaps by a specific user ID. If omitted, returns swaps for all users under your organization.

limit

string

required

Number of swaps to return. Defaults to 10, maximum is 100.

createdBefore

string

required

Filter swaps created before this date. ISO format: YYYY-MM-DD.

createdAfter

string

required

Filter swaps created after this date. ISO format: YYYY-MM-DD.

Response:

Response

{
  "count": 2,
  "data": [
    {
      "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-20T04:08:10.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"
        },
        "error": null,
        "errorDetails": null
      }
    },
    {
      "transferType": "WALLET.SWAP",
      "transferDetails": {
        "id": "swp_def456",
        "requestId": "2cd4f7f1-5940-5ecf-9ad4-c17e0756bf97",
        "status": "PENDING",
        "createdAt": "2025-08-20T02:30:15.123456+00:00",
        "updatedAt": "2025-08-20T02:30:15.123456+00:00",
        "source": {
          "currency": "usdt",
          "amount": 50,
          "chain": "POLYGON",
          "userId": "usr_abc123"
        },
        "destination": {
          "currency": "usdc",
          "userId": "usr_abc123",
          "chain": "POLYGON",
          "walletAddress": "0xe5727a4B1d93A26D6A7Adfaae145EFa41ED7f204"
        },
        "quoteInformation": {
          "sendGross": {
            "amount": "50",
            "currency": "usdt"
          },
          "sendNet": {
            "amount": "50",
            "currency": "usdt"
          },
          "receiveGross": {
            "amount": "50",
            "currency": "usdc"
          },
          "receiveNet": {
            "amount": "50",
            "currency": "usdc"
          },
          "rate": "1",
          "expiresAt": "2025-08-20T02:35:15.123456+00:00"
        },
        "error": null,
        "errorDetails": null
      }
    }
  ],
  "nextCursor": "2025-08-20T02:30:15.123456+00:00"
}

count

integer

Total number of swaps returned in this response.

data

array

Array of swap objects. Each object follows the same structure as the swap details returned by the retrieve endpoint.

nextCursor

string

Timestamp cursor for pagination. Use this value with createdBefore parameter to fetch the next page of results.

Pagination: To fetch more swaps, use the nextCursor value as the createdBefore parameter in your next request. Continue until count is less than your limit, indicating you’ve reached the end.

Key Concepts

Amount Specification

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.

Exchange Rates

The quoteInformation.rate shows the exchange rate between currencies. Rates may vary slightly based on liquidity Always verify receiveNet to see the exact amount you’ll receive after any fees.

External Wallet Swaps

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

Swap vs Bridge vs Transfer

Understanding the differences:Swaps: Exchange different currencies on the same/across chain (USDC → USDT)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

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"
    }
  }'

The response will show status OPEN_QUOTE. Save the swap id from the response.

Accept the swap

Accept the swap to execute the exchange:

curl -X POST "https://sandbox.hifibridge.com/v2/wallets/swaps/swp_abc123/accept" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response will show status CRAETED for successful swap request acceptance.

Verify completion

Review the swap details to confirm:

Status – should be COMPLETED
Destination Amount – the amount received

Handle errors

If status is FAILED:

Check error field for error type
Review errorDetails for specific failure reason
Common issues: insufficient balance, unsupported pair, not enough liquidity

Getting Help

📧 Email: [email protected]
💬 Slack: Message us in our shared Slack channel

Wallet Transfers - Same-chain transfers without currency exchange
Bridging - Cross-chain asset movement
Wallets - Understand wallet addresses and balances
Webhooks - Real-time swap status notifications
API Reference - Complete endpoint documentation

Introduction

Core concepts

Features

Compliance

References

Swaps

Overview

Supported Pairs

Fees

Creating Swaps

Accepting Swaps

Transaction Status

Tracking Swaps

Listing Swaps

Key Concepts

Sample Code

Basic swap flow

Getting Help

Introduction

Core concepts

Features

Compliance

References

​Overview

​Supported Pairs

​Fees

​Creating Swaps

​Accepting Swaps

​Transaction Status

​Tracking Swaps

​Listing Swaps

​Key Concepts

​Sample Code

​Basic swap flow

​Getting Help

​Related Resources

Overview

Supported Pairs

Fees

Creating Swaps

Accepting Swaps

Transaction Status

Tracking Swaps

Listing Swaps

Key Concepts

Sample Code

Basic swap flow

Getting Help

Related Resources