SDK setup

@highlightxyz/sdk is a fully typed TypeScript client, auto-generated from the backend’s OpenAPI schema. Every parameter, response, and error type matches the API exactly — there’s no manual drift.

Install

bun add @highlightxyz/sdk

ESM-only. Works on Bun 1.1+, Node 20+, and modern browsers.

Create a client

Minimum config — public endpoints only:

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

const client = createHighlightClient({
  baseUrl: "https://api.highlightv2.xyz",
});

With a JWT (from SIWE or Privy sign-in):

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

The auth callback is invoked on every request, so you can refresh a cached token lazily.

With an API key (for server-to-server):

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

API keys use the same bearer scheme as JWTs — just pass the plaintext.

Making requests

All methods take a single flat parameters object. Path, query, and body params are merged:

// Public read
const collection = (await client.collection.get({ highlightId: "abc123" })).data;

// Auth'd list
const list = (await client.collection.list({
  blockchains: [8453],
  testnet: false,
  types: ["OpenEdition"],
})).data;

// Auth'd create
const created = (await client.collection.create({
  name: "My Drop",
  description: "Genesis collection",
  type: "OpenEdition",
  logoMediaId: mediaUuid,
  image: imageUrl,
  contract: { chainId: 8453, name: "DROP", symbol: "DROP", standard: "ERC721" },
})).data;

Response shape

Every method returns a discriminated result — no exceptions on non-2xx:

type SdkResponse<T> = {
  data?: T;
  error?: unknown;
  response?: Response;
};

Pattern:

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

Error payloads are typed NamedError shapes — match on res.error.name for fine-grained dispatch.

Sub-clients

All domain operations hang off client:

Client	Purpose	Docs
client.collection	Collections, sales, deploy	Collections, Sales, Deploy workflow
client.token	Minted token queries	Tokens
client.gate	Access control	Gates
client.media	Upload & storage	Media, Upload flow
client.mechanic	Built-in & custom mechanics	Mechanics
client.contract	Contract records	Contracts
client.config	Chains & system contracts	Config
client.user.signin, client.user.siwe.nonce	Sign in	Auth
client.apiKey	API key management	Auth: API keys
client.health	Liveness check	—

See clients overview for the full method list.

Type imports

Re-exported enums and types from the root:

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

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

Related

• Developer quick start — first call
• Clients overview — every method at a glance
• Authentication — SIWE, Privy, API keys
• Errors — typed error catalog