API SaleSwap

Введение

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

Чтобы использовать API SaleSwap, вам необходимо получить API key и API secret.

Получение ключа API

Чтобы получить API Key и API Secret, выполните следующие действия:

Войдите или Зарегистрируйтесь на SaleSwap
Перейдите в раздел API management
Нажмите кнопку "Сгенерировать" и следуйте инструкциям в появившемся окне
Скопируйте API Key и API Secret и сохраните их в надежном месте. Используйте эти параметры для запросов к API SaleSwap

Запрос и пример

Отправляемые данные должны быть в формате JSON с кодировкой UTF-8.

Для успешных запросов API все запросы должны содержать несколько обязательных заголовков:

Заголовок Content-Type должен быть application/json; charset=UTF-8
Заголовок X-API-KEY должен содержать ваш полученный API Key (YOUR_API_KEY)
Заголовок X-API-SIGN должен содержать подпись GENERATED_SIGN. Чтобы получить подпись, вы должны использовать свой API Secret (YOUR_API_SECRET) в качестве ключа операции HMAC SHA256 и строку данных json в качестве значения.

X-API-SIGN generation

Curl Python PHP


			[linux]$ echo -n 'DATA_JSON' | openssl dgst -sha256 -hmac "YOUR_API_SECRET"
			(stdin)= GENERATED_SIGN


			cURL -X POST \
			  -H "Accept: application/json" \
			  -H "X-API-KEY: YOUR_API_KEY" \
			  -H "X-API-SIGN: GENERATED_SIGN" \
			  -H "Content-Type: application/json; charset=UTF-8" \
			  -d 'DATA_JSON'
			  "/api/v2/METHOD" -L


			import hmac
			import json
			import hashlib
			import requests
			  
			def sign(params):
			  if isinstance(params, dict):
			    parts = []
			    for k in params:
			      parts.append('%s=%s' % (k, params[k]))
			    payload = '&'.join(parts)
			  else:
			    payload = params
			  return hmac.new(
			    key=YOUR_API_SECRET.encode(),
			    msg=payload.encode(),
			    digestmod=hashlib.sha256
			  ).hexdigest()
			  
			  
			def request(method, params={}):
			  url = 'https://ff.io/api/v2/' + method
			  data = json.dumps(params)
			  headers = {
			    'X-API-KEY':  YOUR_API_KEY,
			    'X-API-SIGN': sign(params)
			  }
			  r = requests.post(url, data=params, headers=headers)
			  return r.json()
			  
			request(METHOD, DATA)


			<?php
			  function sign($data) {
			    return hash_hmac('sha256', $data, YOUR_API_SECRET);
			  }
			  
			  function request($method, $data) {
		        $url = 'https://ff.io/api/v2/'.$method;
		        
		        $req = json_encode($data);
		        
		        $ch = curl_init();
		        curl_setopt($ch, CURLOPT_URL, $url);
		        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
		        curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
		        curl_setopt($ch, CURLOPT_POST, true);
		        curl_setopt($ch, CURLOPT_POSTFIELDS, $req);
		        curl_setopt($ch, CURLOPT_HTTPHEADER, array(
		          'Content-Type:application/json',
		          'X-API-KEY: '  . YOUR_API_KEY,
		          'X-API-SIGN: ' . sign($req)
		        ));
		        $response = curl_exec($ch);
		        curl_close($ch);
		        
		        $result = json_decode($response, true);
		        if ($result['code'] == 0) {
		          return $result['data'];
		        } else {
		          throw new Exception($result['msg'], $result['code']);
		        }
		      }
		      
		      request(METHOD, DATA);
			?>

Ограничения запроса

Лимит запросов в минуту составляет 250 единиц.

Запрос /api/v2/create стоит 50 единиц, все остальные запросы стоят 1 единицу.

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

Официальные библиотеки

Вы можете использовать готовые библиотеки для использования SaleSwap API:

PHP (Download)
Python (Download)

Доступные валюты

POSThttps://ff.io/api/v2/ccies

Получение списка валют, поддерживающихся сервисом SaleSwap, а также данных по их отображению и информации о доступности на приём и отправку.

Параметры

Для данного запроса не нужно передавать параметры.

Генерация X-API-SIGN осуществляется с помощью вызова функции HMAC SHA256 от пустой строки, если параметры не передаются, или от пустого JSON объекта.

Example request

