# Initiate FX Swap

Create an FX swap request from the business NGN wallet into a target currency wallet. The request is created in pending state and can be tracked using the swap ID and transaction reference.

## API Endpoint

**POST**  
`/api/v1/fx/swap`

### Headers

- **Authorization**
  - BearerAuth
  - `Authorization: Bearer <token>`

### Request Body

- `application/json`

| Field               | Type              | Description                                       |
|---------------------|-------------------|---------------------------------------------------|
| source_amount       | number            | Format: `float`                                   |
| target_currency     | string            | Length: `3 <= length <= 3`                        |
| negotiated_rate?    | number|null       | Format: `float`                                   |
| source_reference     | string            |                                                   |

### Response Body

#### 201  application/json

```json
{
  "requestId": "f6b79ec2-cf4e-4a6f-9ffd-cd61f33ec8ea",
  "requestTimestamp": "2026-04-21 14:08:27",
  "message": "FX swap initiated successfully.",
  "statusCode": 201,
  "data": {
    "id": "01966f94-0ea8-7309-80e2-4a8676e8d5e2",
    "destinationCurrency": "USD",
    "sourceCurrency": "NGN",
    "debitedAmount": {
      "value": 250000,
      "currency": "NGN",
      "formatted": "NGN 250,000.00"
    },
    "creditedAmount": {
      "value": 157.68,
      "currency": "USD",
      "formatted": "USD 157.68"
    },
    "status": "pending",
    "reference": "TRX_6WZSIYEK43",
    "sourceReference": "SRC_FX_20260421_001",
    "negotiatedRate": 1585.5,
    "createdAt": "2026-04-21T14:08:27+00:00"
  }
}
```

#### Error Responses

#### 400  application/json

```json
{
  "requestId": "0d6c4691-16be-4aa4-a6b0-30198cd59fef",
  "requestTimestamp": "2026-04-21 14:09:04",
  "message": "Insufficient balance. Available: NGN 100000, Requested: NGN250000",
  "statusCode": 400
}
```

#### 401  application/json

```json
{
  "requestId": "f006ad7b-096c-4254-8c7e-2d23a55b0b0e",
  "requestTimestamp": "2026-04-21 14:09:40",
  "message": "Unauthenticated.",
  "statusCode": 401
}
```

#### 422  application/json

```json
{
  "requestId": "f006ad7b-096c-4254-8c7e-2d23a55b0b0e",
  "requestTimestamp": "2026-04-21 14:10:03",
  "message": "The given data was invalid.",
  "errors": {
    "target_currency": [
      "The selected target currency is invalid."
    ]
  },
  "statusCode": 422
}
```

### cURL Example

```bash
curl -X POST "https://atlas.tryduplo.com/api/v1/fx/swap" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_amount": 250000,
    "target_currency": "USD",
    "source_reference": "SRC_FX_20260421_001"
  }'
```

Last updated on 5/27/2026.