Author profile photo
Команда Swapgate
19 ноября 2024 г.
~3 мин. чтения

APIv2

Следующие методы используются для расширения возможностей вашего сервиса с помощью функций обмена Swapgate.io.

Алгоритм

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

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

                                                                            A окончательный ​=A расчетный ∗ (1 − K надбавка / 100)

Финал​ Окончательная итоговая сумма, прогнозируемая для обмена
Расчетный​ Первоначальная дата для получения прогноза по обмену
К- разметка значение параметра разметки

Исходя из представленной формулы, величина наценки 0,3, предусмотренная для обмена 1 BTC → USDT, дает следующие результаты, в результате чего итоговый прогноз увеличивается на 0,3%:

                                                                       49549,728053855135 * (1 – 0,3/100) = 49401,07886969357

API

Данные о тарифах можно получить с помощью API v1, обратившись к /api/v1/rates/public/one endpoint .

API v1 не требует авторизации ключей API или белых списков IP-адресов.

Параметр Описание Пример
instrumentFromCurrencyTitle Название валюты, подлежащей обмену БТД
instrumentFromNetworkTitle Сетевая валюта для обмена БТД
instrumentToCurrencyНазвание Название валюты, которую необходимо получить USDT
instrumentToNetworkTitle Сеть валюты, необходимо получить ее ТРК20
rateMode Режим обмена курса ПЛАВАЮЩИЙ или ФИКСИРОВАННЫЙ. ПЛАВАЮЩИЙ
заявленныйДепозитСумма Сумма депозита, заявленная звездному клиенту 1
разметка Параметр разметки 0.3 
GET /api/v1/rates/public/one?instrumentFromCurrencyTitle=BTC&instrumentFromNetworkTitle=
BTC&instrumentToCurrencyTitle=USDT&instrumentToNetworkTitle=TRC20&rateMode=FLOATING&claimedDepositAmount=
1&markup=0.3
{
	"instrumentFrom": {
		"currencyTitle": "BTC",
		"networkTitle": "BTC",
		"precisionDecimals": 11
	},
	"instrumentTo": {
		"currencyTitle": "USDT",
		"networkTitle": "TRC20",
		"precisionDecimals": 1
	},
	"depositRules": {
		"minAmount": "0.0010202831699481001984",
		"maxAmount": "0"
	},
	"withdrawalRules": {
		"minAmount": "51.324600057525118367",
		"maxAmount": "0",
		"withdrawalFeeRules": {
			"maxAmount": "1",
			"minAmount": "1"
		}
	},
	"minConfirmationsToWithdraw": 2,
	"minConfirmationsToTrade": 2,
	"updatedAt": "2024-08-05T13:31:44.315Z",
	"liquidityProviderPublicCode": "radio",
	"amountToGet": "50201.90689595",
	"amountToGive": "1",
	"marketMinAmount": "0.1",
	"enableFixedRate": true,
	"amountToGiveCurrencyTitle": "BTC",
	"rateMode": "FLOATING",
	"finalNetworkFeeAmount": "0",
	"platformFee_Absolute": null,
	"liquidityProviderQuotes": {
		"sellQuote": {
			"baseValue": "1",
			"quoteValue": "50304.27"
		},
		"buyQuote": {
			"baseValue": "50294.99",
			"quoteValue": "1"
		}
	},
	"price": "50201.90689595",
	"marketLeftPrice": "50304.27",
	"marketRightPrice": "0.000019882696069727819809",
	"marketAmountToGet": "50243.798064469251204",
	"marketAmountToGetUSDT": "50243.798064469251204",
	"quotesWithoutNetworkFee": {
		"sellQuote": {
			"baseValue": "1",
			"quoteValue": "50202.90689595"
		},
		"buyQuote": {
			"baseValue": "50294.99",
			"quoteValue": "0.997985"
		}
	},
	"quotes": {
		"sellQuote": {
			"baseValue": "1",
			"quoteValue": "50201.90689595"
		},
		"buyQuote": {
			"baseValue": "50294.99",
			"quoteValue": "0.99796512097183797717"
		}
	},
	"markup": "0.3"
}

Параметр наценки в потоке заказов

Алгоритм

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

                                                                                                                                    Вывод = Обмен * ( 1 – ( Платформа C(%) + Наценка K ) / 100)

