Examples

🔑 Authentication

🐘 PHP example:

//these pamameters are for affiliate example.com and you are free to use them for your testing
$key = 'syoihuudkjqc3882';
$private = 'z2z77e0pl8rhtn9w';

$body = null;
$nonce = rand() << 32 | rand();//generates random long integer, for example: 1353154049963006992

//there are multiple supported body shapes, so please pick yours
$bodyJson = json_encode($body);//raw escaped
$bodyJson = json_encode($body ?: []);//array escaped
$bodyJson = json_encode($body ?: null);//null escaped
//default implementation of json_encode automatically escapes slashes, unlike json functions in other languages
//these options make it to behave more "standard"
$bodyJson = json_encode($body, JSON_UNESCAPED_SLASHES);//raw unescaped
$bodyJson = json_encode($body ?: [], JSON_UNESCAPED_SLASHES);//array unescaped
$bodyJson = json_encode($body ?: null, JSON_UNESCAPED_SLASHES);//null unescaped

$signature = hash_hmac('sha256',
    $key
    . "$"
    . $nonce
    . "$"
    . $bodyJson
    ,
    $private);

// curl call itself
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.btcex.cz/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, false);

if (!is_null($body)) {//post method if $body is not NULL
    curl_setopt($ch, CURLOPT_POST, true);
    //but there it is NOT required to have same shape as in signature
    $dataJson = json_encode($body);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $dataJson);
}

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "btcex-key: $key",
    "btcex-nonce: $nonce",
    "btcex-signature: $signature",
    "btcex-test: 1",//request is run in test mode, which prevents from changing resources on our site
]);
$response = curl_exec($ch);
curl_close($ch);


$rType = (string)curl_getinfo($ch, CURLINFO_CONTENT_TYPE);//application/json
$rCode = (int)curl_getinfo($ch, CURLINFO_RESPONSE_CODE);//return code
$rData = json_decode($response, true);//json decoded data

var_dump($rType);
var_dump($rCode);
var_dump($rData);
die();

On successful call you should get partner example.com

See following input and output variables for signature function in order to test you have it right:

$nonce = 4835119959885924862;
$key = 'syoihuudkjqc3882';
$private = 'z2z77e0pl8rhtn9w';
//-----
$body = null;
$signatureList = [
    'raw_escaped' => [
        'json' => 'null',
        'signature' => '126e70930a16cfea5f6c8d8cba64aa3e13b6a12a47c7e54532a6c58298dc433f',
    ],
    'array_escaped' => [
        'json' => '[]',
        'signature' => 'cb11e4c0411ced017a6fda9df5c34cc78898685e488b2b05769acc01c9cdf5b6',
    ],
    'null_escaped' => [
        'json' => 'null',
        'signature' => '126e70930a16cfea5f6c8d8cba64aa3e13b6a12a47c7e54532a6c58298dc433f',
    ],
    'raw_unescaped' => [
        'json' => 'null',
        'signature' => '126e70930a16cfea5f6c8d8cba64aa3e13b6a12a47c7e54532a6c58298dc433f',
    ],
    'array_unescaped' => [
        'json' => '[]',
        'signature' => 'cb11e4c0411ced017a6fda9df5c34cc78898685e488b2b05769acc01c9cdf5b6',
    ],
    'null_unescaped' => [
        'json' => 'null',
        'signature' => '126e70930a16cfea5f6c8d8cba64aa3e13b6a12a47c7e54532a6c58298dc433f',
    ],
];
//-----
$body = [];
$signatureList = [
    'raw_escaped' => [
        'json' => '[]',
        'signature' => 'cb11e4c0411ced017a6fda9df5c34cc78898685e488b2b05769acc01c9cdf5b6',
    ],
    'array_escaped' => [
        'json' => '[]',
        'signature' => 'cb11e4c0411ced017a6fda9df5c34cc78898685e488b2b05769acc01c9cdf5b6',
    ],
    'null_escaped' => [
        'json' => 'null',
        'signature' => '126e70930a16cfea5f6c8d8cba64aa3e13b6a12a47c7e54532a6c58298dc433f',
    ],
    'raw_unescaped' => [
        'json' => '[]',
        'signature' => 'cb11e4c0411ced017a6fda9df5c34cc78898685e488b2b05769acc01c9cdf5b6',
    ],
    'array_unescaped' => [
        'json' => '[]',
        'signature' => 'cb11e4c0411ced017a6fda9df5c34cc78898685e488b2b05769acc01c9cdf5b6',
    ],
    'null_unescaped' => [
        'json' => 'null',
        'signature' => '126e70930a16cfea5f6c8d8cba64aa3e13b6a12a47c7e54532a6c58298dc433f',
    ],
];
//-----
$body = ['foo' => 'bar/baz']);
$signatureList = [
    'raw_escaped' => [
        'json' => '{"foo":"bar\\/baz"}',
        'signature' => '472254611513c81b11d4ee1c3b7ac9b30bb9266d0fb85f7d4cae4978e428b1a4',
    ],
    'array_escaped' => [
        'json' => '{"foo":"bar\\/baz"}',
        'signature' => '472254611513c81b11d4ee1c3b7ac9b30bb9266d0fb85f7d4cae4978e428b1a4',
    ],
    'null_escaped' => [
        'json' => '{"foo":"bar\\/baz"}',
        'signature' => '472254611513c81b11d4ee1c3b7ac9b30bb9266d0fb85f7d4cae4978e428b1a4',
    ],
    'raw_unescaped' => [
        'json' => '{"foo":"bar/baz"}',
        'signature' => '5fe2a575b88260ca5da7df1e985490cafe042847be35647104ca09d39682c10a',
    ],
    'array_unescaped' => [
        'json' => '{"foo":"bar/baz"}',
        'signature' => '5fe2a575b88260ca5da7df1e985490cafe042847be35647104ca09d39682c10a',
    ],
    'null_unescaped' => [
        'json' => '{"foo":"bar/baz"}',
        'signature' => '5fe2a575b88260ca5da7df1e985490cafe042847be35647104ca09d39682c10a',
    ],
];

