API overview

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

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.

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.

Base URL and versioning

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

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, and each call costs its weight from your account’s budget, 250 units per 60 seconds by default (see Rate limits).

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

The statuses an order moves through are listed in Order statuses, and every error code in Errors.

What you need

• A Kotova account at 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.
• An API key, created on the same page after you accept the API Terms of Use.
• 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 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.

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 shows both, and you can request a higher commission or a higher limit there. The affiliate terms 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.

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:

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. Changes to the API that need your action are announced at least 30 days ahead. There is no service level agreement; GET /health tells you whether the API can serve requests right now.

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

QuickstartFrom an account to a first order, step by step.

AuthenticationYour key, how to send it and how to keep it secret.

Display requirementsWhat your application must show its users.