@jsonbored/metagraphed

Typed TypeScript client for the metagraph.sh backend API — operational metadata, health, schemas, and public-interface discovery for Bittensor subnets.

The client is generated from the live, versioned openapi.json, so request paths, query parameters, and response shapes are fully typed and stay in lockstep with the API contract.

Install

npm install @jsonbored/metagraphed

Usage

import { metagraphedFetch } from "@jsonbored/metagraphed";

// Fully typed path + query params + response envelope.
const subnets = await metagraphedFetch("/api/v1/subnets", {
  query: { limit: 10, sort: "completeness_score", order: "desc" },
});
console.log(subnets.data, subnets.meta.pagination);

// One call for everything a subnet page needs.
const overview = await metagraphedFetch("/api/v1/subnets/{netuid}/overview", {
  pathParams: { netuid: 7 },
});

// Point at a different origin, and tune/disable the request timeout.
const health = await metagraphedFetch("/api/v1/health", {
  baseUrl: "https://metagraph.sh",
  timeoutMs: 5000, // default 30000; pass 0 to disable; an explicit `signal` wins
});

A resolved value is always a success envelope. On any non-2xx the client throws a MetagraphedError carrying the HTTP status, the API error code, and the parsed error envelope — so you branch with try/catch, not on ok:

import { metagraphedFetch, MetagraphedError } from "@jsonbored/metagraphed";

try {
  const subnet = await metagraphedFetch("/api/v1/subnets/{netuid}", {
    pathParams: { netuid: 7 },
  });
  console.log(subnet.data);
} catch (error) {
  if (error instanceof MetagraphedError) {
    // error.status (e.g. 404), error.code (e.g. "artifact_not_found"), error.envelope
    if (error.code === "rate_limited") {
      /* back off and retry */
    }
  }
}

Paginate a list endpoint

metagraphedPaginate follows meta.pagination.next_cursor until it's exhausted:

import { metagraphedPaginate } from "@jsonbored/metagraphed";

for await (const page of metagraphedPaginate("/api/v1/subnets", {
  query: { limit: 100 },
})) {
  for (const subnet of page.data) console.log(subnet.netuid);
}

Call the read-only RPC proxy

metagraphedRpc POSTs a JSON-RPC request to the Subtensor proxy (/rpc/v1/<network>) and returns the result, throwing MetagraphedError on an HTTP or JSON-RPC-level error:

import { metagraphedRpc } from "@jsonbored/metagraphed";

const healthInfo = await metagraphedRpc("finney", { method: "system_health" });

Configured client: retries, ETag caching, convenience methods

createMetagraphedClient wraps the typed surface with opt-in retries/backoff, opt-in ETag conditional caching, ergonomic per-collection methods, and a fetchAll auto-pagination helper. Everything is opt-in and tree-shakeable — with no options it behaves exactly like metagraphedFetch.

import { createMetagraphedClient } from "@jsonbored/metagraphed";

const client = createMetagraphedClient({
  // Opt-in retries on 429/5xx + transport errors (network / timeout) — exponential
  // backoff + jitter, honors Retry-After. Caller-initiated aborts are never retried.
  retry: { retries: 3 }, // or `retry: true` for defaults
  // Opt-in ETag conditional caching: revalidates with If-None-Match, serves the
  // cached body on a 304. `true` uses a bounded in-memory LRU (size it with
  // `createLruEtagCache(n)`); or pass your own `{ get, set }` store.
  cache: true,
});

// Typed convenience methods for the v1 collections + single resources.
const subnets = await client.subnets({ limit: 10 });
const subnet7 = await client.getSubnet(7);
const provider = await client.getProvider("allways");

// fetchAll walks every page and returns the flattened rows.
const all = await client.fetchAll("/api/v1/subnets", { query: { limit: 100 } });

// request() / paginate() / rpc() share the same retry + cache config.
const health = await client.request("/api/v1/health");

Every REST response is the standard envelope { ok, schema_version, data, meta } (meta.pagination on list routes, meta.published_at for freshness). See the API stability guide for the envelope, pagination, caching, error codes, and x-metagraph-* headers.

Versioning

The package tracks the /api/v1 contract; changes within v1 are additive. The exported types are regenerated from openapi.json on each release.

License

Apache-2.0 — see LICENSE. (The metagraphed backend itself is AGPL-3.0; this client SDK is permissively licensed so you can embed it freely.)