Отзыв​ Сумма валюты, отправленная клиенту в качестве результата обмена
Обмен​ Количество валюты, которая была доступна Swapgate после выполнения нашей торговой стратегии.
Платформа C (% ) Процент сессии, текущий Swapgate
К- разметка значение параметра разметки

Исходя из приведенной формулы, значение наценки 0,3, указанное при оформлении заказа, увеличивает процент комиссии Swapgate на 0,3.
В следующей комиссии Swapgate установлен на 1 процент:

                                                                                                                                 Снятие = Обмен * (1 – (1 + 0,3) / 100)

использование предыдущего примера, обмен 1 BTC на USDT на основе рыночной цены 50243,798064469251204 BTC:USDT приводит к следующему итоговому результату средств клиента:

50243.798064469251204 * (1 – (1 + 0.3) / 100) = 49590.62868963115

Исходя из представленной формулы, значение наценки 0,3, указанное при создании заказа, увеличит процент комиссии Swapgate на 0,3.
После того как обмен с параметром наценки перейдет в состояние COMPLETED, параметр наценки будет использован в формуле расчета партнерской маржи:

                                                                                                                              C affiliate = C platform * (C affiliate(%) / 100) + C platform * (K markup / 100)

C affiliate​ Количество валюты, отправленной на кошелек партнера за обмен (партнерская маржа)
C platform Сумма валюты, которую Swapgate получил от обмена (маржа платформы)
C affiliate(%)​ Процент комиссионных, определенный для аффилированного лица
K markup ​ markup значение параметра

Передача параметра markup

При создании заказа Swapgate API принимает параметр разметки наряду с другими параметрами создания заказа:


{
	"rateMode": "FLOATING",
	"instrumentFrom": {
		"currencyTitle": "USDT",
		"networkTitle": "TRC20"
	},
	"instrumentTo": {
		"currencyTitle": "BTC",
		"networkTitle": "BTC"
	},
	"destinationAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
	"destinationAddressMemo": null,
	"refundAddress": null,
	"refundAddressMemo": null,
	"claimedNetworkFee": null,
	"legacyOrderId": null,
	"referrerId": "aff_616",
	"claimedDepositAmount": "125000",
	"utmData": [],
	"browserFingerprint": "6b3add86bec11616427d069556a33548"
	"markup": "0.2" // <-- here
}

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

Использование API v2

Использование конечных точек API v2 требует дополнительной настройки авторизации. Без необходимых параметров авторизации конечные точки v2 будут выбрасывать ошибку 403 Forbidden.
Интеграция состоит из двух шагов – создания API-ключа и интеграции его использования в API-запросы. Создав ключ API, наши b2b-клиенты получат пару ключей для подписи своих запросов, а также список белых IP-адресов, которые могут получить доступ к конечным точкам API.

