SEP-0038 - Anchor RFQ API

The SEP-38 standard defines a way for anchors to provide quotes for the exchange of an off-chain asset and a different on-chain asset, and vice versa. Quotes may be indicative or firm ones. When either is used is explained in the sections below.

Create a SEP38QuoteService instance

Let’s start with creating a SEP38QuoteService object, which we’ll use for all SEP-38 interactions. Authentication is optional for these requests, and depends on the anchor implementation. For our example we will include it.

By providing the quote server url directly via the constructor:

final service = SEP38QuoteService("http://api.stellar.org/query");

By providing the domain hosting the stellar.toml file

final service = await SEP38QuoteService.fromDomain("place.domain.com");

This will automatically load and parse the stellar.toml file. It will then create the SEP38QuoteService instance by using the quote server url provided in the stellar.toml file.

Authentication

Authentication is done using the Sep-10 WebAuth Service, and we will use the authentication token in the SEP-38 requests.

Get Anchor Information

First, let’s get information about the anchor’s support for SEP-38. The response gives what stellar on-chain assets and off-chain assets are available for trading.

SEP38InfoResponse response = await service.info(jwtToken: jwtToken);
List<SEP38Asset> assets = response.assets;

Asset Identification Format

Before calling other endpoints we should understand the scheme used to identify assets in this protocol. The following format is used:

<scheme>:<identifer>

The currently accepted scheme values are stellar for Stellar assets, and iso4217 for fiat currencies.

For example to identify USDC on Stellar we would use:

stellar:USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN

And to identify fiat USD we would use:

iso4217:USD

Further explanation can be found in SEP-38 specification.

Get Prices

Now let’s get indicative prices from the anchor in exchange for a given asset. This is an indicative price. The actual price will be calculated at conversion time once the Anchor receives the funds from a user.

In our example we’re getting prices for selling 5 fiat USD.

SEP38PricesResponse response = await service.prices(
    sellAsset: "iso4217:USD", sellAmount: "5", jwtToken: jwtToken);

List<SEP38BuyAsset> buyAssets = response.buyAssets;

The response gives the asset prices for exchanging the requested sell asset.

Get Prices

Next, let’s get an indicative price for a certain pair.

Once again this is an indicative value. The actual price will be calculated at conversion time once the Anchor receives the funds from a User.

Either a sellAmount or buyAmount value must be given, but not both. And context refers to what Stellar SEP context this will be used for (ie. sep6, sep24, or sep31`).

SEP38PriceResponse response = await service.price(
    context: "sep6",
    sellAsset: "iso4217:USD",
    buyAsset: "stellar:SRT:GCDNJUBQSX7AJWLJACMJ7I4BC3Z47BQUTMHEICZLE6MU4KQBRYG5JY6B",
    sellAmount: "5",
    jwtToken: jwtToken);

The response gives information for exchanging these assets.

Post Quote

Now let’s get a firm quote from the anchor. As opposed to the earlier endpoints, this quote is stored by the anchor for a certain period of time. We will show how we can grab the quote again later.

var request = SEP38PostQuoteRequest(
    context: "sep6",
    sellAsset: "iso4217:USD",
    buyAsset: "stellar:SRT:GCDNJUBQSX7AJWLJACMJ7I4BC3Z47BQUTMHEICZLE6MU4KQBRYG5JY6B",
    sellAmount: "5");

SEP38QuoteResponse response = await service.postQuote(request, jwtToken);

var quoteId = response.id;
var expirationDate = response.expiresAt;
var totalPrice = response.totalPrice;
// ...

However now the response gives an id that we can use to identify the quote. The expiresAt field tells us how long the anchor will wait to receive funds for this quote.

Get Quote

Now let’s get the previously requested quote. To do that we use the id from the .postQuote() response.

SEP38QuoteResponse response = await service.getQuote(quoteId, jwtToken);

The response should match the one given from .postQuote() we made earlier.

Further readings

SDK’s SEP-38 test cases.