@hightop/sdk

TypeScript SDK for the Hightop Agent API.

The SDK ships generated Agent API types and endpoint metadata plus a small hand-written client for auth, fetch transport, idempotency enforcement, errors, timeouts, raw requests, and operation polling.

Configuration

Header-key auth:

import { HightopAgentClient } from '@hightop/sdk'

const client = new HightopAgentClient({
  baseUrl: process.env.HIGHTOP_BASE_URL,
  agentId: process.env.HIGHTOP_AGENT_ID,
  apiKey: process.env.HIGHTOP_API_KEY,
})

Bearer-token auth:

const client = new HightopAgentClient({
  baseUrl: process.env.HIGHTOP_BASE_URL,
  bearerToken: process.env.HIGHTOP_BEARER_TOKEN,
})

baseUrl defaults to https://api.hightop.com in the SDK. Auth may be omitted at construction time so public routes can be fetched, but protected endpoint calls throw until agentId/apiKey or bearerToken is configured.

Typed Helpers

Common helpers are exposed as domain methods:

import { HightopAgentClient, createIdempotencyKey } from '@hightop/sdk'

const client = new HightopAgentClient({
  baseUrl: process.env.HIGHTOP_BASE_URL,
  agentId: process.env.HIGHTOP_AGENT_ID,
  apiKey: process.env.HIGHTOP_API_KEY,
})

const self = await client.self.get()
const repay = await client.borrow.repay(
  { asset: 'GREEN', amount_usd: '10' },
  { idempotencyKey: createIdempotencyKey() },
)
const final = await client.operations.wait(repay.operation_id)

Public no-auth helpers:

const openapi = await new HightopAgentClient({ baseUrl: 'https://api.hightop.com' }).openapi.get()
const capabilities = await new HightopAgentClient({ baseUrl: 'https://api.hightop.com' }).capabilities.json()

Generated Endpoint Surface

Every catalogued /v1/agent/* endpoint is available through the generated typed request map:

const oneOff = await client.request(
  'POST /v1/agent/one-off-payments',
  {
    to: '0x...',
    asset: 'USDC',
    amount_usd: '25',
  },
  {
    idempotencyKey: createIdempotencyKey(),
  },
)

The generated package artifact exports:

import type { AgentApiRequestFor, AgentApiResponseFor, AgentApiEndpointKey } from '@hightop/sdk'

These types are regenerated from the Agent API contract and validated by npm run validate:agent-api-generated.

Raw Requests

rawRequest is available for support workflows and newly reviewed integration cases. It only allows known /v1/agent/* routes, plus public OpenAPI/capabilities JSON routes.

const operation = await client.rawRequest({
  method: 'GET',
  path: '/v1/agent/operations/operation-id',
  query: { include: 'onchain' },
})

For routes that require idempotency, rawRequest requires an explicit idempotencyKey.

Errors And Timeouts

Non-2xx responses throw HightopAgentSDKError. The original response body, normalized Agent API error, HTTP status, and response headers are preserved.

try {
  await client.borrow.repay({ asset: 'GREEN', amount_usd: '10' }, { idempotencyKey: createIdempotencyKey() })
} catch (error) {
  if (error instanceof HightopAgentSDKError && error.code === 'asset_not_allowed') {
    console.log(error.agentError?.details)
  }
}

Request timeouts are synthesized by the SDK with code request_timeout. These errors are client-side and are not idempotency-cached by the server if the request was never received.