API-методы

Формирование запроса

Обратите внимание, текущая версия API может незначительно измениться.

Запрос-ответ

Все запросы к API представляют из себя JSON запрос методом POST или GET, когда нет тела запроса, на адрес следующего вида: https://api.bitflip.cc/method/METHOD.

METHOD – любой доступный метод из списка.

Тело запроса представляет из себя JSON в виде обычной hash-структуры:

{"version": "1.0","nonce": 0,"argument": "...value"}

version (опционально) – желаемая версия API для использования. По умолчанию – последняя доступная.

nonce (опционально) – если данный параметр передан, то все последующие запросы выполнятся только в случае большего nonce, чем в предыдущем. Тип – int64. По умолчанию – 0, проверка не учитывается.

Ответ унифицирован и представляет из себя следующую структуру:

[error, response]

error – null или строка с кодом ошибки, если она есть.

response – результат запроса, в зависимости от вызванного метода.

Дополнительно возвращаются заголовки с метадаными:

X-Server-Time – серверное время в UNIX TIMESTAMP * 1000 (UTC)

X-API-Version – используемая версия API для ответа

Открытые и закрытые методы

Существуют открытые и закрытые методы. Открытые методы не требуют авторизацию и возвращают результат на любой запрос. Закрытые методы требуют создания специального API-токена в личном кабинете с целью использовать его для авторизации.

Закрытые методы принимают токен и подпись запроса в заголовках. Токен передается в заголовке X-API-Token. Подпись запроса передается в заголовке X-API-Sign.

Формирование подписи

Формирование подписи происходит следующим образом. Берется тело POST-запроса, например '{"version": 1.0}', далее оно подписывается с помощью алгоритма HMAC sha-512 с использованием секретного ключа токена.

Например, наш секретный ключ – top-secret. Наш JSON-запрос – {"version": 1.0}. Подпись в этом случае будет формироваться как HMAC sha512. Подпись: fb909103d8177205a227a1f58079e4bda61be8e32faa71cd1ae17487651b42c3676073f827d208b53e8198ca231a3259cafeeb7521932e6e1f4ac7d177055d09

Примеры

Запрос:

curl -H 'Content-type: application/json' -d '{"version": "1.0"}' https://api.bitflip.cc/method/server.getTime

Ответ:

[null, 1499927970357]

Коды ошибок

При ошибочном ответе в качестве ошибки возвращается строковой идентификатор оишбки.

e_api_version_not_found – неправильная версия API.

e_api_method_not_found – указан несуществующий метод API.

e_api_token_not_found – неправильный токен, переданный в заголовке X-API-Token.

e_api_token_inactive – токен отключен, запросы по нему невозможны.

e_api_sign_incorrect – неправильная подпись для текущего запроса в заголовке X-API-Sign.

e_something_went_wrong – что-то пошло не так, попробуйте повторить или обратиться в техподдержку.

e_[field]_required – не передано обязательное поле [field] в теле запроса, где [field] – id, pair, type, amount, rate, symbbol.

e_[field]_incorrect – неправильное значение в поле [field] запроса, где [field] – limit, pair, state, symbol, period, locale.

e_[field]_not_found – объект типа [field] не был найден, возможно, неправильные значения, где [field] – pair, wallet, order, symbol, locale.

Методы

server.getTime открытый

Получение текущего времени на сервере.

Возвращает число с UNIX TIMESTAMP * 1000 (UTC).

Результат:

1499940778211

market.getTrades открытый

Получение списка проведенных сделок по определенной торговой паре.

Параметры:

pair (обязательно) – пара в формате строки, например, btc:usd.

limit (опционально) – число, сколько сделок выводить. От 1 до 500, по умолчанию – 50.

Результат:

[{"id": "QPYRgfwiB9","type": "buy","amount": 0.01,"rate": 3000,"price": 30,"timestamp": 1497768062},"..."]

id – внутренний строковой идентификатор сделки.

type – тип: buy или sell.

amount – общее количество единиц по сделке.

rate – ставка за единицу.

price – общая стоимость всех единиц.

timestamp – UNIX TIMESTAMP проведения сделки.

market.getUserTrades закрытый

Получение списка проведенных сделок по определённой торговой паре пользователем текущего токена.

См. market.getTrades.

market.getUserOrders закрытый

Получение списка ордеров по торговой паре пользователем текущего токена.

Параметры:

pair (обязательно) – пара в формате строки, например, btc:usd.

