Quote - Stellar Developer Docs

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

ImportantDocumentation for Kotlin is currently work in progress. Some of information may not be applicable for Kotlin, or missing. Code samples may be incomplete.

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.

TypeScript
Flutter
Swift

const accountKp = ... // our account keypair

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

var accountKp = ... // our account keypair

var auth = await anchor.sep10();
var authToken = await auth.authenticate(accountKp);
var sep38 = anchor.sep38(authToken: authToken);

let accountKp = ... // our account keypair

let sep10 = try await anchor.sep10
let authToken = try await sep10.authenticate(userKeyPair: accountKp)
let sep38 = try await anchor.sep38(authToken: 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.

TypeScript
Flutter
Swift

const resp = await sep38.info();

var resp = await sep38.info();

let resp = try 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.

TypeScript
Flutter
Swift

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

var resp = await sep38.prices(
  sellAsset: "iso4217:USD",
  sellAmount: "5",
);

let response = try await sep38.prices(sellAsset: "iso4217:USD",
                                      sellAmount: "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).

TypeScript
Flutter
Swift

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

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

let resp = try await sep38.price(
    context: "sep6",
    sellAsset: "iso4217:USD",
    buyAsset: "stellar:SRT:GCDNJUBQSX7AJWLJACMJ7I4BC3Z47BQUTMHEICZLE6MU4KQBRYG5JY6B",
    sellAmount: "5")

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.

TypeScript
Flutter
Swift

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

var requestResp = await sep38.requestQuote(
  sellAsset: "iso4217:USD",
  buyAsset:
    "stellar:SRT:GCDNJUBQSX7AJWLJACMJ7I4BC3Z47BQUTMHEICZLE6MU4KQBRYG5JY6B",
  sellAmount: "5",
  context: "sep6",
);

let resp = try await sep38.requestQuote(
    context: "sep6",
    sellAsset: "iso4217:USD",
    buyAsset: "stellar:SRT:GCDNJUBQSX7AJWLJACMJ7I4BC3Z47BQUTMHEICZLE6MU4KQBRYG5JY6B",
    sellAmount: "5")

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.

TypeScript
Flutter
Swift

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

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

let quoteId = requestResp.id
let getResp = try await sep38.getQuote(quoteId: quoteId)

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

​Creating SEP-38 Object

​Get Anchor Information

​Asset Identification Format

​Get Prices

​Get Price

​Post Quote

​Get Quote

Creating SEP-38 Object

Get Anchor Information

Asset Identification Format

Get Prices

Get Price

Post Quote

Get Quote