​
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();
};
External Wallet Demo