Примечание: для выполнения запросов /api/v1/users/* у вас должен быть активный cookie авторизации.

Создание ключа API

При создании ключа API необходимо передать массив белых списков IP-адресов:


POST /api/v1/users/generate-api-key

Request:
{
	"name": "test",
	"whiteListIp": ["127.0.0.1"],
	"isActive": true
}

Response:
{
	"apiId": 40,
	"name": "test",
	"isActive": true,
	"publicKey": "ZgzycV6Sf78BZKuyIAiz+0Bor002+0/rx1gLKsmYCsY=",
	"secretKey": "a482a8e3a3ff9aeadefb11d3d8c11253e7e8412e05ef2b8599016cc87a64b7d6",
	"whiteListIp": [
		"127.0.0.1"
	],
	"createdAt": "2024-08-05T13:54:18.427Z"
}

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

Примечание: Поле secretKey будет отображаться только один раз, во время создания ключа API. Мы советуем сохранить его сразу после создания ключа API.

Список ключей API

Если ваша интеграция требует использования более одного API-ключа, вы можете легко перечислить их с помощью конечной точки list:


GET /api/v1/users/list-api-key

[
	{
		"apiId": 40,
		"name": "test",
		"isActive": true,
		"settings": {},
		"publicKey": "ZgzycV6Sf78BZKuyIAiz+0Bor002+0/rx1gLKsmYCsY=",
		"whiteListIp": [
			"127.0.0.1"
		],
		"createdAt": "2024-08-05T13:54:18.427Z"
	}
]

Управление ключами API

Управление существующими ключами API может быть осуществлено через нашу линию поддержки клиентов b2b. Это включает в себя:

  • удаление ключей API
  • Добавление новых IP-адресов из белого списка к существующему ключу API
  • Обновление и добавление настроек для ключа API (например: минимальные/максимальные значения для разметки)
  • Деактивация ключей API

Использование ключа API

API v2 требует установки 3 заголовков при каждом запросе:

Заголовок Значение
x-api-public-key Ваш открытый ключ, полученный при создании ключа API
x-api-timestamp Временная метка UNIX
x-api-signature Подпись под запросом

Значение меняется с помощью hmac sha256. Поскольку контроль данных использует строковую конкатенацию временной метки, строковое представление запроса тела и открытый ключ, закрытый ключ используется в качестве ключа к функции hmac:


function signRequest(requestBody) {
  const timestamp = new Date().getTime();
  const publicKey = "ZgzycV6Sf78BZKuyIAiz+0Bor002+0/rx1gLKsmYCsY=";
	const privateKey = "a482a8e3a3ff9aeadefb11d3d8c11253e7e8412e05ef2b8599016cc87a64b7d6";
	
	const encoder = new TextEncoder();
	const data = encoder.encode(
		timestamp + JSON.stringify(requestBody) + publicKey,
	);
	
	const hmac = createHmac('sha256', privateKey);
	const dataSign = hmac.update(data);
	const signature = dataSign.digest('base64');
	
	return signature;
}

signRequest({ myKey: "myValue" })

Пример кода инициативы


const { createHmac } = require('crypto');

const API_PREFIX = 'https://swapgate.io/api/';
const PUBKEY = 'public_key'; // changeme
const PRIVKEY = 'private_key'; // changeme

function signRequest(requestBody, timestamp) {
  const encoder = new TextEncoder();
  const data = encoder.encode(timestamp + JSON.stringify(requestBody) + PUBKEY);

  const hmac = createHmac('sha256', PRIVKEY);
  const dataSign = hmac.update(data);
  const signature = dataSign.digest('base64');

  return signature;
}

async function createOrder() {
  const clientBrowserFingerprint = '6b3add86bec11616427d069556a33548';
  const orderRateMode = 'FLOATING';
  const depositAmount = '1';
  const clientDestinationAddress = 'TUhw6S1HyXDhycKvTec3x7HNGQfNn3Vhpc';
  const clientDestinationAddressMemo = null;
  const markup = '0.3';
  const instrumentFromCurrencyTitle = 'BTC';
  const instrumentFromNetworkTitle = 'BTC';

  const instrumentToCurrencyTitle = 'USDT';
  const instrumentToNetworkTitle = 'TRC20';

  // Step 1. Prepate createOrder request body using obtained rate data

  const createOrderRequestBody = {
    rateMode: orderRateMode,
    instrumentFrom: {
      currencyTitle: instrumentFromCurrencyTitle,
      networkTitle: instrumentFromNetworkTitle,
    },
    instrumentTo: {
      currencyTitle: instrumentToCurrencyTitle,
      networkTitle: instrumentToNetworkTitle,
    },
    destinationAddress: clientDestinationAddress,
    destinationAddressMemo: clientDestinationAddressMemo,
    refundAddress: null,
    refundAddressMemo: null,
    markup: markup,
    claimedNetworkFee: null,
    legacyOrderId: null,
    referrerId: null,
    claimedDepositAmount: depositAmount,
    utmData: [],
    browserFingerprint: clientBrowserFingerprint,
  };

  // Step 2. Prepare signature based on key pair and createOrder request data

  const timestamp = new Date().getTime();
  const signature = signRequest(createOrderRequestBody, timestamp);

  // Step 3. Call API v2 create-order endpoint

  const order = JSON.parse(
    await (
      await fetch(`${API_PREFIX}v2/orders/public/create`, {
        method: 'POST',
        headers: {
          'x-api-public-key': PUBKEY,
          'x-api-timestamp': timestamp,
          'x-api-signature': signature,
          'content-type': 'application/json; charset=utf-8',
        },
        body: JSON.stringify(createOrderRequestBody),
      })
    ).text(),
  );

  console.log('order', order);
}

void createOrder();
Поделиться статьей: