Hego Buyer API

Critical Security Warning

Never share your API key. Anyone who has it has full access to spend your Hego wallet balance. Do not expose it in frontends, query strings, or public repositories. Use protected environment variables.

Base URL & Authentication

https://api.hegodigitaldev.com/api/v1/buyer

All requests (except /health) require your API key in the headers:

X-API-Key: hg_live_...
// Alternatively supported:
Authorization: Bearer hg_live_...

Operational Services

GET /health

Public service health and operational status.

GET /products

Complete catalog with descriptions, current prices, and instructions.

GET /balance

Check the available USDT balance in your wallet.

POST /orders

Create a new purchase order, reserve stock, and deduct balance atomically.

GET /orders/{id}

Check order status. Returns delivery credentials if completed.

GET /orders/{id}/download

Get a secure download link for file-type products.

GET /webhook

Check your current asynchronous notification configuration.

POST /webhook

Strict Purchase Rules

To protect your funds, the POST /orders endpoint is highly strict:

Idempotency-Key: Every POST request must send this header. If your system loses connection during the call, retry with the same key. You'll avoid paying twice for the same order.
Price Protection (expectedPriceUsdt): You must report the price at which you plan to buy. If the product cost varied since your last catalog sync, the order is rejected (409 PRICE_CHANGED) without charges.
Integral Stock: There are no partial deliveries. If you request 5 units and there are only 4, the entire order is rejected.
Telegram Recipient: If the top-up product requires a user, the recipientUsername field must strictly start with an @.

Content Delivery

Hego's architecture processes some providers immediately and others through asynchronous delegation:

Immediate Products (Local Stock/B2B): When calling POST /orders, the response will contain a completed status and the array of items (credentials, links, pins) in the delivery.items field.
Asynchronous Products (External Providers): The returned status will be pending_delivery. You must listen to the order.completed webhook event or poll GET /orders/{id} to obtain the final content.
Binary Files (file): Files NEVER travel embedded via JSON. The API will return an authenticated downloadUrl. By making a GET to this URL, you'll obtain the original pure binary file.

Webhooks and Retries

Your integration must be reactive

Prices, stock, and descriptions change in real-time. Subscribe to catalog events to update your frontend or internal databases before attempting to sell a product.

Subscribe with POST /webhook. Hego will dispatch a POST payload to your URL cryptographically signed (HMAC-SHA256) in the X-Hego-Signature header.

Supported Events

catalog.updated: A product has changed price, name, status (active/inactive) or description.
stock.changed: A product's inventory has varied (restock, consumption, withdrawal).
order.completed: An asynchronous order was delivered. (The webhook notifies the status, you must then GET to read the items).
order.failed: An asynchronous order failed and the money has been refunded intact to your balance.
balance.low: Your USDT wallet balance has dropped below your balanceThresholdUsdt.

Fault Tolerance

If your server does not respond with a 2xx status to our webhook, we make up to 5 attempts in total (immediate, 1m, 5m, 30m, 6h). Use the delivery ID or order status to deduplicate events processed in your backend.

The signed body includes type (the event) and eventId next to the event data. catalog.updated and stock.changed may group several products into one delivery: use productIds (and productId for the latest). We do not follow redirects (3xx counts as a failure), only public https URLs on ports 443 or 8443 are accepted, and delivery history is kept for a few days.

Error Handling

All 4xx and 5xx errors return a JSON object with the status code, an error code (error), a descriptive message, and a unique requestId for tracking.

Operational Note: Any 400, 401, or 429 error will trigger an automatic internal alert to the Hego developer team with your requestId to proactively diagnose your integration.

HTTP Code	Primary Cause
400 Bad Request	Invalid payload, missing `productId` or wrong recipient format.
401 Unauthorized	Invalid, revoked, or missing API key in the headers.
409 Conflict	Conflict: `expectedPriceUsdt` does not match the real one (PRICE_CHANGED) or Idempotency-Key collision.
429 Too Many Requests	Rate Limit exceeded or halted by the preventive low balance protection limit.
500 Server Error	Internal platform crash or database connectivity down.

What is openapi.yaml for?

The OpenAPI standard (formerly known as Swagger) programmatically describes all our routes, schemas, examples, and parameters. It saves you days of work:

Code Generation: Use tools like openapi-generator to compile the entire client for our API in Node.js, Python, PHP, or Go with a single command.
Postman / Insomnia: Import the openapi.yaml file into Postman and you'll have the entire endpoints collection preconfigured and ready to launch requests.

Download openapi.yaml