state (опционально) – строка или массив статусов сделок для фильтрации из доступных, например, [opened, traded] для активных или closed для закрытых. По умолчанию выборка идет только по активным.

limit (опционально) – число, сколько сделок выводить. От 1 до 500, по умолчанию – 50.

Результат:

[{"id": "QPYRgfwiB9","state": "opened","type": "buy","open_amount": 0.001,"amount": 0.001,"rate": 0.001,"price": 0.000001,"timestamp": 1498215757},"..."]

id – внутренний строковой идентификатор ордера

state – статус ордера: opened, closed, traded, canceled

amount – общее количество единиц по ордеру

rate – ставка за единицу

price – общая стоимость всех единиц

timestamp – UNIX TIMESTAMP создания ордера.

market.getOrderBook закрытый

Получение стакана на продажу и покупку по конкретной торговой паре.

Параметры:

pair (обязательно) – пара в формате строки, например, btc:usd.

type (опционально) – строка или массив типов ордеров для фильтрации из доступных: buy, sell. По умолчанию – [buy, sell].

limit (опционально) – число, сколько сделок выводить. От 1 до 500, по умолчанию – 50.

Результат:

{"buy": [{"amount": 0.2,"rate": 2247,"price": 449.4},"..."],"sell": [{"amount": 0.2487343,"rate": 2233,"price": 555.4236919},"..."]}

buy – список активных ордеров на покупку.

sell – список активных ордеров на продажу.

amount – количество единиц.

rate – ставка за одну единицу.

price – цена по текущей ставке за все единицы как amount * rate.

market.getPairs открытый

Получение всех доступных пар для торгов и информации о них.

Результат:

[{"pair": "BTC:USD","enabled": true,"fee": {"maker": 0.001,"taker": 0.0018},"amount": {"min": 0.001,"max": 10000000,"step": 0.00000001},"rate": {"min": 0.001,"max": 10000000,"step": 0.00000001},"price": {"min": 0.001,"max": 10000000,"step": 0.00000001}},"..."]

pair – торгуемая пара, например, BTC:USD.

enabled – участвует ли пара на торгах, булевое значение.

fee.maker – установленная комиссия на пару как мейкера, используется лучшая из возможных – комиссия на паре или аккаунте в зависимости от объема сделок.

fee.taker – установленная комиссия как тейкера на этой паре.

amount – информация о торгуемой единице, минимальное и максимальное допустимое значение, и шаг.

rate – информация о ставке.

price – информация об общей цене на ордер по текущей паре (amount * rate).

market.getSymbols открытый

Получение всех торгуемых символов на платформе.

Результат:

["USD","RUB","BTC","LTC","ETH","..."]

market.getRates открытый

Получение текущих ставок по активным ордерам.

Результат:

[{"pair": "USD:EUR","buy": 0,"sell": 0},{"pair": "USD:RUB","buy": 294,"sell": 0.3435902},"..."]

pair – торгуемая пара.

buy – ставка на покупку, если 0 – нет данных.

sell – ставка на продажу, если 0 – нет данных.

market.getOHLC открытый

Получение OHLC данных по сделкам на торговой паре.

Параметры:

pair (обязательно) – пара в формате строки, например, btc:usd.

period (опционально) – период в часах от 1 до 24. По умолчанию – 24.

Результат:

{"volume": 0,"high": 0,"low": 0,"open": 0,"close": 0,"ohlc_avg": 0,"hlc_avg": 0}

volume – объем торгов.

high – максимальная ставка за единицу.

low – минимальная ставка за единицу.

open – открывающая ставка за единицу.

close – закрывающая ставка за единицу.

ohlc_avg – среднее значение (open + high + low + close) / 4.

hlc_avg – среднее значение (high + low + close) / 3.

order.get закрытый

Получение информации об ордере пользователя текущего токена по его идентификатору.

Параметры:

id – строковой идентификатор ордер.

Результат:

{"id": "QPYRgfwiB9","state": "traded","type": "sell","pair": "BTC:USD","open_amount": 34,"amount": 28.477,"rate": 111,"price": 3160.947,"timestamp": 1498321616}

id – внутренний строковой идентификатор ордера.

state – статус ордера: opened, closed, traded, canceled.

type – тип ордера: buy или sell.

pair – торгуемая пара.

open_amount – общее количество единиц по ордеру на этапе открытия.

