Instant exchange API

The following methods are used to empower your service with Changelly exchange features. You can implement these features or request more by contacting our developers team. Changelly PRO is always white-labeled and you can use it the way you like.

Table of contents:

  1. Getting started
  2. Usage
    1. Protocol
    2. Authentication
    3. Currency list
    4. Setting up addresses
    5. Estimated exchange amount
    6. Minimum exchangeable amount
    7. Identifying the transaction
    8. Getting exchange status
    9. Socket.io
    10. Support
  3. Basic UI
  4. Coming soon

Getting started

  1. Contact pro@changelly.com for API access.
  2. Get verification.
  3. Get the API key and API secret.
  4. Start implementing.
  5. Check the implementation examples on Github.

Usage

Use case

Here is simple use case of our exchange API:
for instance, user wants to exchange LTC (Litecoin) to BTC (Bitcoin)
  1. GUI — asks the user for the LTC amount to exchange;
  2. API — 'getExchangeAmount' returns estimated BTC amount after exchange;
  3. GUI — shows estimate BTC amount for user and ask confirmation;
  4. GUI — asks the user for it's BTC wallet address to send coins after exchange;
  5. API — 'generateAddress' for exchange pair LTC->BTC — returns LTC address to receive coins from user;
  6. GUI — asks the user to send LTC coins to the address for exchange;
  7. User sends coins, their are exchanged and withdraw to his BTC address;
  8. Via socket.io API functions you can get the user's transaction status online;
  9. Via 'getTransactions' you can get all the transactions history.

Protocol

Changelly API uses JSON-RPC 2.0 protocol, defining only a handful of data types and commands.

Example:
{
  "jsonrpc": "2.0",
  "method": "getMinAmount",
  "params": {
    "from": "btc",
    "to": "bcn"
  },
  "id": 1
}

Authentication

All calls must contain the following headers:

api-key — Your API key.
sign — The query's data signed by your key's "secret" according to the HMAC-SHA512 method.

NodeJs example:
var crypto = require("crypto");
 
var message = {
  "jsonrpc": "2.0",
  "method": "getMinAmount",
  "params": {
    "from": "btc",
    "to": "bcn"
  },
  "id": 1
};
 
var sign = crypto
             .createHmac('sha512', apiSecret)
             .update(JSON.stringify(message))
             .digest('hex');

Currency list

Command 'getCurrencies' will return you the currency list available for an exchange. Check the list of available currencies at Supported currencies page before you start.

Example:
{
  "jsonrpc": "2.0",
  "method": "getCurrencies",
  "params": {},
  "id": 1
}

Setting up addresses

With the method 'generateAddress', you will create a pair of addresses for deposits and withdrawals. Every pair is unique for a user. So if a user sends some coins to the same address twice, the coins will be exchanged and sent to the user's wallet.

'address' is necessary for sending exchanged coins.
'extraId' is a field required by some currencies as additional information to proceed with the transaction: payment ID (CryptoNote currencies), destination tag (XRP) or public key (NXT).

Example:
{
  "jsonrpc": "2.0",
  "method": "generateAddress",
  "params": {
    "from": "eth",
    "to": "xmr",
    "address": "47hxsKgUYrKb37beq2vowcf1ojfxu1X3zjpUH6uGyBjrWHnGQLGbLwa5LKQcUN8jVG9SprG8s2hRMexJWhdvEPmuV3ncZSQ",
    "extraId": "ad5baa2b10ce0a015aa153a369bdc096ef29954a5096b98042296ddd79b3a4a8"
  },
  "id": 1
}

Estimated exchange amount

You can notify users of the amount they will receive after exchange using 'getExchangeAmount'. You need to provide the request with currency pair ('from', 'to') and the 'amount' user is exchanging.

Example:
{
  "jsonrpc": "2.0",
  "method": "getExchangeAmount",
  "params": {
    "from": "eth",
    "to": "btc",
    "amount": "3.99"
  },
  "id": 1
}

Minimum exchangeable amount

We don’t have maximum limits, but to proceed with an exchange we need it to be larger than the exchange fee. Use 'getMinAmount' with a currency pair ('from', 'to') to notify users of the minimum amount they need to send.

Example:
{
  "jsonrpc": "2.0",
  "method": "getMinAmount",
  "params": {
    "from": "btc",
    "to": "eth",
  },
  "id": 1
}

Note: most users do not read the information about the minimum amount. Be sure to highlight this information in your UI. If users send less than the minimum amount, their coins will likely be lost.

Identifying the transaction

In some cases, you'll have to identify the exchange a user has ordered (for example, to provide support or to show the exchange process). You can use two unique identifiers: 'transactionID' and 'transactionHash'.

Example:
{
  "jsonrpc": "2.0",
  "method": "getTransactions",
  "params": {
    "currency": "xmr", //optional
    "address": "47hxsKgUYrKb37beq2vowcf1ojfxu1X3zjpUH6uGyBjrWHnGQLGbLwa5LKQcUN8jVG9SprG8s2hRMexJWhdvEPmuV3ncZSQ", //optional
    "extraId": null, //optional
    "limit" 10,
    "offset" : 10
  },
  "id": 1
}

Getting exchange status

With the transaction ID, you can get Exchange status to notify your user or to provide additional support.

Example:
{
  "jsonrpc": "2.0",
  "method": "getStatus",
  "params": {
    "id": "1d36f592f21e"
  },
  "id": 1
}
StatusDescription
'confirming'Your transaction is in a mempool and waits to be confirmed.
'exchanging'Your payment is received and being exchanged via our partner.
'sending'Money is sending to the recipient address.
'finished'Money is successfully sent to the recipient address.
'failed'Transaction has failed. In most cases, the amount was less than the minimum.
'refunded'Exchange was failed and coins were refunded to user's wallet. The wallet address should be provided by user.

Socket.io

As well as JSON RPC, the API provides socket.io interface for receiving exchange status. You can subscribe on 'status' events. The subscription should be signed and have a valid logon message.

Example:
socket.on("connect", function() {
  socket.emit("subscribe",
    {
      "apiKey": apiKey,
      "sign": sign,
      "message": {
        "Login": {}
      }
    }
  );
});
 
socket.on("status", function(data) {
  console.log(data);
});

Support

Direct your users to Changelly's support. You can receive the widget code and instructions by request.


Basic UI

You can get the basic web page with API implementation by request.

About Changelly

Coming soon

  • Revenue share — set your own exchange fee and receive revenue
  • Back office — start supporting your users with and easy-to-use admin panel




Contact pro@changelly.com for API access.