Crypto Capital API v4.1.0-beta.8

Warning!Be advised, this is a pre-release version of the API intended to allow developers the chance to start writing code which will work with v4 once it is officially released. This is a beta release. There will be no new functionality added before final release, only bug fixes. There is no guarantee that a bug fix will not break your code, but we will make every attempt possible to avoid that happening. If you find a bug, or would like to see some specific feature included in the final release, please send an email to support@cryptocapital.co.

Overview

The Crypto Capital API v4 allows users to query the status of their accounts, including balances and transaction history, to initiate transfers, and to receive real-time notifications of transfers both inbound and outbound made to the user's accounts.

Connection

The API allows for 3 types of connections:

  • A RESTful API - Grants the user the ability to query account balances and transaction history, as well as to initiate transfers to other accounts.
  • A Websockets API - Grants the user all of the same abilities as the RESTful API and adds real-time notification of new inbound and outbound transfers.

Account Registration

Unlike previous versions of the API, account registration has been moved to the Crypto Capital banking platform UI. There is a simple, three step process for registration.

  1. Log in to your account.
  2. Click on "User Management":

    alt text

  3. Click on "Regenerate Key":

    alt text

Save your Key and Secret for use by the API.

RESTful API

The RESTful API allow users to query the status of their accounts and initiate transfers. All methods are require authentication using the API keys and the following request headers:

  • key: The API Key.
  • message: A specifically formatted message that will be signed using the Secret. The exact format of the message will be described below through the
  • signature: The SHA1 hash of message + key + secret
  • nonce: A unique number which should increase with every API request made by the client. This is used to prevent re-play attacks.

GET /v4/ping

This method takes no action against the account, however it is useful to developers as a way of confirming that code signing is working properly and that all Crypto Capital systems are operational.

Message Format

PING + nonce

Response

A successful response will contain the JSON encoded string:

"PONG"

A failed response will contain a JSON encoded statusCode and errorMessage:

statusCode Meaning
0 Success
1 Missing Parameter
2 Invalid parameter
3 User has no access to this service
5 Non-existent customer uid
6 Invalid signature
100 Invalid message
101 Invalid nonce
102 Unknown error

Sample Code

var key = '1234567890abcdef';
var secret = '1234567890abcdef';
var command = 'PING';
var nonce = Date.now();
var message = command + nonce;
var signature = CryptoJS.SHA1(message + key + secret);

var options = {
  url: 'https://api.cryptocapital.co/v4/ping',
  headers: {
    'key': key,
    'message': message,
    'signature': signature,
    'nonce': nonce
  }
};

request(options, function(err, res, body) {
  // do something
  // ...
});

GET /v4/accounts

This method is used to fetch a list of all accounts belonging to the API user.

Message Format

ACCOUNTS + nonce

Response

A successful response will contain an array of JSON encoded accounts with details:

key Meaning
accountNumber Account Number
name Name of the account
date Date the account was opened
currency Currency the account balance is denominated in
balance Account balance
available Available funds

A failed response will contain a JSON encoded statusCode and errorMessage:

statusCode Meaning
0 Success
1 Missing Parameter
2 Invalid parameter
3 User has no access to this service
4 No records
100 Invalid message
101 Invalid nonce
102 Unknown error
999 Unknown error

Sample Code

var key = '1234567890abcdef';
var secret = '1234567890abcdef';
var command = 'ACCOUNTS';
var nonce = Date.now();
var message = command + nonce;
var signature = CryptoJS.SHA1(message + key + secret);

var options = {
  url: 'https://api.cryptocapital.co/v4/accounts',
  headers: {
    'key': key,
    'message': message,
    'signature': signature,
    'nonce': nonce
  }
};

request(options, function(err, res, body) {
  // do something
  // ...
});

GET /v4/account/:accountNumber

This method is used to fetch the balance and other metadata from a specific account.

Message Format

ACCOUNT + nonce + accountNumber

Response

A successful response will contain the JSON encoded account details:

key Meaning
accountNumber Account Number
name Name of the account
date Date the account was opened
currency Currency the account balance is denominated in
balance Account balance
available Available funds

A failed response will contain a JSON encoded statusCode and errorMessage:

statusCode Meaning
0 Success
1 Missing Parameter
2 Invalid parameter
3 User has no access to this service
4 No records
100 Invalid message
101 Invalid nonce
102 Unknown error
999 Unknown error

Sample Code

var key = '1234567890abcdef';
var secret = '1234567890abcdef';
var command = 'ACCOUNT';
var nonce = Date.now();
var accountNumber = '900000000';
var message = command + nonce + accountNumber;
var signature = CryptoJS.SHA1(message + key + secret);

var options = {
  url: 'https://api.cryptocapital.co/v4/account/' + accountNumber,
  headers: {
    'key': key,
    'message': message,
    'signature': signature,
    'nonce': nonce
  }
};

request(options, function(err, res, body) {
  // do something
  // ...
});

GET /v4/statement/:accountNumber

This method is used to fetch the transaction history from a specific account.

Query Parameters

This method requires one of the following query parameters:

query Meaning
limit Specifies the maximum number of records to return.
fromtime Unix timestamp for a datetime from which to retrieve records.
transactionid Unique identifier of a single traction

Message Format

STATEMENT + nonce + accountNumber

Response

A successful response will contain a JSON encoded array of transactions matching the query filters including the following details:

key Meaning
type Transaction type: transfer, deposit, withdraw
id System-wide unique transaction number
date Date of the transaction
sendAccount Account the transfer was debited from (assuming type is transfer or withdraw)
receiveAccount Account the transfer was credited to (assuming type is transfer or deposit)
sendCurrency Currency of the sendAccount (if applicable)
receiveCurrency Currency of the receiveAccount (if applicable)
sendAmount Amount of funds debited from the sendAccount (if applicable)
receiveAmount Amount of funds credited to the receiveAccount (if applicable)
narrative Transaction narrative

A failed response will contain a JSON encoded statusCode and errorMessage:

statusCode Meaning
0 Success
1 Missing Parameter
2 Invalid parameter
3 User has no access to this service
4 No records
10 Unknown account number
100 Invalid message
101 Invalid nonce
102 Unknown error
999 Unknown error

Sample Code

var key = '1234567890abcdef';
var secret = '1234567890abcdef';
var command = 'STATEMENT';
var nonce = Date.now();
var accountNumber = '900000000';
var limit = '50';
var message = command + nonce + accountNumber;
var signature = CryptoJS.SHA1(message + key + secret);

var options = {
  url: 'https://api.cryptocapital.co/v4/statement/' + accountNumber + '?limit=' + limit,
  headers: {
    'key': key,
    'message': message,
    'signature': signature,
    'nonce': nonce
  }
};

request(options, function(err, res, body) {
  // do something
  // ...
});

POST /v4/transfer

This method is used to initiate an internal transfer.

Request Parameters

The request body should contain a JSON object with the following parameters:

parameter datatype description
fromAccount string Account the transfer should be debited from (must be owned by the API user)
toAccount string Account the transfer should be credited to (can belong to any user)
currency string Currency to base the transfer amount on. Must match either the fromAccount or toAccount.
amount string Amount to send denominated in the specified currency
narrative string Transfer narrative

Cross-Currency Transfers

In the event that a transfer is requested between two accounts of different currencies, a forex conversion will be performed at current market prices, and a fee will be applied. If the currency matches that of the fromAccount, the fromAccount will be debited the amount specified, and the toAccount will be credited an amount determined by the forex conversion, less the conversion fee. If the currency matches that of the toAccount, the fromAccount will be debited an amount determined by the forex conversion, plus the conversion fee, and the toAccount will be credited with the amount specified.

Message Format

TRANSFER + nonce + fromAccount + toAccount + currency + amount

Response

A successful response will contain the following JSON object, to indicate that the transfer was successfully queued. This response does not mean the transfer has been completed. The user should wait for a transfer notification or run a STATEMENT query to ensure that the transfer posted successfully.

{"statusCode":0,"data":"Transfer Queued Successfully"}

A failed response will contain a JSON encoded statusCode and errorMessage:

statusCode Meaning
0 Success
1 Missing Parameter
2 Invalid parameter
3 User has no access to this service
10 Unknown account number
11 Unknown beneficiary
12 Currency mismatch
14 Insufficient funds
100 Invalid message
101 Invalid nonce
103 Invalid parameter
102 Unknown error
999 Unknown error

Sample Code

var key = '1234567890abcdef';
var secret = '1234567890abcdef';
var command = 'TRANSFER';
var nonce = Date.now();
var params = { "fromAccount" : "9000000000",
               "toAccount" : "9000000001",
               "currency" : "USD",
               "amount" : "100.00",
               "narrative" : "Sample transfer"
};

var message = command + nonce + params.fromAccount + params.toAccount + params.currency + params.amount;
var signature = CryptoJS.SHA1(message + key + secret);

var options = {
  url: 'https://api.cryptocapital.co/v4/transfer',
  method: 'POST',
  headers: {
    'key': key,
    'message': message,
    'signature': signature,
    'nonce': nonce
  },
  json: params
};

request(options, function(err, res, body) {
  // do something
  // ...
});

POST /v4/withdraw

This method is used to initiate an external transfer to another financial institution.

Request Parameters

The request body should contain a JSON object with the following parameters:

parameter datatype description
fromAccount string Account the transfer should be debited from (must be owned by the API user)
beneficiary object Object containing the following additional details about the beneficiary
beneficiary.name string Name of the beneficiary account holder
beneficiary.account string Account number of the beneficiary account
beneficiary.bic string BIC string describing the beneficiary account
beneficiary.bank string Bank Name where the beneficiary account is held
beneficiary.country string 2-character iso3166 country code of the bank
currency string Currency to base the transfer amount on.
amount string Amount to send denominated in the specified currency
narrative string Transfer narrative

Cross-Currency Transfers

In the event that a transfer is requested between two accounts of different currencies, a forex conversion will be performed at current market prices, and a fee will be applied.

Message Format

WITHDRAW + nonce + fromAccount + beneficiary.account + currency + amount

Response

A successful response will contain the following JSON object, to indicate that the withdraw was successfully queued. This response does not mean the withdraw has been completed. The user should wait for a transfer notification or run a STATEMENT query to ensure that the transfer posted successfully.

{"statusCode":0,"data":"Transfer Queued Successfully"}

A failed response will contain a JSON encoded statusCode and errorMessage:

statusCode Meaning
0 Success
1 Missing Parameter
2 Invalid parameter
3 User has no access to this service
10 Unknown account number
11 Unknown beneficiary
12 Currency mismatch
14 Insufficient funds
100 Invalid message
101 Invalid nonce
103 Invalid parameter
102 Unknown error
999 Unknown error

Sample Code

var key = '1234567890abcdef';
var secret = '1234567890abcdef';
var command = 'WITHDRAW';
var nonce = Date.now();
var params = { "fromAccount" : "9000000000",
               "beneficiary" : {
                   "name" : "Alice Account Holder",
                   "account" : "1234567890",
                   "bic" : "ABCDUSNYXXX",
                   "bank" : "Bank of America",
                   "country" : "US"
               },
               "currency" : "USD",
               "amount" : "100.00",
               "narrative" : "Sample transfer"
};

var message = command + nonce + params.fromAccount + params.beneficiary.account + params.currency + params.amount;
var signature = CryptoJS.SHA1(message + key + secret);

var options = {
  url: 'https://api.cryptocapital.co/v4/withdraw',
  method: 'POST',
  headers: {
    'key': key,
    'message': message,
    'signature': signature,
    'nonce': nonce
  },
  json: params
};

request(options, function(err, res, body) {
  // do something
  // ...
});

POST /v4/user

This request is used to create a new user for a customer.

Message Format

USER + nonce

