SDK TypeScript

Use o pacote oficial @hypercallxyz/sdk para chamar a API REST da Hypercall a partir de TypeScript ou JavaScript moderno.

O SDK oferece:

• Clientes tipados para métodos públicos, de conta e de exchange assinados.
• Validação de requisições em tempo de execução antes do envio de cada requisição.
• Helpers EIP-712 para construir exatamente a mensagem assinada pela carteira.
• Padrões de produção com https://api.hypercall.xyz e timeout de requisição de 10 segundos.

O código-fonte é público em github.com/hypercall-public/hypercall-typescript-sdk.

Escopo atual

O SDK TypeScript cobre leituras REST, escritas REST pré-assinadas e helpers de assinatura. Use a API WebSocket diretamente para receber atualizações em streaming de ordens, execuções, portfólio e mercado.

O ExchangeClient não encapsula POST /bulk_order, PUT /bulk_order, configuração de MMP nem ordens de perpétuos. Assine essas requisições com as structs documentadas e chame os endpoints diretamente.

Instalação

npm install @hypercallxyz/sdk

O pacote é ESM e exporta declarações TypeScript em todos os pontos de entrada públicos. Fixe uma versão exata em integrações de produção que precisem de upgrades controlados.

Ler dados de mercado

O InfoClient oferece acesso tipado a dados de mercado e ao estado da conta. O HttpTransport usa a API de produção por padrão.

import { HttpTransport, InfoClient } from "@hypercallxyz/sdk";

const info = new InfoClient({
  transport: new HttpTransport(),
});

const markets = await info.markets({ include_instruments: false });
const currency = markets.data[0]?.underlying;

if (!currency) {
  throw new Error("Hypercall returned no active markets");
}

const summaries = await info.optionSummaries({ currency });

console.log(summaries.result?.[0]?.instrument_name);
console.log(summaries.result?.[0]?.mark_price);

Métodos comuns do InfoClient incluem:

Área	Métodos
Metadados da exchange	exchangeInfo, markets, instruments, optionSummaries, orderbook
Estado da conta	portfolio, orders, orderStatus, fills, settlementPayouts, authorizedAgents
Atividade	trade, trades, transfers, historicalPnl, historicalTheos
Risco e identidade	riskGrid, profile, profileTrades, referralBinding, referralCodeByOwner
RFQ e liquidação	rfqStatus, liquidations, liquidationStatus, liquidationHistory

Os parâmetros da requisição vêm primeiro. Passe um AbortSignal opcional como último argumento.

const controller = new AbortController();

const portfolio = await info.portfolio(
  { wallet: "0xYourWalletAddress" },
  controller.signal,
);

console.log(portfolio.data?.available_balance);

Configurar o transporte

Passe uma URL de API explícita quando sua aplicação selecionar o ambiente por meio de configuração.

const transport = new HttpTransport({
  apiUrl: "https://api.hypercall.xyz",
  timeout: 15_000,
  fetchOptions: {
    cache: "no-store",
  },
});

• apiUrl tem como padrão https://api.hypercall.xyz.
• timeout tem como padrão 10.000 milissegundos. Defina como null somente quando o chamador fornecer sua própria política de cancelamento.
• fetchOptions aplica opções padrão de fetch a todas as requisições. O SDK controla o método e o corpo da requisição.

Assinar e enviar uma escrita

O ExchangeClient aceita payloads de requisição pré-assinados. O chamador continua responsável pela conexão da carteira, pela seleção do nonce e pela criação da assinatura.

O helper de assinatura produz o domínio EIP-712, os tipos, o tipo primário e a mensagem. Passe esses dados tipados para o método de assinatura fornecido pela sua biblioteca de carteira.

import { ExchangeClient, HttpTransport, InfoClient } from "@hypercallxyz/sdk";
import {
  buildPlaceOrderValue,
  buildTypedData,
  PLACE_ORDER_TYPES,
} from "@hypercallxyz/sdk/signing";

declare const nonceStore: {
  next(signer: string, nowMs: number): Promise<number>;
};

declare const yourWallet: {
  signTypedData(typedData: unknown): Promise<`0x${string}`>;
};

const wallet = "0xYourWalletAddress";
const transport = new HttpTransport();
const info = new InfoClient({ transport });
const exchange = new ExchangeClient({ transport });

const instruments = await info.instruments({ currency: "BTC" });
const instrument = instruments.result?.find(
  ({ is_active, orderbook }) => is_active && orderbook,
);

if (!instrument) {
  throw new Error("Hypercall returned no active BTC orderbook instrument");
}

// Back this allocator with durable, per-signer state. It should atomically
// persist and return max(nowMs, previousNonce + 1).
const nonce = await nonceStore.next(wallet, Date.now());

const order = {
  wallet,
  symbol: instrument.instrument_name,
  side: "Buy" as const,
  size: "0.1",
  price: "100",
  tif: "gtc" as const,
  route: "book_only" as const,
  clientId: "quote-123",
  nonce,
};

const typedData = buildTypedData({
  chainId: 999,
  primaryType: "PlaceOrder",
  types: PLACE_ORDER_TYPES,
  message: buildPlaceOrderValue(order),
});

// Replace this with the typed-data signing call from your wallet library.
const signature = await yourWallet.signTypedData(typedData);

const result = await exchange.placeOrder({
  wallet: order.wallet,
  symbol: order.symbol,
  side: order.side,
  size: order.size,
  price: order.price,
  tif: order.tif,
  route: order.route,
  client_id: order.clientId,
  nonce: order.nonce,
  signature,
});

console.log(result.status);

Os valores assinados devem coincidir

Os campos wallet, symbol, side, size, price, tif, route, client_id e nonce enviados à API devem corresponder exatamente aos campos assinados equivalentes de PlaceOrder. Mantenha price e size como strings. Uma representação de string diferente produz uma assinatura diferente.

Alocação de nonce: a Hypercall aceita nonces dentro de dois dias antes e um dia depois do timestamp do servidor. Use o tempo epoch em milissegundos como semente, persista de forma atômica o último nonce por signatário e incremente de forma monotônica para evitar colisões entre workers concorrentes e reinicializações de processo.

Rota: o tipo route do SDK inclui rfq_only, mas a API atualmente o rejeita em todos os endpoints de ordem. Use book_only ou best_execution.

Seleção de instrumento: resolva um instrumento ativo pelo InfoClient imediatamente antes de construir uma ordem. Não fixe no código um símbolo de opção com data em uma integração de longa duração.

Use o tipo e o builder reduce-only correspondentes para requisições reduce-only:

• Envio: PLACE_ORDER_REDUCE_ONLY_TYPES com buildPlaceOrderReduceOnlyValue.
• Substituição: REPLACE_ORDER_REDUCE_ONLY_TYPES com buildReplaceOrderReduceOnlyValue.

Consulte Autenticação e assinatura para ver o domínio de assinatura de produção, as regras de nonce, a autorização de agentes e todas as mensagens de escrita suportadas.

Tratar erros

O pacote raiz exporta as classes de erro do SDK.

import {
  HttpRequestError,
  ValidationError,
} from "@hypercallxyz/sdk";

try {
  await info.portfolio({ wallet: "invalid-wallet" });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error("Invalid request:", error.message);
  } else if (error instanceof HttpRequestError) {
    console.error("HTTP request failed:", error.response?.status, error.message);
  } else {
    throw error;
  }
}

• ValidationError significa que o SDK rejeitou uma requisição inválida antes de enviá-la.
• HttpRequestError significa que a requisição falhou, expirou, foi abortada, retornou um status de erro ou retornou JSON inválido.
• Resultados de negociação ainda podem informar um status rejeitado em uma resposta HTTP bem-sucedida. Inspecione a resposta do método em vez de depender apenas de exceções.

Consulte Erros da API para orientações estáveis sobre tratamento de erros.

Pontos de importação

Importação	Uso
@hypercallxyz/sdk	HttpTransport, InfoClient, ExchangeClient, classes de erro e tipos públicos
@hypercallxyz/sdk/api/info	Métodos de informação tipados de baixo nível e schemas de requisição
@hypercallxyz/sdk/api/exchange	Métodos de exchange tipados de baixo nível e schemas de requisição
@hypercallxyz/sdk/signing	Mapas de tipos EIP-712, builders de valores e helpers de dados tipados

Para detalhes de requisição e resposta por endpoint, use a Referência da API REST. Para o histórico de versões e exemplos executáveis, use o changelog do SDK e o diretório examples/.