Curl Python PHP


			cURL -X POST \
			  -H "Accept: application/json" \
			  -H "X-API-KEY: YOUR_API_KEY" \
			  -H "X-API-SIGN: GENERATED_SIGN" \
			  -H "Content-Type: application/json; charset=UTF-8" \
			  "/api/v2/ccies" -L


			<?php
			  require_once('fixedfloat.php');
			  
			  $ff = new SaleSwapApi(YOUR_API_KEY, YOUR_API_SECRET);
			  
			  return $ff->ccies();
			?>

Ответ

Успешный ответ содержит массив объектов с информацией о валютах.

Field	Type	Description
code	number	Response status code. If the request is successful, then the status code is "0", otherwise it is an error
msg	string	Status message
data	Array	List of currencies supported by SaleSwap
data[].code	string	Unique currency code in SaleSwap
data[].coin	string	Common asset ticker
data[].network	string	Blockchain network in which this asset is represented
data[].name	string	Name of currency
data[].recv	boolean	Availability of currency for acceptance into the service from the client
data[].send	boolean	Availability of currency to send to the client
data[].tag	string	The name of the additional field, if available; otherwise null
data[].logo	string	Link to currency image
data[].color	string	Currency color specified in HEX format
data[].priority	number	Priority in the list of currencies of the service

Example JSON response


			{
  "code": 0,
  "msg": "",
  "data": [
    {
      "code": "BTC",
      "coin": "BTC",
      "network": "BTC",
      "name": "Bitcoin",
      "recv": true,
      "send": true,
      "tag": null,
      "logo": "https://fixedfloat.com/assets/images/coins/svg/btc.svg",
      "color": "#f7931a",
      "priority": "5",
    },
    ...,
  ],
}

Обменный курс

POSThttps://ff.io/api/v2/price

Получение обменного курса пары валют в выбранном направлении и типе курса.

ВНИМАНИЕ! Для получения обменных курсов всех доступных валют следует использовать экспортных вайл курсов, доступный по ссылке https://ff.io/rates.xml

Для данного метода, как и для метода /api/v2/create, доступна возможность увеличения начисляемого заработка по партнёрской программе с помощью параметра afftax.

Окончательный обменный курс при передаче параметров afftax и refcode зависит от того, было ли получено разрешение для вашего кода партёрской программы на получаемый заработок для заказов, созданных по API, и базового процента (AFFBASE), установленного для вашего кода, и будет считаться по формуле:


total = FF - AFFB + afftax, если afftax < FF - AFFB
total = afftax x 2        , если FF - AFFB < afftax < FF
total = FF + afftax       , если afftax > FF

где FF - базовый процент сервиса за выбранный тип курс обмена (1% для фиксированного курса и 0.5% для плавающего курса);
AFFB - базовый процент от прибыли сервиса, установленный для вашего кода партнёрской программы, за выбранный тип курс обмена (AFFBASE для фиксированного курса и AFFBASE÷2 для плавающего курса)

Для наглядности предлагаем ознакомиться с таблицей ниже при AFFBASE=0.4, где FFP = FF - AFFB:

FIXED RATE			FLOAT RATE
Total	FFP	afftax	Total	FFP	afftax
1.0	0.6	0.4	0.5	0.3	0.2
1.1	0.6	0.5	0.55	0.3	0.25
1.2	0.6	0.6	0.6	0.3	0.3
1.4	0.7	0.7	0.7	0.35	0.35
1.6	0.8	0.8	0.8	0.4	0.4
1.8	0.9	0.9	0.9	0.45	0.45
2.0	1.0	1.0	1.0	0.5	0.5
2.1	1.0	1.1	1.05	0.5	0.55
2.2	1.0	1.2	1.1	0.5	0.6

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


FF + afftax

где FF - базовый процент сервиса за выбранный тип курс обмена (1% для фиксированного курса и 0.5% для плавающего курса).

Заработок будет начисляться на ваш аккаунт, если код партнёрской программы был передавн в параметре refcode и данный код принадлежит вашему аккаунту. В противном случае параметры afftax и refcode будут проигнорированы.

Параметры

