# REST API

Use these endpoints to send REST requests <https://trade.finerymarkets.com/api> (or <https://test.finerymarkets.com/api> for test environment).

There are general rules for all REST requests:

* All calls should be signed using key/secret pair
* All calls are **POST** requests
* All calls use `application/json` format
* Additional nonce (`unsigned int64`) and timestamp (`Efx::Timestamp`) parameters are required
* `EFX-Key` and `EFX-Sign` HTTP headers are used for authentication

To authenticate a request send additional headers:

`EFX-Key`: your public key

`EFX-Sign`: content signature. Concatenate a name of an API method with payload string and sign it with your private key using HMAC SHA384.

In order to protect from attacks, it is required to send a **nonce** and **timestamp**. Any new value of nonce must be unique within a 2-minute window. You may use the same nonce with multiple keys, but make sure its value is constantly increasing.&#x20;

{% hint style="danger" %}
Do not use the same key with multiple asynchronous REST services, it will be difficult to synchronise nonce values.
{% endhint %}

See an example of REST request below. Generating a signature for REST request using key/secret pair (*javascript with CryptoJS lib*):

```javascript
let method = "dealHistory"
let content = {
    "instrument": "BTC-USD"
}

let payload = JSON.stringify({
  ...content,
  "nonce": 12345,
  "timestamp": new Date().valueOf()
})

// Put your API keys there
let key = "RlZ4sKsHSr5zmYKIzbtf772J9y9gx8nekd8COrawI5V"
let secret = "cZpZ1vwzOaXuiONfIQVg8h6za97FoHhrwwgoSCNwDAR"

let signature = CryptoJS.HmacSHA384(method + payload, secret).toString(CryptoJS.enc.Base64)

const response = axios({
    method: 'POST',
    url: this.host + method,
    headers: {
        'EFX-Key': key,
        'EFX-Sign': signature,
        'Content-Type': 'text/html'
    },
    data: payload
}).then((response) => {
    let data = response.data
    console.log("Response received", data)
}).catch(function (error) {
    switch (error.response.status) {
        case 400: {
            let data = error.response.data
            let errorCode = data.error // data.error contains error code
            console.log("Error received:", errorCode)
            break
        }
        default: {
            // some unhandled error (connection error for example)
            console.log("Error received:", response)
            break
        }
    }
})
```

{% hint style="warning" %}
**Important**. To create a valid signature concatenate a method name with a payload string. Use the same payload string as you send in the request.
{% endhint %}