# API overview

> What the Kotova X API does, how a quote becomes an order at the executing source, what you need before you start, and what your application must show its users.

- Source: https://docs.kotova.io/x/api
- API base URL: https://api.kotova.io/x/v1
- OpenAPI document: https://api.kotova.io/x/v1/openapi.json

The Kotova X API gives your application the same comparison the Kotova X app runs. It
asks every eligible liquidity source what it would give for a trade and returns the
best offer, together with the source that made it. Your users send their funds
directly to that source. They never pass through Kotova.

## What the API does

With the API, your application can list the currencies, networks and sources Kotova X
works with, request a quote for a swap, create an order from that quote, and follow
the order until it is final. Quotes come from the same engine, with the same ranking
and the same terms, as [app.kotova.io](https://app.kotova.io). The API is free to use,
and orders placed through it are priced like orders in the app.

A source is an independent service or protocol that executes a swap. Kotova X
compares what the sources offer and routes each order to the one that offered the
best result. The source executes the swap; Kotova X does not.

## One quote, one order

A quote request asks every eligible source in parallel and keeps the best answer:

- with `amount_type: "from"` (your user names the amount to send), the largest amount
  received;
- with `amount_type: "to"` (your user names the amount to receive), the smallest
  amount to send.

Ties go to the source with the earlier `display_order` in `GET /sources`, then to
the name in alphabetical order. What Kotova earns on an order never weighs in the
ranking. The details are in
[Quoting and routing](https://docs.kotova.io/x/how-it-works/quoting-and-routing).

The response names the winning source in `source`, the next best ones in
`fallback_sources`, and carries a single-use `quote_id`. An order created from that
`quote_id` is placed at that source. If it cannot take the order, the order is placed
at the first of the quote's fallback sources that can, unless you send
`retry_next_best_source: false`; it never goes to a source the quote does not name.
Requesting a quote has no side effects: nothing is created at any source until you
create the order.

A quote fixes the sources and the pair. It does not lock a rate: the amounts in the
order you create are the ones that count. See [Quotes](https://docs.kotova.io/x/api/quotes).

## Where the funds go

When you create an order, the source gives it a deposit address. Your user sends the
deposit to that address, which belongs to the source, and the source sends the payout
to the address your user chose. Kotova never receives or holds the funds, and a refund
also comes from the source. See
[Non-custodial architecture](https://docs.kotova.io/x/introduction/non-custodial).

## Base URL and versioning

```text
https://api.kotova.io/x/v1
```

Every path on these pages is relative to this base URL. The API speaks JSON (UTF-8,
`snake_case`), except the XML rates feed:

- Amounts are decimal strings such as `"0.05"`; send them as strings too.
- Timestamps are ISO 8601 in UTC, ending in `Z`.
- Currencies are identified by their ticker (`BTC`), networks by their code (`btc`,
  `trx`) and sources by their `slug`.
- Ignore response fields you do not know: fields are added without notice.
- Unknown fields in a request body, and unknown or repeated query parameters, are
  refused with [`invalid_request`](https://docs.kotova.io/x/api/errors#invalid_request) rather than ignored.
- Every response carries an `X-Request-Id` header. Quote it when you contact support.

The version is part of the path. Changes that do not break an existing integration
ship within v1; a breaking change comes only as a new version, announced at least
30 days ahead. See the [Changelog](https://docs.kotova.io/x/api/changelog).

## Endpoints

Keyless endpoints need no key and ignore one if you send it. They are cached by the
CDN, any web page may call them, and calls that reach the server are limited to 120
per minute per IP address. Keyed endpoints need your
[API key](https://docs.kotova.io/x/api/authentication), and each call costs its weight from your account's
budget, 250 units per 60 seconds by default (see [Rate limits](https://docs.kotova.io/x/api/rate-limits)).

| Operation | Method and path | Key | Weight | Documented in |
| --- | --- | --- | --- | --- |
| `getIndex` | `GET` the base URL itself, without a trailing slash | No | – | [Utilities](https://docs.kotova.io/x/api/utilities) |
| `getHealth` | `GET /health` | No | – | [Utilities](https://docs.kotova.io/x/api/utilities) |
| `getOpenApi` | `GET /openapi.json` | No | – | [Utilities](https://docs.kotova.io/x/api/utilities) |
| `getCurrencies` | `GET /currencies` | No | – | [Currencies and icons](https://docs.kotova.io/x/api/currencies) |
| `getNetworks` | `GET /networks` | No | – | [Currencies and icons](https://docs.kotova.io/x/api/currencies) |
| `getPairs` | `GET /pairs` | No | – | [Currencies and icons](https://docs.kotova.io/x/api/currencies) |
| `getSources` | `GET /sources` | No | – | [Sources](https://docs.kotova.io/x/api/sources) |
| `getRatesXml` | `GET /rates/variable.xml`, `GET /rates/fixed.xml` | No | – | [XML rates feed](https://docs.kotova.io/x/api/rates-feed) |
| `createQuote` | `POST /quote` | Yes | 1 | [Quotes](https://docs.kotova.io/x/api/quotes) |
| `createOrder` | `POST /orders` | Yes | 50 | [Orders](https://docs.kotova.io/x/api/orders) |
| `getOrder` | `GET /orders/{id}` | Yes | 1 | [Orders](https://docs.kotova.io/x/api/orders) |
| `listOrders` | `GET /orders` | Yes | 1 | [Orders](https://docs.kotova.io/x/api/orders) |
| `validateAddress` | `POST /addresses/validate` | Yes | 1 | [Utilities](https://docs.kotova.io/x/api/utilities) |
| `getMe` | `GET /me` | Yes | 1 | [Utilities](https://docs.kotova.io/x/api/utilities) |

The statuses an order moves through are listed in [Order statuses](https://docs.kotova.io/x/api/order-statuses),
and every error code in [Errors](https://docs.kotova.io/x/api/errors).

## What you need

- A Kotova account at [app.kotova.io](https://app.kotova.io) with a confirmed,
  permanent e-mail address. Disposable addresses cannot be used for API access.
- Two-factor authentication with an authenticator app, turned on in your account.
  Creating or regenerating a key asks for a code from it.
- A referral code. Generating one creates your affiliate profile, and your API key
  belongs to that profile. You can generate it on the
  [account API page](https://app.kotova.io/account/api).
- An API key, created on the same page after you accept the
  [API Terms of Use](https://kotova.io/terms/api).
- A server to call the API from. The key is a secret and must stay there, never in a
  website or a mobile app.

The [Quickstart](https://docs.kotova.io/x/api/quickstart) walks through these steps and a first order.

## What you must show

Two things are mandatory wherever your application presents a Kotova X quote or
order:

- **Kotova X as the provider**, by name and icon. Quotes, orders and `GET /sources`
  carry them in the `provider` block.
- **The source notices**, before your user confirms an order. Each quote carries the
  notice of its source in `source.notice` and those of its fallback sources in
  `fallback_sources`, in the language you ask for with `lang`, word for word as the
  Kotova X app shows them.

Describe Kotova X as what it is: a service that compares sources and routes the order
to one of them. The source executes the swap. The rules and examples are in
[Display requirements](https://docs.kotova.io/x/api/display-requirements).

## How you earn

Your API key belongs to your affiliate profile. Every order created with it is
attributed to that profile and earns commission like an order placed through your
referral link: a share of Kotova's net revenue from each completed order. Orders that
expire or are refunded earn none.

The commission rate and the rate limit are set per account, on your affiliate
profile, so they stay the same when you regenerate your key. Your
[account API page](https://app.kotova.io/account/api) shows both, and you can request
a higher commission or a higher limit there. The
[affiliate terms](https://kotova.io/terms/affiliate) govern commission and payouts.

## Not available yet

These are not available yet in the API:

- **Webhooks.** Read an order with `GET /orders/{id}` to follow it.
- **Lightning as a receive network.** `GET /currencies` never offers Lightning as a
  network to receive on.
- **Endpoints for emergency choices and refund addresses.** When an order needs a
  decision, your user makes it on the order page at `status_detail.resolve_url`.
- **A minimum-receive guard**, which would refuse an order whose amount received falls
  below a minimum you set.
- **E-mail notifications to your users.** Kotova sends none for API orders: you keep
  your users informed.
- **A sandbox.** Every order you create is a real order at its source. See
  [Testing before you go live](https://docs.kotova.io/x/api/quickstart#testing-before-you-go-live).

## Machine-readable specification

The API describes itself in an OpenAPI 3.1 document, which is the source of truth for
every name on these pages:

```text
https://api.kotova.io/x/v1/openapi.json
```

Every endpoint section in these docs has a **Try it** console built from that
document. The whole API section is also available as one Markdown file, for use with
language models: `https://docs.kotova.io/x/api/llms-full.txt`.

## Terms and support

Use of the API is governed by the [API Terms of Use](https://kotova.io/terms/api).
Changes to the API that need your action are announced at least 30 days ahead. There
is no service level agreement; [`GET /health`](https://docs.kotova.io/x/api/utilities) tells you whether the
API can serve requests right now.

For help with keys, limits or an integration, write to
[api@kotova.io](mailto:api@kotova.io). Include the `X-Request-Id` of the response in
question and, for an order, its id (`X-XXXXXX`).

- [Quickstart](https://docs.kotova.io/x/api/quickstart): From an account to a first order, step by step.
- [Authentication](https://docs.kotova.io/x/api/authentication): Your key, how to send it and how to keep it secret.
- [Display requirements](https://docs.kotova.io/x/api/display-requirements): What your application must show its users.