Real-Time vs Offline Quotes
Grain offers two quoting and execution flows. Each has a separate Quote step (get a price) and Accept step (lock the trade).Real-time
Quote: The partner calls Grain’s API to get a live executable price for a specific transaction. Grain fetches a rate from a liquidity provider and returns it with an expiration window. Accept: The partner accepts the quote before it expires. The trade is executed immediately at the quoted rate. If the quote has expired, the partner must request a new one. Use real-time for lower-volume, higher-value transactions where the partner can afford an API call per transaction — e.g., a customer confirming a specific payment or hedge.Offline
Quote: The partner pre-fetches rates from Grain in bulk, then stores and applies them locally without calling Grain for every individual transaction. This avoids high API call volumes in scenarios where thousands of results need FX pricing simultaneously. Accept: When the end customer selects a specific transaction, the partner sends the accept call to Grain referencing the pre-fetched rate. Grain executes the trade based on the previously quoted price. Use offline for high-volume, display-heavy scenarios — e.g., a bedbank searching for hotels where each search result needs an FX-converted price. Calling Grain in real time for every hotel in every search would create excessive load. Instead, the partner fetches rates periodically and applies them locally.Quote Expiration
Every quote includes avalidUntilTs field — a timestamp indicating when the quote expires. After this time, the quote can no longer be accepted and the partner must request a new one.
Quote validity directly impacts pricing: a longer validity window means Grain carries more market risk while holding the price, which may result in a wider spread. Real-time quotes typically have short validity, while offline quotes may be valid for longer periods.
| API Endpoint | Rate Type | Executable | Markup | Use Case |
|---|---|---|---|---|
| /pricing/rate | Spot | No | No | Display / Analytics |
| /hedges/realtime/quote | Hedge | Yes | Yes | Real-time execution |
| /hedges/offline/quote | Hedge | Yes | Yes | Bulk / offline execution |
| /spots/quote | Spot | Yes | Yes | Same-day conversion |
Fixed Side
When you request a quote you pin exactly one amount — the fixed side — and Grain derives the other from the rate. You can fix either side, or neither (deferring the amount to the Accept call).- To Amount fixed — you send
toCurrencyAmount(e.g. the listing or invoice amount you need to deliver). Grain derivesfromCurrencyAmount. - From Amount fixed — you send
fromCurrencyAmount(the amount your customer pays). Grain derivestoCurrencyAmount.
fixedSide field, so you always know which amount was specified and which was calculated.
Quote Direction
The quote is always expressed as fromCurrency per 1 toCurrency, regardless of which side you fix. Fixing either side gives the same rate — only multiply-vs-divide changes:Example
MXN → USD, quote = 20.6165. Fix To —toCurrencyAmount = 1,560 USD:
fromCurrencyAmount = 32,161.8 MXN: