Data source interface (GFI)
GFI (Game Feed Interface) v1 is the only game-data format the platform understands, and the standard entry point for data sources. Any system that produces live baccarat, dragon tiger or Niu Niu rounds — an official provider, a live studio's dealer or data-entry system, a relay, a computer-vision system — pushes events such as "betting open", "betting closed", "card dealt", "result", "correction" and "void" to the platform in GFI.
Who this chapter is for
This chapter is for data-source developers. If you are an operator integrating the game into your site, start with the quick start.
- Source: a data provider registered with the platform and holding credentials, identified by
sourceId(starts with a lower-case letter; 2–32 lower-case letters, digits,_or-, for exampleacme-live). Source IDs and keys are created by the platform; ask the platform for one. - Source table: a table ID in the source's own namespace, for example
B001([A-Za-z0-9_.:-], up to 64 characters). The platform binds it to a public table. - Stream: the event sequence of one
(sourceId, source table). Ordering, de-duplication and resume all work per stream. - The single source of truth is the JSON Schema (2020-12) plus this chapter. The GFI event validator checks events in your browser.
Transport
The event format is identical on all three transports:
| Transport | Endpoint | Use |
|---|---|---|
| WebSocket (recommended) | wss://{ingest-host}/ingest/v1/stream | Always-on sources; lowest latency |
| HTTPS batches | POST https://{ingest-host}/ingest/v1/events | Sources that cannot keep a connection, or for resending |
| Service Binding | platform-internal | Only for Workers on the platform's own Cloudflare account |
{ingest-host} is a dedicated host name:
| Environment | Host |
|---|---|
| Production | elite-ingest.ewin888.com |
| Test | elite-dev-ingest.ewin888.com |
Other HTTPS endpoints:
| Method and path | Purpose | Response |
|---|---|---|
POST /ingest/v1/events | Send a batch of events, body {"events": [...]} | {"acks": {...}, "nacks": [...], "resync": [...]} |
POST /ingest/v1/validate | Dry run: the same checks as events, but nothing is stored or applied | Same |
GET /ingest/v1/resume?tables=B001,B002 | The last acknowledged seq of each stream | {"resume": {"B001": 1530, "B002": 0}} |
POST /ingest/v1/heartbeat | Heartbeat (HTTPS sources), body {"ts": "…", "tables": {"B001": "ok"}} | {"ok": true, "serverTime": "…"} |
The platform decides which transports each source may use; using another one returns 403.
Authentication
Every HTTPS request and WebSocket handshake carries these headers. The signing rule is the same as for the tenant API:
X-Source-Id: <sourceId>
X-Timestamp: <Unix seconds> within 300 seconds of platform time
X-Nonce: <16–64 letters and digits> must not repeat within 10 minutes
X-Signature: hex( HMAC-SHA256( secret,
METHOD + "\n" + PATH + "\n" + X-Timestamp + "\n" + X-Nonce + "\n" + hex(SHA-256(body)) ) )PATHis the path plus the query string, for example/ingest/v1/resume?tables=B001,B002.- For the WebSocket handshake
METHODisGETand the body is the empty string. - Optional hardening: an IP allowlist on the source IP.
- Error responses look like
{"code": "…", "message": "…"}:
| HTTP | code | Cause |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or malformed auth headers, unknown source, bad signature, outside the time window, nonce reused |
| 403 | SOURCE_DISABLED | The source is disabled |
| 403 | UNAUTHORIZED | That transport is not enabled for the source, or the source IP is not allowed |
| 400 | INVALID_EVENT | The body is not JSON |
| 404 | NOT_FOUND | Unknown endpoint |
| 405 | METHOD_NOT_ALLOWED | Wrong method (for example GET on events) |
| 413 | LIMIT_EXCEEDED | Batch limits exceeded |
| 426 | UPGRADE_REQUIRED | /ingest/v1/stream without a WebSocket upgrade |
Limits
| Item | Value |
|---|---|
| Events per batch | ≤ 500 and ≤ 1 MiB |
| One event | ≤ 64 KiB |
| Unacknowledged events per stream (in flight) | ≤ 2,000; wait for acks beyond that |
| Heartbeat interval | 5 seconds |
| Considered lost | No heartbeat and no event for 15 seconds |
| Signature time window | ±300 seconds |
| Nonce must not repeat within | 10 minutes |
Over the batch limits a WebSocket is closed with code 4008; HTTPS returns 413.
Next
- Events & data model: the envelope, the event catalog, baccarat, dragon tiger and Niu Niu results (including Niu Niu's face-down deal and hand-by-hand reveal), timing and betting windows.
- Reliability, health & errors: acks, de-duplication, gaps and resync, resume, heartbeats, error codes, trust levels and a WebSocket session.
- GFI event validator: check a batch of events in your browser.