Skip to content

Sign & encrypt

This page demonstrates signing requests and encrypting them for transfer.

Info

The Signature of the call contains the payload of your request which is 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.

Therefore, the payload you sign contains: - the timestamp concatenated with the HTTP method of the request - the URL of the request (base and endpoint) - JSON body (optional: if required at that endpoint)

Construct your Signature

Generate your Signature hash:

  1. Construct the request to sign in the format: [timestamp][method][URL][body].
    The Qredo service doesn't 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

  2. Take the secret from the Qredo Wallet Web App and decode it from its Base64 format into bytes of unencoded data.

  3. Using the decoded secret, hash the request as constructed in Step 1 with the HMAC-SHA256 algorithm.
  4. Encode the Signature with URL-safe Base64 encoding.
  5. 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. It isn't recommend for use in production.

Qredo API tool

The Qredo API tool:

  • Signs API requests
  • Submits signed API requests to Qredo
  • Is available both as a command-line tool and as a Web UI

This Golang tool is hosted on GitHub. You are welcome to clone or fork the repository 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 command-line tool, verify whether you have Golang installed:

go version

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

  1. Clone a local copy of the API tool.

  2. Navigate to the local apitool repository.

  3. Using the command-line tool, build the API tool to work with your keys:

Build API tool in the command-line

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

go build -o apitool

Use command prompt: cmd.exe: 

go build -o apitool.exe

The command-line tool 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 command-line tool, run the following command:

Sign API requests in the command line

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

./apitool -api-key 9OgjbzwhoE4LJA \
-secret EXAMpleAPIsecrETthatCONTAINSnumber5andLetT3r5y8vdERqOFZCNHlzaWZWYjBzOG9BcWU4a0Uu \
-method GET \
-url https://api.qredo.network/qapi/v1/balance sign
The command-line tool prints out the Signature (qredo-api-sign header) and the timestamp (qredo-api-ts header): 
qredo-api-sign: S1GnAxSlgbL0-KA47kBwa0c7XLgX7cWUi00NMXYV5jA
qredo-api-key: KeY9OgjhoE4LJA
qredo-api-ts: 1234438269

Use command prompt: cmd.exe: 

apitool -api-key k3y9OgjhoE4LJA -secret EXAMpleAPIsecrETthatCONTAINSnumber5andLetT3r5y8vdERqOFZCNHlzaWZWYjBzOG9BcWU4a0Uu8vdERqOFZCNHlzaWZWYjBzOG9BcWU4a0Uu -method GET -url https://api.qredo.network/qapi/v1/balance sign
The command-line tool prints out the Signature (qredo-api-sign header) and the timestamp (qredo-api-ts header): 
qredo-api-sign: S1GnAxSlgbL0-KA47kBwa0c7XLgX7cWUi00NMXYV5jA
qredo-api-key: KeY9OgjhoE4LJA
qredo-api-ts: 1234438269

You can now proceed to send a request.

Send requests using the Qredo API tool

In the command-line tool, run the following command:

Send API requests in the command line

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

./apitool -api-key k3y9OgjhoE4LJA \
-secret EXAMpleAPIsecrETthatCONTAINSnumber5andLetT3r5y8vdERqOFZCNHlzaWZWYjBzOG9BcWU4a0Uu8vdERqOFZCNHlzaWZWYjBzOG9BcWU4a0Uu \
-method GET \
-url https://api.qredo.network/qapi/v1/balance send
The command-line tool prints out the API call response as uncompressed JSON: 
{"assets":{"ETH-TESTNET":{"total":1800000000,"available":1800000000,"pendingIn":0,"pendingOut":0,"scale":1000000000}}}

Use command prompt: cmd.exe: 

apitool -api-key KeY9OgjhoE4LJA -secret EXAMpleAPIsecrETthatCONTAINSnumber5andLetT3r5y8vdERqOFZCNHlzaWZWYjBzOG9BcWU4a0Uu8vdERqOFZCNHlzaWZWYjBzOG9BcWU4a0Uu -method GET -url https://api.qredo.network/qapi/v1/balance send
The command-line tool 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 command-line tool, run the following command:

Initiate the Web UI API tool

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

./apitool ui
The command-line tool prints out the local host location of the API tool Web UI: 
WebUI listening on http://127.0.0.1:4569

Use command prompt: cmd.exe: 

apitool ui
The command-line tool 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:

  1. Enter your API key and API secret.
  2. Enter the full URL path of your selected API endpoint. For example, with GET /balance, enter https://api.qredo.network/qapi/v1/balance.
  3. Select the HTTP method of the API request you want to send. For example, with GET /balance, set this value to GET.
  4. 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 doesn't have a body, e.g., GET requests.
  5. 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.
  1. Enter your API key and API secret.
  2. Enter the full URL path of your selected API endpoint. For example, with GET /balance, enter https://api.qredo.network/qapi/v1/balance.
  3. Select the HTTP method of the API request you want to send. For example, with GET /balance, set this value to GET.
  4. In the Body text box, enter the API call body.
  5. 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: 2023-01-18