Hg Best API Developer Portal

Developer Dashboard

Welcome, !

Your Plan & Billing

Your API Keys

API Usage

Test Your API

Streamline Integration with Our SDK!

Our Software Development Kit (SDK) is designed to simplify your integration with the Hg Best API. It handles complex tasks like HMAC-SHA256 request signing, error parsing, and provides intuitive, type-safe methods for interacting with our powerful analytical endpoints. This allows you to focus on building your application's core features rather than the intricacies of API communication.

The examples below focus on Node.js/JavaScript/TypeScript environments, as this is the primary ecosystem currently supported by our official SDK. We are actively working on expanding official SDK support to a wider array of languages and platforms in the future.

Installation (Node.js Environments)

Install the SDK in your Node.js project using your preferred package manager:

# Using npm
npm install @hgbest/api-sdk

# Using pnpm
pnpm install @hgbest/api-sdk

# Using yarn
yarn add @hgbest/api-sdk

Getting Started with the SDK (Node.js/TypeScript/JavaScript)

Initialize the SDK with your generated API Key and API Secret. For optimal security, always load your API Secret from secure environment variables in a server-side environment. Never expose your API Secret in client-side (browser) code.

// For TypeScript or modern JavaScript environments
import { HgBestClient } from '@hgbest/api-sdk';

// Initialize the client with your credentials
// These credentials should be loaded from secure environment variables in your backend.
const client = new HgBestClient({
  apiKey: process.env.HB_API_KEY || "pk-YOUR_API_KEY_HERE",           // Get this from your Dashboard
  apiSecret: process.env.HB_API_SECRET || "sk-YOUR_API_SECRET_HERE"   // Store securely as environment variable!
});

// --- Example: Global Supply Chain Alert ---
async function getRiskAlert() {
  try {
    console.log("Fetching Global Supply Chain Alert...");
    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 Alert Score:", response.risk_alert.risk_score_10);
    console.log("Recommendation:", response.risk_alert.immediate_recommendation);
  } catch (error) {
    console.error("Failed to get risk alert:", error);
  }
}
getRiskAlert(); // Call the function

// --- Example: Predictive Patient Summary ---
async function getPatientSummary() {
  try {
    console.log("Fetching Predictive Patient Summary...");
    const response = await client.health.predictivePatientSummary({
      patient_id: "PAT987654",
      unstructured_notes: [
        "Patient complains of persistent dry cough for 2 weeks, mild shortness of breath, and recent weight loss. Smokes 1 pack/day. Family history of lung cancer.",
        "Follow-up: No fever, slight wheezing noted on auscultation. CXR ordered."
      ]
    });
    console.log("Patient ID:", response.patient_id);
    console.log("Priority Risk:", response.priority_risk_areas[0].recommended_action);
  } catch (error) {
    console.error("Failed to get patient summary:", error);
  }
}
getPatientSummary(); // Call the function

// --- Example: Macro Sentiment Score ---
async function getMacroSentiment() {
  try {
    console.log("Fetching Macro Sentiment Score...");
    const response = await client.finance.macroSentimentScore({
      market_focus: "AI Hardware Sector",
      regulatory_filings_keywords: ["chip manufacturing", "antitrust investigation"],
      news_keywords: ["AI boom", "global chip shortage", "semiconductor tariffs"]
    });
    console.log("Overall Risk Signal:", response.overall_risk_signal);
    console.log("Key Insight:", response.impact_prediction.key_insight);
  } catch (error) {
    console.error("Failed to get macro sentiment score:", error);
  }
}
getMacroSentiment(); // Call the function

// --- Example: Algorithmic Divergence Signal (Stock/Crypto) ---
async function getDivergenceSignal() {
  try {
    console.log("Fetching Algorithmic Divergence Signal...");
    const response = await client.market.algorithmicDivergenceSignal({
      asset_ticker: "ETH",
      additional_context: "Upcoming Ethereum upgrade, increasing DeFi activity, recent exchange hacks."
    });
    console.log("Asset:", response.asset_ticker);
    console.log("Divergence Score:", response.divergence_score_percent + "%");
    console.log("Directional Bias:", response.directional_bias);
  } catch (error) {
    console.error("Failed to get divergence signal:", error);
  }
}
getDivergenceSignal(); // Call the function

