Trading por API

Use esta guía si está integrando un market maker, un sistema de cotización o un servicio de ejecución con Hypercall.

API de producción

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

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

Estado de testnet: la testnet está deshabilitada temporalmente hasta que Hypercall adquiera más HYPE de testnet. Las nuevas integraciones de market makers deben usar producción, salvo que Hypercall le proporcione un entorno dedicado.

Streams con lista de acceso

El streaming de proveedores de cotizaciones indicativas aún no está disponible de forma general. Hypercall puede habilitarlo para integraciones aprobadas, pero la incorporación habitual de market makers debe usar datos de mercado por REST junto con los canales WebSocket autenticados de órdenes, ejecuciones y portafolio.

Lista de verificación de incorporación

• Wallet de trading: wallet EVM capaz de firmar datos tipados EIP-712.
• Fondeo: fondeo en USDC de producción en app.hypercall.xyz.
• Acceso: contacte a Hypercall si necesita límites de market maker o streaming de proveedor de cotizaciones indicativas.
• Entorno: las URLs REST y WebSocket de producción indicadas arriba. No asuma que la testnet está disponible.
• Conciliación: almacene sus propios IDs de orden de cliente, nonces, órdenes, ejecuciones y snapshots de posiciones.

Vías de integración

SDK de TypeScript

Instale el paquete oficial de TypeScript para obtener clientes REST tipados, validación de solicitudes en tiempo de ejecución y utilidades de firma EIP-712:

npm install @hypercallxyz/sdk

Consulte la guía del SDK de TypeScript para lecturas de datos de mercado, consultas de cuenta, escrituras firmadas, manejo de errores y puntos de entrada del paquete. Actualmente el SDK de TypeScript cubre REST y firma. Conéctese directamente a la API WebSocket para recibir actualizaciones en streaming.

Crates de Rust

Hypercall publica crates públicos de Rust para la superficie de integración soportada en github.com/hypercall-public/hypercall-rust. No están en crates.io. Agréguelos como dependencias git y fije un tag o commit.

Crate	Uso
hypercall-client	Cliente REST, cliente WebSocket, utilidades de firma EIP-712, firma local y firma con AWS KMS
hypercall-sdk-types	DTOs públicos de solicitud y respuesta compartidos por el cliente
hypercall-ws-protocol	Tipos públicos de mensajes WebSocket
hypercall-hyperliquid	Crate auxiliar opcional de Hyperliquid para integraciones que también hacen cobertura en Hyperliquid
hypercall-liquidator	Cliente de referencia para liquidación en Standard Margin. No es necesario para el market making habitual

Use los crates siempre que sea posible. Codifican el dominio de firma actual, la forma de las solicitudes, las reglas de ruta y las reglas de formato de cadenas, que son fáciles de equivocar a mano.

REST y WebSocket directos

Si no usa Rust, tome como referencia las páginas de Referencia de la API, Autenticación y firma y API WebSocket.

1. Descubrir mercados

Comience cargando los mercados activos y las especificaciones de los 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 los grupos de activo subyacente y vencimiento listados.
• GET /instrument-specs?currency=BTC para las especificaciones de opciones negociables.
• GET /options-summary?currency=BTC para campos resumen a nivel de cadena: mejor bid, mejor ask, precio mark y valores de tipo griegas.

2. Configurar la firma

Las operaciones de escritura usan firmas EIP-712.

• Chain ID de producción: 999
• Nombre del dominio: Hypercall
• Versión del dominio: 1
• Contrato verificador: 0x0000000000000000000000000000000000000000

Por lo general, los market makers deben usar una wallet de agente:

1. La wallet propietaria aprueba un agente con POST /approve-agent.
2. La wallet de agente firma órdenes y cancelaciones en nombre de la wallet propietaria.
3. La wallet propietaria sigue siendo la identidad de portafolio, fondeo y riesgo.

Consulte Autenticación y firma para ver las estructuras y los nombres de campo exactos.

3. Cotizar con órdenes masivas

Para las cotizaciones de market maker, use POST /bulk_order con 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..."
      }
    ]
  }'

Reglas importantes:

• price y size son cadenas tanto en el payload firmado como en el cuerpo JSON.
• El formato de las cadenas debe coincidir exactamente entre la firma y el cuerpo JSON.
• El tamaño de una orden masiva está limitado a 50 órdenes por solicitud.
• La ruta masiva es solo libro. route puede ser book_only u omitirse. route: "best_execution" se rechaza en órdenes masivas; para ello use POST /order. route: "rfq_only" se rechaza hoy en todos los endpoints de órdenes.
• Los nonces son timestamps en milisegundos. Se rechaza un nonce que esté fuera del rango comprendido entre dos días antes y un día después de la hora del servidor. Consulte Gestión de nonces.
• La mayoría de los rechazos de trading devuelven HTTP 200 con status: "REJECTED". Revise siempre cada resultado.

