Trading 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 WebSocket: wss://api.hypercall.xyz/ws

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

Streams com allowlist

O streaming de provedores de cotação indicativa ainda não está disponível de forma geral. A Hypercall pode habilitá-lo para integrações aprovadas, mas o onboarding padrão 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 trading: 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, acesso de writer ou streaming de provedor de cotação indicativa.
• Ambiente: URLs REST e WebSocket de produção acima. Não assuma que a testnet está disponível.
• Reconciliação: persista seus próprios client order IDs, nonces, ordens, execuções e snapshots de posições.

Caminhos de Integração

Crates Rust

A Hypercall publica crates Rust públicas para a superfície de integração suportada:

O repositório público em Rust é github.com/hypercall-public/hypercall-rust.

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 para Hyperliquid, para integrações que também fazem hedge na Hyperliquid
hypercall-liquidator	Cliente de referência para liquidação em Margem Padrão. Não é necessário para market making comum

Use as crates sempre que possível. Elas 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 está usando Rust, use as páginas de Referência da API, Autenticação e Assinatura e API WebSocket como fonte de 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 ativos subjacentes e vencimentos listados.
• GET /instrument-specs?currency=BTC para as especificações de opções negociáveis.
• GET /options-summary?currency=BTC para melhor bid, melhor ask, marca e campos de resumo no estilo Greeks em nível de chain.

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 de verificação: 0x0000000000000000000000000000000000000000

Market makers normalmente devem usar uma carteira agente:

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

Veja 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": 1001,
        "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": 1002,
        "signature": "0x..."
      }
    ]
  }'

Regras que importam:

• price e size são strings tanto no payload assinado quanto no corpo JSON.
• A formatação das strings deve corresponder exatamente entre a assinatura e o corpo JSON.
• O tamanho do lote de ordens é limitado a 50 ordens por requisição.
• A rota em lote é apenas book-only. route: "best_execution" e route: "rfq_only" são caminhos de ordem única, não caminhos de cotação em lote.
• A maioria das rejeições de trading retorna HTTP 200 com status: "REJECTED". Sempre inspecione cada resultado.

4. Atualize as Cotações

Use PUT /bulk_order quando você quiser cancelar ordens de cotação existentes e criar substituições 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",
        "route": "book_only",
        "client_id": "mm-bid-1",
        "nonce": 1003,
        "signature": "0x..."
      }
    ]
  }'

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 de substituição 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. Atualizações de execuções parciais são intencionalmente omitidas aqui.
• fills como fonte de verdade para execuções parciais e trades executados.
• portfolio para atualizações do estado da conta.
• orderbook, trades, options_chain e index_prices para dados públicos de mercado.

Veja API WebSocket para formatos de canais e comportamento de liveness.

6. Reconcilie o Estado

Execute 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 em caso de estado desconhecido até que o estado do REST e do WebSocket estejam de acordo novamente.

7. Entenda o Escopo do Lançamento

O Mainnet Alpha é intencionalmente restrito.

• Margem: a Margem Padrão está ativa. A Margem de Portfólio não está habilitada de forma geral.
• Acesso de writer: exposição vendida em opções requer acesso aprovado.
• Streaming indicativo: streams de provedores de cotação são liberados por allowlist e ainda não são um caminho de integração pública geral.
• Ferramentas de liquidação: a crate pública de liquidator é para fluxos de liquidação em Margem Padrão, não para market making comum.
• Testnet: indisponível até que a Hypercall adquira mais HYPE de testnet.

Problemas Comuns

Falha na verificação de assinatura

• Verifique se price e size são strings JSON.
• Verifique se as strings assinadas correspondem exatamente às strings enviadas.
• Use o chain ID 999 para produção.
• Use um nonce novo para cada escrita assinada.
• Confirme que o assinante é 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 necessário para a estratégia que você está cotando.

Venda rejeitada por acesso ou cobertura

• Garanta que a venda esteja coberta por inventário comprado já executado, ou entre em contato com a Hypercall para obter acesso de writer.
• Não assuma que o acesso de writer está habilitado para uma carteira nova.

Sem execuções no WebSocket

• Envie uma mensagem Authenticate antes de assinar canais autenticados.
• Assine fills, não apenas order_updates.
• Recorra ao 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