Api version 2.1.2!
!
PUBLIC VERSION (LAST UPDATED 14/04/2015)!
!
!
Table of contents!
!
!
!
Table of contents!
2!
Changes log!
3!
1. Public trader's API!
4!
1.1. Get exchange depth!
4!
1.2. Get last executed orders!
5!
1.3. Get ticker info!
6!
1.4. Get exchange info!
7!
2. Private trader's API!
8!
2.1. Get current active orders!
8!
2.2. Create new order!
9!
2.3. Remove active order!
10!
2.4. Get trader history!
11!
2.5. Get trader information!
11!
3. Merchant's API!
13!
3.1. Create merchant requests!
14!
3.2. Get merchant requests!
15!
3.3. Remove merchant requests!
16!
4. Sign request!
17!
5. Sample scripts!
18
Changes log!
!
!
date
description
14/04/2015
Order_id has been added as a response parameter to the trader/history method.!
Latest API url prefix is '/api/v2.1/' now.
04/02/2015
Merchant API methods have been added!
-Get merchant requests!
-create merchant request!
-remove merchant request
26/08/2014
Initial version
1. Public trader's API!
!
Public methods will be cached by WebServer for 1 second.!
!
1.1. Get exchange depth!
!
METHOD: !
URL:! !
!
GET !
/api/v2.1/exchange/depth!
Parameters!
Name
Type
Required
Example
platform
Char(6)
v
BTCUSD
limit
Integer
10
!
!
!
Request example:!
!
GET /api/v2.1/exchange/depth?platform=BTCUSD&limit=4!
!
Response example:!
!
{'ask': [[35.0, 50.0], !
[80.0, 50.0], !
[90.0, 50.0], !
[90.0, 60.0]], !
'bid': [[54.0, 45.0], !
[90.0, 40.0], !
[90.0, 30.0], !
[50.0, 30.0]]}!
!
where «ask» and «bid» arrays include sets of [amount,cost] arrays. Records ordered by cost:
«bids» - in descending order, «asks» - in ascending order.!
!
!
1.2. Get last executed orders!
!
METHOD:!
URL:! !
!
GET !
/api/v2.1/exchange/history!
Parameters!
Name
Type
Required
Example
platform
Char(6)
v
BTCUSD
limit
Integer
!
!
Request example:!
!
GET /api/v2.1/exchange/history?platform=BTCUSD&limit=2!
!
Response example:!
!
10
[{'platform': 'BTCUSD', 'amount': 3.0, 'cost': 90.0, 'time': 1408452279, 'tid': 558119, 'type': 'SELL'},
{'platform': 'BTCUSD', 'amount': 3.0, 'cost': 88.0, 'time': 1408452279, 'tid': 558120, 'type': 'SELL'},
{'platform': 'BTCUSD', 'amount': 3.0, 'cost': 20.0, 'time': 1408452300, 'tid': 558121, 'type': 'SELL'}]!
!
Name
Description
platform
Platform unique identifier
amount
Amount in operation main currency (e.x. BTC on BTCUSD platform)
cost
Cost/price per 1 main currency unit (e.x. 90USD per 1BTC)
time
unix timestamp
tid
transaction unique identifier
type
BUY or SELL
!
!
!
!
!
1.3. Get ticker info!
!
METHOD:!
URL:! !
!
GET !
/api/v2.1/exchange/ticker!
Parameters!
Name
Type
Required
example
platform
Char(6)
v
BTCUSD
!
!
Request example:!
!
GET /api/v2.1/exchange/ticker?platform=BTCUSD!
!
!
!
Response example:!
!
{'ticks': {!
!
'15min': {!
!
!
'min_cost': 45.0, !
!
!
'updated': 1409230239, !
!
!
'pair_amount': 67.5, !
!
!
'total_amount': 1.5, !
!
!
'max_cost': 45.0}, !
!
'30min': {!
!
!
'min_cost': 2, !
!
!
'updated': 1409230239, !
!
!
'pair_amount': 677.0,! !
!
!
'total_amount': 16.0, !
!
!
'max_cost': 45.0},!
!
'hour': {!
!
!
'pair_amount': 701.0, !
!
!
'updated': 1409230239, !
!
!
'min_cost': 2, !
!
!
'total_amount': 19.0, !
!
!
'max_cost': 45.0}, !
!
'two_hour': {!
!
!
'pair_amount': 701.0, !
!
!
'updated': 1409230239, !
!
!
'min_cost': 2, !
!
!
'total_amount': 19.0, !
!
!
'max_cost': 45.0},!
!
'six_hour': {!
!
!
'pair_amount': 675.0, !
!
!
'updated': 1409230239, !
!
!
'min_cost': 45.0, !
!
!
'total_amount': 15.0, !
!
!
'max_cost': 45.0}, !
!
'day': {!
!
!
'pair_amount': 701.0, !
!
!
'updated': 1409230239, !
!
!
'min_cost': 2, !
!
!
'total_amount': 19.0, !
!
!
'max_cost': 45.0}!
}, !
'last_operation': {!
!
'tid': 558119, !
!
'amount': 3.0, !
!
'cost': 90.0, !
!
'type': 'SELL', !
!
'time': 1408452279!
!
}!
}!
!
!
!
1.4. Get exchange info!
!
METHOD:!
URL:! !
GET !
/api/v2.1/exchange/info!
!
Request example:!
!
GET /api/v2.1/exchange/info!
!
Response example:!
!
{'active_platforms': [!
!
!
{'platform': 'BTCUSD', 'main_currency': 'BTC', 'pair_currency': 'USD'}, !
!
!
{'platform': 'LTCUSD', 'main_currency': 'LTC', 'pair_currency': 'USD'}, !
!
!
{'platform': 'LTCBTC', 'main_currency': 'LTC', 'pair_currency': 'BTC’}!
!
]!
}!
!
NOTE: response returns a list of all active platforms available through API.!
!
!
!
2. Private trader's API!
!
Private methods belong only to the customer and must have API_KEY and SIGNED_DATA http
headers. Additional security is provided by auto incremental operation counter NONCE which is
mandatory field for every private method call. Signature building rules can be found in chapter
«sign request data»!
!
In case when incorrect nonce is provided, next correct value will be returned as!
!
{!
!
!
}!
'nonce': 12345, !
'error': 'invalid nonce. expected:12345'!
!
2.1. Get current active orders!
!
METHOD:!
URL:! !
!
GET !
/api/v2.1/trader/orders!
Parameters!
Name
Type
limit
Integer
100
to_id
Integer
123456
nonce
Integer
!
!
!
Request example:!
!
GET /api/v2.1/exchange/info?nonce=123!
!
Response example:!
!
[!
!
!
!
!
!
!
!
!
!
!
{!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
}, !
{!
!
'pair_total': -1.0, !
'platform': 'BTCUSD', !
'order_id': 46150389, !
'main_total': 0.0, !
'time_created': 1409053980, !
'commission': 0.0, !
'amount': 1.0, !
'cost': 1.0, !
'status': 'Opened', !
‘status_code’: 0,!
'type': 'BUY'!
'pair_total': 0.0, !
Required
v
Example
123
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
]!
!
}!
'platform': 'LTCUSD', !
'order_id': 46150373, !
'main_total': -6.0, !
'time_created': 1408452795, !
'commission': 0.0, !
'amount': 6.0, !
'cost': 110.0, !
'status': 'Opened', !
‘status_code’: 0,!
'type': 'SELL'!
!
Name
Description
order_id
Unique order identifier. Can be used to remove order
cost
Cost/price per 1 main currency unit
amount
Amount in main currency units (e.x. BTC on BTCUSD platform)
platform
Platform identifier
main_total
Amount in main units on hold in case of SELL order!
and received amount in case of BUY order
pair_total
Amount in pair units on hold in case of BUY order!
and received amount in case of SELL order
type
Order type. «BUY» or «SELL»
commission
Order processing commission in percent. Deducted immediately after order creation
time_created
Unix timestamp of order
status_code
0 - Opened!
1 - Closed!
2 - Partial!
3 - Cancelled
status
Description of status_code
!
!
2.2. Create new order!
!
METHOD:!
URL:! !
!
POST!
/api/v2.1/trader/orders!
Parameters!
Name
Type
Required
Example
cost
Decimal(8,8)
v
1234.5678
amount
Decimal(8,8)
v
1234.5678
platform
Char(6)
v
BTCUSD
Name
Type
Required
Example
type
Char(6)
v
BUY or SELL
nonce
Integer
v
123
!
!
!
Request example:!
!
POST /api/v2.1/trader/orders!
!
cost=1&amount=1&platform=BTCUSD&type=BUY&nonce=123!
!
Response example:!
!
{!
!
!
!
!
!
!
!
!
!
!
}!
'status': 'Opened', !
'pair_total': -1.0, !
'order_type': 'BUY', !
'order_id': 46150414, !
'status_code': 0, !
'amount': 1.0, !
'platform': 'BTCUSD', !
'main_total': 0.0, !
'cost': 1.0, !
'status': 'Opened'!
!
!
2.3. Remove active order!
!
METHOD:!
URL: ! !
!
POST !
/api/v2.1/trader/remove_order!
Parameters
Name
Type
Required
Example
order_id
Integer
v
123456789
nonce
Integer
v
123
!
!
Request example:!
!
POST /api/v2.1/trader/remove_order!
!
order_id=46150414&nonce=123!
!
Response example:!
!
{'status': 'success', 'message': 'order removed’}!
!
!
2.4. Get trader history!
!
METHOD:!
URL: ! !
!
GET !
/api/v2.1/trader/history!
Parameters!
Name
Type
Required
limit
Integer
100
to_id
Integer
12345
nonce
Integer
v
Example
123
!
!
!
Request example:!
!
GET /api/v2.1/trader/history?limit=100&nonce=123!
!
!
!
Response example:!
!
!
[!
!
{'platform': 'BTCUSD', 'amount': 1.0, 'cost': 45.0, 'time': 1408975930, 'tid': 558128, 'type':
'SELL', 'order_id': 123}, !
!
!
{'platform': 'BTCUSD', 'amount': 5.0, 'cost': 50.0, 'time': 1408452795, 'tid': 558127, 'type':
'BUY', 'order_id': 123}, !
!
!
{'platform': 'BTCUSD', 'amount': 5.0, 'cost': 55.0, 'time': 1408452787, 'tid': 558126, 'type':
'BUY', 'order_id': 123}!
]!
!
!
2.5. Get trader information!
!
METHOD:!
URL: ! !
GET !
/api/v2.1/trader/info!
!
Parameters: nonce!
!
Request example:!
!
GET /api/v2.1/trader/info?nonce=123!
!
!
Response example:!
!
{!
!
!
'balance': {!
!
'BTC': 1234.5678,!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
}!
!
'EUR': 0.0,!
!
'GBP': 0.0,!
!
'LTC': 123456.0,!
!
'NVC': 0.0,!
!
'USD': 123456.78,!
!
'YAC': 0.0!
!
},!
'commission': 0.0,!
'holds': {!
!
'BTC': 0.0,!
!
'EUR': 0.0,!
!
'GBP': 0.0,!
!
'LTC': 6.0,!
!
'NVC': 0.0,!
!
'USD': 54321.0,!
!
'YAC': 0.0!
}!
!
Name
Description
balance
Amounts of funds available for trading
commission
Commission for processing trades, in %
holds
Current funds on hold - either for placing orders or pending withdrawals
!
!
3. Merchant's API!
coin.mx provides the way to process payments. There are two different types of interaction:!
!
-users can purchase payments from UNVERIFIED merchants - anonymous transfers;!
-users can purchase payments from VERIFIED merchants - approved coinmx users.!
!
!
Here you can see the details of both !
!
!
VERIFIED merchant
UNVERIFIED merchant
Verified Sign
YES
no
Currencies
Fiat and Crypto
crypto
Logo
YES
no
User's
protection
YES
no
API
YES
no
Custom
callbacks
YES
no
Customer
contacts
YES
no
Url generation rules for unverified merchant's requests you can find on the EasyPayWidget page.!
For verified merchant API usage all the requests have to be signed (see "Sign request" chapter). 3.1. Create merchant requests!
Parameter "duration" shows the number of days during which the request can be argued or
cancelled by any side. Within this period the transaction will be set on hold. This parameter can be
adjusted to improve customer's loyalty or to reduce the merchant's risks. !
!
METHOD:!
URL: ! !
!
POST !
/api/v2.1/merchant/transfer_requests!
Parameters!
Name
Type
Required
Example
amount
Float
v
100
merchant_id
Integer
v
123
description
Char(2048)
v
Leather jacket
duration
Integer
v
1
currency
Char(3)
v
USD
nonce
Integer
v
123
!
Request example:!
GET /api/v2.1/merchant/transfer_requests?
amount=10&currency=USD&description=test&duration=1&merchant_id=1&nonce=123!
!
Response example:!
[!
{!
'description': 'test', !
'created': 1423058115, !
'status_date': 1423058155, !
'currency': 'USD', !
'amount': 10.0, !
'transfer_status': 'Pending', !
'duration': 1, !
'pay_url': 'https://coin.mx/landing/pay?pay_id=df3b-1d5f-cdc0-1a75-00a6-c937-f1f2-6d5f',!
'external_id': 'df3b-1d5f-cdc0-1a75-00a6-c937-f1f2-6d5f'!
}!
]!
!
output parameters!
Name
Description
created
unix timestamp of request creation
description
Request description, e.x. "New leather jacket"
currency
USD, BTC, LTC are available
amount
requested amount (type: float)
pay_url
url merchant should provide his customer with
external_id
unique request identifier
3.2. Get merchant requests!
!
METHOD:!
URL: ! !
!
GET !
/api/v2.1/merchant/transfer_requests!
Parameters!
Name
Type
Required
Example
limit
Integer
merchant_id
Integer
v
12345
nonce
Integer
v
123
external_id
Char(40)
100
qwer-qwer-qwer
!
!
!
Request example:!
!
GET /api/v2.1/merchant/transfer_requests?merchant_id=100&nonce=123!
!
!
!
Response example:!
!
[!
{!
'description': 'test description', !
'created': 1423058115, !
'status_date': 1423058155, !
'currency': 'USD', !
'amount': 10.0, !
'transfer_status': 'Complete', !
'duration': 1, !
'pay_url': 'https://coin.mx/landing/pay?pay_id=df3b-1d5f-cdc0-1a75-00a6-c937-f1f2-6d5f',!
'external_id': 'df3b-1d5f-cdc0-1a75-00a6-c937-f1f2-6d5f'!
}!
]!
!
output parameters!
Name
Description
created
unix timestamp of request creation
description
Request description, e.x. "New leather jacket"
currency
USD, BTC, LTC are available
amount
requested amount (type: float)
pay_url
url merchant should provide his customer with
external_id
unique request identifier
!
3.3. Remove merchant requests!
!
METHOD:!
URL: ! !
!
POST !
/api/v2.1/merchant/transfer_requests!
Parameters!
Name
Type
Required
Example
external_id
Char(40)
v
qwer-qwer-qwer
nonce
Integer
v
123
!
!
!
Request example:!
!
GET /api/v2.1/merchant/transfer_requests?external_id=
!
!
!
Response example:!
!
qwer-qwer-qwer&nonce=123!
{!
'status': 'success', !
'message': 'request removed'!
} 4. Sign request!
To create request signature you need to sort you parameters, join them with ‘=‘ and ‘&’ signs as
follow:!
for example you want to send next 4 parameters!
!
!
!
a: ‘value1’!
!
b: ‘value2’!
!
x: ‘value3’!
!
nonce:123!
!
!
you need to build next string S:!
!
«a=value1&b=value2&nonce=123&x=value3»!
!
SIGNED_DATA = base64.b64encode(str(HMAC(YOUR_SECRET, PATH+'?'+S, sha512).digest())),!
where PATH is a http path (e.x. "/api/v2.1/trader/info").!
!
!
!
!
5. Sample scripts!
!
Python and PHP sample ApiClient scripts are hosted on GitHub!
!
https://github.com/cmxteam/simple_client!
!