Rates

Rates play a crucial role in supporting currency swaps and cross withdrawals. When working with the Rate API, there are 3 possible steps,

Get Rate,
Create Rate
Refresh Rate

Depending on your use case, the Get Rate step is optional and can be ignored. This is because, the Create Rate and Refresh Rate steps can be combined to serve the same purpose.

Let's look at each of this steps in detail.

🚧
Supported currencies
Before retrieving rate, you have to ensure that the currency pair is supported by Shutterscore and enabled on your account. Click here to see the currency pairs supported by Shutterscore.

Get Rate
Get rate is used when both of the currencies to be converted are unknown. It's also used in situations when the user has not yet committed to performing a transaction and is still browsing or exploring your application.

None of the currencies are known
In this scenario, the user has not selected a currency, hence the conversion currencies are unknown. However, the merchant may want to return the convertible currencies and also provide an instant rate as the user switches between currencies. The request and responses are given below. As can be seen, the response contains an array of objects with all swappable currency pairs enabled on the merchant's account

{{baseurl}}/v1/merchant/public/markets/rates

{
    "status": true,
    "statusCode": 200,
    "message": "rates setting successfully retrieved",
    "data": [
        {
            "pair": "NGN/USDT",
            "buy": {
                "fiat": "NGN",
                "asset": "USDT",
                "to_currency": "USDT",
                "from_currency": "NGN",
                "fee": 1,
                "fee_type": "PERCENTAGE"
                "refresh_in": 90,
                "rate": 741.05,
                "market": "BUY"
            },
            "sell": {
                "fiat": "NGN",
                "asset": "USDT",
                "to_currency": "NGN",
                "from_currency": "USDT",
                "fee": 1,
                "fee_type": "PERCENTAGE"
                "refresh_in": 90,
                "rate": 731.05,
                "market": "SELL"
            }
        }
    ]
}

Both currencies are known
When both currencies are known, it is important to understand and provide the source currency (from_currency) and the destination currency (to_currency).

{{baseurl}}/v1/merchant/public/markets/rates?to_currency=NGN&from_currency=USDT

{
    "status": true,
    "statusCode": 200,
    "message": "rates setting successfully retrieved",
    "data": {
        "fiat": "NGN",
        "asset": "USDT",
        "to_currency": "NGN",
        "from_currency": "USDT",
        "fee": 1,
        "fee_type": "PERCENTAGE",
        "refresh_in": 20,
        "rate": 730.55,
        "market": "SELL"
    }
}

Create Rate
Create rate is used when both of the currencies to be converted are known and the user has committed to performing a transaction by providing an amount. The amount provided can be either the source amount (from_amount) or the destination amount (to_amount) and not both. Details of the request and response from the API are provided below.

Field	Data Type	Description
from_currency	String - Currency Code. See Supported Currencies	Required - Source currency or currency who's balance you have and you want to exchange for the other
to_currency	String - Currency Code. See Supported Currencies	Required - Destination currency or currency you want to receive (or payout in the case of a withdrawal)
from_amount	Number	Required when to_amount is not provided - Amount of the source currency to want to exchange
to_amount	Number	Required when from_amount is not provided - Amount of the destination currency you'd like to receive
transaction_type	String - deposit, swap or withdrawal	Optional - the type of transaction that the rate will be used for
deposit_method	String	Optional - the deposit method for the deposit transaction. Only required in transactions that use specialised deposit methods e.g binance-pay
withdrawal_method	String	Optional - the withdrawal method for the withdrawal transaction. Only required in transactions that use specialised withdrawal methods e.g mobile-money-payout

{{baseurl}}/v1/merchant/public/rates/create

{
    "from_currency": "USDT",
    "to_currency": "GHS",
    "from_amount": 5000
}

