Display requirements

Two things are mandatory wherever your application presents a Kotova X quote or order. Kotova X must appear by name and icon as the provider, and the notice of every source that may execute the order must appear before your user confirms. Both are conditions of using the API; see also the API Terms of Use.

What you must show

	What	Where	From
1	The name Kotova X and the Kotova X icon	Wherever you present a Kotova X quote or order	The provider block
2	The notice of the quote’s source and, unless the order is sent with retry_next_best_source: false, the notices of its fallback sources, each with its link	Before your user confirms the order, and before it is created	source.notice and fallback_sources[].source.notice in the quote

GET /sources restates both in its attribution block: provider_display_required and source_notice_required_before_order are true, and docs_url points to this page. See Sources.

Show Kotova X as the provider

Kotova X is the provider of the service: it compares the sources’ offers and routes the order to the one that made the best offer. Show it by name and icon wherever your application presents a Kotova X quote or order: the offer itself, the confirmation step, the order’s status view, and any receipt or order history that lists it.

• The name is exactly Kotova X, with a space and a capital X. Never KotovaX, Kotova-X or a translation.
• The icon is the Kotova X icon from the files below, shown next to the name.
• The data is the provider block, which comes with every quote, every order and GET /sources, and is the same everywhere:

{
  "name": "Kotova X",
  "icon": {
    "url": "https://cdn.kotova.io/images/brand/kotova-x/icon.svg",
    "fallback_url": "https://assets.kotova.io/images/brand/kotova-x/icon.svg"
  },
  "icon_png": {
    "url": "https://cdn.kotova.io/images/brand/kotova-x/icon-256.png",
    "fallback_url": "https://assets.kotova.io/images/brand/kotova-x/icon-256.png"
  },
  "website_url": "https://app.kotova.io"
}

You may link the name or the icon to website_url, the Kotova X app.

The Kotova X icon

File	Size	URL	Fallback URL
SVG (provider.icon)	Scalable	https://cdn.kotova.io/images/brand/kotova-x/icon.svg	https://assets.kotova.io/images/brand/kotova-x/icon.svg
PNG	64 × 64 px	https://cdn.kotova.io/images/brand/kotova-x/icon-64.png	https://assets.kotova.io/images/brand/kotova-x/icon-64.png
PNG	128 × 128 px	https://cdn.kotova.io/images/brand/kotova-x/icon-128.png	https://assets.kotova.io/images/brand/kotova-x/icon-128.png
PNG (provider.icon_png)	256 × 256 px	https://cdn.kotova.io/images/brand/kotova-x/icon-256.png	https://assets.kotova.io/images/brand/kotova-x/icon-256.png

The fallback URL is the same file on Kotova’s mirror. If the first URL fails to load, retry once with the fallback, as described in Icons. You may link to these files or self-host unmodified copies of them.

• Show the icon at 24 pixels or larger.
• Use it unmodified: no recolouring, distortion, rotation or shadow.
• Keep a clear space around it, and do not place it on a busy background. The icon is a dark tile, so it reads on light and dark backgrounds alike.

Show the source notice before your user confirms

Every quote names the source that will execute the order, and carries that source’s notice in source.notice:

{
  "text": "The exchange service is provided by SideShift. Creating an order confirms your agreement with the SideShift rules.",
  "link_text": "SideShift rules",
  "link_url": "https://sideshift.ai/legal",
  "lang": "en"
}

Show it before your user confirms the order:

• Word for word. Show notice.text as it is. Do not shorten it, reword it, translate it yourself or replace the source’s name.
• With its link. notice.link_text is part of notice.text. Render that part as a link to notice.link_url.
• At the right moment. Before your user confirms, and before the order is created. We recommend showing it in the same view as the control that creates the order, visible without an extra click.
• Never pre-accepted. Your user’s confirmation is their agreement. Do not accept the notice on their behalf, for example with a consent box that is already ticked.
• For the right source. Take the notices from the quote your user is confirming. The order is created at that quote’s source or one of its fallback sources, and a new quote can name different ones.

The notice is the line the Kotova X app shows before an order is created. It names the source because the source executes the swap and its rules apply to the order. A source without rules of its own, such as a decentralised protocol, links to Kotova’s Terms of Service instead; its terms_url is then null.

Fallback sources

By default, when the quote’s source cannot take the order, POST /orders places it with the first of the quote’s fallback_sources that can (see Next best source). Your user then agrees to that source’s rules, so its notice must have been shown too.

