Get a Quote

The Quote API allows you to request quotes for foreign exchange (FX) trades. By providing the buy and sell currency codes, you can obtain a quote that includes the rate, expiry time, and value date for the payment.

Request

To request a quote, specify the buy and sell currency codes and either the buy amount or the sell amount. You cannot provide both amounts in the same request.

Request Body:

Required Fields:
- sellCurrency: The ISO currency code of the currency you are selling.
- buyCurrency: The ISO currency code of the currency you are buying.
Conditional Fields: One of these two amounts is required when requesting a quote
- sellAmount: The amount of the sell currency you are trading.
- buyAmount: The amount of the buy currency you want to receive.
Optional Fields:
- clientMargin: This is an optional field where you can specify margin (in percentage terms) that you want StoneX to add to the rate before returning the Quote. This can be used if you have front-end applications which want to add margins on top of your agreed base margin with StoneX. For ex - If you'd like to add 1% additional margin to the rate StoneX provides you, you can pass 1 in this field and we will adjust the rate to add 1% additional margin.
- valueDate : We support multiple value date types such as spot (T+2), earliest (T+0 or T+1 depending on currency), requested date (specific date you want to pay) etc. If you are set up for REQUESTED value date type, you will need to provide the value date you want in the YYYY-MM-DD format. Contact us if you would like to change your default value date type which is always spot dates.

{  
  "sellCurrency": "USD",  
  "buyCurrency": "KES",  
  "sellAmount": 100,
  "valueDate" : "2025-09-24",
  "clientMargin" : 1
}

{  
  "sellCurrency": "USD",  
  "buyCurrency": "KES",  
  "buyAmount": 10000, 
  "valueDate" : "2025-09-24",
  "clientMargin" : 1
}

Response

Upon a successful request, the API will return a quoteId along with details of the rate, fee, and other relevant information.

{
    "quoteId": "ebcf6342-065d-4496-9e1f-23609ff99e77",
    "sellCurrency": "USD",
    "buyCurrency": "KES",
    "sellAmount": 100,
    "buyAmount": 12792.78,
    "rate": 127.9278,
    "fee": 0,
    "createdTime": "2025-09-22T14:19:37.7093953Z",
    "quoteExpiry": "2025-09-22T14:29:37.7093953Z",
    "valueDate": "2025-09-24"
}

{
    "quoteId": "7e51c011-1ef7-4dcd-a768-5aa36540376c",
    "sellCurrency": "USD",
    "buyCurrency": "KES",
    "sellAmount": 78.17,
    "buyAmount": 10000,
    "rate": 127.9278,
    "fee": 0,
    "createdTime": "2025-09-22T14:21:34.603897Z",
    "quoteExpiry": "2025-09-22T14:31:34.603897Z",
    "valueDate": "2025-09-24"
}

Fields:

quoteId: A unique identifier for the quote.
sellCurrency: The currency being sold.
buyCurrency: The currency being bought.
sellAmount: The amount of the sell currency.
buyAmount: The amount of the buy currency.
rate: The exchange rate for the trade.
fee: Any applicable fee for the trade.
createdTime: The timestamp when the quote was created.
quoteExpiry: The time until the quote is valid.
valueDate: The date when the payment will be settled.

Usage:

Prepare Request: Include the buyCurrency and sellCurrency codes, and provide either buyAmount or sellAmount in the request body.
Request Quote: Send a POST request to the endpoint to obtain a quoteId.
Book Trade: Use the quoteId provided in the response to book the trade. Ensure that the trade is completed before the quoteExpiry time.

Notes:

Currency Codes: Ensure currency codes are in ISO 4217 format (e.g., USD, EUR, KES).
Amounts: You can provide only one of buyAmount or sellAmount in the request.
Quote Expiry: The quoteExpiry (rate validity) indicates when the quote will no longer be valid. Normally this is set to 200 secs but we are flexible and can change the rate validity in line with your agreed onboarding terms. Please contact us if you'd like to discuss this.
Direct vs Indirect Quotes: In FX markets, a direct quote refers to the amount of domestic currency needed to purchase one unit of a foreign currency. We always return our rates as Direct Quotes. So when you request a rate for BRL/USD, where BRL is the buy currency and USD is the sell currency, we will return the rate like 5.7700 BRL per USD.
The US dollar (USD) is typically used as the base currency in most FX quotes due to its global dominance. However, there are notable exceptions where USD is the quote currency instead. These exceptions include:
1. GBP/USD - British Pound is the base currency
2. EUR/USD - Euro is the base currency
3. AUD/USD - Australian Dollar is the base currency
4. NZD/USD - New Zealand Dollar is the base currency