Request Parameters

The request body should contain a JSON object with the following parameters: {"email":"morganfreeman@gmail.com", "firstname": "Morgan", "lastname": "Freeman"} | parameter | datatype | description | | ----- | ------- | | email | string | 'new user's email address' | | firstname | string | 'primary name' | | lastname | string | 'family name' |

Response

A successful response will contain the JSON encoded new user details

A failed response will contain a JSON encoded statusCode and errorMessage:

statusCode Meaning
0 Success
1 Missing Parameter
2 Invalid parameter
3 User has no access to this service
5 Non-existent customer id
13 Duplicate email
100 Invalid message
101 Invalid nonce
102 Unknown error
999 Unknown error

Sample Code


let nonce = Date.now();
var key = '1234567890abcdef';
var secret = '1234567890abcdef';
message = "USER" + nonce;

let sig = CryptoJS.SHA1(message + key + secret).toString();

let options = {
    url: 'https://api.cryptocapital.co/v4/user',
    method: 'POST',
    json: {"email":"morganfreeman@gmail.com", "firstname": "Morgan", "lastname": "Freeman"},
    headers: {
        'key': key,
        'message': message,
        'signature': sig,
        'nonce': nonce,
    },
};

request(options, function(err, res, body) {
  // do something
  // ...
});

POST /v4/application

This request is used to create a new user for a customer.

Message Format

APPLICATION + nonce

Request Parameters

The request body should contain a JSON object with the following parameters:

parameter datatype description
title string 'new user's email address'
firstname string 'primary name'
lastname string 'family name'
dob string 'Date of birth in YYYYMMDD format'
birthPlace string 'City or locality of birth'
nationality string 'Country of nationality'
idNumber string 'Number of passport or photo id'
idIssueCity string 'Place of issue of the identity document'
idExpiryDate string 'Date of expiration of identity document in YYYYMMDD format'
phone string 'Phone number of the customer'
fax string 'Fax number of the customer'
mobilePhone string 'Mobile phone number of the customer'
emailAddress string 'Email address of the customer where application form will be sent'
address string 'Street address of the customer'
address2 string 'Additional details of the customer's address'
city string 'City of the customer's address'
zipCode string 'Postal code of the customer's address'
country string 'Country of residence of the customer'
destinationCountries string 'Countries to which the customer will perform outgoing transfers'
originCountries string 'Countries from which the customer will receive incoming transfers'
outgoingVolume string 'Expected number of outgoing transfers per month'
incomingVolume string 'Expected number of incoming transfers per month'
averageValue string 'Average value of each transfer'
maxValue string 'Maximum value of each transfer'
initialDeposit string 'The initial deposit of funds to your primary account'
initialDepositCurrency string 'The currency of the initial deposit to your primary account'
originBankName string 'The bank name from where you will transfer the initial deposit'
originBankAddress string 'The bank address from where you will transfer the initial deposit'
originAccountName string 'The holder's account name with the bank'
originAccountNo string 'The holder's account number with the bank'
originSignatory string 'The name of the signatory with the bank'
originDescription string 'The description of how these funds were generated'
accountCurrency string 'The currency in which to open the account.'
introducerName string 'The person or company who has recommended you to open an account with us'
introducerEmailAddress string 'The email address of the person/company who introduced us to you'
customertype string 'Customer type (personal or corporate)'

Restrictions

Only personal accounts are supported. customertype=personal

Response

A successful response will contain the JSON encoded the customer application reference

A failed response will contain a JSON encoded statusCode and errorMessage:

statusCode Meaning
0 Success
1 Missing Parameter
2 Invalid parameter
3 User has no access to this service
23 Duplicate Email Address
100 Invalid message
101 Invalid nonce
102 Unknown error
999 Unknown error

Sample Code


