Skip to main content
Conversions let you exchange funds between currencies — for example, converting NGN to USD after collecting a payment, or moving USDT into local currency before a payout. You can request a real-time quote to see the exact rate and output amount before committing.

​
How conversions work

1

Get a quote

Request a conversion quote by specifying the source currency, target currency, and amount. The response includes a locked exchange rate and a quote_id valid for a short window.
2

Execute the conversion

Submit a conversion request with the quote_id from the previous step to execute at the quoted rate. If the quote has expired, the conversion will use the current market rate.
3

Confirm the result

The conversion response confirms the exact amounts exchanged, the rate applied, and the conversion status.
Quotes expire. Execute your conversion before the expires_at timestamp to guarantee the quoted rate. If you submit after expiry, the current market rate applies.

​
Get a quote

Request a conversion quote before executing. 
POST /api/v1/conversions/quotes

​
Request fields

​
body.from_currency
string
required
The currency you are converting from (e.g., NGN, USD, USDT).
​
body.to_currency
string
required
The currency you are converting to (e.g., USD, GHS, BTC).
​
body.amount
number
required
The amount of from_currency to convert.
curl -X POST https://api.syncgrampay.com/api/v1/conversions/quotes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_currency": "NGN",
    "to_currency": "USD",
    "amount": 500000
  }'
Response 
{
  "quote_id": "qte_01hxyz",
  "from_currency": "NGN",
  "to_currency": "USD",
  "from_amount": "500000.00",
  "to_amount": "312.50",
  "exchange_rate": "0.000625",
  "expires_at": "2024-06-15T14:35:00Z"
}

​
Quote response fields

​
quote_id
string
Unique identifier for this quote. Pass this to the conversion endpoint to lock the rate.
​
from_currency
string
The source currency code.
​
to_currency
string
The target currency code.
​
from_amount
string
The amount being converted from, as a decimal string.
​
to_amount
string
The amount you will receive in the target currency, as a decimal string.
​
exchange_rate
string
The exchange rate applied, as a decimal string.
​
expires_at
string
ISO 8601 timestamp when this quote expires. Execute the conversion before this time to lock the rate.

​
Execute a conversion

Convert funds at the quoted or current market rate. 
POST /api/v1/conversions

​
Request fields

​
body.from_currency
string
required
The currency you are converting from.
​
body.to_currency
string
required
The currency you are converting to.
​
body.amount
number
required
The amount of from_currency to convert.
​
body.quote_id
string
required
The quote_id from a prior quote request. Providing a valid, unexpired quote locks the exchange rate.
curl -X POST https://api.syncgrampay.com/api/v1/conversions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_currency": "NGN",
    "to_currency": "USD",
    "amount": 500000,
    "quote_id": "qte_01hxyz"
  }'
Response 
{
  "conversion_id": "cvn_01habc",
  "status": "COMPLETED",
  "from_currency": "NGN",
  "to_currency": "USD",
  "from_amount": "500000.00",
  "to_amount": "312.50",
  "exchange_rate": "0.000625",
  "quote_id": "qte_01hxyz",
  "created_at": "2024-06-15T14:33:00Z"
}

​
List conversions

Retrieve a paginated list of conversions for your organization. 
GET /api/v1/conversions

​
Query parameters

​
query.from_currency
string
Filter by source currency code.
​
query.to_currency
string
Filter by target currency code.
​
query.status
string
Filter by conversion status, e.g. COMPLETED.
​
query.start_date
string
ISO 8601 start date for the filter range.
​
query.end_date
string
ISO 8601 end date for the filter range.
​
query.limit
number
default:"50"
Number of results to return. Maximum 100.
​
query.offset
number
default:"0"
Number of results to skip for pagination.
curl "https://api.syncgrampay.com/api/v1/conversions?from_currency=NGN&to_currency=USD&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response 
{
  "total": 42,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "conversion_id": "cvn_01habc",
      "status": "COMPLETED",
      "from_currency": "NGN",
      "to_currency": "USD",
      "from_amount": "500000.00",
      "to_amount": "312.50",
      "exchange_rate": "0.000625",
      "quote_id": "qte_01hxyz",
      "created_at": "2024-06-15T14:33:00Z"
    }
  ]
}

​
Get a conversion

Retrieve the details of a single conversion by ID. 
GET /api/v1/conversions/{conversion_id}

curl https://api.syncgrampay.com/api/v1/conversions/cvn_01habc \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Conversion response fields

​
conversion_id
string
Unique identifier for the conversion.
​
status
string
Current status of the conversion. Typically COMPLETED once processed.
​
from_currency
string
The source currency code.
​
to_currency
string
The target currency code.
​
from_amount
string
The amount converted from, as a decimal string.
​
to_amount
string
The amount received in the target currency, as a decimal string.
​
exchange_rate
string
The exchange rate applied at execution time, as a decimal string.
​
quote_id
string
The quote ID used to lock the rate, if one was provided.
​
created_at
string
ISO 8601 timestamp when the conversion was executed.