Skip to main content

Quote

info

This guide is available on three different programming languages: Typescript, Kotlin and Flutter (Dart). You can change the shown version on each page via the buttons above.

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.

Creating Sep-38 Object​

Let's start with creating a sep38 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.

Authentication is done using Sep-10, and we add the authentication token to the sep38 object.

const accountKp = ... // our account keypair

const auth = await anchor.sep10();
const authToken = await auth.authenticate({ accountKp });
const sep38 = anchor.sep38(authToken);

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.

const resp = await sep38.info();

For example a response will look like this. The asset identifiers are described below in Asset Identification Format.

{
  assets: [
    {
      asset: 'stellar:SRT:GCDNJUBQSX7AJWLJACMJ7I4BC3Z47BQUTMHEICZLE6MU4KQBRYG5JY6B'
    },
    {
      asset: 'iso4217:USD',
      country_codes: [Array],
      sell_delivery_methods: [Array],
      buy_delivery_methods: [Array]
    }
  ]
}

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.

const resp = await sep38.prices({
  sell_asset: "iso4217:USD",
  sell_amount: "5",
});

The response gives the asset prices for exchanging the requested sell asset. For example, a response look like this:

{
  "buy_assets": [
    {
      "asset": "stellar:USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "price": "5.42",
      "decimals": 7
    }
  ]
}

Get Price​

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).

const resp = await sep38.price({
  sellAsset: "iso4217:USD",
  buyAsset:
    "stellar:SRT:GCDNJUBQSX7AJWLJACMJ7I4BC3Z47BQUTMHEICZLE6MU4KQBRYG5JY6B",
  sellAmount: "5",
  context: "sep6",
});

The response gives information for exchanging these assets. For example, a response will look like this:

{ price: '1.18', sell_amount: '5.00', buy_amount: '4.24' }

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.

The request body is similar to the .price() call we made earlier.

const requestResp = await sep38.requestQuote({
  sell_asset: "iso4217:USD",
  buy_asset:
    "stellar:SRT:GCDNJUBQSX7AJWLJACMJ7I4BC3Z47BQUTMHEICZLE6MU4KQBRYG5JY6B",
  sell_amount: "5",
  context: "sep6",
});

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

An example response looks like this:

{
  id: '019417b3-91ce-473a-929f-15e19470733a',
  price: '0.81',
  expires_at: '2024-01-03T20:34:48.190481Z',
  sell_asset: 'iso4217:USD',
  buy_asset: 'stellar:SRT:GCDNJUBQSX7AJWLJACMJ7I4BC3Z47BQUTMHEICZLE6MU4KQBRYG5JY6B',
  sell_amount: '5.00',
  buy_amount: '6.17'
}

Get Quote​

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

const quoteId = requestResp.id;
const getResp = await sep38.getQuote(quoteId);

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