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 la testnet: la testnet está temporalmente deshabilitada hasta que Hypercall adquiera más HYPE de testnet. Las nuevas integraciones de market makers deben usar producción, a menos que Hypercall le proporcione un entorno dedicado.

Streams con lista de permitidos

El streaming indicativo para proveedores de cotizaciones aún no está disponible de forma general. Hypercall puede habilitarlo para integraciones aprobadas, pero la incorporación estándar de market makers debe usar los datos de mercado por REST junto con los canales autenticados de WebSocket 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 con USDC de producción en app.hypercall.xyz.
• Acceso: contacte a Hypercall si necesita límites de market maker, acceso de escritor (writer) o streaming indicativo para proveedores de cotizaciones.
• Entorno: las URLs de producción REST y WebSocket indicadas arriba. No asuma que la testnet está disponible.
• Reconciliación: persista sus propios client order IDs, nonces, órdenes, ejecuciones y snapshots de posiciones.

Rutas de integración

Crates de Rust

Hypercall publica crates públicos de Rust para la superficie de integración soportada:

El repositorio público de Rust es github.com/hypercall-public/hypercall-rust.

Crate	Uso
hypercall-client	Cliente REST, cliente WebSocket, helpers 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 de WebSocket
hypercall-hyperliquid	Crate helper opcional de Hyperliquid para integraciones que también realizan cobertura en Hyperliquid
hypercall-liquidator	Cliente de referencia para liquidación con Margen Estándar. No es necesario para el market making habitual

Use los crates siempre que sea posible. Estos codifican el dominio de firma actual, las formas de las solicitudes, las reglas de rutas y las reglas de formato de strings, que son fáciles de equivocar si se implementan a mano.

REST y WebSocket sin SDK

Si no utiliza Rust, use las páginas API Reference, Authentication & Signing y WebSocket API como fuente de verdad.

1. Descubrir los 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 listados de activos subyacentes y vencimientos.
• GET /instrument-specs?currency=BTC para las especificaciones de opciones negociables.
• GET /options-summary?currency=BTC para campos de resumen a nivel de cadena: mejor bid, mejor ask, precio mark y campos de resumen 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

Los market makers normalmente deberían usar una wallet agente:

1. La wallet propietaria aprueba un agente con POST /approve-agent.
2. La wallet 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 Authentication & Signing para ver los structs y nombres de campos exactos.

3. Cotizar con órdenes en bloque

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

Reglas importantes:

• price y size son strings tanto en el payload firmado como en el cuerpo JSON.
• El formato de los strings debe coincidir exactamente entre la firma y el cuerpo JSON.
• El tamaño de la orden en bloque está limitado a 50 órdenes por solicitud.
• La ruta en bloque es solo para el libro (book-only). route: "best_execution" y route: "rfq_only" son rutas de orden individual, no rutas de cotización en bloque.
• La mayoría de los rechazos de trading devuelven HTTP 200 con status: "REJECTED". Inspeccione siempre cada resultado.

4. Actualizar las cotizaciones

Use PUT /bulk_order cuando quiera cancelar las órdenes de cotización existentes y colocar los 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",
        "route": "book_only",
        "client_id": "mm-bid-1",
        "nonce": 1003,
        "signature": "0x..."
      }
    ]
  }'

PUT /bulk_order cancela el lote anterior antes de crear el lote nuevo. Los resultados se devuelven por cada reemplazo en el orden de la solicitud. Una cancelación fallida impide que esa orden de reemplazo sea creada.

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. Las actualizaciones de ejecuciones parciales se omiten intencionalmente aquí.
• fills como fuente de verdad para ejecuciones parciales y operaciones ejecutadas.
• portfolio para actualizaciones del estado de la cuenta.
• orderbook, trades, options_chain e index_prices para datos públicos de mercado.

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

6. Reconciliar el estado

Ejecute un ciclo de reconciliación incluso si su conexión WebSocket está saludable.

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 inicio.
2. Cargue las órdenes abiertas y las ejecuciones más recientes antes de cotizar.
3. Suscríbase a las actualizaciones de WebSocket.
4. Cotice con client IDs 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 WebSocket vuelvan a coincidir.

7. Comprender el alcance del lanzamiento

Mainnet Alpha está intencionalmente restringido.

• Margen: el Margen Estándar está activo. El Margen de Portafolio no está habilitado de forma general.
• Acceso de escritor (writer): la exposición corta en opciones requiere acceso aprobado.
• Streaming indicativo: los streams para proveedores de cotizaciones requieren estar en la lista de permitidos y aún no son una ruta de integración pública general.
• Herramientas de liquidación: el crate público de liquidador está pensado para flujos de liquidación con Margen Estándar, no para el market making habitual.
• Testnet: no disponible hasta que Hypercall adquiera más HYPE de testnet.

Problemas comunes

Falla en la verificación de la firma

• Verifique que price y size sean strings JSON.
• Verifique que los strings firmados coincidan exactamente con los strings enviados.
• Use el chain ID 999 para producción.
• Use un nonce nuevo para cada escritura firmada.
• Confirme que el firmante es la wallet o un agente aprobado.

Margen insuficiente

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

Venta rechazada por acceso o cobertura

• Asegúrese de que la venta esté cubierta por inventario largo ejecutado, o contacte a Hypercall para obtener acceso de escritor (writer).
• No asuma que el acceso de escritor está habilitado para una wallet nueva.

No llegan ejecuciones por WebSocket

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

Próximos pasos

• Autenticación: Authentication & Signing
• Protocolo WebSocket: WebSocket API
• Límites de tasa: Rate Limits
• Errores: Errors & Rejection Reasons
• Referencia: API Reference