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. Your API extra commission
  3. Usage
    1. Protocol
    2. Authentication
    3. Currency list
    4. Minimum exchangeable amount
    5. Estimated exchange amount
    6. Generating transaction
    7. Identifying the transaction
    8. Getting exchange status
    9. Socket.io
  4. Support
    1. Dedicated support-line
    2. Operations history online

1 Getting started

  1. Register and get the API key — generate;
  2. Start implementing;
  3. In case of questions ask [email protected].

2 Your API extra commission

You may up any extra commission you want.

For example, you could choose to take a 0.5% commission (as an example, though we can set up any commission you want). We always take our 0.5%, so in this case your users would then have a total commission of 1%.

To set up an extra commission, please email us with a link to your service.

Your API exrta commission is included in a result of getExchangeAmount function call.

3 Usage

Usage schema

Implementation examples on GitHub:

API Documentation link: https://api-docs.changelly.com
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' or 'getCurrenciesFull' 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 'createTransaction' 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.

3.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
}

3.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');

3.3 Currency list

Commands 'getCurrencies' and 'getCurrenciesFull' 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
}

3.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.

3.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
}
Extra API fee is included in "amount".

3.6 Generating transaction

With the method 'createTransaction', 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.

'from' is a currency to exchange from
'to' is a currency to exchange to
'address' is necessary for sending exchanged coins;
'extraId' is a field required by some currencies as additional information to proceed with 'amount' is expected amount that user will send to payin address the transaction: payment ID (CryptoNote currencies), destination tag (XRP) or message (NXT).

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

3.7 Identifying the transaction

You can use transaction ID returned from 'createTransaction' method.

Also you can use 'getTransactions' method to list all transactions those satisfy request params.

Example:
{
  "jsonrpc": "2.0",
  "method": "getTransactions",
  "params": {
    "currency": "eth", //optional
    "address": "0x079a84b458f48dd53a319c85a9031fd2d6216412", //optional
    "extraId": null, //optional
    "limit" 10,
    "offset" : 10
  },
  "id": 1
}

3.8 Getting exchange status

With the transaction ID, obtained from createTransaction call, 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.

3.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"
}

4 Support

4.1 Dedicated support-line

Changelly provides two options for support. Please choose your support-line and inform us at [email protected]:

— You just redirect users to our support line;

— You provide the first line support from your side and send your tickets directly to our dedicated email address. These tickets are forwarded strictly to our second level support team. It will be assigned the highest priority. Please don't make our email public.

Inform us in case the dedicated support-line is needed. Feel free to request it at [email protected].

Also, send us a link to your service, confirm that you are ready to provide support from your side and you won’t share that email with your clients.

The support-line option is provided at the discretion of the Changelly's developer team.

4.2 Operations history online

You can check all the transactions with online stats on the history page in your personal account.

About Changelly

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