amount – оставшееся количество единиц по ордеру, доступных для проведения сделки.

rate – ставка за единицу.

price – общая стоимость всех единиц.

timestamp – UNIX TIMESTAMP создания ордера.

order.create закрытый

Исполнение и создание нового ордера на покупку или продажу.

Параметры:

pair (обязательно) – пара в формате строки, например, btc:usd.

type (обязательно) – тип ордера: buy или sell.

amount (обязательно) – количество единиц для размещения в ордере.

rate (обязательно) – ставка за единицу.

Результат:

{"executed": {"amount": 0.001,"min_rate": 111,"max_rate": 111,"price": 0.111},"order": {"id": "QPrHefwiB9","state": "opened","type": "sell","open_amount": 0.001,"amount": 0.001,"rate": 2399,"price": 2.399,"timestamp": 1499944786}}

executed.amount – исполненное количество (куплено или продано).

executed.min_rate – минимальная ставка, по которой исполнен ордер.

executed.max_rate – максимальная ставка, по которой исполнен ордер.

executed.price – итоговоая стоимость единиц.

order – созданный ордер, если заявка не была исполнена полностью, см. order.get.

order.cancel закрытый

Отмена активного ордера и возврат неиспользованных средств на кошелек.

Параметры:

id (обязательно) – строковой идентификатор ордера.

Результат:

{"id": "QPYRgfwiB9","state": "canceled","type": "sell","open_amount": 1,"amount": 1,"rate": 2399,"price": 2399,"timestamp": 1499944328}

См. order.get

wallet.get закрытый

Получение информации о своем кошельке по идентификатору.

Параметры:

id (обязательно) – строковой идентификатор кошелька.

Результат:

{"id": "QPYRgfwiB9","symbol": "LTC","address": "LQoifHCPS2Vqgt3mk64xmfn1abdfGpgAda","amount": {"available": 1353.71391024,"pending": 2342,"trading": 2144},"timestamp": 1498772107}

id – строковой идентификатор кошелька на платформе.

symbol – валюта кошелька.

address – адрес для пополнения кошелька, если это криптовалюта.

amount.available – текущий доступный баланс на кошельке.

amount.pending – временно недоступный баланс в системе, например, обработка вывода.

amount.trading – сумма, находящаяся на созданных ордерах.

timestamp – UNIX TIMESTAMP последнего изменения (транзакции).

wallet.getBySymbol закрытый

Получение информации о своем кошельке по идентификатору.

Параметры:

symbol (обязательно) – строковой идентификатор символа, например, LTC.

См. wallet.get

wallet.getBalances закрытый

Получение всех кошельков и балансов для текущего аккаунта.

Результат:

[{"id": "QPYRgfwiB9","symbol": "USD","address": "","amount": {"available": 1353.71391024,"pending": 2342,"trading": 2144},"timestamp": 1498772107},"..."]

См. wallet.get

wallet.getTransactions закрытый

Получение последних транзакций по идентификатору своего кошелька.

Параметры:

id (обязательно) – строковой идентификатор кошелька.

locale (опционально) – желаемая локаль для описаний транзакций: ru, en. По умолчанию – ru.

Результат:

[{"id": "QNTQJE9uak","desc": "Wallet transfer","state": "confirmed","amount": 0.12199999,"fee": 0,"timestamp": 1500050521},"..."]

id – строкой идентификатор транзакции на платформе.

desc – текстовое описание транзакции.

state – статус транзакции: confirmed, pending, processing, canceled.

amount – сумма транзакции в валюте кошелька вместе с комиссией.

fee – комиссия на текущую транзакцию.

timestamp – UNIX TIMESTAMP создания транзакции.

user.get закрытый

Получение информации о пользователи текущего токена.

Результат:

{"id": "QPYRgfwiB9","name": "ro","fee": {"taker": 0.0014,"maker": 0.0007},"trade_volume": {"USD": 0,"BTC": 18.34399996,"LTC": 0.01,"ETH": 0,"DASH": 0,"DOGE": 0,"XRP": 0},"trade_volume_btc": 22.04484664}

id – строковой идентификатор пользователя.

name – имя пользователя на платформе.

fee.taker – комиссия на ордеры как тейкер.

fee.maker – комиссия на ордеры как мейкер.

trade_volume – оборот за последние 30 дней в разных валютах.

trade_volume_btc – объем оборотов за 30 дней в биткоинах, на оснвое которого устанавливается новая комиссия на сделки.