The SDK handles all the underlying authentication magic, including HMAC-SHA256 request signing, ensuring your interactions with the Hg Best API are secure and valid. It also provides robust error handling, allowing you to focus on your application's core logic.

Integration with Other Languages (Manual Approach)

Our API is built on standard HTTP protocols, making it accessible from virtually any programming language. If an official SDK is not yet available for your preferred language, you can still integrate by manually constructing HTTP requests and implementing the HMAC-SHA256 authentication:

The core steps are:

1. Generate a valid JWT (JSON Web Token) or API Key/Secret pair from your Hg Best API dashboard.
2. Construct the HTTP request (method, path, headers, body).
3. Generate a Unix timestamp (milliseconds since epoch).
4. Compute the SHA256 hash of the request body (if present).
5. Form the "String to Sign" (as detailed in the Authentication section above).
6. Compute the HMAC-SHA256 signature of the "String to Sign" using your API Secret.
7. Add the `X-API-KEY`, `X-API-TIMESTAMP`, and `X-API-SIGNATURE` headers to your HTTP request.
8. Send the request to the API endpoint.

Refer to the Authentication: The Two-Key System section above for detailed specifications on manual signing. We encourage community contributions for SDKs in other languages!

For more advanced usage, configuration options, and additional language support, please refer to the dedicated SDK documentation (coming soon!).

Comprehensive API Reference

Welcome to the Hg Best API documentation! Here you'll find everything you need to integrate our cutting-edge analytical power into your applications. Our API provides specialized, high-value data analysis functions to empower your decision-making and enhance your custom business solutions.

Authentication: The Two-Key System

We employ a robust, two-key authentication system to ensure the security and integrity of your API calls:

• API Key (Public Identifier): A unique string (e.g., pk-xxxx...) that identifies your application. It's sent in the X-API-KEY header.
• API Secret (Private Credential): A highly sensitive string (e.g., sk-yyyy...) used to cryptographically sign your requests. It must be kept absolutely confidential and never exposed in client-side code.

How to Authenticate (Manual Signing):

If you're not using our SDK, you'll need to manually sign each request using the HMAC-SHA256 algorithm.

1. Construct the String to Sign: Concatenate the following elements, separated by newline characters (\n):

   HTTP_METHOD (e.g., "POST")
   PATH (e.g., "/risk/global-supply-chain-alert")
   TIMESTAMP (Unix milliseconds as string, e.g., "1709280000000")
   BODY_HASH (SHA256 hash of the request body, hex encoded. Empty string if no body.)

2. Compute the HMAC-SHA256 Signature: Use your API Secret as the key for HMAC-SHA256 hashing of the "String to Sign". Encode the result in hexadecimal.
3. Add Headers to Request:
   • X-API-KEY: [Your API Key]
   • X-API-TIMESTAMP: [Timestamp used in signing]
   • X-API-SIGNATURE: [Generated HMAC-SHA256 Signature]
   • Content-Type: application/json (for POST/PUT requests)

Security Best Practice: Always perform request signing on your secure backend server. Never expose your API Secret in frontend code, mobile apps, or publicly accessible repositories.

Base URL

All API requests should be sent to: https://hgbest-backend.onrender.com

Error Handling

Our API uses standard HTTP status codes to indicate the success or failure of a request. In case of an error (4xx or 5xx status codes), the response body will typically contain a JSON object with more details, including a custom error code and message.

{
  "error": {
    "message": "Detailed error description.",
    "code": "CUSTOM_ERROR_CODE"
  }
}

• 200 OK: The request was successful, and the response body contains the requested data.
• 400 Bad Request: The request was malformed or missing required parameters. The message will provide specific details, e.g., "Missing required parameters: asset_ticker."
• 401 Unauthorized: Authentication failed due to missing or invalid authentication credentials (e.g., missing X-API-KEY, invalid timestamp, or expired authentication token for generating an API key).
• 403 Forbidden: The server understood the request but refuses to authorize it. This could be due to an invalid API Key, a signature mismatch, a disabled API key, or insufficient permissions. The message will specify the exact reason.
• 429 Too Many Requests: The client has sent too many requests in a given amount of time. This usually indicates an exceeded usage limit for your API key.
• 500 Internal Server Error: An unexpected error occurred on the server. This could be due to issues with the underlying analytical engine or other backend components.

Endpoints Overview

