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. Minimum exchangeable amount
    5. Estimated exchange amount
    6. Setting up addresses
    7. Identifying the transaction
    8. Getting exchange status
    9. Socket.io
    10. Support
  3. Basic UI
  4. Extra options

1 Getting started

  1. Register and get the API key — generate;
  2. Start implementing;
  3. In case of questions ask pro@changelly.com.

2 Usage

Usage schema

Implementation examples on GitHub:

API URL https://api.changelly.com

Use case

Here is simple use case of our exchange API:
  1. API — get available currencies at the moment with 'getCurrencies' method;
  2. GUI — asks user for currency pair he wants to exchange; For example, it can be LTC (Litecoin) to ETH (Ethereum);
  3. API — get minimum exchangeable amount for selected currency pair with 'getMinAmount' method;
  4. GUI — asks the user for amount to exchange;
  5. API — call 'getExchangeAmount' method to get estimated ETH amount after exchange;
  6. GUI — shows estimate amount for user and ask confirmation;
  7. GUI — asks the user for it's wallet address to send coins after exchange;
  8. API — call 'generateAddress' method to get the LTC address to which the user should send his funds;
  9. GUI — asks the user to send LTC coins to the address for exchange;
  10. User sends coins, their are exchanged and withdraw to his ETH address;
  11. Via socket.io API functions you can get theuser's transaction status online;
  12. Via 'getTransactions' you can get all the transactions history.

2.1 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": "ltc",
    "to": "eth"
  },
  "id": 1
}

2.2 Authentication

All calls must contain the following headers:

api-key — your API key;
sign — the query's serialized body 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": "ltc",
    "to": "eth"
  },
  "id": 1
};
 
var sign = crypto
             .createHmac('sha512', apiSecret)
             .update(JSON.stringify(message))
             .digest('hex');

2.3 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
}

2.4 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": "ltc",
    "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.

2.5 Estimated exchange amount

You can show to users estimated amount of coins they receive as a result of exchange using 'getExchangeAmount'. You need to provide the request with currency pair ('from', 'to') and the 'amount' user is going to exchange.

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

To get rate for multiple currency pairs, you just have to pass array of arguments, i.e. for one currency pair:

{
  "jsonrpc": "2.0",
  "method": "getExchangeAmount",
  "params": [{
    "from": "ltc",
    "to": "eth",
    "amount": "3.99"
  }, {
    "from": "dash",
    "to": "xmr",
    "amount": "3.99"
  }],
  "id": 1
}

2.6 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 message (NXT).

Example:
{
  "jsonrpc": "2.0",
  "method": "generateAddress",
  "params": {
    "from": "ltc",
    "to": "eth",
    "address": "0x49f79352100bd92eb2ba3daa30852f03abdd8315",
    "extraId": null
  },
  "id": 1
}

2.7 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": "eth", //optional
    "address": "0x079a84b458f48dd53a319c85a9031fd2d6216412", //optional
    "extraId": null, //optional
    "limit" 10,
    "offset" : 10
  },
  "id": 1
}

2.8 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
}
Response example:
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.

2.9 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);
});
Event data example:
{
  "id": "adfa2359b68d",
  "status": "finished",
  "payinConfirmations": "10",
  "hash": "9f19186213799b82776c6792238c6b1c016404bb7003346f890bf754b36f69ca",
  "payinHash": "9f19186213799b82776c5792238c6b1c016504bb7003346f890bf754b36f69ca",
  "payoutHash": "0x1d04f3df2f7209ca985895ecf2e31a07e04889367d37d98c1e8d90fdfb568ec8",
  "payinAddress": "NBLQ6PE7Z5CVANJNXGOR74UQLOJ2YMGJJOZ4YFAQ",
  "payinExtraId": "7c5aefb158ec11e7bbdcafa2978ff15b",
  "payoutAddress": "0x988fa9Bb5C0a462932d9C714E2643a4692E4ABc5",
  "payoutExtraId": null,
  "currencyFrom": "ltc",
  "currencyTo": "eth",
  "amountFrom": "10",
  "amountTo": "0.2",
  "networkFee": "0.01"
}

2.10 Support

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


Basic UI

About Changelly

Extra options (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.




To get access to api, please login

Or Sign up for a new account with email:

Track record proved security

Connection uses TLS 1.2