NatGold API

v2.0.0 · real-time NatGold token metrics

Endpoints

GET /api/natgold-snapshots/latest

The most recent snapshot. Includes the latest bitcoin price.

GET /api/natgold-snapshots/list-latest

The most recent snapshots, newest first.

GET /api/natgold-snapshots/stream

Server-sent events. Emits a snapshot event, carrying differences, as each snapshot is archived.

GET /health

Readiness, including how long ago the last snapshot was archived. /health/live is a liveness check that does not touch the database.

Query parameters

Name	Applies to	Default	Notes
`limit`	`list-latest`	10	Clamped to 1 to 1000.
`differences`	both	false	`true`, `false`, `1` or `0`. Adds movement against the previous close.

Response format

Every successful response is wrapped in a data key. Monetary values are strings with five decimal places, so no precision is lost passing through JSON numbers. Timestamps are UTC, ISO 8601, with six fractional digits.

{
  "data": {
    "id": 1519957,
    "timestamp": "2026-08-12T12:20:54.677358Z",
    "aisc": "1861.92705",
    "gold_price": "4408.20000",
    "aisc_open": "1861.92705",
    "aisc_previous_close": "1854.81301",
    "natgold_open_price": "2506.94795",
    "natgold_previous_close_price": "2514.06199",
    "natgold_price": "2546.27295",
    "aisc_differences": { "numeric": "7.11404", "percentage": "0.38354" },
    "natgold_differences": { "numeric": "32.21096", "percentage": "1.28123" },
    "bitcoin_price": "64238.60656"
  }
}

Consuming the stream

const events = new EventSource("https://api.natgold.com/api/natgold-snapshots/stream");

events.addEventListener("snapshot", (event) => {
  const { data } = JSON.parse(event.data);
  console.log(data.natgold_price, data.natgold_differences);
});

TypeScript definitions

Types are generated from the server's Rust definitions, so they cannot drift from what the API actually sends. They live in ts/natgold-api-model in the repository and are published as @natgold/natgold-api-model.

import type { Snapshot, Data } from "@natgold/natgold-api-model";

const response: Data<Snapshot> = await fetch(url).then((r) => r.json());