Negociação via API

Use este guia se você está integrando um market maker, sistema de cotação ou serviço de execução com a Hypercall.

API de produção

URL base REST: https://api.hypercall.xyz

URL do WebSocket: wss://api.hypercall.xyz/ws

Status da testnet: a testnet está temporariamente desativada até que a Hypercall obtenha mais HYPE de testnet. Novas integrações de market makers devem usar produção, a menos que a Hypercall forneça a você um ambiente dedicado.

Streams com allowlist

O streaming de cotações indicativas para provedores de cotação ainda não está disponível de forma geral. A Hypercall pode habilitá-lo para integrações aprovadas, mas o onboarding comum de market makers deve usar dados de mercado via REST mais os canais WebSocket autenticados de ordens, execuções e portfólio.

Checklist de onboarding

• Carteira de negociação: carteira EVM capaz de assinar dados tipados EIP-712.
• Financiamento: depósito de USDC em produção em app.hypercall.xyz.
• Acesso: entre em contato com a Hypercall se você precisar de limites de market maker ou de streaming de cotações indicativas para provedores de cotação.
• Ambiente: URLs REST e WebSocket de produção acima. Não presuma que a testnet está disponível.
• Reconciliação: persista seus próprios client order IDs, nonces, ordens, execuções e snapshots de posição.

Caminhos de integração

SDK TypeScript

Instale o pacote oficial em TypeScript para clientes REST tipados, validação de requisições em tempo de execução e helpers de assinatura EIP-712:

npm install @hypercallxyz/sdk

Consulte o guia do SDK TypeScript para leituras de dados de mercado, consultas de conta, escritas assinadas, tratamento de erros e pontos de entrada do pacote. Atualmente, o SDK TypeScript cobre REST e assinatura. Conecte-se diretamente à API WebSocket para atualizações em streaming.

Crates Rust

A Hypercall publica crates Rust públicos para a superfície de integração suportada em github.com/hypercall-public/hypercall-rust. Eles não estão no crates.io. Adicione-os como dependências git e fixe uma tag ou commit.

Crate	Uso
hypercall-client	Cliente REST, cliente WebSocket, helpers de assinatura EIP-712, assinatura local e assinatura via AWS KMS
hypercall-sdk-types	DTOs públicos de requisição e resposta compartilhados pelo cliente
hypercall-ws-protocol	Tipos públicos de mensagens WebSocket
hypercall-hyperliquid	Crate auxiliar opcional da Hyperliquid para integrações que também fazem hedge na Hyperliquid
hypercall-liquidator	Cliente de referência para liquidação em Standard Margin. Não é necessário para market making normal

Use os crates sempre que possível. Eles codificam o domínio de assinatura atual, os formatos de requisição, as regras de rota e as regras de formatação de strings, que são fáceis de errar manualmente.

REST e WebSocket diretos

Se você não estiver usando Rust, use as páginas Referência da API, Autenticação e assinatura e API WebSocket como fonte da verdade.

1. Descubra os mercados

Comece carregando os mercados ativos e as especificações dos instrumentos:

curl https://api.hypercall.xyz/markets
curl "https://api.hypercall.xyz/instrument-specs?currency=BTC"
curl "https://api.hypercall.xyz/options-summary?currency=BTC"

Use:

• GET /markets para os grupos de ativo subjacente e vencimento listados.
• GET /instrument-specs?currency=BTC para as especificações de opções negociáveis.
• GET /options-summary?currency=BTC para campos de resumo no nível da cadeia: melhor bid, melhor ask, mark e campos no estilo das gregas.

2. Configure a assinatura

Operações de escrita usam assinaturas EIP-712.

• Chain ID de produção: 999
• Nome do domínio: Hypercall
• Versão do domínio: 1
• Contrato verificador: 0x0000000000000000000000000000000000000000

Market makers normalmente devem usar uma carteira de agente:

1. A carteira proprietária aprova um agente com POST /approve-agent.
2. A carteira de agente assina ordens e cancelamentos em nome da carteira proprietária.
3. A carteira proprietária continua sendo a identidade de portfólio, financiamento e risco.

Consulte Autenticação e assinatura para as structs e nomes de campos exatos.

3. Cote com ordens em lote

Para cotações de market maker, use POST /bulk_order com route: "book_only".

curl -X POST https://api.hypercall.xyz/bulk_order \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [
      {
        "wallet": "0x...",
        "symbol": "BTC-20260131-100000-C",
        "price": "100.0",
        "size": "0.1",
        "side": "Buy",
        "tif": "gtc",
        "route": "book_only",
        "client_id": "mm-bid-1",
        "mmp_enabled": true,
        "nonce": 1791273600000,
        "signature": "0x..."
      },
      {
        "wallet": "0x...",
        "symbol": "BTC-20260131-100000-C",
        "price": "101.0",
        "size": "0.1",
        "side": "Sell",
        "tif": "gtc",
        "route": "book_only",
        "client_id": "mm-ask-1",
        "mmp_enabled": true,
        "nonce": 1791273600001,
        "signature": "0x..."
      }
    ]
  }'

Regras importantes:

• price e size são strings tanto no payload assinado quanto no corpo JSON.
• A formatação das strings deve ser idêntica entre a assinatura e o corpo JSON.
• O lote é limitado a 50 ordens por requisição.
• A rota em lote é somente livro. route pode ser book_only ou omitido. route: "best_execution" é rejeitado em lote; use POST /order para isso. route: "rfq_only" é rejeitado em todos os endpoints de ordem atualmente.
• Nonces são timestamps em milissegundos. Um nonce fora do intervalo de dois dias antes a um dia depois do horário do servidor é rejeitado. Consulte Gerenciamento de nonces.
• A maioria das rejeições de negociação retorna HTTP 200 com status: "REJECTED". Sempre inspecione cada resultado.

