Hosts API

The Hosts API provides information about the nodes (GPU hosts) on the Nosana Network: discovery, specifications, metrics, uptime, and rewards. It also contains the self-service routes node operators use to register and keep their node in sync.

Discovering hosts

import { 
function createNosanaClient(network: NosanaNetwork | undefined, customConfig: PartialClientConfig & {
    connect: ConnectFactoryConfig & {
        clientSecret: string;
    };
}): NosanaClient & {
    connect: ServerConnect;
} (+3 overloads)createNosanaClient, 
type NosanaNetwork = "mainnet" | "devnet" | "localnet"
const NosanaNetwork: {
    readonly MAINNET: "mainnet";
    readonly DEVNET: "devnet";
    readonly LOCALNET: "localnet";
}NosanaNetwork } from '@nosana/kit';

const const client: NosanaClientclient = function createNosanaClient(network?: NosanaNetwork, customConfig?: PartialClientConfig): NosanaClient (+3 overloads)createNosanaClient(
const NosanaNetwork: {
    readonly MAINNET: "mainnet";
    readonly DEVNET: "devnet";
    readonly LOCALNET: "localnet";
}NosanaNetwork.type MAINNET: "mainnet"MAINNET, {
  PartialClientConfig.api?: Partial<APIConfig> | undefinedapi: { apiKey?: string | undefinedapiKey: 
const process: {
    env: Record<string, string>;
}process.env: Record<string, string>env.stringNOSANA_API_KEY },
});

// List nodes (optionally filtered)
const const nodes: Record<string, unknown>nodes = await const client: NosanaClientclient.NosanaClient.api: NosanaApiClientapi.hosts: NosanaHostsApihosts.NosanaHostsApi.list: (request?: NodeListRequest) => Promise<Record<string, unknown>>list();

// Node details: basic, full, or extended info
const const node: Record<string, unknown>node = await const client: NosanaClientclient.NosanaClient.api: NosanaApiClientapi.hosts: NosanaHostsApihosts.NosanaHostsApi.get: (id: string) => Promise<Record<string, unknown>>get('node-address');
const const full: Record<string, unknown>full = await const client: NosanaClientclient.NosanaClient.api: NosanaApiClientapi.hosts: NosanaHostsApihosts.NosanaHostsApi.getFull: (id: string) => Promise<Record<string, unknown>>getFull('node-address');
const const info: Record<string, unknown>info = await const client: NosanaClientclient.NosanaClient.api: NosanaApiClientapi.hosts: NosanaHostsApihosts.NosanaHostsApi.getInfo: (id: string) => Promise<Record<string, unknown>>getInfo('node-address');

// What GPUs are available on the network right now?
const const gpus: Record<string, unknown>gpus = await const client: NosanaClientclient.NosanaClient.api: NosanaApiClientapi.hosts: NosanaHostsApihosts.NosanaHostsApi.getAvailableGpus: () => Promise<Record<string, unknown>>getAvailableGpus();

// Node distribution by country
const const byCountry: Record<string, unknown>byCountry = await const client: NosanaClientclient.NosanaClient.api: NosanaApiClientapi.hosts: NosanaHostsApihosts.NosanaHostsApi.getByCountry: () => Promise<Record<string, unknown>>getByCountry();

Method	HTTP	Path	Description
hosts.list(query?)	GET	/nodes/	List nodes
hosts.get(id)	GET	/nodes/{id}	Get a node
hosts.getFull(id)	GET	/nodes/{id}/full	Full node info
hosts.getInfo(id)	GET	/nodes/{id}/info	Extended node info
hosts.getAvailableGpus()	GET	/nodes/available-gpus	Available GPUs
hosts.getQueuedNodes(query?)	GET	/nodes/queued-nodes	Queued nodes
hosts.getWithAccess(query?)	GET	/nodes/with-access	Nodes with market access
hosts.getByCountry()	GET	/stats/nodes-country	Node distribution by country

Metrics, uptime & rewards

// Node metrics and uptime
const const metrics: Record<string, unknown>metrics = await const client: NosanaClientclient.NosanaClient.api: NosanaApiClientapi.hosts: NosanaHostsApihosts.NosanaHostsApi.getMetrics: (id: string, request?: NodeMetricsQuery) => Promise<Record<string, unknown>>getMetrics('node-address');
const const uptime: Record<string, unknown>uptime = await const client: NosanaClientclient.NosanaClient.api: NosanaApiClientapi.hosts: NosanaHostsApihosts.NosanaHostsApi.getUptime: (node: string, request?: NodeUptimeRequest) => Promise<Record<string, unknown>>getUptime('node-address');

// Rewards: per node or network-wide
const const nodeRewards: Record<string, unknown>nodeRewards = await const client: NosanaClientclient.NosanaClient.api: NosanaApiClientapi.hosts: NosanaHostsApihosts.NosanaHostsApi.getRewardsById: (id: string) => Promise<Record<string, unknown>>getRewardsById('node-address');
const const allRewards: Record<string, unknown>allRewards = await const client: NosanaClientclient.NosanaClient.api: NosanaApiClientapi.hosts: NosanaHostsApihosts.NosanaHostsApi.getRewards: () => Promise<Record<string, unknown>>getRewards();

// Recent benchmark runs for a node
const const benchmarks: Record<string, unknown>benchmarks = await const client: NosanaClientclient.NosanaClient.api: NosanaApiClientapi.hosts: NosanaHostsApihosts.NosanaHostsApi.getRecentBenchmarks: (id: string) => Promise<Record<string, unknown>>getRecentBenchmarks('node-address');

Method	HTTP	Path	Description
hosts.getMetrics(id, query?)	GET	/nodes/{id}/metrics	Node metrics
hosts.getUptime(node, query?)	GET	/nodes/heartbeats/uptime/{node}	Node uptime
hosts.getRewardsById(id)	GET	/nodes/{id}/rewards	Rewards for one node
hosts.getRewards()	GET	/nodes/rewards	Global rewards
hosts.getRecentBenchmarks(id)	GET	/nodes/{id}/recent-benchmarks	Recent node benchmarks

Market assignment

Helpers around which market a node belongs to or should request:

Method	HTTP	Path	Description
hosts.getRequestMarket(query?)	GET	/nodes/request-market	Market a node should request
hosts.getMarketRelation(query?)	GET	/nodes/market-relation	Node ↔ market relation
hosts.getMinimumRequiredVersion(query?)	GET	/nodes/minimum-required-version	Minimum required node version

Node-operator routes

These routes are used by the node software itself (registration, heartbeats, metric reporting). You normally don't call them unless you are building or operating a host:

Method	HTTP	Path	Description
hosts.register(body)	POST	/nodes/register	Register a node
hosts.syncNode(body)	POST	/nodes/sync-node	Sync node state
hosts.heartbeat(body)	POST	/nodes/heartbeat	Send a heartbeat
hosts.payment(body)	POST	/nodes/payment	Node payment
hosts.postMetrics(id, body)	POST	/nodes/{id}/metrics	Report node metrics
hosts.updateAddress(id, body)	PATCH	/nodes/{id}/address	Update node address
hosts.updateContact(id, body)	PATCH	/nodes/{id}/contact	Update node contact info

Interested in running a host yourself? See the Host GPUs guide.