​
Authentication

All requests to Handcash must include the headers:
  • app-secret
  • app-id
For requests that invoke a particular wallet, user, or business wallet, a Signed Payload is required. Auth Tokens can be obtained in a couple of different ways:
  • Generated by the client server in the Wallet-as-a-Service flow.
  • Returned in a query parameter in a redirect in the Handcash Connect flow.
  • Found in the business wallet “Wallet” section for a business wallet.

​
Required Headers for Signed Payload

Include the following headers when making authenticated requests:
HeaderDescription
app-idYour application’s unique identifier provided by Handcash.
app-secretYour application’s secret key provided by Handcash.
oauth-publickeyThe public key of the wallet or user making the request.
oauth-timestampCurrent timestamp to prevent replay attacks.
oauth-nonceUnique random string per request to prevent replay attacks.
oauth-signatureECDSA signature of the request, generated using your private key.

​
Generating a Signature

To create the oauth-signature:
  1. Create the Signature String: Concatenate the HTTP method, endpoint, body, timestamp, and nonce.
  2. Hash the Signature String: Use SHA-256 to hash the signature string.
  3. Sign the Hash: Use ECDSA with your private key to sign the hashed string.
  4. Include the Signature: Add the signature to the oauth-signature header.

​
Code Snippet

Here’s how to generate the oauth-signature in JavaScript: 
const crypto = require('crypto');

function getRequestSignatureString(method, endpoint, body, timestamp, nonce) {
    return `${method}\n${endpoint}\n${timestamp}\n${JSON.stringify(body)}${nonce ? `\n${nonce}` : ''}`;
}

function signPayload(method, endpoint, body, timestamp, privateKey, nonce){
  const hash = crypto.Hash.sha256(Buffer.from(getRequestSignatureString(method, endpoint, body, timestamp, nonce)));
  return crypto.ECDSA.sign(hash, privateKey).toString();
};