submit: BHRIGU Bitcoin Research State API

submissions/mcp-hackathon/bhrigu-bitcoin-research-state-api/RIGHTS.md

@@ -0,0 +1,14 @@
+# Submission rights declaration
+
+Project: `BHRIGU Bitcoin Research State API`
+Submission slug: `bhrigu-bitcoin-research-state-api`
+Submitter: `Yulchiev A.Kh`
+Date: `2026-09-08`
+
+The submitter confirms that they own, or have sufficient authorization for, the source code, service, frozen public research baseline, BHRIGU branding used in this package, and other materials submitted in this pull request.
+
+Subject to the official program terms, the submitter authorizes X-Agent to retain, reproduce, audit, test, archive, and publish the submitted program artifact for judging, fraud prevention, dispute handling, ecosystem submission, and post-award accountability. Closing the pull request, deleting a fork, or deleting an external repository does not revoke the official archive rights attached to an accepted and rewarded entry.
+
+Third-party components and their licenses: no bundled runtime dependencies. The service uses the Node.js runtime and calls public Binance market-data and mempool.space endpoints subject to their respective terms. See `source/THIRD_PARTY.md`.
+
+Exceptions or restrictions: authorization covers only the bounded source and materials actually present in this submission directory. ORION, private prompts, planners, evaluators, private corpora, unpublished research methods, credentials, wallet/payment code, and other protected BHRIGU internals are not included in the artifact and are not submitted.

submissions/mcp-hackathon/bhrigu-bitcoin-research-state-api/SUBMISSION.md

@@ -0,0 +1,51 @@
+# BHRIGU Bitcoin Research State API
+
+## Capability
+
+- **One-line description:** Returns a live, read-only Bitcoin research state combining Binance market time, Bitcoin protocol time, source freshness, and a precommitted observation window.
+- **Who it helps:** AI agents and researchers that need a compact Bitcoin state with explicit provenance, time coordinates, and no trading authority.
+- **Capability boundary:** Observation and research only. It does not trade, place orders, access wallets, move funds, read private account data, or provide a price target.
+
+## Live API
+
+- **API base URL:** https://bhrigu-bitcoin-research-state-api.vercel.app/v1
+- **Health-check URL:** https://bhrigu-bitcoin-research-state-api.vercel.app/health
+- **Authentication:** none
+- **Rate limits / known limits:** BTCUSDT only; outbound public sources have their own limits; each upstream call has an 8-second timeout; no SLA is claimed.
+- **API contract:** `GET /v1/state` with optional `?symbol=BTCUSDT`. JSON response contains market, protocol_time, window, memory, authority, and limits objects.
+
+## Source and reproducibility
+
+- **Source repository:** https://github.com/AiBhrigu/bhrigu-bitcoin-research-state-api
+- **Review commit:** `05a455ba1407f7b07de226f6c78eefda15b24880`
+- **Source submitted in this PR:** `source/`
+- **Run tests:** `npm ci && npm test`
+- **Run locally:** `npm ci && npm start`, then `curl http://localhost:3000/v1/state`
+- **Deploy:** deploy the exact review commit to Vercel with Node.js 22+; no environment variables or secrets are required.
+- **Version binding:** `/health` and `/.well-known/xagent-verification.json` both expose the exact deployed Git commit.
+## Verification
+
+Reproducible calls and expected results are in `verification/README.md`.
+
+- **Health-check result:** HTTP 200 with `status: ok` and exact review commit.
+- **Capability call:** `GET /v1/state?symbol=BTCUSDT`.
+- **Expected error behavior:** unsupported symbols return HTTP 400; non-GET state requests return HTTP 405; unavailable Binance market evidence fails closed rather than fabricating a live market state.
+
+## Security and data handling
+
+- **Data collected:** none. The service is stateless and does not accept user identity, account, wallet, or credential data.
+- **Purpose and retention:** no user data is stored. A frozen public research baseline is shipped in source for comparison with live public observations.
+- **Third parties / outbound network calls:** Binance public market-data-only endpoint and mempool.space public Bitcoin tip-height endpoint.
+- **Secrets:** none required; none committed.
+- **Known risks / restrictions:** public upstream availability and rate limits can affect live output. Market-source failure is fail-closed. Protocol tip failure is explicitly marked unavailable. Research state is not a trading signal.
+
+## MCP productization shape
+
+A future MCP wrapper can expose one read-only tool around `GET /v1/state`, with `symbol` constrained to `BTCUSDT`, no authorization scope, no side effects, and explicit source/freshness fields. MCP implementation is intentionally not required for this reviewed API artifact.
+
+## Support
+
+- **Team / builder:** BHRIGU / AiBhrigu
+- **Contact:** https://x.com/bhrigu_io
+- **Canonical project surface:** https://www.bhrigu.io/
+- **License / rights:** no general open-source license is granted. X-Agent review/archive rights are limited to the bounded submitted artifact and are declared in `RIGHTS.md`.

