Affiliates

Server Time - 18.10 29 Mar

BTC Price - $1058.1

LTC Price - $2.93999

Introduction

cryptonit offers special access to its services for affiliates. This enables affiliates to use the services of cryptonit in a wider range by controlling user accounts.

Considerations

Depending on the application your a developing, different access and integration is required. Most easy it is explained by whom is accessing user account data, or who is the owner? If you develop an application only for yourself, you most likely will also be the owner of the account you are accessing. We can call this developer access.

A secound style of integration we can call affiliate. In this case you develop an application which is not only used by you, but also by a wider audience. In this case you, the developer, will not be the direct owner of the data your applicaiton is accessing. This second case is which we want to cover here.

Requirements

The API for affiliates is only available for approved users to ensure the quality of these services. To become an approved user we refer to the FAQ. After your account was approved simply send a short notice to support@cryptonit.net and we will enable your account for affiliate purposes.

This access is intended for the requested user and services only. If we discover that this access is shared with others not belonging to the original person, access will be immediately blocked.

URL paths

Access for affiliates is given under different URL paths. This is to ensure that the correct authentication is used. For user account related API calls the base path is:

https://cryptonit.net/apiv2/rest/users/

and for exchange related API calls, like placing or canceling orders:

https://cryptonit.net/apiv2/rest/exchange/

Authentication

The API for affiliates is only available via OAuth. The reason for this is that OAuth is a standarzied way to give outside services (your application) access to user information without revealing the password. OAuth is in wide use and major internet companies like Google, Yahoo etc. are using it. There are two versions of OAuth: the older version 1 and the newer version 2. We at cryptonit support both version. However, due to its simplicity, we recommend the user of OAuth2. Both version are covered in this document. OAuth refers to version 1 while OAuth2 documention is about version 2.

OAuth

The security of OAuth lies in the use of signing all content transfered between the client and the server. This signing is very technical and we recommend to use of a library which are normally available for all programming languages.

Paths

The OAuth paths of cryptonit are available under:

$req_url = 'https://cryptonit.net/oauth/request_token';
$auth_url = 'https://cryptonit.net/oauth/authorize';
$acc_url = 'https://cryptonit.net/oauth/access_token';

In this explaination we will use the PHP PECL oauth library. For other programming languages, the instructions given here should not require too much adaption.

Consumer

First you have to register a so-called consumer. The consumer will give you access to user accounts to view transactions, withdraw coins, place orders, etc.

To request a new consumer please visit the following URL. Please create the consumer with a callback to your service. Write down the consumer token and secret.

Authorization

Authorization gives general access to your application. To request an oauth token and server, please follow the following instructions:

$consumer_key = '<your consumer key>';
$consumer_secret = '<your comsumer secret>';
// create an OAuth object with the consumer token and secret
$oauth = new OAuth($consumer_key, $consumer_secret, OAUTH_SIG_METHOD_HMACSHA1, OAUTH_AUTH_TYPE_URI);
// request a new token
$request_token_info = $oauth->getRequestToken($req_url);
// your oauth token and secret
$oauth_secret = $request_token_info['oauth_token_secret'];
$oauth_token = request_token_info['oauth_token'];

Now please visit: $auth_url . "?oauth_token=" . $oauth_token, confirm the OAuth token and give the appropriate rights. This will authorize your service.

Access

The final step is to request an access token:

// create an OAuth object with the consumer token and secret
$oauth = new OAuth($consumer_key, $consumer_secret, OAUTH_SIG_METHOD_HMACSHA1, OAUTH_AUTH_TYPE_URI);
// and get an access token
$access_token_info = $oauth->getAccessToken($acc_url);
$oauth_access_token = $access_token_info['oauth_token']; $oauth_access_secret = $access_token_info['oauth_token_secret'];
// the access token is then used for all API requests

OAuth2

OAuth2 is the more recent approach for authorized client to server communication. Instead of signing content, communication must be done over HTTPS. This requires that the client verifies the identity of the server by analyzing the fingerprints of the certificate. This is beyond the scope of this document and much depends on the involved HTTP library using for communication with the server.

Paths

The OAuth2 paths of cryptonit are available under:

$auth_url = 'https://cryptonit.net/oauth2/authorize';
$token_reg_url = 'https://cryptonit.net/oauth/token';
$token_status_url = 'https://cryptonit.net/oauth2/tokens/<token>';

Scopes

OAuth2 is working with scopes to fine gratualy access features. A user can therefore give an application only restricted access to his data. At cryptonit we are using three different scopes:

  1. basic: refers to the most basic scope and only allows reading user account information about: funds, cryptocurrencies, orders
  2. withdraw: with this permission the client will be able to perform withdraw requests of any cryptocurrency
  3. trade: this permission allows the client to place or cancel user's orders

When authorizing the client, please always pass scopes. Without a valid scope in your request, it will be simply denied.

Authorization code

Requesting an authorization code basically means you build a URL passing all the needed parameters. This URL consists of:

  1. cryptonit OAuth2 URL
  2. response_type: set fixed to code
  3. client_id: id representing your application (will be created by us for you)
  4. scopes: at least one or up to three scopes (see above). Multiple scopes separated by URL encoded space character (%20)
  5. state: some unique identifier provided by you. Needed to check request was processed correctly.
  6. redirect_uri: URL of your application (localhost) or your website (site URL)

We give an example in JAVA:

StringBuilder sb = new StringBuilder(); // better for processing strings
sb.append("https://cryptonit.net/oauth2/authorize"); // cryptonit URL
sb.append("?response_type=code"); // as explained above
sb.append("&client_id="+CLIENT_ID); // you unique client id
sb.append("&scope=basic%20withdraw"); // the scopes
sb.append("&state="+state); // with state any proper url encoded string
sb.append("&redirect_uri="+REDIRECT_URI); // the url of your site/service

same exmaple in PHP: $URL = "https://cryptonit.net/oauth2/authorize"; // cryptonit URL
$URL .= "?response_type=code"; // as explained above
$URL .= "&client_id="+$CLIENT_ID"; // you unique client id
$URL .= "&scope=basic%20withdraw"; // the scopes
$URL .= "&state="+$state"; // with state any proper url encoded string
$URL .= "&redirect_uri="+$REDIRECT_URI"; // the url of your site/service

Opening this URL in the browser of the user, will redirect him to cryptonit and ask him to confirm the request. If he confirms this request, he user will be redirected back to your application with additional paramerters:

  1. code: an authorization code
  2. state: the state identifier you provided with your request.

At this point you should verify the state to ensure it is the one you are thinking to receive. This is most important to assign this code to the correct user in your website. Having this code you are now able to receive the access token by performing a POST request to the token request url.

BasicNameValuePair[] params = {
new BasicNameValuePair("grant_type", "authorization_code"),
new BasicNameValuePair("code", authorizationCode),
new BasicNameValuePair("redirect_uri", REDIRECT_URI),
new BasicNameValuePair("client_id", CLIENT_ID),
new BasicNameValuePair("client_secret", CLIENT_SECRET),
};
HttpPost httppost = new HttpPost(TOKEN_PATH);
try {
httppost.addHeader(HttpHeaders.HOST, "cryptonit.net"); // for OAuth2.0
httppost.setHeader(HttpHeaders.CONTENT_TYPE, "application/x-www-form-urlencoded");
httppost.setHeader(HttpHeaders.USER_AGENT, "CryptonitPocket"); // for OAuth2.0
UrlEncodedFormEntity urlEncodedFormEntity = new UrlEncodedFormEntity(Arrays.asList(params));
httppost.setEntity(urlEncodedFormEntity);
HttpClient httpClient;
HttpResponse resp = httpClient.execute(httppost);
if(resp.getStatusLine().getStatusCode() == HttpStatus.SC_OK) {
String response = (resp.getEntity() != null) ? EntityUtils.toString(resp.getEntity()) : "";
}
}

$data = array(
'grant_type' => 'authorization_code',
'code' => $authorizationCode,
'redirect_uri' => $REDIRECT_URI,
'client_id' => $CLIENT_ID,
'client_secret' => CLIENT_SECRET
);
// prepare cURL for POSTING
$curl = curl_init($token_req_url);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Accept: application/json', 'Content-Type: application/x-www-form-urlencoded'));
curl_setopt($curl, CURLOPT_POSTFIELDS, $data); // Set POST data
curl_setopt($curl, CURLOPT_HEADER, FALSE); // Ask to not return Header
// get the response
$response = curl_exec($curl);

The result of this request be an array consisting of:

  • access_token: will be your authorization token to do requests via the API
  • expires_in: the time this access token is valid
  • token_type: the type of the token
  • scope: the scopes of the token
  • refresh_token: token to receive a new access token in case it has been expired

The access token is set in the header as:

"Authorization: Bearer <access_token>"

Bonus

In the following section we will explain how to receive the "Terms of Service" and register a new user. Access to this functions to now require OAuth, since this is only a communication of you, the developer with is from cryptonit. We will pass you a special API token for these requests. The url to reach these function is: $api_url = 'https://cryptonit.net/apiv2/rest/affiliates';

Terms of Service

As you will create user accounts on our site from your services you will be responsible to display the "Terms of Service" to your users. You can receive the terms by:

<
p> // create an OAuth object with the consumer token and secret
$oauth = new OAuth($consumer_key, $consumer_secret, OAUTH_SIG_METHOD_HMACSHA1, OAUTH_AUTH_TYPE_URI);
// set the access token
$oauth->setToken($oauth_access_token,$oauth_access_secret);
// get the Terms of Services and display them to the user
$oauth->fetch("$api_url/terms");
$terms = json_decode($oauth->getLastResponse());

$terms is an array containing the "Terms of Service" at the key "text", the revision information at "revision" and the timestamp of last change at "timestamp".

Register user

To reqister a new user you have to POST the user data to the API url:

// create an OAuth object with the consumer token and secret
$oauth = new OAuth($consumer_key, $consumer_secret, OAUTH_SIG_METHOD_HMACSHA1, OAUTH_AUTH_TYPE_URI);
// set the access token and secret
$oauth->setToken($oauth_access_token,$oauth_access_secret);
// prepare the array with data
$data = array(
  "name" => "<username>",
  "pass" => "<password>",
  "mail" => "<email address>",
  "terms_of_use" => "1", // "1" means accept terms of cryptonit
);
// wrap the data into an "account"
$user_data = array("account" => $data);
// encode the data as JSON
$data = json_encode($user_data);

// post the new user data.
$oauth->fetch("$api_url/user", $user_data, OAUTH_HTTP_METHOD_POST, array("Content-Type" => "application/json"));
$json = json_decode($oauth->getLastResponse());

The result will tell you if the user was created or not. To avoid collisions it might be best to prepend all your usernames with an prefix indicating your service. This way you will not run into troubles if usernames already exist.