Clients overview

@highlightxyz/sdk is a generated client: one TypeScript class per OpenAPI tag, hung as lazy getters off HighlightClient. Every method is typed end-to-end — parameters, responses, and errors — from the backend’s Zod schemas.

import { createHighlightClient } from "@highlightxyz/sdk";

const client = createHighlightClient({
  baseUrl: "https://api.highlightv2.xyz",
  auth: () => accessToken,
  security: [{ type: "http", scheme: "bearer" }],
});

The sub-clients

Client	Methods	Docs
client.collection	list, create, get, finalizeBaseUri, updateEditionDetails, updateSeriesDetails, updateGenerativeDetails, getSales, addSale, updateSale, deleteSale, claimSale, bidSale, confirmBid, confirmSale, deploy, deployStatus, deployConfirm	Collections, Sales
client.token	list, get	Tokens
client.gate	list, get, create, update, remove	Gates
client.media	createUploadSession, upload, process, get, listChildren, getChild, publish, delete	Media
client.mechanic	list, get, create, update, addDeployment, removeDeployment	Mechanics
client.contract	list, get	Contracts
client.config	chains, systemContract	Config
client.user	signin	Auth reference
client.user.siwe	nonce	Auth reference
client.apiKey	list, create, revoke	Auth reference
client.health	get	—

A few sub-clients exist purely for infra/admin (indexer routes hang directly off HighlightClient as postIndexerChainsByChainIdActivate etc.) — you won’t normally call them from client code.

Response shape

Every method returns a discriminated result:

type SdkResponse<T> = {
  data?: T;          // populated on 2xx
  error?: unknown;   // populated on non-2xx — typed NamedError payload
  response?: Response; // the underlying fetch Response
};

No exceptions on non-2xx. Your code decides whether to throw.

const res = await client.collection.get({ highlightId });
if (res.error) {
  throw new Error(`Failed (${res.response?.status}): ${JSON.stringify(res.error)}`);
}
const collection = res.data;

For an ergonomic unwrap helper, see the pattern in packages/testing/src/helpers.ts.

Type imports

All enums and entity types are re-exported from the root:

import {
  CollectionType,
  ContractStandard,
  SaleType,
  SaleAccessMode,
  GateMatchMode,
  MediaKind,
  MediaScope,
  MediaAssetStatus,
  GenerativeEditionType,
} from "@highlightxyz/sdk";

import type {
  HighlightClient,
  HighlightClientConfig,
  CollectionListResponses,
  CollectionGetResponses,
} from "@highlightxyz/sdk";

Per-operation response types are named <Tag><Operation>Responses and <Tag><Operation>Errors — e.g. CollectionCreateResponses, MediaUploadErrors.

Related

• SDK setup — installation and client configuration
• Developer quick start — first call
• REST API — auto-generated route schemas