submissions/mcp-hackathon/bhrigu-bitcoin-research-state-api/source/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+.vercel/
+.env*
+.DS_Store
+npm-debug.log*
+.vercel

submissions/mcp-hackathon/bhrigu-bitcoin-research-state-api/source/IP_BOUNDARY.md

@@ -0,0 +1,28 @@
+# IP Boundary
+
+## Public artifact
+
+This repository intentionally contains only:
+
+- the read-only HTTP adapter;
+- deterministic state-shaping logic;
+- one frozen public observation baseline;
+- public-source fetchers;
+- tests and deployment metadata.
+
+## Explicitly excluded
+
+The following are not part of this artifact and must not be added during hackathon packaging:
+
+- ORION core or private services;
+- private prompts, planners, evaluators, or routing contracts;
+- private or unpublished corpora;
+- unpublished reconstruction or forecasting methods;
+- credentials, secrets, customer/account data;
+- wallet, payment, transfer, withdrawal, or trade execution logic.
+
+## Law
+
+`EXPOSE MEANING / PROTECT MECHANISM`
+
+Any future submission must copy only the source already present in this bounded public repository unless separately reviewed and authorized.

submissions/mcp-hackathon/bhrigu-bitcoin-research-state-api/source/README.md

@@ -0,0 +1,60 @@
+# BHRIGU Bitcoin Research State API
+
+A bounded, read-only Bitcoin research capability built for the X-Agent Open Innovation track.
+
+It turns public Bitcoin evidence into one agent-callable research-state object:
+
+`FIELD → WINDOW → REALITY → MEMORY`
+
+## What it returns
+
+- live Binance Spot BTCUSDT market state;
+- Bitcoin protocol-time coordinates;
+- source and freshness evidence;
+- the precommitted Sep 10, 2026 observation boundary;
+- current-vs-baseline delta;
+- explicit confirmation/invalidation phase;
+- zero trading, wallet, payment, transfer, or private-account authority.
+
+## API
+
+`GET /v1/state`
+
+Optional query: `?symbol=BTCUSDT`.
+
+`GET /health`
+
+Returns the exact deployed Git commit.
+
+`GET /.well-known/xagent-verification.json`
+
+Returns the X-Agent slug and exact deployed Git commit.
+
+## Local run
+
+Requires Node.js 22+.
+
+```bash
+npm test
+npm start
+curl http://localhost:3000/v1/state
+```
+
+No API key or account credential is required.
+
+## Public data dependencies
+
+- Binance public Spot 24h ticker for BTCUSDT.
+- mempool.space public Bitcoin tip-height endpoint.
+
+If the Binance market source is unavailable, the capability fails closed instead of fabricating a live state. Protocol tip-height failure is exposed as unavailable while the frozen protocol epoch metadata remains explicit.
+
+## IP boundary
+
+This repository contains only the bounded public adapter and its frozen public research record. It does not contain ORION, private prompts, planners, evaluators, private corpora, unpublished reconstruction logic, credentials, account state, wallet code, payment code, or trading execution.
+
+See `IP_BOUNDARY.md`.
+
+## License / rights
+
+No general open-source license is granted by this repository. Any future X-Agent hackathon submission will use only the explicit rights declaration required for the submitted public artifact.

submissions/mcp-hackathon/bhrigu-bitcoin-research-state-api/source/THIRD_PARTY.md

@@ -0,0 +1,17 @@
+# Third-party public data
+
+## Binance Spot public market data
+
+Endpoint class: public market data, security type `NONE`.
+
+Used for BTCUSDT 24-hour ticker fields only. No Binance account authentication, API key, trading endpoint, wallet endpoint, transfer endpoint, or private account endpoint is used.
+
+## mempool.space public Bitcoin tip height
+
+Used only to retrieve the current public Bitcoin block height and derive position within the current halving epoch.
+
+If this source is unavailable, the API exposes the source as unavailable and does not substitute hidden data.
+
+## Runtime dependencies
+
+The project has no npm runtime dependencies. It uses only Node.js built-ins and the platform-provided `fetch` implementation.

submissions/mcp-hackathon/bhrigu-bitcoin-research-state-api/source/api/about.mjs

