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

# Swaps

> Convert stablecoins on Solana — create a swap, deposit, and track settlement.

Swaps convert one Solana SPL token into another (e.g. USDC → EURC). You receive a **deposit address**; once funded, RemitFlex executes the conversion and pays out to your destination wallet.

Every swap is tied to a **customer** under your organisation. Omit `customerId` to use your org's primary customer (created at signup).

**Required scopes:** `fx:read`, `transfers:read`, `transfers:write`

## When to use swaps

* Same-chain stablecoin conversion on Solana
* Treasury FX (USDC → EURC)
* Payout preparation before a local off-ramp partner (manual today)

For cross-chain collection, use [Payment routes](/products/payment-routes) instead.

## Lifecycle

| Status                             | Meaning                                 |
| ---------------------------------- | --------------------------------------- |
| `awaiting_deposit`                 | Waiting for deposit to `depositAddress` |
| `deposit_received`                 | Deposit detected on-chain               |
| `swapping`                         | Conversion executing                    |
| `completed`                        | Output sent to `destinationAddress`     |
| `failed` / `expired` / `cancelled` | Terminal states                         |

## Create a swap

```bash theme={null}
curl -X POST https://api.remitflex.io/v1/swaps \
  -H "Authorization: Bearer $REMITFLEX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "USDC",
    "to": "EURC",
    "amount": 100,
    "destinationAddress": "YOUR_SOLANA_WALLET",
    "customerId": "optional-customer-uuid"
  }'
```

| Field                | Description                                       |
| -------------------- | ------------------------------------------------- |
| `from` / `to`        | Currency codes (see `GET /v1/rates/currencies`)   |
| `amount`             | Human-readable input amount                       |
| `destinationAddress` | Solana address receiving output tokens            |
| `customerId`         | Optional. Defaults to your org's primary customer |

Send the `from` token to `depositAddress` before `expiresAt`.

## List swaps by customer

```bash theme={null}
curl "https://api.remitflex.io/v1/swaps?customerId=CUSTOMER_UUID" \
  -H "Authorization: Bearer $REMITFLEX_API_KEY"
```

## Track and cancel

```bash theme={null}
# Status
curl https://api.remitflex.io/v1/swaps/{id} \
  -H "Authorization: Bearer $REMITFLEX_API_KEY"

# Cancel (only while awaiting_deposit)
curl -X POST https://api.remitflex.io/v1/swaps/{id}/cancel \
  -H "Authorization: Bearer $REMITFLEX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

## Failed swaps

When a swap reaches `failed`, the `errorMessage` field contains a **human-readable** reason — never raw Solana simulation logs or program errors.

```json theme={null}
{
  "status": "failed",
  "errorMessage": "This conversion could not be completed because there was not enough SOL to pay network fees. Please contact support with your swap ID — your deposit will be reviewed."
}
```

Common causes include insufficient fee-payer balance, slippage beyond tolerance, or on-chain simulation failure. Surface `errorMessage` to your user and include the swap `id` when contacting RemitFlex support.

The same sanitized message appears on swap rows in [`GET /transactions`](/api-reference/list-transactions) under `receipt.errorMessage`.

## API reference

<CardGroup cols={2}>
  <Card title="Create swap" icon="plus" href="/api-reference/create-swap">`POST /swaps`</Card>
  <Card title="List swaps" icon="list" href="/api-reference/list-swaps">`GET /swaps`</Card>
  <Card title="Get swap" icon="eye" href="/api-reference/get-swap">`GET /swaps/{id}`</Card>
  <Card title="Rates" icon="chart-line" href="/products/rates">Check FX before creating</Card>
</CardGroup>