Signing a Request Using HMAC SHA256

SIGNED endpoints require an additional Signature header to verify the authenticity of the request.

Follow the steps below to compute a signature using HMAC SHA256.

How to compute the signature with HMAC SHA256

The signature is generated using the HMAC SHA256 algorithm. This method combines your SecretKey and the uri?totalParams to produce a unique code. The generated signature is not case sensitive.

totalParams consists of the query string (parameters in the URL) concatenated with the request body (payload).

Your secretKey should remain private and never be included in the request.

This ensures the security of your API interactions by validating the sender and protecting against unauthorized requests.

Prepare the payload

Concatenate the query string and the request body to create the signature payload totalParams. Ensure the data is formatted consistently.

Generate the binary signature

Use the HMAC SHA256 algorithm with your secretKey as the key and totalParams as the data.

Encode the signature

Convert the binary output of the HMAC operation to a hexadecimal string.

How to send a signed API request

Once the signature is computed, include it in the API request as follows:

Add the Signature to the request header

Include the computed signature in the Signature header of your request.

Include your API Key

Add your 3Commas APIKey in the request header.

Send the request

Ensure the request method, headers, and payload are identical to those used during signature computation to avoid mismatches.

Keep in mind, the signature is not case sensitive.

Look here for some examples.

How to Sign the Request

Below is a step-by-step example of how to send a valid signed payload from the Linux command line using echo, openssl, and curl.

Here are examples of signed endpoints, along with step-by-step guides for interacting with them.

Example with Endpoint

POST

/public/api/ver1/users/change_mode

API Credentials:

Key	Value
api_key	vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
secret	NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j

Request Parameters

Parameter:mode

Value:paper

Request via Query String

Request Preparation

path

/public/api/ver1/users/change_mode

queryString

mode=paper

payload

/public/api/ver1/users/change_mode?mode=paper

Generating the HMAC SHA256 Signature

echo -n "/public/api/ver1/users/change_mode?mode=paper" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"

After running the command, you'll get the signature:

bca8d8c10acfbe8e76c5335d3efbe0a550487170a8bb7aaea0a13efabab55316

Making the API Call

curl
-H "Apikey: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A"
-H "Signature: bca8d8c10acfbe8e76c5335d3efbe0a550487170a8bb7aaea0a13efabab55316"
-X POST 'https://api.3commas.io/public/api/ver1/users/change_mode?mode=paper'

Request via Request Body

Request Preparation

path

/public/api/ver1/users/change_mode

requestBody

mode=paper

payload

/public/api/ver1/users/change_mode?mode=paper

Generating the HMAC SHA256 Signature

echo -n "/public/api/ver1/users/change_mode?mode=paper" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"

After running the command, you'll get the signature:

bca8d8c10acfbe8e76c5335d3efbe0a550487170a8bb7aaea0a13efabab55316

Making the API Call

curl
-H "Apikey: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" 
-H "Signature: bca8d8c10acfbe8e76c5335d3efbe0a550487170a8bb7aaea0a13efabab55316"
-X POST 'https://api.3commas.io/public/api/ver1/users/change_mode' -d 'mode=paper'

Request via Raw JSON

Request Preparation

path

/public/api/ver1/users/change_mode

requestBody

{"mode": "paper"}

payload

/public/api/ver1/users/change_mode

Generating the HMAC SHA256 Signature

echo -n "/public/api/ver1/users/change_mode" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"

After running the command, you'll get the signature:

0475b407ba6f2388d213134e478b330f74073388a232737837f79018694ae373

Making the API Call

curl
-H "Apikey: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" 
-H "Signature: 0475b407ba6f2388d213134e478b330f74073388a232737837f79018694ae373" 
-H "Content-Type: application/json" 
-X POST 'https://api.3commas.io/public/api/ver1/users/change_mode' --data-raw '{"mode": "paper"}'

How to Send the Signed Request

Here is a step-by-step example of how to call your endpoint through Postman. Once Postman works with the values, you can implement it in code.

Example with Endpoint

GET

/public/api/ver1/bots/:bot_id/show

Set up GET url

With include_events https://api.3commas.io/public/api/ver1/bots/EnterBotIdHere/show?include_events=true

By using include_events in the query string, in Postman, your Params field will be automatically filled in.

Calculate your Signature

Use a HMAC SHA256 generator tool.

Input value	Secret Key	Hashed Output
/public/api/ver1/bots/84512/show?include_events=true	Use your secret API key from 3commas	Signature result to be used in Step 3

Set up Headers

Key	Value
Apikey	3commas API key goes here
Signature	Calculated Signature from Step 2 goes here

These 2 key/value pairs can be entered in Postman under Headers (which is located under the GET url field).

Receive JSON object

If you have followed these steps you should now receive a status 200 OK with your JSON data.