Newport Exchange API

curl -s "https://api.newportexchange.org/v2/crypto/BTC"

// quickstart-public.mjs — Node 18+ (global fetch). Run: node quickstart-public.mjs
const res = await fetch('https://api.newportexchange.org/v2/crypto/BTC', { signal: AbortSignal.timeout(10_000) });
if (!res.ok) throw new Error(`HTTP ${res.status}`);

const btc = await res.json(); // a bare object, not wrapped in "data"
// Several numeric fields are JSON strings — parse them before doing arithmetic.
console.log(btc.name, btc.price_usd, Number(btc.percent_change_day).toFixed(2) + '%');

# quickstart_public.py — Python 3.8+, pip install requests
import requests

resp = requests.get("https://api.newportexchange.org/v2/crypto/BTC", timeout=10)
resp.raise_for_status()

btc = resp.json()  # a bare object, not wrapped in "data"
# Several numeric fields are JSON strings — parse them before doing arithmetic.
print(btc["name"], btc["price_usd"], f'{float(btc["percent_change_day"]):.2f}%')

curl -s "https://api.newportexchange.org/v2/posts?symbol=BTC&limit=5" \
  -H "X-API-Key: YOUR_API_KEY"

// quickstart.mjs — Node 18+ (global fetch). Run: node quickstart.mjs
const API_BASE = 'https://api.newportexchange.org/v2';
const API_KEY = process.env.NEX_API_KEY ?? 'YOUR_API_KEY';

const res = await fetch(`${API_BASE}/posts?symbol=BTC&limit=5`, {
  headers: { 'X-API-Key': API_KEY },
});
if (!res.ok) {
  const err = await res.json().catch(() => ({}));
  throw new Error(`HTTP ${res.status}: ${err.message ?? res.statusText}`);
}

const { data, meta } = await res.json();
for (const post of data) console.log(post.published_at, post.title);
console.log('More pages available:', meta.has_more);

# quickstart.py — Python 3.8+, pip install requests
import os

import requests

API_BASE = "https://api.newportexchange.org/v2"
API_KEY = os.environ.get("NEX_API_KEY", "YOUR_API_KEY")

resp = requests.get(
    f"{API_BASE}/posts",
    headers={"X-API-Key": API_KEY},
    params={"symbol": "BTC", "limit": 5},
    timeout=10,
)
resp.raise_for_status()
body = resp.json()

for post in body["data"]:
    print(post["published_at"], post["title"])
print("More pages available:", body["meta"]["has_more"])

