@justgold/partner-sdk

Official SDK for authenticating requests to the JustGold API. Provides HMAC-SHA256 request signing and verification with no dependencies.

Installation

npm install @justgold/partner-sdk

or

yarn add @justgold/partner-sdk

Requirements

• Node.js >= 18

Quick Start

import { signRequest } from '@justgold/partner-sdk';

const headers = signRequest({
  method: 'POST',
  path: '/v1/orders',
  body: JSON.stringify({ amount: 100 }),
  clientId: 'YOUR_CLIENT_ID',
  secret: 'YOUR_CLIENT_SECRET',
});

// Attach the returned headers to your HTTP request
fetch('https://api.justgold.me/v1/orders', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    ...headers,
  },
  body: JSON.stringify({ amount: 100 }),
});

Signing Algorithm

Every request must be signed using HMAC-SHA256. This section documents the algorithm so you can implement it in any language.

Required Headers

| Header | Description | |---------------|--------------------------------------------------| | x-client-id | Your client ID, provided by JustGold | | x-timestamp | Unix timestamp (seconds) at time of request | | x-signature | HMAC-SHA256 hex signature of the string to sign |

String to Sign

Construct the string to sign by joining the following fields with a newline character (\n):

METHOD\n
PATH\n
SORTED_QUERY_STRING\n
BODY_HASH\n
TIMESTAMP

| Field | Description | |----------------------|-----------------------------------------------------------------------------| | METHOD | HTTP method in uppercase, e.g. GET, POST | | PATH | Request path without query string, e.g. /v1/orders | | SORTED_QUERY_STRING| Query parameters sorted alphabetically by key, joined with &, e.g. page=1&sort=asc. Empty string if no query params. | | BODY_HASH | SHA-256 hex digest of the raw request body. Use SHA-256 of an empty string if no body. | | TIMESTAMP | The same Unix timestamp sent in x-timestamp |

Generating the Signature

signature = HMAC-SHA256(secret, stringToSign)
           |> hex encode

Timestamp Tolerance

The server rejects requests where the x-timestamp differs from the server's current time by more than 300 seconds (5 minutes). Always use a fresh timestamp per request.