Sign API calls¶

You now have set up API access and keys and it is time to make some API calls.

In this section you will learn how to:

Deploy the Partner API Signing Client.
Start signing requests using the Partner API Signing Client.

The Qredo Partner & Core Client API authorizes all requests using a signature (passed as a x-sign header), combined with a timestamp or nonce.

To facilitate your experience with signing API requests, Qredo provides the Partner API Signing Client: an example client application that generates signatures and timestamps with API calls.

This section pertains to Production only!!!

Everything in this section applies to partner's experience on Production. You can skip this section for action on Play.

Signatures in Partner API¶

A Signature (passed as an x-sign header in the API) must be paired with a Timestamp (or Nonce) to authorize all requests to the Partner & Core Client API.

The Signature is the URL-safe base64 encoding (RFC 4648) of the RSA PKCS #1 1.5 signature of the SHA256 hash of the payload to be signed.

The Payload to be signed is the nonce or timestamp concatenated with the URL of the request then the body in compressed JSON format (if that particular call requires a body).

Use either timestamp or nonce in Partner & Core Client API calls

Pass either x-timestamp or x-nonce header with every API call.

Timestamp - an Unix Epoch timestamp: passed as x-timestamp header. All timestamps returned by the API are Epoch timestamps.
Nonce - an integer, that must be ever-increasing with each next request passed as x-nonce header.

Examples in this guide use timestamps only.

In summary:

Construct the JSON body.

Construct the request to sign in the format: [timestamp/nonce][URL][body]

Sign POST /company using a timestamp

This example uses the POST /company API call: create a company.

Uncompressed JSON

1639490495https://api.qredo.network/api/v1/p/company{
  "name": "ACME Corp",
  "city": "Paris",
  "country": "FR",
  "domain": "acme.com",
  "ref": "9827feec-4eae-4e80-bda3-daa7c3b97add"
}

Compressed JSON

1639490495https://api.qredo.network/api/v1/p/company{"name":"ACME Corp","city":"Paris","country":"FR","domain":"acme.com","ref":"9827feec-4eae-4e80-bda3-daa7c3b97add"}

Hash it with the SHA256 algorithm.
Sign the hash with RSA PKCS #1 1.5.
Encode the signature with URL-safe Base64 encoding.

Send the body exactly as signed

After signing a PUT or POST request, make sure to send the JSON body formatted exactly as signed, otherwise you will get an error.

Partner API Signing Client¶

The Partner API Signing Client is a tool written in Golang which, allows you to:

Sign API requests.
Submit signed API requests to Qredo.
Listen on a websocket URL for incoming requests to fetch:
- transaction and withdrawal requests Core Client custody.
- requests to connect either dedicated or multi-counterparty wallets to an exchange.
- sweep transactions.
- atomic swap quotes posted to the liquidity hub.

The Signing Client source code is written in Go and is available on Github. You can clone or fork the repo and use its code as an example when building your custom request signing client.

The Signing Client is for tests only

The Partner API Signing Client is provided for illustrative purposes only. Qredo does not recommend its use for operations on production.

Install Golang and set up the Signing Client¶

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 locally the Partner API Signing Client repo.
Copy or move the apikey file to the local /partnerapi-sign directory.
Copy or move your private.pem file to the /partnerapi-sign directory. Remember that you already added the public key to your account in the Qredo web application.
Navigate to the local partnerapi-sign repository.
Using the CLI, build the Partner API Signing Client to work with your keys:
Build Signing Client in CLI
Linux/Mac
You can also use this command on Windows using PowerShell:
go build -o partnerapi-sign
Windows
Use command prompt: cmd.exe:
go build -o partnerapi-sign.exe
The cursor moves to a new line in the CLI and you can proceed to signing requests.

Sign requests using the Signing Client¶

Run the following command:
Run Signing Client in CLI
Linux/Mac
You can also use this command on Windows using PowerShell:
./partnerapi-sign sign
Windows
Use command prompt: cmd.exe:
partnerapi-sign.exe sign
In the prompt, enter the resource url (do not add the HTTP method, just the URL) and press <Enter> on your keyboard.

The prompt that follows requires of you to paste in the JSON body with HTTP POST and HTTP PUT requests.

Sign API requests using Signing Client

Request without a body

This example uses GET /company/search to retrieve all companies per account:

» ./partnerapi-sign sign
url: https://api.qredo.network/api/v1/p/company/search
body (hit Ctrl+Z followed by <enter> to end):

There is no JSON body to add: on your keyboard, press 'Ctrl+D' (or 'Ctrl+Z' if you're using Windows) and then Enter.

Request with a JSON body

This example uses POST /company to create a new company:

» ./partnerapi-sign sign
url: https://api.qredo.network/api/v1/p/company
body (hit Ctrl+Z followed by <enter> to end):
{
  "name": "Randomcompanyname",
  "city": "Paris",
  "country": "FR",
  "domain": "randomcompanyname.com",
  "ref": "00-00-0a1"
}

Prepare your JSON body and copy-paste it here. Next, on your keyboard, press 'Ctrl+D' (or 'Ctrl+Z' if you're using Windows) and then Enter.

With either request type (with or without a JSON body), the Signing Client returns a hash value, a signature and a timestamp.

Hash: 3cc42895c46b50d72907879a8427859f25ddb761ee551196a38c52987c149eff
x-sign: Vc_KZBmtqdrFiGVPvDcSfmly-dK652y9kLvxSYo93hmqza_RZq1YtJXamsMAxCQTZf6JXviVLDaqtQIwjB1Jjl3ms6jyjDFC4wp0qNh9m43rNj4xY7tfoE98qzkmeTJ9BIXEvEkQtruRHsw0bG9cjQlNKmA2NtNEyquEkUsSBX1phFudvDDtIlUWqA
x-timestamp: 1634226826

Test signing requests together with the Swagger UI¶

If you have completed all steps as described above, you can perform a final test: submit the GET /company/search request you signed just above.

Go to the Swagger UI and open the GET /company/search resource tab.
Select Try it out to enable editing the API call: the header parameters become available for input.
Copy each of the respective values of x-timestamp and x-sign and paste them in the respective fields in the Swagger UI.

With POST requests, submit the JSON body as signed

If you decide to test signing the POST /company resource described above (instead of GET /company/search ), don't forget to submit the JSON body formatted exactly as when signed.

Click Execute. You should get a HTTP 200 OK response with details about supported assets:

{
  "total_count": 2,
  "matches": [
    {
      "company_id": "1zVKzkBWXXXXXXXXXXXXHgebFAP",
      "name": "Company One",
      "domain": "company-001.com"
    },
    {
      "company_id": "1zXMfYGSXXXXXXXXXXXX6wU5oU5",
      "name": "Company 2",
      "domain": "company-002.com"
    }
  ]
}

Some notes regarding the Signing Client¶

Testing the Signing Client is easier when you use an editor to compose, format and edit you API requests and copy-paste them in the CLI.
On the step when you sign a body, after you are finished (regardless if you need to paste a body or not), make sure you do not accidentally press any other key besides 'Ctrl+D' (or 'Ctrl+Z' if you're using Windows) followed by 'Enter'. Otherwise, the signing process might be affected and submitting the API call could result in error code HTTP 1020 for a bad signature.
With API requests that have a JSON body (e.g. every POST request) - you can use uncompressed OR compressed JSON. The only rule is: if you signed compressed, then submit compressed, if you signed uncompressed, then submit exactly the same formatted JSON as the one that was signed. Otherwise, you'll get error code HTTP 1020 for a bad signature.
```
{
  "code": 1020,
  "msg": "errPartnerAuth",
  "detail": {
    "reason": "signature"
  }
}
```
If you use a tool that formats JSON and adds tabs (as opposed to space intervals) - the signature will not work and the API call would result in error code HTTP 1020 for a bad signature.

You are now ready to start using the API

If you have completed all steps you can now begin using the Partner & Core Client API.

Last update: 2022-07-15