@@ -0,0 +1,13 @@
+import { methodGate, sendJson } from "../lib/http.mjs";
+
+export default function handler(req, res) {
+  if (!methodGate(req, res)) return;
+  sendJson(res, 200, {
+    name: "BHRIGU Bitcoin Research State API",
+    capability: "read-only Bitcoin research state",
+    endpoint: "/v1/state",
+    health: "/health",
+    verification: "/.well-known/xagent-verification.json",
+    boundary: "RESEARCH_STATE_NOT_TRADE"
+  }, "public, max-age=60");
+}

submissions/mcp-hackathon/bhrigu-bitcoin-research-state-api/source/api/health.mjs

@@ -0,0 +1,7 @@
+import { healthPayload } from "../lib/runtime.mjs";
+import { methodGate, sendJson } from "../lib/http.mjs";
+
+export default function handler(req, res) {
+  if (!methodGate(req, res)) return;
+  sendJson(res, 200, healthPayload(), "public, max-age=30");
+}

submissions/mcp-hackathon/bhrigu-bitcoin-research-state-api/source/api/state.mjs

@@ -0,0 +1,23 @@
+import { buildState } from "../lib/state.mjs";
+import { methodGate, sendJson } from "../lib/http.mjs";
+
+export default async function handler(req, res) {
+  if (!methodGate(req, res)) return;
+  const url = new URL(req.url || "/v1/state", "http://localhost");
+  const symbol = String(url.searchParams.get("symbol") || "BTCUSDT").toUpperCase();
+  if (symbol !== "BTCUSDT") {
+    sendJson(res, 400, { error: "UNSUPPORTED_SYMBOL", supported: ["BTCUSDT"] });
+    return;
+  }
+  try {
+    const state = await buildState();
+    sendJson(res, 200, state, "public, max-age=10, s-maxage=10");
+  } catch (error) {
+    sendJson(res, 502, {
+      error: "PUBLIC_MARKET_SOURCE_UNAVAILABLE",
+      source: "Binance Spot BTCUSDT",
+      detail: String(error.message || error),
+      trading_authority: false
+    });
+  }
+}

submissions/mcp-hackathon/bhrigu-bitcoin-research-state-api/source/api/verification.mjs

@@ -0,0 +1,7 @@
+import { verificationPayload } from "../lib/runtime.mjs";
+import { methodGate, sendJson } from "../lib/http.mjs";
+
+export default function handler(req, res) {
+  if (!methodGate(req, res)) return;
+  sendJson(res, 200, verificationPayload(), "public, max-age=30");
+}

submissions/mcp-hackathon/bhrigu-bitcoin-research-state-api/source/lib/http.mjs

@@ -0,0 +1,14 @@
+export function sendJson(res, status, payload, cache = "no-store") {
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json; charset=utf-8");
+  res.setHeader("cache-control", cache);
+  res.setHeader("access-control-allow-origin", "*");
+  res.setHeader("x-content-type-options", "nosniff");
+  res.end(JSON.stringify(payload));
+}
+
+export function methodGate(req, res) {
+  if (req.method === "GET") return true;
+  sendJson(res, 405, { error: "METHOD_NOT_ALLOWED", allowed: ["GET"] });
+  return false;
+}

submissions/mcp-hackathon/bhrigu-bitcoin-research-state-api/source/lib/live.mjs

