Back to top

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 V2
GET/v2/rates

Example URI

GET https://api.coinmotion.com/v2/rates
Request
HideShow
Headers
Content-Type: application/json
Response  200
HideShow
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 V1
GET/v1/rates

Example URI

GET https://api.coinmotion.com/v1/rates
Request
HideShow
Headers
Content-Type: application/json
Response  200
HideShow
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 balance
POST/v1/balances

Example URI

POST https://api.coinmotion.com/v1/balances
Request
HideShow
Headers
Content-Type: application/json
X-COINMOTION-APIKEY: "abcdef",
X-COINMOTION-SIGNATURE: "bH/xZab/841ct2BPvLhCLrIOm5ILA0eLQ4PSH/gOHsLD2qUuqXFEP1TkWd/MOrWpdlxuPkiSlOrTlOigb7ah3Q=="
Body
{
  "nonce": "1463731543"
}
Response  200
HideShow
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.

Buy
POST/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 remains amount_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^16
      • LTC : amount_btc * 10^6
      • XRP : amount_btc * 10^6
      • XLM : amount_btc * 10^7
      • UNI : amount_btc * 10^15
      • AAVE : amount_btc * 10^15
      • LINK : amount_btc * 10^15
      • USDC : amount_btc * 10^4
  • 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 to btc for backwards compatibility.

Example URI

POST https://api.coinmotion.com/v1/buy
Request
HideShow
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"
}
Response  200
HideShow
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.

Sell
POST/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 remains amount_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 to btc for backwards compatibility.

Example URI

POST https://api.coinmotion.com/v1/sell
Request
HideShow
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"
}
Response  200
HideShow
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 address
POST/v1/deposit_address

  • generate_new (boolean,optional) - Set to true to create a new address. Defaults to false.

  • comment (string,optional) - Comment for deposit address if generate_new is true.

  • currency_code (string,optional) - Cryptocurrency for which to create the address. See /v2/rates for options available. If not given, will default to btc for backwards compatibility.

Example URI

POST https://api.coinmotion.com/v1/deposit_address
Request
HideShow
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"
}
Response  200
HideShow
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.

Send
POST/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 remains amount_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 to btc 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

POST https://api.coinmotion.com/v1/send
Request
HideShow
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"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": true,
  "payload": {
    "id": 579
  }
}

Withdraw

Use to withdraw currency from user’s account.

Withdraw
POST/v1/withdraw

  • amount_cur (string) - Amount in user’s currency in cents

Example URI

POST https://api.coinmotion.com/v1/withdraw
Request
HideShow
Headers
Content-Type: application/json
X-COINMOTION-APIKEY: "abcdef",
X-COINMOTION-SIGNATURE: "bH/xZab/841ct2BPvLhCLrIOm5ILA0eLQ4PSH/gOHsLD2qUuqXFEP1TkWd/MOrWpdlxuPkiSlOrTlOigb7ah3Q=="
Body
{
  "nonce": 1463734473,
  "amount_cur": 1234
}
Response  200
HideShow
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.

Deposit
POST/v1/deposit

  • amount_cur (string) - Amount in user’s currency in cents

Example URI

POST https://api.coinmotion.com/v1/deposit
Request
HideShow
Headers
Content-Type: application/json
X-COINMOTION-APIKEY: "abcdef",
X-COINMOTION-SIGNATURE: "bH/xZab/841ct2BPvLhCLrIOm5ILA0eLQ4PSH/gOHsLD2qUuqXFEP1TkWd/MOrWpdlxuPkiSlOrTlOigb7ah3Q=="
Body
{
  "nonce": 1463734473,
  "amount_cur": 1000
}
Response  200
HideShow
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

Convert
POST/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

POST https://api.coinmotion.com/v1/convert
Request
HideShow
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"
}
Response  200
HideShow
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 %"
  }
}

Generated by aglio on 05 Apr 2022