Skip to content
Kuna API v3 Documentation
Branch: master
Clone or download
Latest commit 30af3f8 Jul 1, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
README.md Update README.md Jul 1, 2019
deposit-status.png Add files via upload Jun 14, 2019
kuna-api-v2.md Update description Jun 19, 2019
kuna-code-statuses.jpeg Add files via upload Jun 13, 2019
kuna-code-validation.js Fix Validation formating Jun 14, 2019
kuna_api.png Add files via upload Jun 10, 2019
withdraw-status.png Add files via upload Jun 14, 2019

README.md

kuna api v3 doc

Документация по Kuna API v3

API планировалось быть организованым по принципам REST. Но что-то пошло не так.
Все методы делятся на публичные (public) и приватные (private).

Для того что бы осуществлять приватные запросы, вы должны быть зерегистрированным пользователем на сайте kuna.io, и иметь специальный API Token, который состоит из публичного (publicKey) и приватного (secretKey) ключей. Используя приватный ключ, нужно сформировать запрос на каждую подпись. Подробнее расписано в разделе Подпись для приватных методов.

Для публичных методов, публичный ключ и подпись запроса не нужны.

API Token можно получить у себя в кабинете, по ссылке https://kuna.io/api_tokens.

Документацию на предыдущую версию API v2 можно найти по ссылке: https://github.com/kunadevelopers/api-docs/blob/master/kuna-api-v2.md

Оглавление

Библиотеки для работы с API v3

Наши проекты находятся в стадии разработки. Мы их выпустим сразу как только будем уверены что они безопасны и стабильны.

Проекты от комьюнити
На свой страх и риск, вы можете использовать реализации API v3 от комъюнити.

JavaScript библиотека: CoinWizard/kuna-sdk
NPM Version NPM Downloads

Схема и сериализация данных в API

Запросы

Доступ к данным осуществляется через стандартные HTTPS запросы в кодировке UTF-8. Данные отправляются и принимаются в формате JSON.

Домен

Для всех методов, публичных или приватных, используется один домен

https://api.kuna.io

К примеру, URL для получения актуального ордербука

https://api.kuna.io/v3/book/{market}

где {market} это ключ пары, btcuah, kunbtc или другой

Заголовки (Headers)

Заголовки, которые нужны для успешного запроса.

Заголовок Описание
Accept Должен быть application/json
Content-Type Только для методов где есть тело. Должен быть application/json
Kun-Nonce Метка времени запроса. Указывается в формате Unix Time Stamp в милисекундах (ms). Только для приватных методов.
Kun-ApiKey Публичный ключ вашего API Token. Только для приватных методов.
Kun-Signature Подпись запроса. Только для приватных методов.

Подпись для приватных методов

Подпись нужно указать в заголовке запроса под ключем Kun-Signature.

Она формируется по формуле

HEX(
    HMAC-SHA384(
      {apiPath} + {nonce} + JSON({body}),
      {secretKey}
    )
)

Где,

Значение Описание
{apiPath} Метод, к примеру /v3/auth/kuna_codes/count
{nonce} Метка времени запроса. Указывается в формате Unix Time Stamp в милисекундах (ms). Это же значние должно быть и в заголовке под ключем Kun-Nonce
{body} Данные, которые передаются в теле запроса. Должны быть в формате JSON. В случае GET методов, когда тело не передается, используется пустой JSON объект - {}.
{secretKey} Приватный ключ вашего API Token

Пример подписи с использованием JavaScript

const crypto = require('crypto');

const publicKey = '';
const secretKey = '';

const apiPath = '/v3/auth/kuna_codes/issued-by-me';
const nonce = new Date().getTime();
const body = {};

const signatureString = `${apiPath}${nonce}${JSON.stringify(body)}`;

const signature = crypto
    .createHmac('sha384', secretKey)
    .update(signatureString)
    .digest('hex');

console.log(signature); // выводит подпись в HEX формате

Пример приватного метода с cURL

curl -X POST \
    https://api.kuna.io/v3/auth/kuna_codes/issued-by-me \
    -H 'Accept: application/json' \
    -H 'Kun-Nonce: 1560007410000' \
    -H 'Kun-ApiKey: vPNvF9ArqV4HqMzpAIyaLvToJJ1x1rfRZP5jNrQf' \
    -H 'Kun-Signature: 0d34c19a5125d68fe2e7fb3a3b58e162cc53e166d1e7790deb5d79f6cb04aad1d5e01daeb3ecf8871c3b767a8ea289ea'
Не пытайтесь использовать этот API Key. Он для примера :)

Публичные методы

Время на сервере

Этот метод возвращает текущее время на сервере Kuna. Полезно, если нужно проверить доступность API.

GET /v3/timestamp

Пример ответа

{
  "timestamp": 1560005994,
  "timestamp_miliseconds": 1560005994692
}

Список доступных валют

Вернет список валют, доступных на Kuna.

GET /v3/currencies

Пример ответа

