API documentation

API

Public endpoints for third-party apps and websites. V1 is free and does not require an API key. Limits apply to keep the service fair for everyone.

Base URL

https://hunterscures.com/api/v1/

Authentication

V1 price: none — open to anyone.
Payments: API key from Merchant tools (Authorization: Bearer hk_live_…).

Rate limits

Price endpoint: 60 requests per minute per IP.
Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. When exceeded you receive HTTP 429 with a JSON error body. Polling every 30–60 seconds is recommended for live UIs.

Endpoints

GET /api/v1/price Available

Current coffee / HCT reference price in UGX per kg. Optional query ?pretty=1 for indented JSON in the browser.

Example response

{
  "ok": true,
  "api": "hunters-public-v1",
  "endpoint": "price",
  "symbol": "HCT",
  "name": "Hunters Cure Token",
  "unit": "UGX per kg",
  "currency": "UGX",
  "price": "7.78000000",
  "price_display": "UGX 7.78",
  "as_of": "2026-10-14T03:50:00+00:00",
  "change_24h_pct": 1.25,
  "docs": "https://hunterscures.com/api-docs",
  "rate_limit": { "limit_per_minute": 60, "remaining": 59, "reset_at": 1760418660 }
}

GET /api/v1/… Soon publishing

Historical series, market volume, and authenticated developer endpoints will be listed here when published.

Integration examples

Copy, adapt, and poll on a sensible interval (e.g. once per minute).

cURL

curl -s "https://hunterscures.com/api/v1/price"

JavaScript (fetch)

async function getHuntersPrice() {
  const res = await fetch("https://hunterscures.com/api/v1/price");
  if (!res.ok) throw new Error("HTTP " + res.status);
  const data = await res.json();
  if (!data.ok) throw new Error(data.message || data.error);
  return data; // data.price, data.unit, data.as_of
}

getHuntersPrice().then(d => console.log(d.price_display));

PHP

$url = "https://hunterscures.com/api/v1/price";
$json = file_get_contents($url);
$data = json_decode($json, true);
if (!empty($data["ok"])) {
    echo $data["price_display"]; // e.g. UGX 7.78
}

Python

import urllib.request, json

url = "https://hunterscures.com/api/v1/price"
with urllib.request.urlopen(url) as r:
    data = json.loads(r.read().decode())
if data.get("ok"):
    print(data["price"], data["unit"])

Node.js

const url = "https://hunterscures.com/api/v1/price";
const data = await (await fetch(url)).json();
if (data.ok) console.log(data.price_display);

CORS

Browser apps can call the price endpoint directly — Access-Control-Allow-Origin: * is enabled for GET (and OPTIONS preflight).

Merchant

Payments API (API key)

Let customers pay you in HCT from their HUNTERS wallet. You create a payment intent; we return a link and QR payload. When they pay, tokens move into your trading balance. Use this for checkouts, invoices, or top-ups on your own site.

1. Get an API key

Log in → Settings → Merchant & payments → create an app. The key is shown once (hk_live_…). Send it as Authorization: Bearer YOUR_KEY or header X-Api-Key.

2. Create a payment

POST https://hunterscures.com/api/v1/payments

{
  "amount_tokens": "10.5",
  "merchant_fee_pct": "2.5",
  "description": "Order #4821",
  "return_url": "https://yoursite.com/order/4821/done",
  "webhook_url": "https://yoursite.com/hooks/hunters",
  "metadata": { "order_id": "4821" },
  "expires_minutes": 60
}

Or pass amount_ugx instead of tokens. Optional merchant markup (you keep it): merchant_fee_tokens, merchant_fee_ugx, or merchant_fee_pct (0–100). Aliases: fee_tokens, fee_ugx, fee_pct.

Fees: Merchant fee → merchant wallet. Platform send fee (from HUNTERS settings) → charged to the payer on top and goes to HUNTERS. Response includes total_to_merchant, platform_fee_tokens, and total_payer_pays.

Response

{
  "ok": true,
  "reference": "PAYA1B2C3D4E5F678",
  "payment_url": "https://hunterscures.com/pay/PAYA1B2C3D4E5F678",
  "qr_payload": "https://hunterscures.com/pay/PAYA1B2C3D4E5F678",
  "amount_tokens": "10.500000000000000000",
  "status": "pending"
}

Show payment_url in a browser button or encode qr_payload as a QR code on your checkout page.

3. Check status

GET /api/v1/payments?ref=PAY… with the same API key. Status: pending · paid · expired · cancelled.

4. Customer experience

Customer opens the link → logs into HUNTERS → Pay with my wallet. HCT leaves their trading balance and arrives in yours (same as an internal transfer). They can also paste the PAY… reference in the wallet Transfer sheet.

PHP example

$ch = curl_init("https://hunterscures.com/api/v1/payments");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_API_KEY",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "amount_ugx" => "5000",
    "description" => "Order 4821",
    "return_url" => "https://yoursite.com/thanks",
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
// $data["payment_url"] → show to customer

JavaScript (Node)

const res = await fetch("https://hunterscures.com/api/v1/payments", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount_tokens: "12.5", description: "Pro plan" }),
});
const data = await res.json();
console.log(data.payment_url);

Security notes

Never expose the API key in front-end browser code — create payments from your server. Verify status with the API or webhook before fulfilling goods. Rate limit: ~120 requests/minute per app.

Fair use

Do not scrape or flood the endpoint. Cache responses for at least 15–30 seconds on your side. Abuse may lead to tighter limits or IP blocks. For higher volume, contact us for future authenticated plans.