> ## Documentation Index > Fetch the complete documentation index at: https://developers.stellar.org/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve Rates > Transactions that involve two non-equivalent on & off-chain assets (such as USDC on Stellar and fiat EUR) must use exchange rates that are communicated to the client application requesting the transaction. When clients make requests to the Platform for these exchange rates, the Platform sends this request to the anchor to fetch it. Rates can be [indicative](https://www.investopedia.com/terms/i/indicativequote.asp) or [firm](https://www.investopedia.com/terms/f/firmquote.asp). The anchor must provide an ID and expiration if the client requests a firm rate. Anchors can provide discounted rates specific client applications. The Platform includes the `client_id` parameter for this reason. Either `sell_amount` or `buy_amount` will be included in requests as parameters, but never both. In the same way, either `sell_delivery_method` and `buy_delivery_method` may be included in requests, but never both, since either `sell_asset` or `buy_asset` is a Stellar asset. Upon receiving the response, the Anchor Platform will validate the amount and price of the response. If the validation fails, the Platform will respond to the client application's request with a HTTP status code of `502 Bad Gateway`. The `sell_amount`, `buy_amount`, `price`, and `fee` are validated as follows: - if `rate.fee` exists, - `rate.fee.asset` must have a positive value of `significant_decimals` defined in the asset configuration. - `rate.fee.total` must equal to the sum of `rate.fee.details.amount`. - if the `rate.fee.asset == rate.sell_asset`, `sell_amount ~= price * buy_amount + fee` must hold true. - if the `rate.fee.asset == rate.buy_asset`, `sell_amount ~= price * (buy_amount + fee)` must hold true. - if `rate.fee` does not exist, `sell_amount ~= price * buy_amount` must hold true. The `~=` is defined as equality within rounding error. The rounding error is defined as `10^(-significant_decimals)` SEP-31SEP-38 ## OpenAPI ````yaml openapi/anchor-platform/bundled-callbacks.yaml GET /rate openapi: 3.1.0 info: version: 3.0.0 description: > The Synchronous Callbacks API specification for the Stellar Anchor Platform project. The Synchronous Callbacks API defines requests made by the Platform while it is processing a request from a client application. The anchor's responses to these requests affect the Platform responses to the client application. title: Callbacks Server license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://callback.business-server.exampleanchor.com security: [] tags: - name: Unique Address description: >- (optional) Provide a unique `stellar_address:memo` pair that will be used to correlate a Stellar payment 1-to-1 with a Platform resource such as a [SEP-31](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0031.md) transaction. - name: Rates description: >- Requests containing data that can be used to provide exchange rates between on & off-chain assets. - name: Customers description: > [SEP-12](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md) requests made from client applications. paths: /rate: get: tags: - Rates summary: Retrieve Rates description: > Transactions that involve two non-equivalent on & off-chain assets (such as USDC on Stellar and fiat EUR) must use exchange rates that are communicated to the client application requesting the transaction. When clients make requests to the Platform for these exchange rates, the Platform sends this request to the anchor to fetch it. Rates can be [indicative](https://www.investopedia.com/terms/i/indicativequote.asp) or [firm](https://www.investopedia.com/terms/f/firmquote.asp). The anchor must provide an ID and expiration if the client requests a firm rate. Anchors can provide discounted rates specific client applications. The Platform includes the `client_id` parameter for this reason. Either `sell_amount` or `buy_amount` will be included in requests as parameters, but never both. In the same way, either `sell_delivery_method` and `buy_delivery_method` may be included in requests, but never both, since either `sell_asset` or `buy_asset` is a Stellar asset. Upon receiving the response, the Anchor Platform will validate the amount and price of the response. If the validation fails, the Platform will respond to the client application's request with a HTTP status code of `502 Bad Gateway`. The `sell_amount`, `buy_amount`, `price`, and `fee` are validated as follows: - if `rate.fee` exists, - `rate.fee.asset` must have a positive value of `significant_decimals` defined in the asset configuration. - `rate.fee.total` must equal to the sum of `rate.fee.details.amount`. - if the `rate.fee.asset == rate.sell_asset`, `sell_amount ~= price * buy_amount + fee` must hold true. - if the `rate.fee.asset == rate.buy_asset`, `sell_amount ~= price * (buy_amount + fee)` must hold true. - if `rate.fee` does not exist, `sell_amount ~= price * buy_amount` must hold true. The `~=` is defined as equality within rounding error. The rounding error is defined as `10^(-significant_decimals)` operationId: getRates parameters: - in: query name: type description: >- The type of rate requested. If `firm`, the response must include `rate.id` and `rate.expires_at`. schema: type: string enum: - indicative - firm required: true - in: query name: client_id description: > An identifier for the client application making the request. This ID can be used to offer different fees to different clients. Client IDs will be the Stellar public key the public key used to authenticate via SEP-10. Anchors must ensure that the public key specified in the request matches a public key known to belong to the sending anchor. This parameter will only be specified if the client is authenticated via SEP-10. Anchors can define whether or not authentication is required for fetching indicative rates. Firm rates always require authentication. schema: type: string - in: query name: sell_asset description: > The asset the client application will send to the anchor in exchange for `buy_asset` in [Asset Identification Format](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0038.md#asset-identification-format). schema: type: string required: true - in: query name: buy_asset description: > The asset the that the anchor will send in exchange for `sell_asset` in [Asset Identification Format](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0038.md#asset-identification-format). schema: type: string required: true - in: query name: sell_amount description: > The amount of `sell_asset` the client application will send in exchange for `buy_asset`. Will not be used in conjunction with `buy_amount`. schema: type: string - in: query name: buy_amount description: > The amount of `buy_asset` the anchor will send in exchange for `sell_asset`. Will not be used in conjunction with `sell_amount`. schema: type: string - in: query name: country_code description: > The [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code of the user's current address. Anchors should expect this parameter to be provided if one of the assets of the buy/sell pair is fiat and it is available in two or more countries. schema: type: string - in: query name: expire_after description: > The client's desired `expires_at` date and time for the quote that can be used if this is a firm quote. This should be a [UTC ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) string. Anchors should return `400 Bad Request` if an expiration date on or after the requested value cannot be provided. schema: type: string - in: query name: sell_delivery_method description: > The method the client or user will use to deliver `sell_asset` to the Anchor. This value may affect the expiration and price provided. The values used for this parameter is defined in the application's configuration. Will not be used in conjunction with `buy_delivery_method`. schema: type: string - in: query name: buy_delivery_method description: > The method the client or user wants used to receive `buy_asset` from the Anchor. This value may affect the expiration and price provided. The values used for this parameter is defined in the application's configuration. Will not be used in conjunction with `sell_delivery_method`. schema: type: string responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/RateResponse' '422': description: > Unprocessable Entity. This status should be returned when the anchor understood the request but cannot return a success response. In these cases, the Platform will respond to the client application's request with a `400 Bad Request` and include the error message provided by the anchor in the response body. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: >- Error. The Platform will respond to the client application with the same response code and body. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: RateResponse: type: object properties: rate: type: object properties: id: type: string description: ID of the firm quote. NOT USED when `type=indicative`. expires_at: type: string format: date-time description: Expiration for the quote. NOT USED when `type=indicative`. price: type: string description: >- The conversion price offered by the anchor for one unit of `buy_asset` in terms of `sell_asset`, without including fees. In traditional finance, `buy_asset` would be referred to as the base asset and `sell_asset` as the counter asset. The formula `sell_amount - fee = price * buy_amount` must hold true ([ref](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0038.md#price-formulas)). sell_amount: type: string description: >- The amount of `sell_asset` the anchor will exchange for `buy_asset`. It could be different from the `sell_amount` provided in the request, depending on how fees are applied by the Anchor. buy_amount: type: string description: >- The amount of `buy_asset` the anchor will provide with `sell_asset`. It could be different from the `buy_amount` provided in the request, depending on how fees are applied by the Anchor. fee: $ref: '#/components/schemas/RateFeeResponse' required: - price - sell_amount - buy_amount Error: type: object properties: error: type: string id: type: string required: - error RateFeeResponse: type: object description: >- An object describing the fees added on top of the rate provided via the `price` attribute. properties: total: type: string description: The total fee to be applied. asset: type: string description: >- The asset the fee will be charged in. Must be represented in [Asset Identification Format](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0038.md#asset-identification-format). details: type: array items: $ref: '#/components/schemas/RateFeeDetailResponse' required: - total - asset RateFeeDetailResponse: type: object properties: name: type: string description: >- The name of the fee, for example `ACH fee`, `Brazilian conciliation fee`, `Service fee`, etc. description: type: string description: A text describing the fee. amount: type: string description: >- The amount of asset applied. If `fee.details` is provided, `sum(fee.details.amount)` should be equals `fee.total`. required: - name - amount ````