4. Actualizar cotizaciones

Use PUT /bulk_order cuando quiera cancelar órdenes de cotización existentes y colocar sus reemplazos en una sola solicitud.

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..."
      }
    ]
  }'

Los reemplazos no llevan campo route y se firman como ReplaceOrder, que agrega el orderId anterior a los campos de la orden. Consulte Autenticación y firma.

PUT /bulk_order cancela el lote anterior antes de crear el nuevo. Los resultados se devuelven por cada reemplazo, en el orden de la solicitud. Si una cancelación falla, no se crea la orden de reemplazo correspondiente.

Para un único reemplazo sensible a la latencia, use PUT /order.

5. Suscribirse a actualizaciones

Conéctese al WebSocket de producción:

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 cambios de estado de las órdenes, incluido PARTIALLY_FILLED. Su filled_size es la cantidad acumulada ejecutada de la orden.
• fills para ejecuciones individuales y la cantidad de cada una.
• portfolio para actualizaciones del estado de la cuenta.
• orderbook, trades, options_chain e index_prices para datos de mercado públicos.

Consulte API WebSocket para conocer los formatos de los canales y el comportamiento de liveness.

6. Conciliar el estado

Ejecute un ciclo de conciliación aunque su conexión WebSocket esté en buen estado.

Estado	Alternativa REST	Canal WebSocket
Órdenes	GET /orders?wallet=...	order_updates
Ejecuciones	GET /fills?wallet=...	fills
Portafolio	GET /portfolio?wallet=...	portfolio
Mercados	GET /markets, GET /instrument-specs	market_updates, options_chain

Ciclo recomendado:

1. Cargue los mercados al iniciar.
2. Cargue las órdenes abiertas y las últimas ejecuciones antes de cotizar.
3. Suscríbase a las actualizaciones por WebSocket.
4. Cotice con IDs de cliente deterministas.
5. Consulte REST periódicamente para recuperarse de desconexiones o mensajes perdidos.
6. Deje de cotizar ante un estado desconocido hasta que el estado de REST y el de WebSocket vuelvan a coincidir.

7. Comprender el alcance del lanzamiento

Mainnet Alpha está limitada de forma intencional.

• Margen: Standard Margin y Portfolio Margin están activos. Cualquier cuenta puede cambiar a Portfolio Margin una vez que su cuenta de HyperCore esté en modo unificado.
• Posiciones cortas en opciones: las posiciones cortas en opciones con Standard Margin están habilitadas, sujetas al margen y a los límites de su nivel. Revise GET /risk/limits?wallet=... para ver standard_margin_shorts_enabled.
• Perpetuos: las órdenes de perpetuos usan un dominio de firma y un endpoint distintos. Consulte Autenticación y firma.
• Streaming indicativo: los streams de proveedores de cotizaciones requieren estar en una lista de acceso y todavía no son una vía de integración pública general.
• Herramientas de liquidación: el crate público de liquidador está pensado para flujos de liquidación de Standard Margin, no para el market making habitual.
• Testnet: no disponible hasta que Hypercall adquiera más HYPE de testnet.

Problemas comunes

Falló la verificación de la firma

• Verifique que price y size sean cadenas JSON.
• Verifique que las cadenas firmadas coincidan exactamente con las enviadas.
• Use el chain ID 999 para producción.
• Use un nonce nuevo para cada escritura firmada.
• Confirme que el firmante sea la wallet o un agente aprobado.

Margen insuficiente

• Revise GET /portfolio?wallet=....
• Agregue colateral o reduzca el tamaño de la cotización.
• Confirme que su wallet tenga el nivel de acceso requerido para la estrategia que está cotizando.

Venta rechazada por acceso o cobertura

• Revise GET /risk/limits?wallet=.... Algunos niveles solo permiten ventas cubiertas por inventario long ya ejecutado.
• Contacte a Hypercall si su wallet necesita un nivel distinto.

No llegan ejecuciones por WebSocket

• Envíe un mensaje Authenticate antes de suscribirse a canales autenticados.
• Suscríbase a fills, no solo a order_updates.
• Recurra a GET /fills?wallet=... después de reconectarse.

Próximos pasos

• Autenticación: Autenticación y firma
• Protocolo WebSocket: API WebSocket
• Límites de tasa: Límites de tasa
• Errores: Errores y motivos de rechazo
• Referencia: Referencia de la API