• Show every fallback notice by the same rules as the quote’s notice: word for word, with its link, before your user confirms and before the order is created, and never pre-accepted.
• The one difference is where. The fallback notices may be shown after the quote’s notice, including in an expandable section placed directly next to it. For example, directly below the quote’s notice, a line “If SideShift can’t take the order, it is placed with:” followed by each fallback notice in order, either listed in full or in an expandable section with that line as its summary. The line that introduces them is your own wording.
• When fallback_sources is empty, the quote’s notice is all there is to show.
• If you cannot show them, send "retry_next_best_source": false with the order. Only the quote’s source is then tried, and the order fails when it cannot take it.

After the order is created

The order’s source is the source that executes it. After a fallback, it is not the quote’s source: the 201 carries a source_fallback warning, and the order’s amounts are that source’s. From then on, show the order’s source, and its notice where you show one, in the order view, status updates, receipts and order history, never the quote’s.

Your user’s language

Ask for the notice in your user’s language with lang. POST /quote, POST /orders, GET /orders/{id} and GET /sources all take it. The supported values are en (the default), de, it, es, fr and ru; a region suffix such as de-AT is accepted. Any other value gives the English notice and an unsupported_lang warning. notice.lang says which language you got.

The notice in six languages

For reference, these are the six forms of the notice. {source} stands for the source’s name, and the part in bold is link_text. When the link goes to Kotova’s Terms of Service, link_url is https://kotova.io/terms/service?lang= followed by the language code.

lang	Source with its own rules	Source that links to Kotova’s Terms of Service
en	The exchange service is provided by {source}. Creating an order confirms your agreement with the {source} rules.	The exchange service is provided by {source}. Creating an order confirms your agreement with the Kotova Terms of Service.
de	Der Tauschdienst wird von {source} bereitgestellt. Die Erstellung eines Auftrags bestätigt Ihre Zustimmung zu den {source}-Regeln.	Der Tauschdienst wird von {source} bereitgestellt. Die Erstellung eines Auftrags bestätigt Ihre Zustimmung zu den Kotova-Nutzungsbedingungen.
it	Il servizio di scambio è fornito da {source}. La creazione di un ordine conferma il tuo accordo con le regole di {source}.	Il servizio di scambio è fornito da {source}. La creazione di un ordine conferma il tuo accordo con le Condizioni di servizio di Kotova.
es	El servicio de intercambio es proporcionado por {source}. La creación de una orden confirma su aceptación de las reglas de {source}.	El servicio de intercambio es proporcionado por {source}. La creación de una orden confirma su aceptación de las Condiciones de servicio de Kotova.
fr	Le service d’échange est fourni par {source}. La création d’un ordre confirme votre accord avec les règles de {source}.	Le service d’échange est fourni par {source}. La création d’un ordre confirme votre accord avec les Conditions d’utilisation de Kotova.
ru	Сервис обмена предоставлен {source}. Создание заказа подтверждает ваше согласие с правилами {source}.	Сервис обмена предоставлен {source}. Создание заказа подтверждает ваше согласие с Условиями использования Kotova.

Always show the notice the API returns

Use this table to plan your layout, not to build the notice. A source’s name, its rules link and the wording itself can change, and the API always returns the current line.

Source names and logos

Showing the source’s name and logo anywhere else is optional. A quote’s and an order’s source block carries name and icon; GET /sources carries them for every source. When icon is null, the source’s logo may not be shown: use the name alone.

Source logos are their owners’ trademarks. Kotova grants no licence to them. If you show one, use it only to identify the source, unmodified, without suggesting that the source endorses your application, and at your own risk.

Describing the service

Do:

• Say that Kotova X compares the offers of independent sources and routes the order to the best one.
• Say that your user’s funds go directly to the source that executes the swap, and never pass through Kotova.
• Call the party that executes the swap the source, and name it.
• Show when a quote expires (expires_at), and request a new quote once it has passed.
• Once the order exists, show the amounts and the source from the order. A quote fixes the sources and the pair; the order’s amounts and source are the ones that apply.
• Say, where identity checks come up, that Kotova performs none itself and that centralised sources may perform them case by case.

Do not:

• Call Kotova or Kotova X an exchange or a custodian, or say that Kotova executes swaps or holds funds.
• Present a source as the provider, or Kotova X as the source.
• Show a quote as executable after its expires_at. Creating an order from it fails with a 410 quote_expired.
• Hide, shorten, reword or translate a notice yourself, accept it on your user’s behalf, or show it only after the order is created. The one exception: the fallback sources’ notices may sit in an expandable section placed directly next to the quote’s notice (see Fallback sources).
• Leave out the notices of the fallback sources when the order is sent without retry_next_best_source: false, or put them in an expandable section anywhere but directly next to the quote’s notice.
• Alter the Kotova X name or icon, or show one without the other.
• Promise anything about rates, timing or the outcome of an order beyond what the quote and the order say.

