Sign & encrypt

In this section, you will learn how to sign requests and encrypt them for transfer.

Info

The payload of a request is passed as the Signature of the call and encrypted using your API secret.

Prerequisites¶

You have created your API key and secret.

Authenticate Requests¶

Pass your API key as a header to authenticate your API request.

Authorize Requests¶

The Qredo API authorizes all requests by examining a Signature (passed as qredo-api-sig header) combined with a timestamp (passed as qredo-api-ts header).

Signatures¶

Sign and encrypt the Signature of your API calls with your API secret.

The Signature is the URL-safe Base64 encoding (RFC 4648) of the HMAC SHA256 hash of the following string: timestamp|method|full path url|body, signed using your API secret.

The payload to be signed is:

the timestamp concatenated with the HTTP method of the request
the URL of the request (base and endpoint)
JSON body (if required at that endpoint)

Construct your Signature¶

Generate your Signature hash:

Construct the request to sign in the format: [timestamp][method][URL][body].
The Qredo service does not process a body with an HTTP GET method; therefore, in the following example, the format [timestamp][method][URL] applies, i.e., there is no body. Note that the timestamp must be identical to qredo-api-ts.
Sign GET /balance
- timestamp: 1647356399
- HTTP method: GET
- URL: https://api.qredo.network/qapi/v1/balance
- body: none
The resulting string with this example is: 1647356399GEThttps://api.qredo.network/qapi/v1/balance
Take the secret from the Qredo Wallet Web App and decode it from its Base64 format into bytes of unencoded data.
Using the decoded secret, hash the request as constructed in Step 1 with the HMAC-SHA256 algorithm.
Encode the Signature with URL-safe Base64 encoding.
Assign the output of Step 4 to the qredo-api-sig header.

Send the body exactly as signed

After signing a body, make sure to send the JSON body formatted precisely as signed. Raw, unsigned JSON will generate an error.

Testing¶

Qredo provides a tool to assist with signing your Signature and testing your integration.

The API tool is for tests only

The API tool is provided by Qredo for illustrative purposes. We do not recommend its use for operations on production.

Qredo API tool¶

The Qredo API tool:

Signs API requests
Submits signed API requests to Qredo
Is available both in CLI and as a simple web UI

This utility is written in Golang and hosted on GitHub. You are welcome to clone or fork the tool to adapt it to your needs when building your custom client for signing and sending requests.

Install Golang and build the API tool¶

To build and run the Signing Client, you must have Golang installed. Using a CLI, check if you have Golang installed and verify the version:

go version

If you don't have Golang, install a recent stable version to proceed.

Clone the API tool repo locally.
Navigate to the local apitool repository.
Using the CLI, build the API tool to work with your keys:

Build API tool in CLI

Linux/Mac

You can also use this command on Windows using PowerShell / Git Bash:

go build -o apitool

Windows

Use command prompt: cmd.exe:

go build -o apitool.exe

The CLI prints out a message about the apitool executable location. You can now proceed with using the API tool.

Sign requests using the Qredo API tool¶

In the CLI, run the following command:

Sign API requests in CLI

Linux/Mac

You can also use this command on Windows using PowerShell / Git Bash:

./apitool -api-key 9OgjbzwhoE4LJA \
-secret JDJhJDA0JHRmSmlkRmp2TEZkMVhmb3ExVTAzWGVKVUV3by8vdERqOFZCNHlzaWZWYjBzOG9BcWU4a0Uu \
-method GET \
-url https://api.qredo.network/qapi/v1/balance sign

The CLI prints out the Signature (qredo-api-sign header) and the timestamp (qredo-api-ts header):

qredo-api-sign: Kbj4AxSlgbL0-KA47kBwa0c7XLgX7cWUi00NMXYV5jA
qredo-api-key: 9OgjbzwhoE4LJA
qredo-api-ts: 1647438269

Windows

Use command prompt: cmd.exe:

apitool -api-key 9OgjbzwhoE4LJA -secret JDJhJDA0JHRmSmlkRmp2TEZkMVhmb3ExVTAzWGVKVUV3by8vdERqOFZCNHlzaWZWYjBzOG9BcWU4a0Uu -method GET -url https://api.qredo.network/qapi/v1/balance sign

The CLI prints out the Signature (qredo-api-sign header) and the timestamp (qredo-api-ts header):

qredo-api-sign: Kbj4AxSlgbL0-KA47kBwa0c7XLgX7cWUi00NMXYV5jA
qredo-api-key: 9OgjbzwhoE4LJA
qredo-api-ts: 1647438269

You can now proceed to send a request.

Send requests using the Qredo API tool¶

In the CLI, run the following command:

Send API requests in CLI

Linux/Mac

You can also use this command on Windows using PowerShell / Git Bash:

./apitool -api-key 9OgjbzwhoE4LJA \
-secret JDJhJDA0JHRmSmlkRmp2TEZkMVhmb3ExVTAzWGVKVUV3by8vdERqOFZCNHlzaWZWYjBzOG9BcWU4a0Uu \
-method GET \
-url https://api.qredo.network/qapi/v1/balance send

The CLI prints out the API call response as uncompressed JSON:

{"assets":{"ETH-TESTNET":{"total":1800000000,"available":1800000000,"pendingIn":0,"pendingOut":0,"scale":1000000000}}}

Windows

Use command prompt: cmd.exe:

apitool -api-key 9OgjbzwhoE4LJA -secret JDJhJDA0JHRmSmlkRmp2TEZkMVhmb3ExVTAzWGVKVUV3by8vdERqOFZCNHlzaWZWYjBzOG9BcWU4a0Uu -method GET -url https://api.qredo.network/qapi/v1/balance send

The CLI prints out the API call response as uncompressed JSON:

{"assets":{"ETH-TESTNET":{"total":1800000000,"available":1800000000,"pendingIn":0,"pendingOut":0,"scale":1000000000}}}

Sign and send requests via Web UI¶

The API tool initiates a locally-served Web UI providing simple controls to sign and send API calls.

Start the API tool Web UI¶

In the CLI, run the following command:

Initiate the Web UI API tool

Linux/Mac

You can also use this command on Windows using PowerShell / Git Bash:

./apitool ui

The CLI prints out the local host location of the API tool Web UI:

WebUI listening on http://127.0.0.1:4569

Windows

Use command prompt: cmd.exe:

apitool ui

The CLI prints out the local host location of the API tool Web UI:

WebUI listening on http://127.0.0.1:4569

Sign and send requests¶

The Web UI supports:

Signing a request: Click Sign

The application returns the API call Signature and timestamp.
Sign and send a request: Click Send

The application returns the API call Signature and timestamp plus the HTTP response body.

With the Web UI running, open the local host location http://127.0.0.1:4569 in a browser and follow these steps:

Sign and Send requests

Enter your API key and API secret.
Enter the full URL path of your selected API endpoint. For example, with GET /balance, enter https://api.qredo.network/qapi/v1/balance.
Select the HTTP method of the API request you want to send. For example, with GET /balance, set this value to GET.
In the Body text box, enter the API call body. Applicable to requests with HTTP methods such as POST or PUT. Leave blank when the request does not have a body, e.g., GET requests.
Click Send. The API tool Web UI prints out the results in two sections of the screen:
- To the right of the Body text box, you can observe your API key shown as (Qredo-API-Key), the API call timestamp (Qredo-API-Ts), and the API call Signature (Qredo-API-Sig).
- Below the buttons Send and Sign, the web UI API tool prints out the response JSON body.

Sign requests

Enter your API key and API secret.
Enter the full URL path of your selected API endpoint. For example, with GET /balance, enter https://api.qredo.network/qapi/v1/balance.
Select the HTTP method of the API request you want to send. For example, with GET /balance, set this value to GET.
In the Body text box, enter the API call body.
Click Sign. The API tool Web UI prints out the results to the right of the screen including: your Qredo-API-Key, the Qredo-API-Ts timestamp, and the API call Signature, shown as the value for Qredo-API-Sig.

Last update: 2022-12-14