To maximize the accuracy and depth of the analytical results, we encourage developers to provide as much relevant detail as possible within the request parameters for each endpoint.

1. POST /risk/global-supply-chain-alert

Proactively identifies obscure, non-obvious global risks impacting specific materials or logistics routes. Utilizes advanced analytical models to predict potential disruptions and provides actionable recommendations to mitigate impacts.

Request Body

The request body should be a JSON object with the following fields:

• material_type (string, **required**): The specific material to analyze (e.g., "Lithium-ion batteries", "rare earth minerals").
• region_of_origin (string, **required**): The geographical origin of the material (e.g., "Global", "Central Africa", "Southeast Asia").
• logistics_route (string, **required**): The primary transportation route for the material (e.g., "Asia to Europe via Suez Canal", "Africa to Asia via maritime").

Request Body Example (JSON):

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

Response Body

A JSON object containing the risk assessment:

• request_id (string): A unique identifier for this risk assessment request.
• risk_alert (object): Contains detailed risk information.
  • risk_score_10 (number): A quantifiable risk score between 0 and 10, indicating severity.
  • event_type (string): The category of the potential risk (e.g., "Geopolitical / Conflict", "Labor Dispute", "Environmental Disaster").
  • anticipated_delay_days (string): Estimated delay duration (e.g., "30-45 days", "10-14 days").
  • summary (string): A concise overview of the identified risk.
  • immediate_recommendation (string): A key actionable insight to mitigate the risk.

Response Body Example (JSON):

{
  "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 high naval presence and heightened long-term risk aversion in the Red Sea and Gulf of Aden are driving sustained rerouting of commercial vessels, including those carrying lithium-ion batteries, around the Cape of Good Hope.",
    "immediate_recommendation": "Develop a multi-modal logistics strategy incorporating both Suez Canal and Cape of Good Hope routes."
  }
}

2. POST /health/predictive-patient-summary

Synthesizes extensive unstructured medical notes into a prioritized list of predictive health risks and differential diagnoses. This powerful tool aims to reduce diagnostic errors and guides immediate, actionable testing or intervention recommendations.

Request Body

The request body should be a JSON object with the following fields:

• patient_id (string, **required**): A unique identifier for the patient.
• unstructured_notes (array of strings, **required**): A list of free-form medical notes, symptoms, travel history, family history, and other relevant observations.

Request Body Example (JSON):

{
  "patient_id": "PAT789012",
  "unstructured_notes": [
    "Patient presents with persistent cough for 3 weeks, mild fever (100.5F), and general fatigue. Recent travel history includes Southeast Asia. Family history of respiratory issues. Smoker for 10 years."
  ]
}

Response Body

A JSON object containing the predictive patient summary:

• patient_id (string): The unique identifier for the patient.
• summary_date (string): ISO 8601 formatted datetime of when the summary was generated.
• priority_risk_areas (array of objects): A prioritized list of identified health risks.
  • category (string): The medical category of the risk (e.g., "Infectious Disease", "Cardiovascular").
  • risk_level (string): The assessed risk level ("High", "Medium", "Low").
  • recommended_action (string): The single most important actionable testing or intervention recommendation.
• concerns_noted (array of strings): A list of key concerns extracted from the unstructured notes.

Response Body Example (JSON):

{
  "patient_id": "PAT789012",
  "summary_date": "2024-03-01T10:30:00Z",
  "priority_risk_areas": [
    {
      "category": "Infectious Disease",
      "risk_level": "High",
      "recommended_action": "Order immediate Chest X-Ray and full infectious disease panel (PCR for TB, fungal, atypical pneumonia)."
    }
  ],
  "concerns_noted": ["persistent cough", "fever", "fatigue", "chest pain", "smoking history"]
}

3. POST /finance/macro-sentiment-score

Provides a complex market impact signal by synthesizing diverse data streams including market chatter, regulatory filings, and historical data correlations. Delivers a quantifiable Portfolio Impact Signal rather than just a basic sentiment score, aiding in high-frequency trading decisions.

Request Body

The request body should be a JSON object with the following fields:

• market_focus (string, **required**): The specific market sector or asset class to focus on (e.g., "Tech sector", "Emerging Markets").
• regulatory_filings_keywords (array of strings, **required**): Keywords to search for in regulatory filings to inform sentiment (e.g., ["SEC filing ABC", "Antitrust investigation"]).
• news_keywords (array of strings, **required**): Keywords to search for in recent news and market chatter (e.g., ["AI regulation", "semiconductor shortage"]).

