Перейти к содержанию

Blockchain connector BTC-like Service API

Обзор

Для каждого поддерживаемого блокчейна доступен набор эндпоинтов, позволяющий сформировать транзакцию, подписать ее и отправить в сеть, а также получить адрес из публичного ключа.

Параметры запросов, встроенные в url, например, идентификатор блокчейна, являются обязательными. Параметры в query string или JSON теле запроса могут быть опциональными и подробно описаны в соответствующих разделах.

Адрес сервера: https://cloud.spatium.net/blockchain-connector-btc-like/v1 Swagger

Для данного адреса сервера доступно взаимодействие со следующими блокчейнами:

  • btc;
  • ltc;
  • bch.

Структура запросов и информации в ответах для них одинакова.

Типы данных

Network

Network - тип сети. Как правило, блокчейны поддерживают минимум два варианта: тестовая сеть для разработки (testnet) с фиктивными активами и стабильная рабочая сеть (livenet) с реальными активами. Структура данных: 

type Network = 'livenet' | 'testnet';

AddressType

AddressType - формат адреса Legacy (p2pkh) или SegWit (p2wpkh), применим только для Bitcoin и Litecoin блокчейнов. Структура данных: 

type AddressType = 'p2pkh' | 'p2wpkh';

UTXO

UTXO (unspent transaction output) - неизрасходованный вывод транзакции. Структура данных: 

type UTXO = {
  txid: string;
  vout: number;
  value: string;
};

  • txid - идентификатор транзакции;
  • vout - идентификатор вывода в этой транзакции;
  • value - сумма.

API

Генерация адреса из публичного ключа

Swagger Get address

Структура запроса POST /api/get-address/{chain}

{
   publicKey: string;
   network?: Network;
   type?: AddressType;
   prefix?: boolean;
}

{
  requestId: string;
  data: {
    address: string;
  };
}

Параметры

  • publicKey - публичный ключ, обязательный параметр (строка),

  • network - тип сети, необязательный параметр, значение по умолчанию 'livenet' (Network),

  • type - формат адреса, необязательный параметр, значение по умолчанию 'p2wpkh', для bch данный параметр игнорируется (AddressType),

  • prefix - наличие префикса в адресе, необязательный параметр, значение по умолчанию false (логическое значение).

Получение данных для формирования транзакции

Для формирования и оценки комиссии транзакции необходимо получить следующий набор данных:

  • список UTXO,
  • размер транзакции,
  • стоимость байта.

Swagger Prepare transaction API

POST /api/prepare-transaction/estimate

GET /api/prepare-transaction/utxo-list/{chain}/{address}

POST /api/prepare-transaction/size/{chain}

GET /api/prepare-transaction/price-per-byte/{chain}

Эндпоинт estimate позволяет получить все необходимые для формирования и оценки транзакции данные одним запросом. Также есть возможность получения этих данных тремя отдельными запросами (utxo-list, size, price-per-byte).

Estimate

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

Swagger Prepare transaction Estimate

Структура запроса POST api/prepare-transaction/estimate/{chain}

{
   address: string;
   publicKey: string;
   network?: Network;
   type?: AddressType;
   to: string;
   amount: string;
}

{
  requestId: string;
  data: {
    utxo: UTXO[];
    size: number;
    fees: { normal: string; fast: string; slow: string };
  };
}

Параметры

  • address - адрес отправителя, обязательный параметр (строка),

  • publicKey - публичный ключ, обязательный параметр (строка),

  • network - тип сети, необязательный параметр, значение по умолчанию 'livenet' (Network),

  • type - формат адреса, необязательный параметр, значение по умолчанию 'p2wpkh', для bch данный параметр игнорируется (AddressType),

  • to - адрес получателя, обязательный параметр (строка),

  • amount - сумма во внутреннем целочисленном формате, обязательный параметр (строка).

Список utxo по адресу

Список UTXO необходим для корректного формирования транзакции и расчета ее размера.

Swagger Prepare transaction UTXO

Структура запроса GET /api/prepare-transaction/utxo-list/{chain}?address={address}&network=livenet

Параметры

  • address - адрес отправителя, обязательный параметр (строка),

  • network - тип сети, необязательный параметр, значение по умолчанию 'livenet' (Network).

Структура ответа

{
 requestId: string;
 data: { utxo: UTXO[] };
}