4. Atualize as cotações

Use PUT /bulk_order quando quiser cancelar ordens de cotação existentes e colocar substitutas em uma única requisição.

curl -X PUT https://api.hypercall.xyz/bulk_order \
  -H "Content-Type: application/json" \
  -d '{
    "replacements": [
      {
        "wallet": "0x...",
        "order_id": 12345,
        "symbol": "BTC-20260131-100000-C",
        "price": "99.5",
        "size": "0.1",
        "side": "Buy",
        "tif": "gtc",
        "client_id": "mm-bid-1",
        "mmp_enabled": true,
        "nonce": 1791273600002,
        "signature": "0x..."
      }
    ]
  }'

Substituições não têm o campo route e são assinadas como ReplaceOrder, que adiciona o orderId antigo aos campos da ordem. Consulte Autenticação e assinatura.

PUT /bulk_order cancela o lote antigo antes de criar o novo lote. Os resultados são retornados por substituição, na ordem da requisição. Um cancelamento com falha impede que a ordem substituta correspondente seja criada.

Para uma única substituição sensível à latência, use PUT /order.

5. Assine as atualizações

Conecte-se ao WebSocket de produção:

const ws = new WebSocket("wss://api.hypercall.xyz/ws");

ws.onopen = () => {
  ws.send(JSON.stringify({ type: "Authenticate", wallet: "0xYourWallet" }));
  ws.send(JSON.stringify({ type: "Subscribe", channel: "order_updates" }));
  ws.send(JSON.stringify({ type: "Subscribe", channel: "fills" }));
  ws.send(JSON.stringify({ type: "Subscribe", channel: "portfolio" }));
};

Use:

• order_updates para mudanças de status de ordens, incluindo PARTIALLY_FILLED. Seu filled_size é a quantidade acumulada executada da ordem.
• fills para execuções individuais e suas quantidades por execução.
• portfolio para atualizações do estado da conta.
• orderbook, trades, options_chain e index_prices para dados de mercado públicos.

Consulte API WebSocket para os formatos dos canais e o comportamento de liveness.

6. Reconcilie o estado

Rode um loop de reconciliação mesmo que sua conexão WebSocket esteja saudável.

Estado	Fallback REST	Canal WebSocket
Ordens	GET /orders?wallet=...	order_updates
Execuções	GET /fills?wallet=...	fills
Portfólio	GET /portfolio?wallet=...	portfolio
Mercados	GET /markets, GET /instrument-specs	market_updates, options_chain

Loop recomendado:

1. Carregue os mercados na inicialização.
2. Carregue as ordens abertas e as execuções mais recentes antes de cotar.
3. Assine as atualizações via WebSocket.
4. Cote com client IDs determinísticos.
5. Consulte o REST periodicamente para se recuperar de desconexões ou mensagens perdidas.
6. Pare de cotar quando o estado for desconhecido até que o estado do REST e do WebSocket voltem a coincidir.

7. Entenda o escopo do lançamento

O Mainnet Alpha é intencionalmente restrito.

• Margem: Standard Margin e Portfolio Margin estão ambas ativas. Qualquer conta pode mudar para Portfolio Margin assim que sua conta HyperCore estiver no modo unificado.
• Posições vendidas em opções: posições vendidas em opções com Standard Margin estão habilitadas, sujeitas à margem e aos limites do seu tier. Verifique standard_margin_shorts_enabled em GET /risk/limits?wallet=....
• Perpétuos: ordens de perpétuos usam um domínio de assinatura e um endpoint separados. Consulte Autenticação e assinatura.
• Streaming indicativo: streams de provedores de cotação exigem allowlist e ainda não são um caminho de integração público geral.
• Ferramentas de liquidação: o crate público de liquidação é para fluxos de liquidação em Standard Margin, não para market making comum.
• Testnet: indisponível até que a Hypercall obtenha mais HYPE de testnet.

Problemas comuns

Falha na verificação da assinatura

• Verifique se price e size são strings JSON.
• Verifique se as strings assinadas coincidem exatamente com as strings enviadas.
• Use o chain ID 999 para produção.
• Use um nonce novo para cada escrita assinada.
• Confirme que o signatário é a carteira ou um agente aprovado.

Margem insuficiente

• Verifique GET /portfolio?wallet=....
• Adicione colateral ou reduza o tamanho da cotação.
• Confirme que sua carteira tem o nível de acesso exigido pela estratégia que você está cotando.

Venda rejeitada por acesso ou cobertura

• Verifique GET /risk/limits?wallet=.... Alguns tiers só permitem vendas cobertas por inventário comprado já executado.
• Entre em contato com a Hypercall se sua carteira precisar de um tier diferente.

Nenhuma execução no WebSocket

• Envie uma mensagem Authenticate antes de assinar canais autenticados.
• Assine fills, não apenas order_updates.
• Recorra a GET /fills?wallet=... após reconectar.

Próximos passos

• Autenticação: Autenticação e assinatura
• Protocolo WebSocket: API WebSocket
• Limites de taxa: Limites de taxa
• Erros: Erros e motivos de rejeição
• Referência: Referência da API