let data = {
    "title": "Mr",
    "firstname": "John",
    "lastname": "Doe",
    "dob": "19860609",
    "birthPlace": "Anyplace",
    "nationality": "US",
    "idNumber": "123456789",
    "idIssueCity": "Anyplace",
    "idExpiryDate": "20210620",
    "phone": "+15555555555",
    "fax": "",
    "mobilePhone": "",
    "emailAddress": "john@doe.com",
    "address": "123 Main St.",
    "address2": "",
    "city": "Anytown",
    "zipCode": "12345",
    "country": "US",
    "destinationCountries": "US, UK, Mexico, Canada",
    "originCountries": "US, UK",
    "outgoingVolume": "10000",
    "incomingVolume": "10000",
    "averageValue": "10000",
    "maxValue": "100000",
    "initialDeposit": "10000",
    "initialDepositCurrency": "USD",
    "originBankName": "BANK OF AMERICA",
    "originBankAddress": "123 Bank Street",
    "originAccountName": "John Doe",
    "originAccountNo": "1234567879",
    "originSignatory": "XYZ lTD. CA",
    "originDescription": "Savings",
    "accountCurrency": "USD",
    "introducerName": "Jane Doe",
    "introducerEmailAddress": "jane@doe.com",
    "customertype": "personal"
};

let nonce = Date.now();
let key = '1234567890abcdef';
let secret = '1234567890abcdef';
let message = "APPLICATION" + nonce;

let sig = CryptoJS.SHA1(message + key + secret).toString();

let options = {
    url: 'https://api.cryptocapital.co/v4/application',
    method: 'POST',
    json: data,
    headers: {
        'key': key,
        'message': message,
        'signature': sig,
        'nonce': nonce,
    },
};

request(options, function(err, res, body) {
  // do something
  // ...
});

Websockets API

In addition to the ability to query account details and initiate transfers, the Websockets API allows users to receive real-time notifications of new inbound and outbound transfers.

The user implementing a Websockets connection should establish a connection to wss://api.cryptocapital.co/v4/ws. All operations should be emitted as JSON objects, with the following parameters:

parameter type description
op string Operation (eg. 'auth')
key string API Key
message string A specifically formatted message that will be signed using the Secret. The exact format of the message will be described below
signature string The SHA1 hash of message + key + secret
nonce string A unique number which should increase with every API request made by the client. This is used to prevent re-play attacks.
params object In the event that a particular operation requires additional parameters, they will be encapsulated as a nested object.

Transfer Notifications

When a new transfer occurs that affects one of the user's accounts, the server will send a transfer notification.

The notification is a JSON object with the following parameters:

parameter type description
transfer object Contains a single transfer object as defined in the STATEMENT response

op: 'ping'

Once connected to the socket server, a recurring ping operation will help to keep the connection alive.

This operation does not require any additional parameters, nor does it require a nonce, or any authentication information.

Sample Code

var ping = setInterval(function() {
    connection.send(JSON.stringify({
        op: 'ping'
    }))
}, 5000);

op: 'auth'

Once connected to the socket server, a registered user should authenticate in order to begin receiving transfer notifications.

Message Format

The signature of the auth command should be based on the following concatenated strings:

'AUTH' + nonce

Response

If authentication is successful, the server will emit an auth message response containing the JSON object:

{"statusCode":0,"message":"Success"}

A failed response will contain a JSON encoded statusCode and errorMessage:

statusCode Meaning
0 Success
1 Missing Parameter
2 Invalid parameter
3 User has no access to this service
5 Non-existent customer uid
6 Invalid signature
100 Invalid message
101 Invalid nonce
102 Unknown error

Sample Code

var connection = new WebSocket("wss://api.cryptocapital.co/v4/ws");

connection.onopen = function() {

    var key = '1234567890abcdef';
    var secret = '1234567890abcdef';
    var nonce = Date.now();
    var message = 'AUTH' + nonce;
    var signature = CryptoJS.SHA1(message + key + secret).toString();
    var authdata = { op: 'auth',
                     key: key,
                     message: message,
                     signature: signature,
                     nonce: nonce
    };

    connection.send(JSON.stringify(authdata));

    connection.onmessage = function(event) {
        console.log(event.data);
    }

}