@@ -0,0 +1,42 @@
+const BINANCE_TICKER = "https://data-api.binance.vision/api/v3/ticker/24hr?symbol=BTCUSDT";
+const MEMPOOL_TIP = "https://mempool.space/api/blocks/tip/height";
+
+async function timedFetch(url, fetchImpl = fetch) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 8000);
+  try {
+    const response = await fetchImpl(url, { signal: controller.signal, headers: { accept: "application/json,text/plain" } });
+    if (!response.ok) throw new Error(`HTTP_${response.status}`);
+    return response;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function fetchMarket(fetchImpl = fetch) {
+  const response = await timedFetch(BINANCE_TICKER, fetchImpl);
+  const d = await response.json();
+  return {
+    venue: "Binance Spot",
+    symbol: "BTCUSDT",
+    last_price_usdt: Number(d.lastPrice),
+    change_24h_pct: Number(d.priceChangePercent),
+    high_24h_usdt: Number(d.highPrice),
+    low_24h_usdt: Number(d.lowPrice),
+    volume_24h_btc: Number(d.volume),
+    source_close_time_ms: Number(d.closeTime),
+    source: BINANCE_TICKER,
+    security_type: "NONE"
+  };
+}
+
+export async function fetchProtocol(fetchImpl = fetch) {
+  try {
+    const response = await timedFetch(MEMPOOL_TIP, fetchImpl);
+    const height = Number(await response.text());
+    if (!Number.isInteger(height) || height < 840000) throw new Error("INVALID_HEIGHT");
+    return { height, source: MEMPOOL_TIP, status: "live" };
+  } catch (error) {
+    return { height: null, source: MEMPOOL_TIP, status: "unavailable", error: String(error.message || error) };
+  }
+}

submissions/mcp-hackathon/bhrigu-bitcoin-research-state-api/source/lib/runtime.mjs

@@ -0,0 +1,14 @@
+export const SLUG = "bhrigu-bitcoin-research-state-api";
+export const SCHEMA = "bhrigu_bitcoin_research_state_v0_1";
+
+export function runtimeCommit() {
+  return process.env.BHRIGU_COMMIT || process.env.VERCEL_GIT_COMMIT_SHA || "LOCAL_DEV";
+}
+
+export function healthPayload() {
+  return { status: "ok", commit: runtimeCommit() };
+}
+
+export function verificationPayload() {
+  return { schemaVersion: 1, slug: SLUG, commit: runtimeCommit() };
+}

submissions/mcp-hackathon/bhrigu-bitcoin-research-state-api/source/lib/state.mjs

@@ -0,0 +1,66 @@
+import { fetchMarket, fetchProtocol } from "./live.mjs";
+import { WINDOW } from "./window.mjs";
+import { SCHEMA, runtimeCommit } from "./runtime.mjs";
+
+export async function buildState({ fetchImpl = fetch, now = new Date() } = {}) {
+  const [market, protocol] = await Promise.all([
+    fetchMarket(fetchImpl),
+    fetchProtocol(fetchImpl)
+  ]);
+  const observedAt = now.toISOString();
+  const sourceAgeMs = Math.max(0, now.getTime() - market.source_close_time_ms);
+  const freshness = sourceAgeMs <= 120000 ? "FRESH" : "STALE";
+  const epochStart = 840000;
+  const nextEpoch = 1050000;
+  const height = protocol.height;
+  const progress = height === null ? null : Math.max(0, Math.min(1, (height - epochStart) / (nextEpoch - epochStart)));
+  const boundary = new Date(WINDOW.boundary_utc);
+  const phase = now < boundary ? "PRE_BOUNDARY" : "POST_BOUNDARY";
+  const baseline = WINDOW.baseline.btcusdt_last_price;
+  const deltaPct = ((market.last_price_usdt - baseline) / baseline) * 100;
+
+  return {
+    schema: SCHEMA,
+    commit: runtimeCommit(),
+    observed_at_utc: observedAt,
+    boundary: "RESEARCH_STATE_NOT_TRADE",
+    market: { ...market, freshness, source_age_ms: sourceAgeMs },
+    protocol_time: {
+      halving_epoch: 4,
+      epoch_start_height: epochStart,
+      next_epoch_height: nextEpoch,
+      block_subsidy_btc: 3.125,
+      live_tip_height: height,
+      epoch_progress_pct: progress === null ? null : Number((progress * 100).toFixed(4)),
+      source: protocol.source,
+      source_status: protocol.status
+    },
+    window: {
+      ...WINDOW,
+      phase,
+      current_vs_baseline_pct: Number(deltaPct.toFixed(4)),
+      comparison_status: phase === "PRE_BOUNDARY" ? "NOT_FINAL_BEFORE_BOUNDARY" : "REALITY_COMPARISON_OPEN"
+    },
+    memory: {
+      law: "FIELD → WINDOW → REALITY → MEMORY",
+      append_only: true,
+      retroactive_rewrite: "forbidden"
+    },
+    authority: {
+      trading: false,
+      wallet: false,
+      payment: false,
+      withdrawal: false,
+      transfer: false,
+      private_account_data: false,
+      credentials_read: false
+    },
+    limits: {
+      method: "GET",
+      symbol: "BTCUSDT only",
+      auth: "none",
+      market_source: "public Binance Spot",
+      protocol_source: "public mempool.space tip height"
+    }
+  };
+}

submissions/mcp-hackathon/bhrigu-bitcoin-research-state-api/source/lib/window.mjs

@@ -0,0 +1,18 @@
+export const WINDOW = Object.freeze({
+  id: "SEP_10_2026",
+  boundary_utc: "2026-09-10T00:00:00Z",
+  role: "precommitted_observation_boundary",
+  baseline: {
+    captured_at_utc: "2026-09-08T11:25:23Z",
+    btcusdt_last_price: 78474,
+    btcusdt_24h_change_pct: -1.226,
+    btcusdt_24h_high: 79643.5,
+    btcusdt_24h_low: 78179.98,
+    bitcoin_tip_height: 966060
+  },
+  invariants: {
+    retroactive_rewrite: "forbidden",
+    price_target: false,
+    trading_signal: false
+  }
+});