Asking for the addresses

This is a recommendation, not a requirement. Ask for the refund address in the same form as the address your user receives on, before they confirm:

• Both addresses together. Show a field for the address your user receives on (to_address, on the to network) and one for their refund address (refund_address, on the from network) side by side, each labelled with its currency and network so that the two are not mixed up.
• The refund address as recommended. Make it optional unless the quote’s requirements.refund_address is required, and say what it is for: if the swap cannot complete, the deposit goes back there. Sent with the order, it goes to the source where the source takes it then, and keeps more of the quote’s fallback sources eligible (see Refund addresses).
• A memo field next to each address whose network takes one (the quote’s requirements.to_memo or requirements.refund_memo is optional), for an address at an exchange account or another address that needs a memo.
• A check before confirming. POST /addresses/validate checks each address against its network’s format.

Example HTML

A minimal confirmation view: Kotova X as the provider, the offer, the address your user receives on and their refund address, the source notice with its link, the notices of the fallback sources in an expandable section directly below it, and the confirm button. The values come from the quote; the ones below are the documentation’s example quote.

<form class="kx-offer">
  <p class="kx-provider">
    <img src="https://cdn.kotova.io/images/brand/kotova-x/icon.svg"
         onerror="this.onerror = null; this.src = 'https://assets.kotova.io/images/brand/kotova-x/icon.svg';"
         alt="" width="24" height="24">
    <span>Kotova X</span>
  </p>

  <p>You send 0.05 BTC and receive about 3389.8 USDT (TRON) through SideShift.</p>

  <label>
    Your USDT (TRON) address
    <input name="to_address" autocomplete="off" spellcheck="false" required>
  </label>
  <label>
    Your BTC refund address (recommended: if the swap cannot complete, your BTC goes back here)
    <input name="refund_address" autocomplete="off" spellcheck="false">
  </label>

  <p class="kx-notice" lang="en">
    The exchange service is provided by SideShift. Creating an order confirms your
    agreement with the
    <a href="https://sideshift.ai/legal" target="_blank" rel="noopener noreferrer">SideShift rules</a>.
  </p>

  <details class="kx-fallbacks">
    <summary>If SideShift can't take the order, it is placed with:</summary>
    <ol>
      <li lang="en">
        The exchange service is provided by ChangeNOW. Creating an order confirms your
        agreement with the
        <a href="https://changenow.io/terms-of-use" target="_blank" rel="noopener noreferrer">ChangeNOW rules</a>.
      </li>
      <li lang="en">
        The exchange service is provided by Changelly. Creating an order confirms your
        agreement with the
        <a href="https://changelly.com/terms-of-use" target="_blank" rel="noopener noreferrer">Changelly rules</a>.
      </li>
    </ol>
  </details>

  <button type="submit">Create order</button>
</form>

The same notices built from the API’s answer. They are set as text, never HTML, so nothing in the answer can inject HTML into your page, and the confirm button turns off when the quote expires:

// quote: the JSON answer of POST /quote.
function renderNotice(el, notice) {
  const link = document.createElement('a');
  link.href = notice.link_url;
  link.target = '_blank';
  link.rel = 'noopener noreferrer';
  link.textContent = notice.link_text;

  const at = notice.text.indexOf(notice.link_text);
  if (at === -1) {
    el.replaceChildren(notice.text, ' ', link);
  } else {
    el.replaceChildren(
      notice.text.slice(0, at),
      link,
      notice.text.slice(at + notice.link_text.length)
    );
  }
  el.lang = notice.lang;
}

renderNotice(document.querySelector('.kx-notice'), quote.source.notice);

const fallbacks = document.querySelector('.kx-fallbacks');
fallbacks.hidden = quote.fallback_sources.length === 0;
fallbacks.querySelector('summary').textContent =
  `If ${quote.source.name} can't take the order, it is placed with:`;
fallbacks.querySelector('ol').replaceChildren(
  ...quote.fallback_sources.map((fallback) => {
    const item = document.createElement('li');
    renderNotice(item, fallback.source.notice);
    return item;
  })
);

const button = document.querySelector('.kx-offer button');
const msLeft = Date.parse(quote.expires_at) - Date.now();
setTimeout(() => {
  button.disabled = true; // the quote has expired: request a new one
}, Math.max(0, msLeft));