Retrieve Rates
GET/rate
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 or firm. 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 ofsignificant_decimals
defined in the asset configuration.rate.fee.total
must equal to the sum ofrate.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)
Request
Query Parameters
Possible values: [indicative
, firm
]
The type of rate requested. If firm
, the response must include rate.id
and rate.expires_at
.
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.
The asset the client application will send to the anchor in exchange for buy_asset
in
Asset Identification Format.
The asset the that the anchor will send in exchange for sell_asset
in
Asset Identification Format.
The amount of sell_asset
the client application will send in exchange for buy_asset
. Will not be used in
conjuction with buy_amount
.
The amount of buy_asset
the anchor will send in exchange for sell_asset
. Will not be used in conjuction
with sell_amount
.
The ISO 3166-1 alpha-3 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.
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 string. Anchors should return 400 Bad Request
if an expiration date on or after the requested value cannot be provided.
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 conjuction with buy_delivery_method
.
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 conjuction with sell_delivery_method
.
Responses
- 200
- 422
- 500
Success.
- application/json
- Schema
- Example (from schema)
Schema
Array [
]
rate
object
ID of the firm quote. NOT USED when type=indicative
.
Expiration for the quote. NOT USED when type=indicative
.
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).
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.
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
object
An object describing the fees added on top of the rate provided via the price
attribute.
The total fee to be applied.
The asset the fee will be charged in. Must be represented in Asset Identification Format.
details
object[]
The name of the fee, for example ACH fee
, Brazilian conciliation fee
, Service fee
, etc.
A text describing the fee.
The amount of asset applied. If fee.details
is provided, sum(fee.details.amount)
should be equals fee.total
.
{
"rate": {
"id": "string",
"expires_at": "2024-10-29T17:23:12.165Z",
"price": "string",
"sell_amount": "string",
"buy_amount": "string",
"fee": {
"total": "string",
"asset": "string",
"details": [
{
"name": "string",
"description": "string",
"amount": "string"
}
]
}
}
}
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.
- application/json
- Schema
- Example (from schema)
Schema
{
"error": "string",
"id": "string"
}
Error. The Platform will respond to the client application with the same response code and body.
- application/json
- Schema
- Example (from schema)
Schema
{
"error": "string",
"id": "string"
}