Request Body Example (JSON):

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

Response Body

A JSON object containing the macro-sentiment score and associated signals:

• signal_id (string): A unique identifier for this financial signal.
• overall_risk_signal (string): An overall assessment of market risk (e.g., "Caution - Moderate Volatility Expected").
• impact_prediction (object): Predicted market impact details.
  • score_0_100 (number): A predictive impact score between 0 and 100.
  • volatility_index_change (string): Predicted change in volatility (e.g., "+1.8%", "-0.5%").
  • key_insight (string): A concise insight explaining the prediction.
• sector_exposure (array of objects): Details on sector-specific exposure levels and sentiment deltas.
  • sector (string): The sector analyzed.
  • exposure_level (string): The assessed exposure level ("HIGH", "MEDIUM", "LOW").
  • sentiment_delta (number): Change in sentiment for the sector (e.g., -0.92, +1.5).

Response Body Example (JSON):

{
  "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": "Anticipated regulatory changes in tech sector combined with supply chain bottlenecks driving market uncertainty."
  },
  "sector_exposure": [
    {
      "sector": "Technology",
      "exposure_level": "HIGH",
      "sentiment_delta": -0.92
    }
  ]
}

4. POST /market/algorithmic-divergence-signal

Identifies when disparate data streams (e.g., social sentiment, macro-economic indicators, on-chain analytics for crypto, supply chain for stocks) are diverging from the current asset price. This signals a high probability of an unexpected, strong price movement (volatility) for stocks or crypto assets, providing valuable insights for algorithmic trading strategies.

Request Body

The request body should be a JSON object with the following fields:

• asset_ticker (string, **required**): The ticker symbol for the asset (e.g., "BTC", "AAPL").
• additional_context (string, optional): Any extra context or specific news events to consider in the analysis.

Request Body Example (JSON):

{
  "asset_ticker": "BTC",
  "additional_context": "Recent regulatory comments from SEC, increasing institutional adoption, declining mining difficulty."
}

Response Body

A JSON object containing the algorithmic divergence signal:

• asset_ticker (string): The ticker symbol of the analyzed asset.
• divergence_score_percent (number): A score (0-100) indicating the strength of the divergence signal.
• directional_bias (string): The predicted direction of the price movement ("Uptrend Probability", "Downtrend Probability", "High Volatility Sideways").
• top_causal_factor (string): The most significant factor contributing to the divergence.
• predictive_factors (array of objects): Detailed factors contributing to the signal.
  • name (string): The name of the predictive factor (e.g., "Social Sentiment (Weighted)").
  • value (string): The value or magnitude of the factor.
  • description (string): A brief explanation of the factor's influence.
• advice (string): Actionable insights or trading strategy suggestions derived from the analysis. This is an AI-generated insight for the developer's application.

Response Body Example (JSON):

{
  "asset_ticker": "BTC",
  "divergence_score_percent": 85,
  "directional_bias": "Uptrend Probability",
  "top_causal_factor": "Growing institutional capital inflows amidst stable on-chain metrics.",
  "predictive_factors": [
    {
      "name": "Social Sentiment (Weighted)",
      "value": "0.88",
      "description": "Significant increase in positive sentiment across major crypto social channels."
    },
    {
      "name": "On-chain Whale Accumulation",
      "value": "High",
      "description": "Large wallets showing consistent accumulation patterns over the last 72 hours."
    }
  ],
  "advice": "Monitor for volume confirmation on breakout above $70,000. Set stop-loss at $68,500. Consider long positions with strong risk management."
}

Legal & Policies

Before integrating with the Hg Best API, please review our comprehensive policies governing API usage, data handling, and developer responsibilities.

• Terms of Service: Outlines the legal agreement for using our API, including acceptable use, limitations, and your responsibilities.
• Privacy Policy: Explains how we collect, use, and protect data, including any data processed through API calls.

Need Assistance? Join Our Vibrant Community!

Facing difficulties, have questions about integration, or need further assistance? Our support team is here to help you get the most out of the Hg Best API. We believe in building a strong developer community!

• Email Support: etshaven@gmail.com
• WhatsApp Support: Chat on WhatsApp

We aim to respond to all inquiries within 24 business hours.