{
    "status": true,
    "statusCode": 200,
    "message": "Rate successfully created",
    "data": {
        "from_currency": "USDT",
        "to_currency": "NGN",
        "from_amount": 5000,
        "to_amount": 3656200,
        "reference": "2212693c-e2f7-46b6-9c32-24b4d722a3e3",
        "expires_at": "2022-09-30T15:36:34.441Z",
        "settlement_time": "30",
        "fee": 36562,
        "fee_type": "FLAT",
        "rate": 731.25,
        "transaction_type": "SWAP",
        "created_at": "2022-09-30T15:35:04.465Z",
        "updated_at": "2022-09-30T15:35:04.465Z",
        "fiat": "NGN",
        "asset": "USDT",
        "used": false
    }
}

Refresh Rate
The rate created in the create rate request expires at a certain time. This time is provided by the expires_at property in the response. However, to prevent an unnecessary creation of multiple rates, expired rates can be refreshed and their expiry time extended. A reference to the rate is required to refresh the rate and extend the expiry time.

Field	Data Type	Description
reference	String	Required - the previously created rate's reference

{{baseurl}}/v1/merchant/public/rates/refresh

{
    "reference": "2212693c-e2f7-46b6-9c32-24b4d722a3e3"
}

{
    "status": true,
    "statusCode": 200,
    "message": "Swap refreshed successfully",
    "data": {
        "from_currency": "USDT",
        "to_currency": "NGN",
        "from_amount": 5000,
        "to_amount": 3656250,
        "reference": "2212693c-e2f7-46b6-9c32-24b4d722a3e3",
        "expires_at": "2022-09-30T15:50:29.365Z",
        "settlement_time": "30",
        "fee": 36562.5,
        "fee_type": "FLAT",
        "rate": 731.25,
        "transaction_type": "SWAP",
        "created_at": "2022-09-30T15:35:04.465Z",
        "updated_at": "2022-09-30T15:48:59.000Z",
        "fiat": "NGN",
        "asset": "USDT",
        "used": false
    }
}

Response properties and description

Below is a table that shows all possible response properties and their description

Field	Data Type	Description
pair	String - Currency pair. See Supported Currencies
buy	Object	Contains properties related to a BUY trade. A buy trade happens when the from_currency is a fiat currency and the to_currency is a cryptocurrency or when the from_currency is less valuable than the to_currency
sell	Object	Contains properties related to a SELL trade. A SELL trade happens when the from_currency is a cryptocurrency and the to_currency is a fiat or when the from_currency is more valuable than the to_currency
fiat	String - Currency code. See Supported Currencies	Fiat Currency
asset	String - Currency code. See Supported Currencies	Cryptocurrency
to_currency	String - Currency code. See Supported Currencies	This is the currency that will be received (in a swap) or withdrawn (in a withdrawal)
from_currency	String - Currency code. See Supported Currencies	This is the currency that will be given or exchanged to get another currency
fee	Number	The fee that applies to the transaction. The fee always applies to the to_amount and is always in to_currency. That is, you will always be charged in the currency you will receive after a swap has been executed. In the get rate API, fee refers to the amount that will be determined using the fee_type to get a final fee value. In the create rate API, fee is the final fee value.
fee_type	String - FLAT or PERCENTAGE	This is the kind of fee that will apply. FLAT fee means that the exact value of the fee will be applied. On the other hand, PERCENTAGE means that the fee value is in percentage and should be calculated with the amount to get the final fee value. Please note that fee_type* does not apply to the create rate api as the final fee value has been already been calculated as fee.*
refresh_in	Number	Number of seconds it will take for the rate to expire
rate	Number	Rate
market	String - BUY or SELL	Market describes the kind of trade that will happen with this specific rate. It can either be BUY or SELL
reference	String	Unique reference to a created rate. Can be used to refresh the rate, perform swaps or execute a cross currency withdrawal.
expires_at	String	The time the rate will expire
settlement_time	Number	Applies to swaps only. It is the Number of minutes it will take before a swap becomes successful and a merchant account is settled in the new currency
transaction_type	String - SWAP or WITHDRAWAL	The type of transaction that will be performed with the rate.
created_at	String	DateTime string that the rate was created
updated_at	String	DateTime string that the rate was last updated

🚧Supported currencies

Get Rate

None of the currencies are known

Both currencies are known

Create Rate

Refresh Rate

Response properties and description

🚧
Supported currencies