[
  {
    "id": 2,            # внутренний ID
    "code": "btc",      # символ валюты
    "name": "Bitcoin",  # имя валюты
    "has_memo": false,  # нужно ли для этой валюты Memo
    "icons": {
      "std": "https://kuna.io/icons/currency/std/btc.svg",
      "xl": "https://kuna.io/icons/currency/xl/btc.svg",
      "png_2x": "https://kuna.io/icons/currency/png/BTC@2x.png",
      "png_3x": "https://kuna.io/icons/currency/png/BTC@3x.png"
    },
    "coin": true,       # является ли валюта криптовалютой
    "explorer_link":    # шаблон ссылки для TXID в експлорере
      "https://www.blockchain.com/btc/tx/#{txid}",
    "sort_order": 5,    # позиция в сортировке
    "precision": {      # параметры округления чисел
      "real": 8,
      "trade": 6
    }
  }
]

Курс валют на бирже

Этот метод позволяет вам получить курсы валют в USD, UAH, BTC, EUR и в рублике, для каждой из существующих валют на Kuna.

GET /v3/exchange-rates/{currency}

Примеры запроса

# вернет объект с курсами для USD
curl https://api.kuna.io/v3/exchange-rates/usd

# если не указать currency, то метод вернет массив всех доступных валют с их курсами
curl https://api.kuna.io/v3/exchange-rates

Пример ответа для USD

{
  "currency": "usd",  # ключ валюты
  "usd": 1,           # курс к доллару соединенных штатов
  "uah": 26.595721,   # курс к гривне Украины
  "btc": 0.0001276,   # курс к Bitcoin
  "eur": 1.13,        # курс к Евро
  "rub": 0.0153752    # курс к рублику
}

Рынки

Этот метод возвращает список валютных пар (рынков), которые доступны для торговли.

GET /v3/markets

Пример ответа

[
  {
    "id": "btcusdt",        # ключ валютной пары
    "base_unit": "btc",     # базовая валюта
    "quote_unit": "usdt",   # валюта котировки
    "base_precision": 6,    # округление базовой валюты
    "quote_precision": 2,   # округление валюты котировки
    "display_precision": 1, # точность для групировки ордеров в ордербуке
    "price_change": -1.89   # изменение цены в % за 24 часа
  }
]

Последние данные по рынку (тикеры)

Этот метод возвращает тикеры по всем рынкам, либо по конкретному.

Тикер представляет собой общий обзор состояния рынка. Он показывает текущую лучшую цену спроса и предложения, а также цену последней сделки. Он также включает в себя информацию, такую как дневной объем и сколько цена изменилась за последний день.

GET /v3/tickers?symbols={symbols}

Примеры запроса

# Вернет информацию по btcuah, kunbtc и ethuah
curl https://api.kuna.io/v3/tickers?symbols=btcuah,kunbtc,ethuah

# Вернет информацию только по рынку btcuah
curl https://api.kuna.io/v3/tickers?symbols=btcuah

# Вернет информацию по всем активным рынкам
curl https://api.kuna.io/v3/tickers?symbols=ALL

Пример ответа

[
  [
    "btcuah",   # символ рынка
    208001,     # цена BID
    11200693,   # объем ордербука BID
    208499,     # цена ASK
    29.255569,  # объем ордербука ASK
    5999,       # изменение цены за 24 часа в котируемой валюте 
    -2.8,       # изменение цены за 24 часа в процентах
    208001,     # последняя цена
    11.3878,    # объем торгов за 24 часа в базовой валюте
    215301,     # максимальная цена за 24 часа
    208001      # минимальная цена за 24 часа
  ]
]

Ордербук

Этот метод позволяет вам получить актуальное состояние ордербука.

GET /v3/book/{symbol}

Пример ответа

[
  [
    208008,    # цена
    0.048076,  # обьем
    1          # количество заявок
  ],
  [
    212220,    # цена
    -0.091058, # обьем
    1          # количество заявок
  ]
]

Обратите внимание, весь ордербук для BID и ASK возвращается одним массивом.

Если обьем > 0, то имеем данные по ордерам BID .
Если обьем < 0, то данные по ордерам ASK.

История сделок

😱 Coming soon
Этот метод еще в разработке и появится в документации так скоро как сможем его показать.

График изменения цены

😱 Coming soon
Этот метод еще в разработке и не готов к масовому использованию. Мы его опубликуем в документации так скоро, как сможем.

Комиссии на ввод и вывод

Метод для получение списка активных способов ввода и вывода средств, а так-же комиссий на ввод или вывод криптовалюты.

GET /v3/fees

Пример ответа

[
  # пример для фиатной валюты
  {
    # способ вывода для фиатных валют
    # возможные варианты: advcash_wallet, payeer, perfectmoney_account,
    #                     perfectmoney_transfer, kuna_code, payment_card
    "code": "advcash_wallet",

    "category": "usd",    # символ фиатной валюты
    "deposit_fees": [     # процент или абсолютное значение для депозита
      {"type": "percent", "amount": "0.0"}
    ],
    "withdraw_fees": [    # процент или абсолютное значение для вывода
      {"type": "percent", "amount": "1.9"}
    ]
  }, 

  # пример для криптовалюты
  {
    "code": "kun",              # символ криптовалюты
    "category": "coin",         # в категории для криптовалюты всегда coin 
    "deposit_fees": [],         # криптовалюта на ввод не трубует дополнительных комиссий
    "withdraw_fees": [          # описание комиссий на вывод
      {
        "type": "fixed",        # комиссия всегда фиксированная
        "asset": {
          "amount": 0.01,       # размер комиссии
          "currency": "waves",  # криптовалюта в которой изымется комиссия
          "to_usd": "0.02"      # курс обмена 
        }
      }
    ],
    "min_deposit": {            # данные о минимальной сумме на депозита
      "amount": 1,
      "currency": "kun",
      "to_usd": "5.66"
    },

    "min_withdraw": {           # данные о минимальной сумме на вывода
      "amount": 1,
      "currency": "kun",
      "to_usd": "5.66"
    }
  }
]