Name	Required	Type	Description
type	true	string	Order type
fromCcy	true	string	Code of the currency the client wants to send
toCcy	true	string	Code of the currency the client wants to receive
direction	true	string	The direction of the exchange determines whether the client wants to send a certain amount or receive a certain amount. Can take one of the following values: ● from — if the client wants to send the amount amount in the currency fromCcy ● to — if the client wants to receive the amount amount in the currency toCcy
amount	true	numeric	If direction="from", then this is the amount in currency fromCcy that the client wants to send. If direction="to", then this is the amount in currency toCcy that the client wants to receive
ccies	false	boolean	Adding a list of currencies to the response with information about the availability for sending and receiving
usd	false	boolean	Amount in USD, by which fromAmount or toAmount will be changed in case the limits are exceeded
refcode	false	string	Affiliate program code for which earnings will be accrued under the affiliate program. If the afftax parameter is not set and this affiliate program code does not participate in earning via the API, passing this parameter will not affect anything. It is possible to transfer only affiliate program codes that were received in the same account in which the API key used for this request was received
afftax	false	float	Desired earnings under the affiliate program as a percentage of the exchange amount. Affects the final exchange rate and earnings under the affiliate program if the refcode parameter is also set.

Example request

Curl Python PHP


			cURL -X POST \
			  -H "Accept: application/json" \
			  -H "X-API-KEY: YOUR_API_KEY" \
			  -H "X-API-SIGN: GENERATED_SIGN" \
			  -H "Content-Type: application/json; charset=UTF-8" \
			  -d '{"fromCcy":"BTC","toCcy":"USDTTRC","amount":0.5,direction":"from","type":"float"}'
			  "/api/v2/create" -L


			<?php
			  require_once('fixedfloat.php');
			  
			  $ff = new SaleSwapApi(YOUR_API_KEY, YOUR_API_SECRET);
			  
		      $data = array(
		        'fromCcy'    => 'BTC',
		        'toCcy'      => 'USDTTRC',
		        'amount'     => '0.5',
		        'direction'  => 'from',
		        'type'       => 'float',
		      );
			  
			  return $ff->price($data);
			?>

Ответ

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

Field	Type	Description
code	number	Response status code. If the request is successful, then the status code is "0", otherwise it is an error
msg	string	Status message
data	Object	An object with information about the currencies of the selected pair, the exchange rate, and the amount sent and received
data.from	Object	Data about the asset that the client must send
data.from.code	string	Unique currency code in SaleSwap
data.from.network	string	Blockchain network in which this asset is represented
data.from.coin	string	Common asset ticker
data.from.amount	string	Amount that the client needs to send
data.from.rate	string	Final exchange rate
data.from.precision	integer	Rounding accuracy
data.from.min	string	Minimum amount
data.from.max	string	Maximum amount
data.from.usd	string	Equivalent in USD
data.from.btc	string	Equivalent in BTC
data.to	Object	Data about the asset that the client will receive
data.to.code	string	Unique currency code in SaleSwap
data.to.network	string	Blockchain network in which this asset is represented
data.to.coin	string	Common asset ticker
data.to.amount	string	Amount that the client must to receive
data.to.rate	string	Final exchange rate
data.to.precision	integer	Rounding accuracy
data.to.min	string	Minimum amount
data.to.max	string	Maximum amount
data.to.usd	string	Equivalent in USD
data.errors	Array	An array of a list of errors. If the array is empty, then creating an order with these parameters is possible. The array may contain the following errors: ● MAINTENANCE_FROM — Currency from data.from object under maintenance ● MAINTENANCE_TO — Currency from object data.to under maintenance ● OFFLINE_FROM — Currency from object data.from is not available ● OFFLINE_TO — Currency from object data.to is not available ● RESERVE_FROM — Not enough currency reserves from object data.from ● RESERVE_TO — Not enough currency reserves from object data.to ● LIMIT_MIN — Amount less than limit ● LIMIT_MAX — The amount is greater than the limit
data.ccies	Array	Added if the ccies parameter is true. An array containing a list of objects with information about the availability for sending and receiving currencies
data.ccies[].code	string	Unique currency code in SaleSwap
data.ccies[].recv	boolean	Availability of currency for acceptance into the service from the client
data.ccies[].send	boolean	Availability of currency to send to the client

