API

Get the token

You need to create the request for authentification:

POST https://api.bestrate.org/api/auth/login

In “body” of the request you need to use the email and password of BestRate’s user

{"email":"......","password":"....."}

You’ll get the token for Partner’s API in the response

{

“success”: true,
“result”:{

“token”: “bearer eyJhbGc……….vV940GT1B0”,
“user”:{
“email”: “…….”

}

}

}

Get the transactions list

POST https://api.bestrate.org/api/partner/transactions

In the header you need to use the token, that you got in the previous step (authentication request)

Authorization: bearer eyJhbGc……….vV940GT1B0

You’ll get transaction list in the response:

{
"success": true,
"result": {
"list": [
{
"transactionId": "c81.....462c",
"service": "changelly",
"fromTicker": "dash",
"toTicker": "btg",
"fromAmount": 2,
"toAmount": 5.37477,
"createdAt": "2017-12-08T10:45:22.000Z",
"completedAt": "2018-03-30T15:39:43.000Z",
"updatedAt": "2018-03-30T15:39:43.000Z",
"blockchainUrl": "https://btgexp.com/tx/9299a.......cce499a",
"toWallet": "Aaaw......d73Jf6J",
"status": "finished",
"partnerId": "demo-widget",
"user": {
"email": "........."
},
"returnWallet": "",
"fromWallet": "Xt3......DPuazE"
},
.....
],
"total": 24
}
}

Descriptopn

“transactionId”: //id of transaction,
“service”: //provider for exchange,
“fromTicker”: //ticker of currency which client sent
“toTicker”: //ticker of currency which partner get to their address,
“fromAmount”://amount of coins which client sent,
“toAmount”: //amount of coins which client should get (by rate at transaction creation moment),
“createdAt”: //date of transaction creation,
“completedAt”: //date when transaction was complete,
“updatedAt”: //date when transaction was updated,
“blockchainUrl”: //blockchain url of exchange transaction (can be null, if transaction not complete or fail),
“toWallet”: //address when coins was send (ico address, or generated holder address),
“status”: //status of transaction

  • new – only created
  • overdue – client created transaction, but not sent coins
  • finished – exchange completed and ico should send coins
  • fail – exchange failed in exchange provider side
  • failed_by_error or failed_by_ico_trade – transaction failed by error on bestrate side)

“partnerId”: //ico partner id,
“tokenWithdrawalWallet”: //eth address for client tokens,
“tokenResultValue”:, //amount of coins which ico should send to tokenWithdrawalWallet (can be null if exchange not finished)
“user”: { //user data
“email”: “[email protected]”},
“additionalFields”: {},//additional fields for transaction
“returnWallet”: //address which client set for refund if transaction fail (can be null if client pay by fiat),
“fromWallet”: //address which exchange provider get coins from client

Widget API:

How to send the data for auto-fill to the user

Our widget can get the user’s data such as email, wallet address and other additional information. In order to do it automatically, check the guide below.

First, create the widget:

var widget = BRWidget.init(...);

After that, you’ll be able to send the data about the user and the transaction at any time:

widget.send(base, additional, extra);

Where

  1. base is the object with the data for the main fields

    {
      // Refund address
      returnWallet?: string; 
      // Refund Destination Tag (xrp, xem, steem, ...)
      extraReturnId?: string;
      // Destination Tag (xrp, xem, steem, ...) 
      // for refund transaction
      extraId?:string;
      // Address for tokens
      tokenWithdrawalWallet?: string;
      // Email
      email?: string;
    }

    The parameters of the object are not obligatory. If some fields are not filled, but are needed to create a transaction, the user will see them on bestrate.org. The same applies to the situation when a field displays an error during creation.

  2. additional is the object with data for additional fields that you create within the widget. In this object, the data with keys is transferred which are the titles of additional fields.

    {
      //  an example for the field Title
      "Title" : string;
    }

    If you have additional fields in your widget here’s the example of your object:

    {
      "Field 1": "any string value",
      "Field 2": "any string value"
    }

    The parameters of the object are not obligatory. If some fields are not filled, but are needed to create a transaction, the user will see them on bestrate.org. The same applies to the situation when a field displays an error during creation.

  3. extra – this is the object with additional fields to write into a transaction, such as marketing tags, a memo key, redirect url and other.

    The format of the object is as follows: key – value, where the key can only be a string, while the value can be a string, a number or a boolean.

    {
      // Payment description or memo key for EOS
      description?: string;
      // Url for return button after transaction end
      redirectUrl?: string;
      [key:string]: mixed;
    }

    Where

    • description – payment description parameter or memo key (EOS) for transaction tracking

    • redirectUrl – link which can be used by the user (for ex., to return back) after finishing the transaction. After redirection from our service the following data is sent using POST method:

      {
        //  Transaction’s information
        //  BestRate’s transaction ID
        id: string;
        //  Transaction’s creation date (UTC date string)
        createdAt: string;
        //  Transaction’s status
        status: ("error"|"success");
        //  Text if transaction is finished with error
        error?: string;
      
        //  Initial currency
        "info.from": string;
        //  Which currency was chosen as the result of the exchange
        "info.to": string;
        //  The volume sent by the user
        "info.fromValue": number;
        //  The volume after the exchange
        "info.toValue": number;
        //  Used exchange service
        "info.service": string;
      
        //  Additional data, that you sent to the widget before the exchange
        "extra.description": string;
        "extra.redirectUrl": string;
        "extra.anyString": string;
      }
Examples:

// Send only extra data
widget.send({},{},{description:'unique id for memo'});
// Send some base data (like user email) and extra data
widget.send({email:'[email protected]'},{},{description:'unique id for memo'});
// Send some base data (like user email) and autofill additional field "Field 1"
widget.send({email:'[email protected]'},{'Field 1':'Some text'});

How to send the new data when a user changes the ticker

Create the widget:

var widget = BRWidget.init(...);

In order to send the new data you need to subscribe for the event ‘change currency’. Check the example below:

//Subscribe on 'change-currency' widget event
widget.on('change-currency', function(newTicker) {
  var base = {...};
  var additional = {...};
  var extra = {...};
  widget.send(base, additional, extra);
});

In the example above, whenever a user changes the currency, the new data will be set. newTicker is the line that designates the ticker ("eth", "btc", "usd" etc.)

How to return back user to your site after finishing the transaction

Create the widget:

var widget = BRWidget.init(...);

After that, send redirectUrl to widget via:

widget.send({},{},{redirectUrl:"your url"});

This link can be used by the user (for ex., to return back) after finishing the transaction. After redirection from our service the following data is sent using POST method:

{
  //  Transaction’s information
  //  BestRate’s transaction ID
  id: string;
  //  Transaction’s creation date (UTC date string)
  createdAt: string;
  //  Transaction’s status
  status: ("error"|"success");
  //  Text if transaction is finished with error
  error?: string;

  //  Initial currency
  "info.from": string;
  //  Which currency was chosen as the result of the exchange
  "info.to": string;
  //  The volume sent by the user
  "info.fromValue": number;
  //  The volume after the exchange
  "info.toValue": number;
  //  Used exchange service
  "info.service": string;

  //  Additional data, that you sent to the widget before the exchange
  "extra.description": string;
  "extra.redirectUrl": string;
  "extra.anyString": string;
}

API documentation

Best wishes, BestRate Team