# Requires jq. "tonumber" converts the string fields; "? // null" keeps
# missing or malformed values as null instead of failing the whole pipeline.
curl -s "https://api.newportexchange.org/v2/crypto/currencies?rankFrom=1&rankTo=100" | jq '
  [ .[] | {
      symbol,
      price_usd,
      market_cap_usd: (.market_cap_usd | tonumber? // null),
      change_24h_pct: (.percent_change_day | tonumber? // null)
    } ]
  | map(select(.change_24h_pct != null))
  | sort_by(-.change_24h_pct) | .[:5]'

// Node 18+. Parse the string fields once, right after fetching.
const NUMERIC_STRING_FIELDS = [
  'price_btc', 'volume_usd_day', 'market_cap_usd',
  'available_supply', 'total_supply', 'max_supply',
  'percent_change_hour', 'percent_change_day', 'percent_change_week',
];

/** Finite number from a JSON number or numeric string, else null (never 0). */
const toNumber = (value) => {
  if (value === null || value === undefined || value === '') return null;
  const n = typeof value === 'number' ? value : Number(value);
  return Number.isFinite(n) ? n : null;
};

const res = await fetch('https://api.newportexchange.org/v2/crypto/currencies?rankFrom=1&rankTo=100', {
  signal: AbortSignal.timeout(10_000),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);

const coins = (await res.json()).map((row) => {
  const coin = { ...row }; // fields you don't know pass through untouched
  for (const field of NUMERIC_STRING_FIELDS) coin[field] = toNumber(row[field]);
  return coin;
});

// Numeric sorting now works (as strings, "9" sorts after "10"):
const topMovers = coins
  .filter((c) => c.percent_change_day !== null)
  .sort((a, b) => b.percent_change_day - a.percent_change_day)
  .slice(0, 5);
console.log(topMovers.map((c) => `${c.symbol} ${c.percent_change_day.toFixed(2)}%`));

# Python 3.8+, pip install requests
from decimal import Decimal, InvalidOperation

import requests

NUMERIC_STRING_FIELDS = (
    "price_btc", "volume_usd_day", "market_cap_usd",
    "available_supply", "total_supply", "max_supply",
    "percent_change_hour", "percent_change_day", "percent_change_week",
)


def to_decimal(value):
    """Decimal from a JSON number or numeric string, else None (never 0)."""
    if value is None or value == "":
        return None
    try:
        return Decimal(str(value))
    except InvalidOperation:
        return None


resp = requests.get(
    "https://api.newportexchange.org/v2/crypto/currencies",
    params={"rankFrom": 1, "rankTo": 100},
    timeout=10,
)
resp.raise_for_status()

coins = []
for row in resp.json():
    coin = dict(row)  # fields you don't know pass through untouched
    for field in NUMERIC_STRING_FIELDS:
        coin[field] = to_decimal(row.get(field))
    coins.append(coin)

movers = sorted(
    (c for c in coins if c["percent_change_day"] is not None),
    key=lambda c: c["percent_change_day"],
    reverse=True,
)[:5]
print([(c["symbol"], f'{c["percent_change_day"]:.2f}%') for c in movers])

# Candle "time" is unix seconds at 00:00 UTC; jq's todate renders it in UTC.
curl -s "https://api.newportexchange.org/v2/crypto-history/BTC?days=3" \
  | jq -r '.[] | "\(.time | todate)  close=\(.close)"'

# Convert one timestamp by hand (GNU date; on macOS use: date -u -r 1790899200)
date -u -d @1790899200 +%F

// Node 18+. Candle `time` and news `publishedAt` are unix SECONDS;
// posts, created_at/updated_at and last_updated are ISO 8601 strings in UTC.
const res = await fetch('https://api.newportexchange.org/v2/crypto-history/BTC?days=3', {
  signal: AbortSignal.timeout(10_000),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const candles = await res.json(); // oldest first

const utcDay = new Intl.DateTimeFormat('en-CA', { timeZone: 'UTC' }); // YYYY-MM-DD
const todayStart = Math.floor(Date.now() / 86_400_000) * 86_400; // 00:00 UTC, in seconds

for (const c of candles) {
  const day = utcDay.format(new Date(c.time * 1000)); // * 1000: seconds → milliseconds
  console.log(day, c.close, c.time >= todayStart ? '(today, still in progress)' : '');
}

// ISO 8601 strings parse directly; never re-interpret them in local time.
const publishedMs = Date.parse('2026-09-25T14:03:00.000Z');

# Python 3.8+, pip install requests
from datetime import datetime, timezone

import requests

resp = requests.get("https://api.newportexchange.org/v2/crypto-history/BTC", params={"days": 3}, timeout=10)
resp.raise_for_status()
today = datetime.now(timezone.utc).date()

for c in resp.json():  # oldest first
    day = datetime.fromtimestamp(c["time"], tz=timezone.utc).date()  # seconds, UTC
    print(day, c["close"], "(today, still in progress)" if day == today else "")

# ISO 8601 strings; before Python 3.11, fromisoformat() needs "Z" spelled out.
published = datetime.fromisoformat("2026-09-25T14:03:00.000Z".replace("Z", "+00:00"))

# -w appends the status code; branch on it, not on the message text.
curl -s -w '\nHTTP %{http_code}\n' "https://api.newportexchange.org/v2/crypto/NOT-A-COIN"
# {"success":false,"message":"Currency not found"}
# HTTP 404

# -f makes curl exit non-zero (22) on 4xx/5xx, for use in shell scripts.
curl -sf "https://api.newportexchange.org/v2/crypto/BTC" > btc.json || echo "request failed" >&2

// Node 18+. One wrapper for every call: returns JSON or throws an ApiError.
const API_BASE = 'https://api.newportexchange.org/v2';

class ApiError extends Error {
  constructor(status, message, details) {
    super(message);
    this.name = 'ApiError';
    this.status = status;
    this.details = details; // validation errors only: [{ field, issue }]
    this.retryable = status === 429 || status >= 500;
  }
}

export async function apiGet(path, { apiKey } = {}) {
  const res = await fetch(`${API_BASE}${path}`, {
    headers: apiKey ? { 'X-API-Key': apiKey } : {},
    signal: AbortSignal.timeout(10_000),
  });
  const body = await res.json().catch(() => null);
  if (res.ok) return body;
  // Error bodies are { success: false, message, details? }.
  throw new ApiError(res.status, body?.message ?? res.statusText, body?.details);
}

try {
  await apiGet('/crypto/NOT-A-COIN');
} catch (error) {
  if (!(error instanceof ApiError)) throw error; // network error or timeout: retry later
  if (error.status === 400) console.error('Fix the request:', error.details ?? error.message);
  else if (error.status === 401 || error.status === 403) console.error('Check the key and its scope');
  else if (error.status === 404) console.error('No such resource');
  else if (error.retryable) console.error('Retry with backoff (see Retries and backoff)');
}

# Python 3.8+, pip install requests
import requests

API_BASE = "https://api.newportexchange.org/v2"


class ApiError(Exception):
    def __init__(self, status, message, details=None):
        super().__init__(f"HTTP {status}: {message}")
        self.status = status
        self.details = details  # validation errors only: [{"field": ..., "issue": ...}]
        self.retryable = status == 429 or status >= 500


def api_get(path, api_key=None, **params):
    headers = {"X-API-Key": api_key} if api_key else {}
    resp = requests.get(f"{API_BASE}{path}", headers=headers, params=params, timeout=10)
    try:
        body = resp.json()
    except ValueError:
        body = None
    if resp.ok:
        return body
    body = body if isinstance(body, dict) else {}
    # Error bodies are {"success": false, "message": ..., "details"?: [...]}.
    raise ApiError(resp.status_code, body.get("message", resp.reason), body.get("details"))


try:
    api_get("/crypto/NOT-A-COIN")
except ApiError as error:
    if error.status == 400:
        print("Fix the request:", error.details or error)
    elif error.status in (401, 403):
        print("Check the key and its scope")
    elif error.status == 404:
        print("No such resource")
    elif error.retryable:
        print("Retry with backoff (see Retries and backoff)")

curl -s -G "https://api.newportexchange.org/v2/posts" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "q=etf" \
  --data-urlencode "symbol=BTC" \
  --data-urlencode "from=2026-09-01" \
  --data-urlencode "sort=newest" \
  --data-urlencode "limit=20" \
  --data-urlencode "page=1"

// Node 18+
const API_BASE = 'https://api.newportexchange.org/v2';
const API_KEY = process.env.NEX_API_KEY ?? 'YOUR_API_KEY';

const params = new URLSearchParams({
  q: 'etf',
  symbol: 'BTC',
  from: '2026-09-01',
  sort: 'newest',
  limit: '20',
  page: '1',
});

const res = await fetch(`${API_BASE}/posts?${params}`, {
  headers: { 'X-API-Key': API_KEY },
});
const body = await res.json();
if (!res.ok) throw new Error(`HTTP ${res.status}: ${body.message}`);

console.log(body.meta); // { page: 1, limit: 20, has_more: …, filters: { … } }
console.log(body.data.map((post) => post.title));

import os

import requests

API_BASE = "https://api.newportexchange.org/v2"
API_KEY = os.environ.get("NEX_API_KEY", "YOUR_API_KEY")

resp = requests.get(
    f"{API_BASE}/posts",
    headers={"X-API-Key": API_KEY},
    params={
        "q": "etf",
        "symbol": "BTC",
        "from": "2026-09-01",
        "sort": "newest",
        "limit": 20,
        "page": 1,
    },
    timeout=10,
)
body = resp.json()
if not resp.ok:
    raise RuntimeError(f"HTTP {resp.status_code}: {body.get('message')}")

print(body["meta"])
print([post["title"] for post in body["data"]])

curl -s "https://api.newportexchange.org/v2/posts/bitcoin-rallies-as-etf-inflows-accelerate" \
  -H "X-API-Key: YOUR_API_KEY"

// Node 18+
const API_BASE = 'https://api.newportexchange.org/v2';
const API_KEY = process.env.NEX_API_KEY ?? 'YOUR_API_KEY';

const slug = 'bitcoin-rallies-as-etf-inflows-accelerate';
const res = await fetch(`${API_BASE}/posts/${encodeURIComponent(slug)}`, {
  headers: { 'X-API-Key': API_KEY },
});

if (res.status === 404) {
  console.log('Post not found');
} else if (!res.ok) {
  throw new Error(`HTTP ${res.status}`);
} else {
  const { data: post } = await res.json();
  const paragraphs = post.body.split('\n\n');
  console.log(post.title, `(${paragraphs.length} paragraphs)`);
}

import os
from urllib.parse import quote

import requests

API_BASE = "https://api.newportexchange.org/v2"
API_KEY = os.environ.get("NEX_API_KEY", "YOUR_API_KEY")

slug = "bitcoin-rallies-as-etf-inflows-accelerate"
resp = requests.get(
    f"{API_BASE}/posts/{quote(slug)}",
    headers={"X-API-Key": API_KEY},
    timeout=10,
)

if resp.status_code == 404:
    print("Post not found")
else:
    resp.raise_for_status()
    post = resp.json()["data"]
    paragraphs = post["body"].split("\n\n")
    print(post["title"], f"({len(paragraphs)} paragraphs)")

curl -s "https://api.newportexchange.org/v2/crypto/currencies?rankFrom=1&rankTo=10"

// Node 18+ — public endpoint, no API key
const res = await fetch('https://api.newportexchange.org/v2/crypto/currencies?rankFrom=1&rankTo=10');
if (!res.ok) throw new Error(`HTTP ${res.status}`);

const coins = await res.json(); // bare array, ordered by rank
for (const coin of coins) {
  console.log(coin.rank, coin.symbol, Number(coin.price_usd).toFixed(2));
}

import requests

resp = requests.get(
    "https://api.newportexchange.org/v2/crypto/currencies",
    params={"rankFrom": 1, "rankTo": 10},
    timeout=10,
)
resp.raise_for_status()

for coin in resp.json():  # bare list, ordered by rank
    print(coin["rank"], coin["symbol"], round(coin["price_usd"], 2))

curl -s "https://api.newportexchange.org/v2/crypto/BTC"

// Node 18+ — public endpoint, no API key
const res = await fetch('https://api.newportexchange.org/v2/crypto/BTC');
if (res.status === 404) throw new Error('Unknown symbol');
if (!res.ok) throw new Error(`HTTP ${res.status}`);

const btc = await res.json(); // a single object, not wrapped in "data"
console.log(btc.name, btc.price_usd, btc.percent_change_day);

import requests

resp = requests.get("https://api.newportexchange.org/v2/crypto/BTC", timeout=10)
if resp.status_code == 404:
    raise SystemExit("Unknown symbol")
resp.raise_for_status()

btc = resp.json()  # a single object, not wrapped in "data"
print(btc["name"], btc["price_usd"], btc["percent_change_day"])

curl -s "https://api.newportexchange.org/v2/crypto/historical/BTC?days=30"

// Node 18+ — public endpoint, no API key
const res = await fetch('https://api.newportexchange.org/v2/crypto/historical/BTC?days=30');
if (!res.ok) throw new Error(`HTTP ${res.status}`);

const candles = await res.json(); // newest first
for (const c of candles) {
  console.log(new Date(c.time * 1000).toISOString().slice(0, 10), c.close);
}

from datetime import datetime, timezone

import requests

resp = requests.get("https://api.newportexchange.org/v2/crypto/historical/BTC", params={"days": 30}, timeout=10)
resp.raise_for_status()

for c in resp.json():  # newest first
    day = datetime.fromtimestamp(c["time"], tz=timezone.utc).date()
    print(day, c["close"])

curl -s "https://api.newportexchange.org/v2/crypto-history/ETH?from=2026-09-01&to=2026-09-26"

// Node 18+ — public endpoint, no API key
const params = new URLSearchParams({ from: '2026-09-01', to: '2026-09-26' });
const res = await fetch(`https://api.newportexchange.org/v2/crypto-history/ETH?${params}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);

const candles = await res.json(); // oldest first
console.log(candles.length, 'daily candles');

import requests

resp = requests.get(
    "https://api.newportexchange.org/v2/crypto-history/ETH",
    params={"from": "2026-09-01", "to": "2026-09-26"},
    timeout=10,
)
resp.raise_for_status()

candles = resp.json()  # oldest first
print(len(candles), "daily candles")

curl -s -i "https://api.newportexchange.org/v2/news?q=ethereum&limit=10&page=1"

// Node 18+ — public endpoint, no API key
const res = await fetch('https://api.newportexchange.org/v2/news?q=ethereum&limit=10&page=1');
if (!res.ok) throw new Error(`HTTP ${res.status}`);

const articles = await res.json(); // bare array, newest first
console.log('page', res.headers.get('X-Page'), 'of size', res.headers.get('X-Per-Page'));
for (const a of articles) {
  console.log(new Date(a.publishedAt * 1000).toISOString(), a.title);
}

from datetime import datetime, timezone

import requests

resp = requests.get(
    "https://api.newportexchange.org/v2/news",
    params={"q": "ethereum", "limit": 10, "page": 1},
    timeout=10,
)
resp.raise_for_status()

for a in resp.json():  # bare list, newest first
    published = datetime.fromtimestamp(a["publishedAt"], tz=timezone.utc)
    print(published.isoformat(), a["title"])

curl -s "https://api.newportexchange.org/v2/news/bitcoin-chart-echoes-cycle-that-delivered-400-gains-analyst"

// Node 18+ — public endpoint, no API key
const alias = 'bitcoin-chart-echoes-cycle-that-delivered-400-gains-analyst';
const res = await fetch(`https://api.newportexchange.org/v2/news/${encodeURIComponent(alias)}`);
if (res.status === 404) throw new Error('News item not found');
if (!res.ok) throw new Error(`HTTP ${res.status}`);

const article = await res.json(); // full description, not an excerpt
console.log(article.title);

import requests

alias = "bitcoin-chart-echoes-cycle-that-delivered-400-gains-analyst"
resp = requests.get(f"https://api.newportexchange.org/v2/news/{alias}", timeout=10)
if resp.status_code == 404:
    raise SystemExit("News item not found")
resp.raise_for_status()

article = resp.json()  # full description, not an excerpt
print(article["title"])

# --max-time caps the whole request; --retry re-tries timeouts, 408, 429 and
# 5xx with exponential backoff and honours Retry-After (curl 7.66+).
curl -s --connect-timeout 5 --max-time 10 --retry 3 "https://api.newportexchange.org/v2/crypto/BTC"

// Node 18+ and browsers. A timeout per request, plus cancelling a request
// whose result is no longer wanted (the user picked another coin).
const API_BASE = 'https://api.newportexchange.org/v2';
let current = null;

export async function loadCoin(symbol) {
  current?.abort(); // a newer request supersedes the previous one
  const controller = new AbortController();
  current = controller;
  const timer = setTimeout(() => controller.abort(new Error('Request timed out')), 10_000);
  try {
    const res = await fetch(`${API_BASE}/crypto/${encodeURIComponent(symbol)}`, {
      signal: controller.signal,
    });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return await res.json();
  } catch (error) {
    if (controller !== current) return null; // superseded: drop the late result silently
    throw error; // timeout, network or HTTP error: show the last good data, retry later
  } finally {
    clearTimeout(timer);
  }
}

# Python 3.8+, pip install requests. requests has NO default timeout.
import requests

session = requests.Session()  # reuses connections across calls

try:
    # (connect timeout, read timeout) in seconds
    resp = session.get("https://api.newportexchange.org/v2/crypto/BTC", timeout=(5, 10))
    resp.raise_for_status()
    print(resp.json()["price_usd"])
except requests.Timeout:
    print("Timed out: treat like a 5xx, keep the cached value, retry with backoff")

# Validate before you build the URL; a failed check never costs a request.
SYMBOL="BTC"
if [[ "$SYMBOL" =~ ^[A-Za-z0-9]{1,15}$ ]]; then
  curl -s "https://api.newportexchange.org/v2/crypto-history/$SYMBOL?days=30"
else
  echo "Not requestable by symbol: $SYMBOL (use the ranked list instead)" >&2
fi

// The rules the API enforces (anything else returns 400).
const API_BASE = 'https://api.newportexchange.org/v2';
const SYMBOL = /^[A-Za-z0-9_-]{1,50}$/; // /crypto/:symbol
const HISTORY_SYMBOL = /^[A-Za-z0-9]{1,15}$/; // historical endpoints, posts ?symbol=
const POST_SLUG = /^[A-Za-z0-9._-]{1,190}$/; // /posts/:slug
const NEWS_ALIAS = /^[A-Za-z0-9._-]{1,100}$/; // /news/:alias

export function historyUrl(symbol, days) {
  if (!HISTORY_SYMBOL.test(symbol)) return null; // e.g. "币安人生": read it from the list
  const n = Math.min(500, Math.max(1, Math.trunc(days)));
  return `${API_BASE}/crypto/historical/${encodeURIComponent(symbol)}?days=${n}`;
}

export const currencyUrl = (symbol) =>
  SYMBOL.test(symbol) ? `${API_BASE}/crypto/${encodeURIComponent(symbol)}` : null;

# The rules the API enforces (anything else returns 400).
import re
from urllib.parse import quote

API_BASE = "https://api.newportexchange.org/v2"
SYMBOL = re.compile(r"[A-Za-z0-9_-]{1,50}")  # /crypto/:symbol
HISTORY_SYMBOL = re.compile(r"[A-Za-z0-9]{1,15}")  # historical endpoints, posts ?symbol=
POST_SLUG = re.compile(r"[A-Za-z0-9._-]{1,190}")  # /posts/:slug
NEWS_ALIAS = re.compile(r"[A-Za-z0-9._-]{1,100}")  # /news/:alias


def history_url(symbol, days):
    if not HISTORY_SYMBOL.fullmatch(symbol):
        return None  # e.g. "币安人生": read it from the ranked list instead
    n = min(500, max(1, int(days)))
    return f"{API_BASE}/crypto/historical/{quote(symbol)}?days={n}"

# One polling step: everything published at or after a stored cursor
# (unix seconds), oldest first, so pages stay stable while new posts arrive.
SINCE=1758808980   # published_at of the newest post you have already processed

curl -s -G "https://api.newportexchange.org/v2/posts" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "from=$SINCE" \
  --data-urlencode "sort=oldest" \
  --data-urlencode "limit=100" \
  --data-urlencode "page=1"
# Repeat with page=2, 3, … while meta.has_more is true.
# Skip ids you have already processed: `from` is inclusive of the boundary.

// poll-posts.mjs — Node 18+. Fetches posts published since the last run.
// Schedule it (cron, a worker loop) no more often than once a minute.
import { readFile, writeFile } from 'node:fs/promises';

const API_BASE = 'https://api.newportexchange.org/v2';
const API_KEY = process.env.NEX_API_KEY ?? 'YOUR_API_KEY';
const STATE_FILE = './posts-cursor.json';
const MAX_RETRIES = 5;

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const toUnix = (iso) => Math.floor(Date.parse(iso) / 1000);

async function getJson(path, params) {
  for (let attempt = 0; ; attempt += 1) {
    const res = await fetch(`${API_BASE}${path}?${new URLSearchParams(params)}`, {
      headers: { 'X-API-Key': API_KEY },
      signal: AbortSignal.timeout(10_000),
    }).catch((error) => {
      // Network error or timeout: retried below like a 5xx.
      if (attempt >= MAX_RETRIES) throw error;
      return null;
    });

    const retryable = res === null || res.status === 429 || res.status >= 500;
    if (retryable && attempt < MAX_RETRIES) {
      // Honour Retry-After (sent with 429s), else RateLimit-Reset, but never wait
      // less than the exponential backoff. Jitter stops clients retrying in sync.
      const headerSeconds = Number(
        res?.headers.get('Retry-After') ?? res?.headers.get('RateLimit-Reset') ?? 0
      );
      const backoffMs = Math.min(60_000, 1000 * 2 ** attempt);
      const headerMs = Number.isFinite(headerSeconds) ? headerSeconds * 1000 : 0;
      await sleep(Math.max(headerMs, backoffMs) + Math.random() * 1000);
      continue;
    }

    const body = await res.json().catch(() => ({}));
    if (!res.ok) throw new Error(`HTTP ${res.status}: ${body.message ?? res.statusText}`);
    return body;
  }
}

async function loadCursor() {
  try {
    return JSON.parse(await readFile(STATE_FILE, 'utf8'));
  } catch {
    // First run: start from 24 hours ago rather than paging the whole archive.
    return { since: Math.floor(Date.now() / 1000) - 86_400, seenIds: [] };
  }
}

export async function pollNewPosts(handlePost) {
  const cursor = await loadCursor();
  const seen = new Set(cursor.seenIds);
  const fresh = [];

  for (let page = 1; ; page += 1) {
    const { data, meta } = await getJson('/posts', {
      from: String(cursor.since),
      sort: 'oldest',
      limit: '100',
      page: String(page),
    });
    for (const post of data) if (!seen.has(post.id)) fresh.push(post);
    if (!meta.has_more) break;
  }

  for (const post of fresh) await handlePost(post);

  // Persist the cursor only after the posts were handled, so a crash replays
  // them instead of skipping them. Remember the ids sitting exactly on the
  // boundary second, because `from` includes that second on the next run.
  if (fresh.length > 0) {
    const newest = Math.max(...fresh.map((p) => toUnix(p.published_at)));
    const boundaryIds = fresh.filter((p) => toUnix(p.published_at) === newest).map((p) => p.id);
    const seenIds = newest === cursor.since ? [...cursor.seenIds, ...boundaryIds] : boundaryIds;
    await writeFile(STATE_FILE, JSON.stringify({ since: newest, seenIds }));
  }
  return fresh.length;
}

const count = await pollNewPosts(async (post) => {
  console.log(post.published_at, post.source, post.title);
});
console.log(`${count} new post(s)`);

"""poll_posts.py — fetch posts published since the last run.

Python 3.8+, pip install requests. Schedule it no more often than once a minute.
"""
import json
import os
import random
import time
from datetime import datetime, timedelta, timezone
from pathlib import Path

import requests

API_BASE = "https://api.newportexchange.org/v2"
API_KEY = os.environ.get("NEX_API_KEY", "YOUR_API_KEY")
STATE_FILE = Path("posts-cursor.json")
MAX_RETRIES = 5

session = requests.Session()
session.headers["X-API-Key"] = API_KEY


def get_json(path, params):
    for attempt in range(MAX_RETRIES + 1):
        try:
            resp = session.get(f"{API_BASE}{path}", params=params, timeout=10)
        except (requests.ConnectionError, requests.Timeout):
            # Network error or timeout: retried like a 5xx.
            if attempt >= MAX_RETRIES:
                raise
            resp = None
        retryable = resp is None or resp.status_code == 429 or resp.status_code >= 500
        if retryable and attempt < MAX_RETRIES:
            # Honour Retry-After (sent with 429s), else RateLimit-Reset, but never
            # wait less than the exponential backoff; jitter avoids retrying in sync.
            headers = resp.headers if resp is not None else {}
            wait = headers.get("Retry-After") or headers.get("RateLimit-Reset") or ""
            wait_seconds = int(wait) if wait.isdigit() else 0
            backoff = min(60, 2 ** attempt)
            time.sleep(max(wait_seconds, backoff) + random.uniform(0, 1))
            continue
        resp.raise_for_status()
        return resp.json()


def to_unix(iso):
    return int(datetime.fromisoformat(iso.replace("Z", "+00:00")).timestamp())


def load_cursor():
    if STATE_FILE.exists():
        return json.loads(STATE_FILE.read_text())
    # First run: start from 24 hours ago rather than paging the whole archive.
    day_ago = datetime.now(timezone.utc) - timedelta(days=1)
    return {"since": int(day_ago.timestamp()), "seen_ids": []}


def poll_new_posts(handle_post):
    cursor = load_cursor()
    seen = set(cursor["seen_ids"])
    fresh = []

    page = 1
    while True:
        body = get_json(
            "/posts",
            {"from": cursor["since"], "sort": "oldest", "limit": 100, "page": page},
        )
        fresh.extend(p for p in body["data"] if p["id"] not in seen)
        if not body["meta"]["has_more"]:
            break
        page += 1

    for post in fresh:
        handle_post(post)

    # Persist only after handling, so a crash replays rather than skips.
    # Keep the ids on the boundary second: `from` includes it next time.
    if fresh:
        newest = max(to_unix(p["published_at"]) for p in fresh)
        boundary = [p["id"] for p in fresh if to_unix(p["published_at"]) == newest]
        seen_ids = cursor["seen_ids"] + boundary if newest == cursor["since"] else boundary
        STATE_FILE.write_text(json.dumps({"since": newest, "seen_ids": seen_ids}))
    return len(fresh)


if __name__ == "__main__":
    count = poll_new_posts(lambda p: print(p["published_at"], p["source"], p["title"]))
    print(f"{count} new post(s)")