Installation

Node.js

# npm
npm install @hgbest/api-sdk

# pnpm
pnpm install @hgbest/api-sdk

# yarn
yarn add @hgbest/api-sdk

Python

pip install hgbest-client-python

C# (.NET)

# .NET CLI
dotnet add package HgBestClient.CSharp

# NuGet Package Manager
Install-Package HgBestClient.CSharp

Getting Started

Initialize with your API Key and Secret. Always load credentials from environment variables — never hardcode secrets in client-side code.

Node.js / TypeScript/Javascript

import { HgBestClient } from '@hgbest/api-sdk';

const client = new HgBestClient({
  apiKey:    process.env.HB_API_KEY    || "pk-YOUR_API_KEY_HERE",
  apiSecret: process.env.HB_API_SECRET || "sk-YOUR_API_SECRET_HERE"
});

async function getRiskAlert() {
  const response = await client.risk.globalSupplyChainAlert({
    material_type:    "Lithium-ion batteries",
    region_of_origin: "Global",
    logistics_route:  "Asia to Europe via Suez Canal"
  });
  console.log("Risk Score:", response.risk_alert.risk_score_10);
}
getRiskAlert();

Python

from hgbest_client import HgBestClientPython

client = HgBestClientPython(
    api_key="pk-YOUR_API_KEY_HERE",
    api_secret="sk-YOUR_API_SECRET_HERE"
)

report_payload = {
    "summaryDate": "2025-12-17",
    "requestId":   "unique-report-12345",
    "riskScore":   75,
    "eventType":   "LogisticsAnomaly",
    "summary":     "Unexpected weather impacting East Coast shipping lanes."
}
response = client.health.submit_report(report_payload)
print(response)

C# (.NET)

using HgBestClient.CSharp;

var client = new HgBestClientCSharp(
    apiKey:    "pk-YOUR_API_KEY_HERE",
    apiSecret: "sk-YOUR_API_SECRET_HERE"
);

var riskPayload = new {
    material_type    = "Semiconductors",
    region_of_origin = "Southeast Asia",
    logistics_route  = "Pacific Ocean to West Coast US"
};
dynamic result = await client.Risk.GlobalSupplyChainAlert(riskPayload);
Console.WriteLine(result);

Manual Integration (Any Language)

The API uses standard HTTP — implement HMAC-SHA256 authentication manually in any language.

1. Generate your API Key/Secret from the Dashboard.
2. Get the current Unix timestamp in milliseconds.
3. Compute SHA256 of the request body (compact JSON, keys sorted alphabetically). Use "" for empty body.
4. Build the string to sign:

   HTTP_METHOD\n
   PATH\n
   TIMESTAMP\n
   BODY_HASH

5. HMAC-SHA256 sign it using your API Secret. Hex-encode the result.
6. Send these headers:

   X-API-KEY:       [Your API Key]
   X-API-TIMESTAMP: [Timestamp]
   X-API-SIGNATURE: [Signature]
   Content-Type:    application/json

Authentication — The Two-Key System

Error Codes

Performance & Timeouts

AI-powered endpoints may take longer due to complex model reasoning and internal retry logic with exponential backoff.

Endpoints

{
  "material_type":    "Lithium-ion batteries",
  "region_of_origin": "Global",
  "logistics_route":  "Asia to Europe via Suez Canal"
}

{
  "request_id": "risk-alert-abc-123",
  "risk_alert": {
    "risk_score_10":          7.5,
    "event_type":             "Geopolitical / Logistical Disruption",
    "anticipated_delay_days": "10-14 days",
    "summary":                "Persistent rerouting via Cape of Good Hope…",
    "immediate_recommendation": "Develop multi-modal logistics strategy."
  }
}

{
  "patient_id": "PAT789012",
  "unstructured_notes": [
    "Persistent cough 3 weeks, mild fever (100.5F), fatigue. Travel: SE Asia."
  ]
}

{
  "patient_id":   "PAT789012",
  "summary_date": "2024-03-01T10:30:00Z",
  "priority_risk_areas": [{
    "category":           "Infectious Disease",
    "risk_level":         "High",
    "recommended_action": "Order Chest X-Ray and full infectious disease panel."
  }],
  "concerns_noted": ["persistent cough", "fever", "smoking history"]
}

{
  "market_focus":                 "Tech sector",
  "regulatory_filings_keywords":  ["SEC filing ABC"],
  "news_keywords":                ["AI regulation", "semiconductor shortage"]
}

{
  "signal_id":           "finance-signal-def-456",
  "overall_risk_signal": "Caution - Moderate Volatility Expected",
  "impact_prediction": {
    "score_0_100":            65,
    "volatility_index_change": "+1.8%",
    "key_insight":            "Regulatory uncertainty driving market volatility."
  },
  "sector_exposure": [{
    "sector":          "Technology",
    "exposure_level":  "HIGH",
    "sentiment_delta": -0.92
  }]
}

{
  "asset_ticker":      "BTC",
  "additional_context": "Recent SEC comments, institutional adoption rising."
}

{
  "asset_ticker":            "BTC",
  "divergence_score_percent": 85,
  "directional_bias":        "Uptrend Probability",
  "top_causal_factor":       "Growing institutional capital inflows.",
  "predictive_factors": [{
    "name":        "Social Sentiment (Weighted)",
    "value":       "0.88",
    "description": "Significant positive sentiment across crypto channels."
  }],
  "advice": "Monitor for volume confirmation above $70,000."
}

Legal & Policies

Support & Community

Facing difficulties or need integration help? Our team responds within 24 business hours.