Example JSON response


			{
  "code": 0,
  "msg": "",
  "data": {
    "from": {
      "code": "BSC",
      "network": "BSC",
      "coin": "BNB",
      "amount": "0.040297",
      "rate": "0.01452202",
      "precision": 8,
      "min": "0.005053",
      "max": "967.072057",
      "usd": "12.28",
      "btc": "0.00058813",
    },
    "to": {
      "code": "BTC",
      "network": "BTC",
      "coin": "BTC",
      "amount": "0.00055984",
      "rate": "68.164781",
      "precision": 8,
      "min": "0.0000479",
      "max": "14.04381911",
      "usd": "11.69",
    },
    "errors": [],
    "ccies": [
      {
        "code": "ADA",
        "recv": true,
        "send": true,
      },
      ...,
    ],
  },
}

Создание заказа

POSThttps://ff.io/api/v2/create

Создание заказа на обмен выбранных валют с заданной суммой и адресом.

Для данного метода, как и для метода /api/v2/price, доступна возможность увеличения начисляемого заработка по партнёрской программе с помощью параметра afftax. Правила использования данного параметры описаны в разделе метода /api/v2/price

Параметры

Name	Required	Type	Description
type	true	string	Order type
fromCcy	true	string	Code of the currency the client wants to send
toCcy	true	string	Code of the currency the client wants to receive
direction	true	string	The direction of the exchange determines whether the client wants to send a certain amount or receive a certain amount. Can take one of the following values: ● from — if the client wants to send the amount amount in the currency fromCcy ● to — if the client wants to receive the amount amount in the currency toCcy
amount	true	numeric	If direction="from", then this is the amount in currency fromCcy that the client wants to send. If direction="to", then this is the amount in currency toCcy that the client wants to receive
toAddress	true	string	Destination address to which the funds will be dispatched upon the successful completion of the Order
tag	false	boolean	If you need to specify a Memo or Destination Tag when sending, you should specify it here. This parameter can be omitted by specifying the MEMO or Destination Tag in toAddress separated by a colon.
refcode	false	string	Affiliate program code for which earnings will be accrued under the affiliate program. If the afftax parameter is not set and this affiliate program code does not participate in earning via the API, passing this parameter will not affect anything. It is possible to transfer only affiliate program codes that were received in the same account in which the API key used for this request was received
afftax	false	float	Desired earnings under the affiliate program as a percentage of the exchange amount. Affects the final exchange rate and earnings under the affiliate program if the refcode parameter is also set.

Example request

Curl Python PHP


			cURL -X POST \
			  -H "Accept: application/json" \
			  -H "X-API-KEY: YOUR_API_KEY" \
			  -H "X-API-SIGN: GENERATED_SIGN" \
			  -H "Content-Type: application/json; charset=UTF-8" \
			  -d '{"fromCcy":"BTC","toCcy":"USDTTRC","amount":0.5,direction":"from","type":"float","toAddress":"TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr"}'
			  "/api/v2/create" -L


			<?php
			  require_once('fixedfloat.php');
			  
			  $ff = new SaleSwapApi(YOUR_API_KEY, YOUR_API_SECRET);
			  
		      $data = array(
		        'fromCcy'    => 'BTC',
		        'toCcy'      => 'USDTTRC',
		        'amount'     => '0.5',
		        'direction'  => 'from',
		        'type'       => 'float',
		        'toAddress'  => 'TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr'
		      );
			  
			  return $ff->create($data);
			?>

Ответ

Успешный ответ содержит содержит объект с информацией о всех данных созданного заказа, включая параметр token, для последующего получения обновлённой информации о заказе с помощью метода /api/v2/order, и управления заказом.

Field	Type	Description
code	number	Response status code. If the request is successful, then the status code is "0", otherwise it is an error
msg	string	Status message
data	Object	Object with information about all the data of the created order
data.token	string	Order access token
data.id	string	Order ID. Consists of 6 characters
data.type	string	Order type. Can be one of the values: ● fixed — fixed rate order ● float — floating rate order
data.email	string	Email address for the order to receive notifications about changes in the order
data.status	string	Order status. Can be one of the values: ● NEW — New order ● PENDING — Transaction received, pending confirmation ● EXCHANGE — Transaction confirmed, exchange in progress ● WITHDRAW — Sending funds ● DONE — Order completed ● EXPIRED — Order expired ● EMERGENCY — Emergency, customer choice required
data.time	Object	Object containing timestamp data
data.time.reg	number	Order creation timestamp
data.time.start	number	Transaction receive timestamp
data.time.finish	number	Timestamp when the order was completed
data.time.update	number	Timestamp of last order update
data.time.expiration	number	Timestamp when order expires