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

# Swap

> Convert between stablecoins held in a HIFI Wallet.

A Swap converts one stablecoin held in a [HIFI Wallet](/v3/core/wallets/hifi-wallet) into another. The destination can be the same wallet, a different HIFI Wallet, or an [External Wallet](/v3/core/wallets/external-wallet) - and can be on a different chain than the source. Like Onramp, Offramp, and Bridge, it's a **quote-then-accept** flow.

For supported pairs check out [Supported Onchain Asset](/v3/docs/references/onchain-assets).

<Info>
  HIFI sources liquidity from both CEXs and DEXs to ensure the best execution.
</Info>

## Create a swap (quote)

Requires an `Idempotency-Key` header. Either `source.amount` or `destination.amount` can drive the conversion, not both.

The source and destination chains are derived from source wallet and destination wallet.

**Request**

```shell theme={null}
curl -X POST https://sandbox.hifi.com/v3/swaps \
  -H "Idempotency-Key: <unique-key>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "requestId": "154116da-3f51-4ed6-bb13-85f39183e176",
    "source": {
        "amount": "100",
        "currency": "USDC",
        "walletId": "{{wallet_id}}"
    },
    "destination": {
        "currency": "USDT",
        "walletId": "{{wallet_id}}"
    }
  }'
```

**Response**

```json theme={null}
{
    "id": "swp_3OGYSITbryTfff41XfaPx",
    "requestId": "154116da-3f51-4ed6-bb13-85f39183e176",
    "status": "OPEN_QUOTE",
    "error": null,
    "errorDetails": null,
    "amount": "100",
    "source": {
        "userId": "usr_WiamhlKfB151vdSch1Ble",
        "walletId": "wlt_cq1lx3hQArvCUSxdGsSC1",
        "currency": "USDC",
        "chain": "ETHEREUM"
    },
    "destination": {
        "userId": "usr_WiamhlKfB151vdSch1Ble",
        "walletId": "wlt_cq1lx3hQArvCUSxdGsSC1",
        "currency": "USDC",
        "chain": "ETHEREUM"
    },
    "receipt": {
        "transactionHash": null
    },
    "quote": {
        "sendGross": {
            "amount": "100.00",
            "currency": "USDC"
        },
        "sendNet": {
            "amount": "100.00",
            "currency": "USDC"
        },
        "receiveGross": {
            "amount": "100.06",
            "currency": "USDT"
        },
        "receiveNet": {
            "amount": "100.06",
            "currency": "USDT"
        },
        "rate": "1.00060",
        "expiresAt": "2026-07-27T01:04:48.202+00:00"
    },
    "createdAt": "2026-07-27T01:04:18.142Z",
    "updatedAt": "2026-07-27T01:04:18.202Z"
}
```

<Info>
  `quote.expiresAt` reflects when the quoted rate was locked in.
</Info>

## Accept a swap quote

Checks the source wallet's on-chain balance against the quoted amount before proceeding.

**Request**

```shell theme={null}
curl -X POST https://sandbox.hifi.com/v3/swaps/swp_3OGYSITbryTfff41XfaPx/quote/accept \
  -H "Idempotency-Key: <unique-key>" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response**

```json theme={null}
{
    "id": "swp_QW1e2r3t4y",
    "status": "CREATED",
    "...": "other fields unchanged"
}
```

<Info>
  If the source wallet's balance is too low to cover the quoted amount, this returns a `200` with `status: "QUOTE_FAILED"` and `error: "INSUFFICIENT_BALANCE"` rather than an error response.
</Info>

## Status

| Status | Meaning | Terminal |
| - | - | - |
| `OPEN_QUOTE` | Quote ready, awaiting accept. | No |
| `QUOTE_FAILED` | No route/liquidity for the pair, or insufficient balance at accept time. | Yes |
| `CREATED` | Quote accepted; queued for execution. | No |
| `PENDING` | Conversion executing. | No |
| `COMPLETED` | Conversion settled. | Yes |
| `FAILED` | Execution failed. | Yes |
| `PENDING_APPROVAL` | Awaiting approval (only if `requireApproval: true` was set). | No |
| `APPROVED` | Approved; proceeding to execution. | No |
| `REJECTED` | Approval was rejected. | Yes |

## Additional information

<AccordionGroup>
  <Accordion title="Transfer approval">
    Swaps can be routed through an approval workflow before they settle - `status` shows `PENDING_APPROVAL` until someone approves it, or `REJECTED` if it's declined. 

    The quote is only generated once the transfer request is approved. Accept the quote afterward to kick off the transaction flow.

    Check out [Transfer Approval](https://docs.hifi.com/v3/features/transaction-approval) for more details.
  </Accordion>
</AccordionGroup>

## Getting Help

* 📧 **Email:** [support@hifi.com](mailto:support@hifi.com)
* 💬 **Slack:** Message us in our shared Slack channel

## Related Resources

* [Transactions Overview](/v3/core/transactions/overview) - Transactions resources
* [Bridge](/v3/core/transactions/bridge) - Move stablecoins across chains
* [Onchain Transfer](/v3/core/transactions/onchain-transfer) - Move stablecoins on the same chain
* [HIFI Wallet](/v3/core/wallets/hifi-wallet) - Provision wallets and read balances


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.