Coinmotion API
This is the Coinmotion API documentation. Data is passed as json objects.
Headers
The following HTTP headers must be present:
-
Content-Type
- application/json -
X-COINMOTION-APIKEY
- Your API key -
X-COINMOTION-SIGNATURE
- Request signature computed as detailed in the Authentication section
Common parameters
nonce
(string) - Nonce must be strictly increasing (e.g. Epoch timestamp)
Authentication
Authentication is done using an API key and a secret. All requests must be signed with a signature, which is computed as follows:
- the payload is the nonce and the parameters object JSON encoded
payload = nonce, parameters object -> JSON encode
- the signature is an HMAC-SHA512 hash of the payload and your API secret
signature = HMAC-SHA512 ($payload, $api_secret)
The signature is encoded as the HTTP header named X-COINMOTION-SIGNATURE.
Default response 200
from server
The default response from the server for a successful request is {"success": true}
.
For a failed request the response is {"success": false}
, which is always accompanied by a message
parameter in the response. Message is subject to change.
Public ¶
Rates V2 ¶
Returns the current bid and ask rates used for orders. Includes all available currencies.
NB. Notice, that this method is part of the upcoming V2 API. This method is provided as an alternative to maintain the backwards compatibility of the V1 rates method.
Explanation of response parameters:
-
currencyCode
: Currency code for the given currency -
buy
: Exchange rate used for buy orders -
sell
: Exchange rate used for sell orders
Response may include some other parameters as well, but these are subject to change and should not be relied upon. They are only intended for the use of the Coinmotion frontend.
Rates V2GET/v2/rates
Example URI
Headers
Content-Type: application/json
200
Headers
Content-Type: application/json
Body
{
"success": true,
"payload": {
"btc": {
"currencyCode": "BTC",
"buy": "3494.61",
"sell": "3534.52"
},
"ltc": {
"currencyCode": "LTC",
"buy": "27.45",
"sell": "27.73"
},
"eth": {
"currencyCode": "ETH",
"buy": "98.58",
"sell": "99.45"
}
}
}
Rates V1 ¶
DEPRECATED: Please use the v2
version instead to get rates for all available currencies. Due to backwards compatibility this v1
method will not be updated to return other currencies.
Returns the current bid and ask rates used for orders.
Explanation of response parameters:
-
bid
: Exchange rate used for sell orders -
ask
: Exchange rate used for buy orders
Rates V1GET/v1/rates
Example URI
Headers
Content-Type: application/json
200
Headers
Content-Type: application/json
Body
{
"success": true,
"payload": {
"bid": "506.68000000",
"ask": "511.74000000"
}
}
Private ¶
Balances ¶
Returns the balances of user’s account.
Explanation of response parameters:
-
eur_avl
: EUR available -
eur_bal
: EUR balance -
eur_res
: EUR reserved -
xxx_avl
: Amount of XXX cryptocurrency available. This is repeated for all cryptocurrencies in the service. -
xxx_bal
: Balance of XXX cryptocurrency. This is repeated for all cryptocurrencies in the service. -
xxx_res
: Amount of XXX cryptocurrency reserved. This is repeated for all cryptocurrencies in the service.
Check balancePOST/v1/balances
Example URI
Headers
Content-Type: application/json
X-COINMOTION-APIKEY: "abcdef",
X-COINMOTION-SIGNATURE: "bH/xZab/841ct2BPvLhCLrIOm5ILA0eLQ4PSH/gOHsLD2qUuqXFEP1TkWd/MOrWpdlxuPkiSlOrTlOigb7ah3Q=="
Body
{
"nonce": "1463731543"
}
200
Headers
Content-Type: application/json
Body
{
"success": true,
"payload": {
"eur_avl": "195.83",
"eur_bal": "195.83000000",
"eur_res": "0.00000000",
"btc_avl": "0.13598432",
"btc_bal": "0.13598432",
"btc_res": "0.00000000",
"ltc_avl": "0.33551643",
"ltc_bal": "0.33551643",
"ltc_res": "0.00000000",
"eth_avl": "0.469421160341067618",
"eth_bal": "0.469421160341067618",
"eth_res": "0.00000000"
}
}
Buy ¶
Use to initiate a buy order. Amount can be set either in a cryptocurrency or the user’s currency - one must be present but specifying both will return an error.
BuyPOST/v1/buy
-
amount_btc
(string,optional) - Amount in satoshis (for BTC) or in the smallest unit of the given cryptocurrency. Do not use decimal values. NB. The parameter name remainsamount_btc
for sake of backwards compatibility, but it’s used for all available cryptocurrencies.- for other ERC-20 currencies, please set the correct amount as:
ETH
: amount_btc * 10^16LTC
: amount_btc * 10^6XRP
: amount_btc * 10^6XLM
: amount_btc * 10^7UNI
: amount_btc * 10^15AAVE
: amount_btc * 10^15LINK
: amount_btc * 10^15USDC
: amount_btc * 10^4
- for other ERC-20 currencies, please set the correct amount as:
-
amount_cur
(string,optional) - Amount in user’s currency in cents -
currency_code
(string,optional) - Cryptocurrency to buy. See/v2/rates
for options available. If not given, will default tobtc
for backwards compatibility.
Example URI
Headers
Content-Type: application/json
X-COINMOTION-APIKEY: "abcdef",
X-COINMOTION-SIGNATURE: "bH/xZab/841ct2BPvLhCLrIOm5ILA0eLQ4PSH/gOHsLD2qUuqXFEP1TkWd/MOrWpdlxuPkiSlOrTlOigb7ah3Q=="
Body
{
"nonce": 1463732737,
"amount_btc": 398684,
"currency_code": "btc"
}
200
Headers
Content-Type: application/json
Body
{
"success": true,
"payload": {
"id": "576",
"amount_cur": -2.07,
"amount_vir": 0.00398684,
"rate": "509.68000000",
"timestamp": "2016-06-08 18:37:32"
}
}
Sell ¶
Use to initiate a sell order. Amount can be set either in a cryptocurrency or the user’s currency - one must be present but specifying both will return an error.
SellPOST/v1/sell
-
amount_btc
(string,optional) - Amount in satoshis (for BTC) or in the smallest unit of the given cryptocurrency. Do not use decimal values. NB. The parameter name remainsamount_btc
for sake of backwards compatibility, but it’s used for all available cryptocurrencies. -
amount_cur
(string,optional) - Amount in user’s currency in cents -
currency_code
(string,optional) - Cryptocurrency to sell. See/v2/rates
for options available. If not given, will default tobtc
for backwards compatibility.
Example URI
Headers
Content-Type: application/json
X-COINMOTION-APIKEY: "abcdef",
X-COINMOTION-SIGNATURE: "bH/xZab/841ct2BPvLhCLrIOm5ILA0eLQ4PSH/gOHsLD2qUuqXFEP1TkWd/MOrWpdlxuPkiSlOrTlOigb7ah3Q=="
Body
{
"nonce": 1463732795,
"amount_btc": 378750,
"currency_code": "btc"
}
200
Headers
Content-Type: application/json
Body
{
"success": true,
"payload": {
"id": "577",
"amount_cur": 1.86,
"amount_vir": -0.0037875,
"rate": "501.64000000",
"timestamp": "2016-06-08 18:37:33"
}
}
Deposit address ¶
Create a new deposit address or return the latest address. Most recently created address is returned when no parameters are set.
NB. There is an up to 10 minutes delay in creating an ETH
address. Please poll periodically without parameters to get your newly created address.
Create deposit addressPOST/v1/deposit_address
-
generate_new
(boolean,optional) - Set totrue
to create a new address. Defaults tofalse
. -
comment
(string,optional) - Comment for deposit address if generate_new istrue
. -
currency_code
(string,optional) - Cryptocurrency for which to create the address. See/v2/rates
for options available. If not given, will default tobtc
for backwards compatibility.
Example URI
Headers
Content-Type: application/json
X-COINMOTION-APIKEY: "abcdef",
X-COINMOTION-SIGNATURE: "bH/xZab/841ct2BPvLhCLrIOm5ILA0eLQ4PSH/gOHsLD2qUuqXFEP1TkWd/MOrWpdlxuPkiSlOrTlOigb7ah3Q=="
Body
{
"nonce": 1463733747,
"generate_new": true,
"comment": "testi 123"
}
200
Headers
Content-Type: application/json
Body
{
"success": true,
"payload": {
"address": "15xA7pUYuVeSNV6xYcdBEvMDr33edJgSom"
}
}
Send ¶
Use to send cryptocurrency to defined address.
WARNING: Ethereum sends are always processed using smart contracts. Please check that your receiving address can accept ETH from a smart contract. If it cannot, you risk losing your ETH irrecoverably.
SendPOST/v1/send
A signup json object has the following attributes:
-
amount_btc
(string) - Amount in satoshis (for BTC) or in the smallest unit of the given cryptocurrency. Do not use decimal values. NB. The parameter name remainsamount_btc
for sake of backwards compatibility, but it’s used for all available cryptocurrencies. -
address
(string) - Bitcoin address -
currency_code
(string,optional) - Cryptocurrency to send. See/v2/rates
for options available. If not given, will default tobtc
for backwards compatibility. -
destination_tag
(string) - Mandatory destination tag when sending XRP. If you are absolutely sure that you can send without the destination tag safely (and risk losing your sent coins), you can use any destination tag as the value.
Example URI
Headers
Content-Type: application/json
X-COINMOTION-APIKEY: "abcdef",
X-COINMOTION-SIGNATURE: "bH/xZab/841ct2BPvLhCLrIOm5ILA0eLQ4PSH/gOHsLD2qUuqXFEP1TkWd/MOrWpdlxuPkiSlOrTlOigb7ah3Q=="
Body
{
"nonce": 1463734335,
"amount_btc": 12345,
"address": "13u4zbs1jw4jqebXvsJ9B17SFP7MFK9FQL",
"currency_code": "btc"
}
200
Headers
Content-Type: application/json
Body
{
"success": true,
"payload": {
"id": 579
}
}
Withdraw ¶
Use to withdraw currency from user’s account.
WithdrawPOST/v1/withdraw
amount_cur
(string) - Amount in user’s currency in cents
Example URI
Headers
Content-Type: application/json
X-COINMOTION-APIKEY: "abcdef",
X-COINMOTION-SIGNATURE: "bH/xZab/841ct2BPvLhCLrIOm5ILA0eLQ4PSH/gOHsLD2qUuqXFEP1TkWd/MOrWpdlxuPkiSlOrTlOigb7ah3Q=="
Body
{
"nonce": 1463734473,
"amount_cur": 1234
}
200
Headers
Content-Type: application/json
Body
{
"success": false,
"status": "error",
"message": "You haven't registered a bank account"
}
Deposit ¶
Use to initialize a currency deposit to the user’s account with SEPA transfer. The actual SEPA transfer needs to be initialized separately.
DepositPOST/v1/deposit
amount_cur
(string) - Amount in user’s currency in cents
Example URI
Headers
Content-Type: application/json
X-COINMOTION-APIKEY: "abcdef",
X-COINMOTION-SIGNATURE: "bH/xZab/841ct2BPvLhCLrIOm5ILA0eLQ4PSH/gOHsLD2qUuqXFEP1TkWd/MOrWpdlxuPkiSlOrTlOigb7ah3Q=="
Body
{
"nonce": 1463734473,
"amount_cur": 1000
}
200
Headers
Content-Type: application/json
Body
{
"success": true,
"payload": {
"id": 55310,
"amount_cur": 10,
"iban": "FI1436363010211357",
"ref_no": "10047309"
}
}
Convert ¶
Use to preview values of buy or sell operation.
Explanation of response parameters:
-
amt
: Base currency value of the conversion after fees -
btc
: Currency value of the conversion after fees -
fee
: Fee amount -
tot
: Total value of the conversion -
fbid
: Sell rate of the currency -
fask
: Buy rate of the currency -
currencyFcode
: Currency code -
feePrcentage
: Fee percentage
ConvertPOST/v1/convert
-
amount
(float) - Amount for the conversion. Can be in euros or cryptocurrencies. -
currencyCode
(string) - Currency code for the conversion. -
baseCurrencyCode
(string) - Base currency code for the conversion. For all conversion pairs see https://api.coinmotion.com/v2/get_currencies/pairs -
amountIsInBase
(bool) - Defines in which currency the amount is. -
type
(string) - Defines the type of conversion. Available values:buy
,sell
,send
,withdrawal
.
Example URI
Headers
Content-Type: application/json
X-COINMOTION-APIKEY: "abcdef",
X-COINMOTION-SIGNATURE: "bH/xZab/841ct2BPvLhCLrIOm5ILA0eLQ4PSH/gOHsLD2qUuqXFEP1TkWd/MOrWpdlxuPkiSlOrTlOigb7ah3Q=="
Body
{
"nonce": 1463734473,
"amount": 10,
"amountIsInBase": true,
"baseCurrencyCode": "eur",
"currencyCode": "btc",
"type": "buy"
}
200
Headers
Content-Type: application/json
Body
{
"success": true,
"payload": {
"amt": "9.84 €",
"btc": "0.00061982 BTC",
"fee": "0.16 €",
"tot": "10.00 €",
"fbid": "15729.12 € / 1 BTC",
"fask": "15875.39 € / 1 BTC",
"currency_fcode": "BTC",
"fee_percentage": "1.60 %"
}
}