🤡 JS example:

At first you need to install libraries yarn add crypto axios

//Include libraries
var crypto = require("crypto");
var axios = require("axios");
//Initialize parameters
var body = null;
var key = "syoihuudkjqc3882";
var privateKey = "z2z77e0pl8rhtn9w";
var nonce = "4835119959885924862";
//Create hash
var hasher = crypto.createHmac("sha256", privateKey);

var hashKey = key + "$" + nonce + "$" + JSON.stringify(body || []);
var hash = hasher.update(hashKey).digest("hex");

//Send request
var apiUrl = "https://api.btcex.cz/";
var headers = {
    "Content-Type": "application/json",
    "btcex-key": key,
    "btcex-nonce": nonce,
    "btcex-signature": hash,
    "btcex-test": "1"
};

if (body) {
    axios.post(apiUrl, body, {headers: headers})
        .then(function (res) { console.log(res) })
        .catch(function (err) { console.log(err) });
} else {
    axios.get(apiUrl, {headers: headers})
        .then(function (res) { console.log(res) })
        .catch(function (err) { console.log(err) });
}

🦩 C# signing example:

using System;
using System.Security.Cryptography;
using System.Text;
using Newtonsoft.Json;
using NUnit.Framework;
 
namespace Btcex.Test;
 
public class Tests
{
    [Test]
    public void TestSignature()
    {
        var nonce = 4835119959885924862;
        var pubKey = "syoihuudkjqc3882";
        var prvKey = "z2z77e0pl8rhtn9w";
        var data = JsonConvert.SerializeObject(new { foo = "bar"});
 
        var sentence = $"{pubKey}${nonce}${data}";
        var bytesPrvKey = Encoding.UTF8.GetBytes(prvKey);
        using var hmacsha256 = new HMACSHA256(bytesPrvKey);
        var bytesSource = Encoding.UTF8.GetBytes(sentence);
        var hash = hmacsha256.ComputeHash(bytesSource);
        var signature = Convert.ToHexString(hash).ToLower();
        
        Assert.AreEqual("9eb77611ed3afdee9d864b72014213d3bea615422feac0fa74b985e9c5c40aeb", signature);
    }
}

🦺 Test mode

To implementation testing there is Test mode present.

It is activated by adding custom hearder: btcex-test: 1

When using, please have in mind following:

underlying resources are not changed (even responses says otherwise though)

when creating orders, their variable_symbol is always 0

you as partner might have test mode enforced (case for example.com for example)