Changelog

The API is versioned in its path. Changes that do not break an existing integration ship within v1; anything that would break one goes into a new version. Changes are listed on this page.

Versioning

The version is part of the base URL: https://api.kotova.io/x/v1. A new version would get a new path, such as /x/v2, next to the old one.

Within v1, these changes can ship at any time, because a correct integration keeps working through them:

• new fields in responses;
• new endpoints;
• new error codes and new warning codes;
• new values in the enums the OpenAPI document marks as extensible, such as a source’s kind, a network’s family, a currency’s type, address_format, status_detail.reason, the reason values of no_source_available and service_unavailable, and warnings[].code.

Build for that: ignore response fields you do not know, act on the HTTP status of an error code you do not know, and ignore warnings you do not know.

Only in a new version come changes that could break an integration: removing or renaming a field, an endpoint or a parameter, changing a field’s type or meaning, and adding a value to a closed enum. The closed enums are the order status, rate_type and amount_type; your code can map every one of their values.

Deprecations and notice

Before any part of v1 stops working, the change is announced at least 30 days ahead:

• in an entry on this page;
• by e-mail to the owners of active API keys;
• in the responses concerned, with a Deprecation header and a Sunset header giving the date after which that part stops working.

Changes to request weights are announced the same way, at least 30 days ahead. Use of the API is governed by the API Terms of Use.

When a currency or network code is renamed, the old spelling is still accepted, and a response to a request that uses it carries a deprecated_alias warning naming the code to use instead. GET /currencies lists a currency’s old spellings in aliases.

Entries

v1 (not yet released)

The first version of the Kotova X API. It is not released yet; this entry describes it as it will launch.

• Catalogue, no key: GET /currencies, GET /networks, GET /sources and GET /pairs, with icons for currencies, networks and sources.
• Quotes: POST /quote returns the best offer across the eligible sources, with a single-use quote_id, the Kotova X provider block and the source notice to show before an order, and up to two next best sources in fallback_sources, each with its amounts and notice.
• Orders: POST /orders creates an order at the quoted source, with Idempotency-Key support. GET /orders/{id} reads one order, refreshing it from its source, and GET /orders lists your account’s API orders.
• Next best source: when the quoted source cannot take an order, POST /orders places it at the first of the quote’s fallback_sources that can, and answers with that order and a source_fallback warning. On by default; send retry_next_best_source: false to use the quoted source only. A failed request lists the sources it tried in details.sources_tried.
• Utilities: POST /addresses/validate, GET /me, GET /health, the index at the base URL and the OpenAPI 3.1 document at GET /openapi.json.
• XML rates feed: GET /rates/variable.xml and GET /rates/fixed.xml, in the format rate monitors read.
• Limits: 250 weight units per 60-second window per account by default, with POST /orders weighing 50 and every other keyed request 1.

Not available yet: webhooks, Lightning as a receive network, endpoints for emergency choices and refund addresses, a minimum-receive guard, e-mail notifications to your users, and a sandbox.