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

# Cross Currency Payouts

> Allows you to convert funds between currency pairs.

The Endpoint allows you to convert funds between currency pairs.

***

## Request parameters

Pass these as request body on the `/fx-quotes` endpoint.

<ParamField body="to_currency" type="string">
  The currency you want to convert to. ISO 4217 format.
</ParamField>

<ParamField body="from_currency" type="string">
  The currency you want to convert from. ISO 4217 format.
</ParamField>

<ParamField body="amount_to" type="number">
  The amount you want to convert to. This is conditionally required.
</ParamField>

<ParamField body="amount_from" type="number">
  The amount you want to convert from. This is conditionally required.
</ParamField>

<ParamField body="account_id" type="string">
  The ID of the account from which to debit the funds.
</ParamField>

<ParamField body="counterparty_id" type="string" required>
  The ID of the counterparty involved in the exchange.
</ParamField>

<ParamField body="payment_detail_id" type="string" required>
  The ID of the payment details associated with the exchange.
</ParamField>

***

## Convert funds between currency pairs.

You can specify either the `amount_to` or `amount_from` field, but not both. The endpoint calculates the other amount based on the current exchange rate.

<CodeGroup>
  ```bash curl -X POST https://api.nuvion.dev/fx-quotes \ theme={null}
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \ 
    -d '{
    "to_currency": "NGN",
    "from_currency": "USD",
    "amount_to": 100,
    "amount_from": 100,
    "account_id": "acc-id",
    "counterparty_id": "cp_id", //Required
    "payment_detail_id":  "pd_id", // Required
  }'
  ```
</CodeGroup>

***

## Response Parameters

<ResponseField name="id" type="string">
  Unique entity identifier.
</ResponseField>

<ResponseField name="to" type="string">
  Currency converted to.
</ResponseField>

<ResponseField name="rate" type="number">
  The exchange rate applied to the conversion.
</ResponseField>

<ResponseField name="from" type="string">
  Currency converted from
</ResponseField>

<ResponseField name="quote" type="object">
  The quote details associated with this forex exchange.

  <Expandable title="quote fields">
    <ResponseField name="used_at" type="null">
      Timestamp for when the quote was used in a forex exchange.
    </ResponseField>

    <ResponseField name="expires_at" type="number">
      Timestamp for when the quote expires.
    </ResponseField>

    <ResponseField name="used_in_payment_id" type="null">
      The ID of the payment that utilized this quote.
    </ResponseField>

    <ResponseField name="valid_for" type="number">
      The duration in seconds for which the quote is valid.
    </ResponseField>

    <ResponseField name="status" type="string">
      The current status of the quote. Example `active`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created" type="number">
  Timestamp for when the forex exchange was created.
</ResponseField>

<ResponseField name="updated" type="number">
  Timestamp for when the forex exchange was last updated.
</ResponseField>

```json Example theme={null}
{
  "id": "01HXYZ5678EFGH",
  "to": "NGN",
  "from": "USD",
  "rate": 750,
  "quote": {
    "used_at": null,
    "expires_at": 1700000000,
    "used_in_payment_id": null,
    "valid_for": 300,
    "status": "active"
  },
  "created": 1690000000,
  "updated": 1690000000
}
```

## Initiate Transfer

To initiate a cross currency transfer, you can use the `id` of the forex exchange in the `fx_quote_id` field when creating a payment. This will apply the exchange rate from the forex exchange to the payment.

### Request parameters

<ParamField body="account_id" type="string" required>
  The ID of the source account to debit.
</ParamField>

<ParamField body="payment_detail_id" type="string" required>
  The ID of the payment detail record with `payment_method: "momo-transfer"`.
</ParamField>

<ParamField body="payment_type" type="string" required>
  The payment type of the transfer. It can be bank-transfer, momo-transfer, stablecoin-transfer, and book-transfer.
</ParamField>

<ParamField body="narration" type="string" required>
  Transfer description. Maximum 100 characters.
</ParamField>

<ParamField body="unique_reference" type="string" required>
  Idempotency key. Maximum 64 characters.
</ParamField>

<ParamField body="fx_quote_id" type="string" required>
  The ID of the forex exchange quote to apply to this transfer.
</ParamField>

### Request

```bash theme={null}
curl -X POST https://api.nuvion.dev/transfers \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_01HXYZ5678EFGH",
    "payment_detail_id": "pd_01KM37FABCD456EFG789HIJ012",
    "narration": "Invoice payment INV-2025-001",
    "payment_type": "bank-transfer",
    "currency": "USD",
    "unique_reference": "PAY-2025-001",
    "fx_quote_id": "01KREAZRKT1WZ0NPWJER3NC78P"
  }'
```