Приватное и торговое API

Каждый приватный метод требует подписи, механизм которой описан в разделе Подпись для приватных методов.

Данные аккаунта

Данный метод возвращает данные об аккаунте, такие как Email, Kuna-ID, активна ли двухфакторная аутентификация.

POST /v3/auth/me

Пример ответа

{
  "email": "my-email@gmail.com",    # email аккаунта
  "kunaid": "kunaid-XXXXXXXXXXXX",  # Kuna ID аккаунте. Его можно сменить через сапорт.
  "two_factor": true,               # активирована ли двухфакторная аутентификация
  "withdraw_confirmation": false,   # нужно ли подтвердение через Email для вывода средств
  "public_keys": {                  # набор ключей для ввода-вывода фиата
    "deposit_sdk_uah_public_key": "pk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "deposit_sdk_usd_public_key": "pk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "deposit_sdk_rub_public_key": "pk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "announcements": false
}

Баланс аккаунта

Метод баланса аккаунта возвращает массив всех балансов всех валют вашего акаунта на Kuna вместе с информацией о достпных средствах.

POST /v3/auth/r/wallets

Пример ответа

[
  [
    'exchange', 
    'USD',      # символ валюты
    1208370,    # полный баланс аккаунта
    null,       # не используется
    1208370     # доступные средства
  ],
  [
    'exchange',
    'KUN',
    800000,
    null,
    760000
  ],
]

Создать ордер

😱 Coming soon
Покачто, этот метод не доступен. Но вы можете создать новый ордер, используя API v2.

Список активных ордеров

Этот метод вернет список всех ваших активных ордеров

POST /v3/auth/r/orders/{?markets}

Примеры запроса

# Вернет список всех активных ордеров
curl -X POST \
  "https://api.kuna.io/v3/auth/r/orders" \
  -d "{}"

# Вернет список активных ордеров только на паре BTC/UAH
curl -X POST \
  "https://api.kuna.io/v3/auth/r/orders/btcuah" \
  -d "{}"

Пример ответа

[
  [
    100279610,      # ID ордера
    null,           # не используется
    null,           # не используется
    'xrpuah',       # код рынка (валютной пары)
    1560089091000,  # время создания (timestamp в милисекундах)
    1560089091000,  # время обновления (timestamp в милисекундах)
    '45.0',         # объем ордера
    '-45.0',        # изначальный обьем ордера
                    # если значение < 0 то ордер на продажу
                    # если > 0, то ордер на покупку
    'LIMIT',        # тип ордера (LIMIT or MARKET)
    null,           # не используется
    null,           # не используется
    null,           # не используется
    null,           # не используется
    'ACTIVE',       # статус ордера
    null,           # не используется
    null,           # не используется
    '14.0',         # цена ордера
    '0.0'           # средняя сделок по ордеру
  ]
]

Список исполненных ордеров

Этот метод вернет список исполненных ордеров

POST /v3/auth/r/orders/{?markets}/hist

Примеры запросов

# Вернет список исполненных ордеров ордеров для любой пары
curl -X POST \
  "https://api.kuna.io/v3/auth/r/orders/hist" \
  -d "{}"

# Вернет список исполненных ордеров только для пары BTC/UAH
curl -X POST \
  "https://api.kuna.io/v3/auth/r/orders/btcuah/hist" \
  -d "{}"

Параметры тела запроса

Параметр Обязательный Описание
start нет Показать ордера с этой даты. Время в миллисекундах. По умолчанию 2 недели назад.
end нет Показать ордера до этой даты. Время в миллисекундах. По умолчанию текущее время.
limit нет Количество записей. По умолчанию 25
sort нет 1 или -1. Порядок сортировки ордеров. По умолчанию ордера возвращаются в порядке убывания.

Пример ответа

[
  [
    100279610,      # ID ордера
    null,           # не используется
    null,           # не используется
    'xrpuah',       # код рынка (валютной пары)
    1560089091000,  # время создания (timestamp в милисекундах)
    1560089091000,  # время обновления (timestamp в милисекундах)
    '45.0',         # объем ордера
    '-45.0',        # изначальный обьем ордера
                    # если значение < 0 то ордер на продажу
                    # если > 0, то ордер на покупку
    'LIMIT',        # тип ордера (LIMIT or MARKET)
    null,           # не используется
    null,           # не используется
    null,           # не используется
    null,           # не используется
    'EXECUTED',     # статус ордера
    null,           # не используется
    null,           # не используется
    '14.0',         # цена ордера
    '13.0'          # средняя сделок по ордеру
  ]
]

Список сделок по ордеру

POST /v3/auth/r/order/{market}:{order_id}/trades

Пример запроса

# Вернет список сделок для ордера ID 10000000 в паре BTC/UAH
curl -X POST \
  "https://api.kuna.io/v3/auth/r/order/btcuah:10000000/trades" \
  -d "{}"

Параметры запроса

Параметр Описание
market Обязательный параметр. Код валютной пары.
order_id Обязательный параметр. ID ордера.

Пример ответа

[
  [
    2538815,            # ID сделки
    'ethuah',           # валютная пара
    1559667470000,      # время сделки
    98140806,           # ID ордера
    '0.032925',         # сумма сделки
    '6798.0',           # курс сделки
    null,               # не используется
    null,               # не используется
    -1,                 # 1 - maker, -1 taker
    '0.0000823125',     # размер комиссии
    'eth'               # валюта комиссии
  ]
]

Отменить ордер

Этот метод позволяет отменить один или несколько активных ордеров.

POST /v3/order/cancel

Пример запроса

# Отменит ордер с ID 1000000 
curl -X POST \ 
  "https://api.kuna.io/v3/order/cancel"
  -d '{"order_id": 1000000}'

# А так можно отменить сразу несколько ордеров, ID 1000000 и ID 1000001
curl -X 'POST' \
  "https://api.kuna.io/v3/order/cancel/multy" \
  -d '{"order_ids": [1000000, 1000001]}'

Пример ответа

{
  "id": 100279610,                  # ID ордера
  "side": "sell",                   # Операция ордера - продажа или покупка
  "type": "limit",                  # Тип ордера, limit или market
  "price": "14.0",                  # Цена ордера
  "avg_execution_price": "0.0",     # Средняя цена сделок по ордеру
  "symbol": "xrpuah",               # Валютная пара ордера
  "timestamp": 1560089091000,       # Время закрытия ордера
  "original_amount": "45.0",        # Изначальный объем ордера
  "remaining_amount": "45.0",       # Объем ордера на момент закрытия
  "executed_amount": "0.0",         # Исполненный объем ордера 
  "is_cancelled": null,
  "is_hidden": null,
  "is_live": null,
  "was_forced": null,
  "exchange": null
}

Сохраненные Карты / Адреса

Добавить новую Карту / Адрес

Удалить Карту / Адрес

Ввод и вывод криптовалюты

Все методы предназначеные для ввода и вывода криптовалюты являются приватными, а значит для каждого вам понадобится подпись.
Если у вас включено подтверждение по почте — то все выводы нужно будет подтверждать. При работе с API с выводами лучше отключать подтверждение по почте.

Kuna Deposit statuses

Kuna Withdraw statuses

Получить адрес для депозита

С помощью этого метода можно узнать на какой адрес нужно зачислять средства. Если аккаунт на Kuna был только что создан, то скорее всего на аккаунте не будет сгенерированных адресов для депозита. В этом случае вам нужно сгенерировать адрес специально для криптовалюты.

POST /v3/auth/deposit/info

Параметры запроса

Параметр Обязательный Описание
currency (string) да Код криптовалюты (btc, ltc, dash, eth и другие)

Пример ответа

{ 
  # количество подтверждений для зачисления средств на баланс
  "confirmations": 1,

  # минимальный размер депозита
  "min_deposit": 1,

  # адрес для депозита
  "address": "rMtb2JEX8xmcgSKxCB7aZPDyzyVhbM2RzV",

  # мемо для криптовалют, которым нужен memo (xrp, eos, stellar)
  "memo": "259002573"
}

⚠️ Eсли адрес для депозита не был сгенерирован, то в поле address будет null. В этом случае вам нужно сгенерировать адрес для депозита с помощью следующего метода.

Сгенерировать новый адрес для депозита

Этот метод позволяет создать новый адрес для депозита криптовалюты.

POST /v3/auth/payment_addresses

Параметры запроса

Параметр Обязательный Описание
currency (string) да Код криптовалюты (btc, ltc, dash, eth и другие)

Пример ответа

{
  "success": true
}

⚠️ Если адрес уже был создан, то при повторном вызове этого метода пройзойдет ошибка:
HTTP/1.1 400 Bad Request

Получить статус депозита

Этим методом можно информацию о депозите криптовалюты или фиата по ID депозита.

POST https://api.kuna.io/v3/auth/deposit/details

Параметры запроса

Параметр Обязательный Описание
id (int32) да ID депозита

Пример ответа

{
  "id": 581303,
  "type": "deposit",

  # время когда был создан депозит
  "created_at": "2019-08-20T13:00:00+02:00",
  
  # адрес на который поступили средства (для крипты)
  "destination": "3P32q2q9WNiMQdfxN2aVYKDaZofQaDcv65E",

  # TXID транзакции (для крипты)
  "txid": "ANDdq75ZTsraJUa6WtUd2kJ7rCvr8y4vH4gBHKn2zjfX",
  
  "currency": 7,                # внутренний ID валюты (/v3/currencies)
  "amount": "1000.0",           # сумма зачисления
  "status": "done",             # статус депозита
  "sn": "Jey38kL3",             # уникальный номер для обращения в сапорт для уточнения статуса
  "provider": null              # способ зачисления в фиате
}

Создание заявки на вывод

Этим методом можно запросить вывод криптовалюты, а так-же он используется и для вывода фита (подробнее в разделе Ввод и вывод фиата).

POST /v3/auth/withdraw

⚠️ Если у вас включено подтверждение по почте — то все выводы нужно будет подтверждать. При работе с выводами по API, лучше отключать подтверждение по почте.

Параметры запроса

Параметр Обязательный Описание
withdraw_type (string) да Код криптовалюты или фиата (btc, ltc, uah, dash, eth и другие)
amount (float) да Сумма вывода (по умолчанию без учета комисcии)
address (string) нет Адрес для вывода криптовалюты (для вывода фиата не нужно его указывать)
gateway (string) нет Шлюз для вывода фиата (не нужен для вывода криптовалюты)
fields (object) нет Дополнительные параметры для вывода фиата (не нужен для вывода криптовалюты)
fund_source_id (int) нет Параметр для вывода фиата через предварительно сохраненный список ресурсов
payment_id (string) нет Memo / Tag / Payment ID. Дополнительны параметр который может быть нужен в таких криптовалютах как XRP, EOS, Stellar и др.
allow_blank_memo (bool) нет Вывод с пустым memo (payment_id) допускается только при значении true для этого параметра.
withdrawall (bool) нет Этот флаг говорит, что amount так-же должен включать комиссию. Полезно, если нужно вывести все средства с аккаунта.

Пример ответа

[
  { 
    # статус заявки на вывод
    "status": "awaiting_confirmation",

    # сообщение новосозданной заявки
    "message": "Your withdrawal request has been successfully submitted.",

    # внутренний ID с которым можно запросить статус этой заявки
    "withdrawal_id": 586829
  }
]

Получить статус заявки на вывод

POST /v3/auth/withdraw/details

Параметры запроса

Параметр Обязательный Описание
id (int32) да ID заявки на вывод

Пример ответа

{
  "id": 586829,                 # внутренний ID заявки

  # дата создания заявки на вывод
  "created_at": "2019-08-20T13:00:00+02:00",

  "destination": "<address>",   # адрес получателя
  "currency": "btc",            # криптовалюта
  "amount": "0.32",             # сумма которая зачислится на адрес
  "status": "string",           # статус заявки
  "txid": "",                   # TXID заявки 
  "sn": "Jey38kL3",             # уникальный номер для обращения в сапорт для уточнения статуса
  "fee": "0.0005",              # комиссия за вывод
  "total_amount": "0.3205",     # суммарно списано с баланса
  "reference_id": ""            # что это???
}

Получить историю вводов и выводов

Этот метод позволяет получить информацию всех операциях ввода и вывода средств.

POST /v3/auth/assets-history/{?type}

Параметры пути метода assets-history

Параметр Описание
type (string) Не обязательный параметр для фильтрации операций по вводу или выводу. Если не указать, то метод вернет и вводы и выводы. withdraws - вернет только операции вывода с аккаунта. deposits - вернет только операции зачисления

Примеры запросов

# Получить абсолютно все транзакции deposit/withdraw или переводы между аккаунтами
curl https://api.kuna.io/v3/auth/assets-history

# Получить только выводы и исходящие транзакции 
curl https://api.kuna.io/v3/auth/assets-history/withdraws

# Получить только зачисления на аккаунт
curl https://api.kuna.io/v3/auth/assets-history/deposits

Параметры запроса

Параметр Обязательный Описание
currency_ids (int32[]) нет Фильтровать операции по список ID валют. ID мо можно получить из метода /v3/currencies
statuses (string[]) нет Фильтровать операции по нескольким из статусов done, pending или canceled
date_from (int32) нет Фильтровать операции от определенного времени. Время в секундах (Unit Time Stamp).
date_to (int32) нет Фильтровать операции до определенного времени. Время в секундах (Unit Time Stamp).
page (int32) нет Номер страницы (по умолчанию 1)
per_page (int32) нет Количество кодов на страницу (по умолчанию 20)
order_by (string) нет Сортировать по created_at, amount (по умолчанию created_at)
order_dir (string) нет Порядок сортировки asc или desc (по умолчанию desc)

Пример ответа

{
  # всего вводов и выводов
  total_items: 1,

  # список операций
  items: [
    {
      # ID операции
      id: 581303,

      # тип `deposit` или `withdraw`
      type: 'deposit',

      # дата операции
      created_at: '2018-09-28T13:06:45Z',

      # адрес на который поступили средства
      destination: '3P32q2q9WNiMQdfxN2aVYKDaZofQaDcv65E',

      # ID криптовалюты, который можно получить в методе `/v3/currencies`
      currency: 7,

      # сумма операции
      amount: 1,

      # статус `done`, `pending` или `canceled`
      status: 'done'
    }
  ],

  # список валют всех операций в списке
  currencies: [
    'waves'
  ]
}

Ввод и вывод фиата

Ввод и вывод фиата на Kuna осуществляется через сервис pay.kuna.io. В Kuna существует 3 фиатные валюты: UAH, USD и RUB. В этом разделе описана процедура для автоматизации процесса ввода и вывода средств. Все методы в Kuna приватные, а значит потребуют подписи.

Получение публичного ключа для каждой из валют

Для некоторых методов для pay.kuna.io вам нужно получить публичный ключ для каждой из поддерживаемых валют. Для этого нужно использовать приватный метод POST https://api.kuna.io/v3/auth/me с которым вы получет JSON ответ, где будут 3 ключа:

{
  "public_keys": {
    # публичный ключ для UAH
    "deposit_sdk_uah_public_key": "pk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

    # публичный ключ для USD
    "deposit_sdk_usd_public_key": "pk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

    # публичный ключ для RUB
    "deposit_sdk_rub_public_key": "pk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"   
  }
}

Для ввода или вывода USD вам нужно использовать deposit_sdk_usd_public_key.

Вывод фиата

Для начала вам нужно получить список доступных способов для вывода.
Это можно сделать с помощью метода POST https://pay.kuna.io/public-api/payout-prerequest.

Пример параметров запроса

{
  "amount": 1000,
  "currency": "UAH",
  "public_key": "<ключ deposit_sdk_uah_public_key>"
}

Вы получите JSON в котором будет содержатся колекция методов вывода под ключем services. Пример коллекции:

{
    "data": {
        "currency": "UAH",
        "amount": 1000,
        "test_mode": false,
        "services": {
            "payment_card_uah": {
                "code": "payment_card_uah",
                "method": "payment_card",
                "currency": "UAH",
                "fields": [{
                  "key": "card_number",
                  "type": "string",
                  "label": { "en": "Card number" },
                  "example": null,
                  "hint": { "en": "Enter card number" },
                  "regexp": "^\\\\d{12,19}$",
                  "required": true,
                  "position": 0
                }],
                "amount_min": 100,
                "amount_max": 250000,
                "exchange_rate": 1,
                "amount": "1000.00",
                "fee": {
                    "rate": 1.5,
                    "fixed": 0,
                    "min": 0,
                    "max": 0
                }
            }
        },
        "methods": {
            "payment_card": {
                "code": "payment_card",
                "category": "payment_card",
                "description": "",
                "name": {"en": "VISA MasterCard"},
                "logo": "https://kuna.io/visamaster.svg",
                "icon": "https://static.openfintech.io/payout_methods/payment_card/icon.svg",
                "metadata": [],
                "position": 0,
                "hide": false
            }
        },
        "account": {
            "name": "Kuna UAH",
            "description": "",
            "icon": "https://kuna.io/images/default.svg?1561271526",
            "website": "https://kuna.io/"
        }
    }
}

Вы должны выбрать нужный сервис и сохранить его code и fields['key'], по этому для payment_card_uah это будет code = payment_card_uah и fields['key'] = card_number.

Потом вам нужно выполнить запрос Создание заявки на вывод с параметрами:

withdraw_type

Код валюты в нижнем регистре (uah, rub, usd).

amount

Сумма для вывода

fields

Содержит имя поля и значение для вывода. Имя поля - это ключ, который вы получили из списка доступных способов вывода (card_number из примера выше), а значение должно быть номером карты, поэтому этот параметр должен быть похож на:

{
  "card_number": "4111111111111111"
}

gateway

Имя сервиса, который будет использован для вывода, это имя сервиса из списка доступных способов вывода (payment_card_uah из примера выше).

withdrawall

Необязательный параметр, установите значение true или 1, если пользователь хочет вывести все средства со счета. Параметрт указывает, что комиссия уже включена в сумму вывода. Например, пользователь хочет снять 1000 UAH, а комиссия составляет 1%, поэтому, если снятие false или 0, общая сумма снятия составит 1000 + 1% = 1010 UAH, а пользователь получит 1000 гривен. В случае, если вывод true или 1 общая сумма вывода составит 1000 UAH, но пользователь получит только 990.1 UAH, а сумма комиссии составит 9.9 UAH.

Вывод на предварительно сохраненную карту

Вы можете совершить вывод используя предварительно сохраненный список средств. В этом случае вам не нужно получать список доступных способов вывода. Просто выполните запрос Создание заявки на вывод с fund_source_id вместо fields:

fund_source_id

Внутренний ID одной из сохраненных карт. Подробнее про сохраненные карты можно прочитать в разделе Сохраненные Карты / Адреса.

Как получить информацию о выводе

  1. Используйте Получить статус заявки на вывод с ID для получения подробной информации о конкретной заявке.
  2. Используйте метод Получить историю вводов и выводов для всей истории выводов.

Ввод фиата на биржу (Депозит)

Для начала вам нужно получить список доступных способов для депозита.
Это можно сделать с помощью метода POST https://pay.kuna.io/public-api/payment-prerequest. \

Пример параметров запроса

{
  "currency": "UAH",
  "public_key": "<ключ deposit_sdk_uah_public_key>"
}

Вы получите JSON, содержащий коллекцию способов депозита:

{
    "data": {
        "currency": "UAH",
        "test_mode": false,
        "services": {
            "payment_card_uah_hpp": {
                "code": "payment_card_uah_hpp",
                "method": "payment_card",
                "flow": "hpp",
                "currency": "UAH",
                "fields": [],
                "amount_min": 100,
                "amount_max": 14000,
                "fee": {
                    "rate": 0,
                    "fixed": 0,
                    "min": 0,
                    "max": 0
                }
            }
        },
        "methods": {
            "payment_card": {
                "code": "payment_card",
                "category": "payment_card",
                "description": "",
                "name": {"en": "VISA MasterCard Ukraine"},
                "logo": "https://kuna.io/depo_mastercard_ukraine.svg",
                "icon": "https://static.openfintech.io/payment_methods/payment_card/icon.svg",
                "metadata": [],
                "position": 0,
                "hide": false
            }
        },
        "account": {
            "name": "Kuna UAH",
            "description": "",
            "icon": "https://kuna.io/images/default.svg?1561307075",
            "website": "https://kuna.io/"
        }
    }
}

Вы должны выбрать нужный сервис и сохранить его code и fields['key']. Имейте ввиду что список fields может быть пустым, это значит что он не обязателен. Для qiwi_rub_hpp это будет code = qiwi_rub_hpp и fields['key'] = phone, а для payment_card_uah_hpp: code = payment_card_uah_hpp, а fields без параметров.

Далее вам нужно выполнить запрос POST https://api.kuna.io/v3/auth/deposit c параметрами:

  • currency - код фиатной валюты в нижнем регистре (uah, rub, usd)
  • amount - сумма депозита

В ответ вы получите deposit_id. Его нужно использовать в поле reference_id в запросе POST https://pay.kuna.io/public-api/payment-invoices.

Для Qiwi (qiwi_rub_hpp):

{
  "public_key": "rub public key",
  "reference_id": "34675687",     # deposit_id из /v3/auth/deposit
  "description": "string",
  "service": "qiwi_rub_hpp",      # code из prerequest

  # параметры из массива fields в prerequest
  "service_fields": {
    "phone": "+9845645756"
  },
  "currency": "rub",
  "amount": 100.78
}

Для AdvCash (advcash_wallet_rub_hpp):

{
  "public_key": "rub public key",
  "reference_id": "34675687",           # deposit_id из /v3/auth/deposit
  "description": "string",
  "service": "advcash_wallet_rub_hpp",  # code из prerequest
  "currency": "rub",
  "amount": 100.78
}

Для Платежной карты (Visa/Mastercard) (payment_card_uah_hpp):

{
  "public_key": "uah public key",
  "reference_id": "34675687",           # deposit_id из /v3/auth/deposit
  "description": "string",
  "service": "payment_card_uah_hpp",    # code из prerequest
  "currency": "uah",
  "amount": 12000
}

Вы получите JSON с ключем active_payment['payload'] который содержит список параметров, которые вы должны использовать для создания простой формы с вашим дизайном (или даже скрытой формы) и далее вы должны отправить ее. Вы будете перенаправлены на страницу процессинга платежа

Упрощенная процедура депозита

Сделайте запрос POST https://api.kuna.io/v3/auth/deposit со списком параметров выше и дополнительным параметром payment_service с значением default. К примеру:

{
  "currency": "uah",
  "amount": 1000,
  "payment_service": "default"
}

Вы получите JSON с несколькими параметрами, которые вы должны использовать для создания простой формы с вашим дизайном (или даже скрытой формы) и далее вы должны отправить ее. Вы будете перенаправлены на страницу процессинга платежа. Например, ответ может выглядеть так:

{ 
  "action": "https://pay.kuna.io/public-api/payment-invoices/process", 
  "params": [
    { "name": "amount", "value": "200.0" },
    { "name": "reference_id", "value": "46797890" },
    { "name": "currency", "value": "UAH" },
    { "name": "service", "value": "payment_service_uah" },
    { "name": "public_key", "value": "uah public key" }
  ]
} 

Как получить информацию о депозите фиата

  1. Что бы получить информацию о конкретном депозите фиата, можно выполнить запрос Получить статус депозита с ID депозита.
  2. Используйте метод Получить историю вводов и выводов для всей истории вводов.

Kuna Codes

Kuna имеет особый функционал для трансфера средств между аккаунтами, без комиссий и СМС. Он называется Kuna Code.

Kuna Code имеет структуру:
857ny-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-KUN-KCode

Всего, тело Kuna Code состоит из 45 символов (или 9 сегментов по 5 символов) и суфикса.

  1. Первый сегмент из 5-ти символов - это публичная часть кода.
  2. Потом идет 8 сегментов по 5 символов, это приватная часть кода.
  3. Суфикса KUN-KCode, это валюта и метка что это код от куны.

Валидация кода offline (по чексумме)

Первые 45 символов сегенирированны случайно. Первый символ, это чексумма остальных 44. Используя первый символ можно валидировать Kuna Code не обращаясь на сервер kuna.io. Первый символ расчитывается как сумма остальных по модулю 58.

Алгоритм валидации KunaCode на JavaScript:

function validateKunaCode(kunaCode) {
  const base58Alphabet = '123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ';

  // Разбиваем KunaCode по строкам и берем тело, без суфикса
  const body = kunaCode.split('-').slice(0, -2).join('');

  // Берем первый символ кода
  const checksum = base58Alphabet.indexOf(body[0]);

  // Отделяем остальные 44 символа кода 
  const str = body.slice(1);
  let i = str.length;
  let sum = 0;

  // Пробегаемся по каждому символу и суммируем его позицию в алфавите base58
  while (i--) {
    sum += base58Alphabet.indexOf(str.charAt(i));
  }
  
  // Сверяем чексумму
  if (sum % 58 !== checksum) {
    // Выбрасываем ошибку, так как чексумма не верная
    throw new Error('Invalid checksum');
  }

  return true;
}

Статусы кодов

Название статуса Описание
created Был создан
processing В процессе выпуска
unconfirmed Ожидает подтверждения
active Можно активировать
redeeming В процессе активации
redeemed Активирован
onhold Под подозрением
canceled Отменен

API объект Kuna Code

Почти все методы возвращают одинаковую структуру данных для Kuna Code. Будь то создание, или получение конкретного кода, или получение списка кодов, вы всегда получите такие данные:

{
  # внутренний ID
  "id": 519,

  # ID для указания к супорту
  "sn": "p9MajCjlLo72",

  # секретный ключ кода, по которому он и активируется
  "code": "857ny-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-KUN-KCode",

  # Kuna-ID того кто может активировать код.
  # если 'all' то активировать может кто угодно
  "recipient": "all",

  # сумма кода
  "amount": "800000",

  # валюта кода
  "currency": "kun",

  # статус кода
  "status": "active",

  # время, до которого нельзя активировать код владельцем
  "non_refundable_before": "2019-08-20T13:00:00+02:00",

  # время создания кода
  "created_at": "2019-03-20T13:00:00+02:00",

  # время активации кода
  "redeemed_at": null,

  # приватный коментарий кода
  "comment": "Try to activate inside your Plark Wallet",

  # публичный коментарий кода
  "private_comment": "Ripple to the MOON!"
}

Проверить Kuna Code

Единственный публичный метод для Kuna Code.
Этот метод позволяет проверить доступность Куна кода по его первому сегменту, а так-же узнать валюту, сумму, использован он или еще нет. Метод вернет API объект Kuna Code.

GET /v3/kuna_codes/{code}/check

Параметры пути

Параметр Описание
code (string) 5 первых символов Kuna Code.

Создать Kuna Code

Можно создать Kuna Code с помощью этого метода. Через API можно указать Kuna ID получателя, дату, до которой код не будет доступен создателю на активацию, публичную и приватную заметку.

POST /v3/auth/kuna_codes

Параметры запроса

Параметр Обязательный Описание
recipient нет Получатель кода. По умолчанию код может актировать кто угодно, но если указать Kuna ID, то код сможет ввести только этот аккаунт.
amount* да Сумма кода
currency* да Валюта кода
non_refundable_before нет Формат ISO8601. Дата до которой владелец кода не сможет его активировать.
comment нет Публичная заметка к коду.
private_comment нет Приватная заметка к коду, которая видна только владельцу кода.

Активировать Kuna Code

Этот метод позволяет активировать Kuna Code и зачислить средства на ваш аккаунт.

PUT /v3/auth/kuna_codes/redeem

Параметры запроса

Параметр Обязательный Описание
code (string) да Код вида 857ny-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-KUN-KCode

При успешной активации вы получете ответ:

HTTP/1.1 200 OK

А теле ответа будет API объект Kuna Code.

Получить информацию о Kuna Code по ID

У любого кунакода есть уникальный номер. Этот метод позволяет получить информацию о Kuna Code по этому номеру. Метод вернет API объект Kuna Code.

POST /v3/auth/kuna_codes/details

Параметры запроса

Параметр Обязательный Описание
id (int32) да Внутренний ID кода

⚠️ Если Kuna Code не пренадлежит вам, то в ответ вы получете ошибку
HTTP/1.1 404 Not Found

Список выпущенных кодов

С помощью этого метода можно получить список кодов, которые были выпущенны с вашего аккаунта. Метод вернет список объектов, описанных в разделе API объект Kuna Code.

POST /v3/auth/kuna_codes/issued-by-me

Параметры запроса

Параметр Обязательный Описание
page (int32) нет Номер страницы (по умолчанию 1)
per_page (int32) нет Количество кодов на страницу (по умолчанию 10)
order_by (string) нет Сортировать по created_at, redeemed_at, amount (по умолчанию created_at)
order_dir (string) нет Порядок сортировки asc или desc (по умолчанию desc)
status (string[]) нет Фильтровать по статусам created, processing, active, redeeming, redeemed, onhold, canceled

Список активированных кодов

С помощью этого метода можно получить список кодов, которые были активированы и средства были зачисленны на ваш аккаунт. Метод вернет список объектов, описанных в разделе API объект Kuna Code.

POST /v3/auth/kuna_codes/redeemed-by-me

Параметры запроса

Параметр Обязательный Описание
page (int32) нет Номер страницы (по умолчанию 1)
per_page (int32) нет Количество кодов на страницу (по умолчанию 10)
order_by (string) нет Сортировать по created_at, redeemed_at, amount (по умолчанию redeemed_at)
order_dir (string) нет Порядок сортировки asc или desc (по умолчанию desc)
You can’t perform that action at this time.