@homelotto168/lotto-agent-sdk

Node client for the Home168 Lotto Feed API. Pull Khong's winning numbers and blocked numbers, report your sales, verify webhook signatures.

Requires Node 18+.

Install

npm i @homelotto168/lotto-agent-sdk

Quick start

import { LottoAgent } from '@homelotto168/lotto-agent-sdk';

const agent = new LottoAgent({ apiKey: process.env.LOTTO_API_KEY! });

// Sanity-check your key
const me = await agent.ping();
console.log('allowed templates:', me.allowed_templates);

// Pull winning numbers for a template
const results = await agent.results({ template: 'khong-gov', from: '2026-04-01' });
for (const r of results.results) {
  console.log(r.close, r.top, r.bottom);
}

// Pull blocked numbers
const blocked = await agent.blocked({ template: 'khong-gov' });
console.log('ignore_2:', blocked.ignore_2);

// Report your sales for one round (idempotent on round_date + round_seq)
await agent.reportSale({
  templateSlug: 'khong-gov',
  roundDate: '2026-04-22',
  roundSeq: 1,
  handle: 125_000,
  payout: 82_500,
  betCount: 147,
  agentRoundId: 'my-round-abc',
});

Webhook signatures

When we push you an event (result.announced, blocked.updated), we sign the body with your webhook secret using HMAC-SHA256. Verify on the receiving side:

import express from 'express';
import { LottoAgent } from '@homelotto168/lotto-agent-sdk';

app.post('/webhooks/home168', express.text({ type: '*/*' }), (req, res) => {
  const ok = LottoAgent.verifyWebhook(
    req.body,                          // raw string body
    req.headers['x-h168-signature'] as string,
    process.env.H168_WEBHOOK_SECRET!,
  );
  if (!ok) return res.status(401).end();

  const payload = JSON.parse(req.body);
  // payload.event, payload.timestamp, payload.data
  res.status(204).end();
});

Retries, timeouts, errors

The client retries 429 and 5xx responses up to maxRetries (default 3) with exponential backoff. 4xx responses are thrown as LottoApiError:

import { LottoApiError } from '@homelotto168/lotto-agent-sdk';

try {
  await agent.reportSale(/* ... */);
} catch (err) {
  if (err instanceof LottoApiError && err.status === 409) {
    // Round already reported with different values. Contact admin for adjustment.
  }
  throw err;
}

Sandbox mode

Ask your Home168 rep to flag your agent account as sandbox_mode. Rollups you post are accepted but excluded from weekly billing. Flip to live when you're confident.