Размер транзакции

Размер транзакции необходим для корректного расчета комиссии транзакции.

Swagger Prepare transaction Size

Структура запроса POST /api/prepare-transaction/size/{chain}

{
   publicKey: string;
   network?: Network;
   type?: AddressType;
   utxo: UTXO[];
   to: string;
   amount: string;
}

{
  requestId: string;
  data: {
    size: number;
  };
}

Параметры

  • publicKey - публичный ключ, обязательный параметр (строка),

  • network - тип сети, необязательный параметр, значение по умолчанию 'livenet' (Network),

  • type - формат адреса, необязательный параметр, значение по умолчанию 'p2wpkh', для bch данный параметр игнорируется (AddressType),

  • utxo - список неизрасходованных выводов транзакций, обязательный параметр (UTXO),

  • to - адрес получателя, обязательный параметр (строка),

  • amount - сумма во внутреннем целочисленном формате, обязательный параметр (строка).

Стоимость байта

Сумма сатоши за один байт размера транзакции необходима для корректного расчета комиссии. Сумма зависит от режима отправки (slow, normal, fast). Итоговая комиссия транзакции рассчитывается как произведение размера транзакции на сумму сатоши за один байт для выбранного режима отправки.

Swagger Prepare transaction Price per byte

Структура запроса GET /api/prepare-transaction/price-per-byte/{chain}?network=livenet

Параметры

  • network - тип сети, необязательный параметр, значение по умолчанию 'livenet' (Network).

Структура ответа

{
 requestId: string;
 data: { bytePrices: { normal: string; fast: string; slow: string } };
}

Транзакции

Swagger Transaction API

POST /api/transaction/get-hash/{chain}

POST /api/transaction/attach-signature/{chain}

POST /api/transaction/send/{chain}

Получение хэша транзакции

Swagger Transaction Get hash

Структура запроса POST /api/transaction/get-hash/{chain}

{
   publicKey: string;
   network?: Network;
   type?: AddressType;
   utxo: UTXO[];
   to: string;
   amount: string;
   fee: string;
}

{
  requestId: string;
  data: { hashes: { inputIndex: number; hash: string }[] };
}

Параметры

  • publicKey - публичный ключ, обязательный параметр (строка),

  • network - тип сети, необязательный параметр, значение по умолчанию 'livenet' (Network),

  • type - формат адреса, необязательный параметр, значение по умолчанию 'p2wpkh', для bch данный параметр игнорируется (AddressType),

  • utxo - список неизрасходованных выводов транзакций, обязательный параметр (UTXO),

  • to - адрес получателя, обязательный параметр (строка),

  • amount - сумма во внутреннем целочисленном формате, обязательный параметр (строка),

  • fee - комиссия транзакции, обязательный параметр (строка).

Подпись транзакции

Swagger Transaction Attach signature

Структура запроса POST /api/transaction/attach-signature/{chain}

{
   publicKey: string;
   network?: Network;
   type?: AddressType;
   utxo: UTXO[];
   to: string;
   amount: string;
   fee: string;
   signatures: {
       inputIndex: number;
       signature: {
         s: string;
         r: string;
         recovery: number;
       };
   }[];
}

{
  requestId: string;
  data: { txdata: string };
}

Параметры

  • publicKey - публичный ключ, обязательный параметр (строка),

  • network - тип сети, необязательный параметр, значение по умолчанию 'livenet' (Network),

  • type - формат адреса, необязательный параметр, значение по умолчанию 'p2wpkh', для bch данный параметр игнорируется (AddressType),

  • utxo - список неизрасходованных выводов транзакций, обязательный параметр (UTXO),

  • to - адрес получателя, обязательный параметр (строка),

  • amount - сумма во внутреннем целочисленном формате, обязательный параметр (строка),

  • fee - комиссия транзакции, обязательный параметр (строка),

  • signatures - массив объектов с данными подписи, обязательный параметр.

Отправка транзакции в сеть

Swagger Transaction Send

Структура запроса POST /api/transaction/send/{chain}

{
   txdata: string;
   network?: Network;
}

{
  requestId: string;
  data: { txid: string };
}

Параметры

  • txdata - данные подписанной транзакции, обязательный параметр (строка),

  • network - тип сети, необязательный параметр, значение по умолчанию 'livenet' (Network).