Trading via API

Utilisez ce guide si vous intégrez un teneur de marché, un système de cotation ou un service d'exécution avec Hypercall.

API de production

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

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

Statut du testnet : le testnet est temporairement désactivé jusqu'à ce que Hypercall acquière davantage de HYPE de testnet. Les nouvelles intégrations de teneurs de marché doivent utiliser la production, sauf si Hypercall vous fournit un environnement dédié.

Flux sur liste d'autorisation

Le streaming de cotations indicatives (quote-provider) n'est pas encore disponible de manière générale. Hypercall peut l'activer pour les intégrations approuvées, mais l'intégration ordinaire d'un teneur de marché doit utiliser les données de marché REST ainsi que les canaux WebSocket authentifiés d'ordres, d'exécutions et de portefeuille.

Liste de contrôle d'intégration

• Portefeuille de trading : portefeuille EVM capable de signer des données typées EIP-712.
• Approvisionnement : approvisionnement en USDC de production sur app.hypercall.xyz.
• Accès : contactez Hypercall si vous avez besoin de limites de teneur de marché, d'un accès vendeur (writer) ou du streaming de cotations indicatives.
• Environnement : URL REST et WebSocket de production ci-dessus. Ne supposez pas que le testnet est disponible.
• Réconciliation : conservez vos propres identifiants d'ordres clients, nonces, ordres, exécutions et instantanés de positions.

Voies d'intégration

Crates Rust

Hypercall publie des crates Rust publiques pour la surface d'intégration prise en charge :

Le dépôt Rust public se trouve à github.com/hypercall-public/hypercall-rust.

Crate	Usage
hypercall-client	Client REST, client WebSocket, utilitaires de signature EIP-712, signature locale et signature AWS KMS
hypercall-sdk-types	DTO publics de requête et de réponse partagés par le client
hypercall-ws-protocol	Types de messages WebSocket publics
hypercall-hyperliquid	Crate utilitaire optionnelle Hyperliquid pour les intégrations qui se couvrent également sur Hyperliquid
hypercall-liquidator	Client de référence pour la liquidation en marge standard. Non requis pour la tenue de marché ordinaire

Utilisez les crates lorsque c'est possible. Elles encodent le domaine de signature actuel, les formats de requêtes, les règles de routage et les règles de formatage de chaînes de caractères, qu'il est facile de se tromper en les codant à la main.

REST et WebSocket bruts

Si vous n'utilisez pas Rust, utilisez les pages API Reference, Authentication & Signing et WebSocket API comme source de vérité.

1. Découvrir les marchés

Commencez par charger les marchés actifs et les spécifications des instruments :

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

Utilisez :

• GET /markets pour les groupes d'actifs sous-jacents cotés et d'échéances.
• GET /instrument-specs?currency=BTC pour les spécifications des options négociables.
• GET /options-summary?currency=BTC pour les champs de synthèse au niveau de la chaîne : meilleure offre, meilleure demande, prix de mark et champs de synthèse de type grecques.

2. Configurer la signature

Les opérations d'écriture utilisent des signatures EIP-712.

• ID de chaîne de production : 999
• Nom de domaine : Hypercall
• Version du domaine : 1
• Contrat de vérification : 0x0000000000000000000000000000000000000000

Les teneurs de marché devraient généralement utiliser un portefeuille agent :

1. Le portefeuille propriétaire approuve un agent avec POST /approve-agent.
2. Le portefeuille agent signe les ordres et les annulations pour le portefeuille propriétaire.
3. Le portefeuille propriétaire reste l'identité de portefeuille, d'approvisionnement et de risque.

Consultez Authentication & Signing pour les structures exactes et les noms de champs.

3. Coter avec des ordres groupés

Pour les cotations de teneur de marché, utilisez POST /bulk_order avec 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..."
      }
    ]
  }'

Règles importantes :

• price et size sont des chaînes de caractères dans la charge utile signée comme dans le corps JSON.
• Le formatage des chaînes doit correspondre exactement entre la signature et le corps JSON.
• La taille des ordres groupés est plafonnée à 50 ordres par requête.
• La route groupée est réservée au carnet d'ordres. route: "best_execution" et route: "rfq_only" sont des chemins pour ordres uniques, pas des chemins de cotation groupée.
• La plupart des rejets de trading renvoient un HTTP 200 avec status: "REJECTED". Inspectez toujours chaque résultat.

4. Rafraîchir les cotations

Utilisez PUT /bulk_order lorsque vous souhaitez annuler des ordres de cotation existants et placer des remplacements en une seule requête.

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 annule l'ancien lot avant de créer le nouveau. Les résultats sont renvoyés par remplacement dans l'ordre de la requête. Une annulation échouée empêche la création de l'ordre de remplacement correspondant.

Pour un remplacement unique sensible à la latence, utilisez PUT /order.

5. S'abonner aux mises à jour

Connectez-vous au WebSocket de production :

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" }));
};

Utilisez :

• order_updates pour les changements de statut des ordres. Les mises à jour d'exécutions partielles sont volontairement omises ici.
• fills comme source de vérité pour les exécutions partielles et les transactions exécutées.
• portfolio pour les mises à jour de l'état du compte.
• orderbook, trades, options_chain et index_prices pour les données de marché publiques.

Consultez WebSocket API pour les formats des canaux et le comportement de maintien de connexion.

6. Réconcilier l'état

Exécutez une boucle de réconciliation même si votre connexion WebSocket est saine.

État	Solution de repli REST	Canal WebSocket
Ordres	GET /orders?wallet=...	order_updates
Exécutions	GET /fills?wallet=...	fills
Portefeuille	GET /portfolio?wallet=...	portfolio
Marchés	GET /markets, GET /instrument-specs	market_updates, options_chain

Boucle recommandée :

1. Chargez les marchés au démarrage.
2. Chargez les ordres ouverts et les dernières exécutions avant de coter.
3. Abonnez-vous aux mises à jour WebSocket.
4. Cotez avec des identifiants clients déterministes.
5. Interrogez REST périodiquement pour vous rétablir après des déconnexions ou des messages manqués.
6. Cessez de coter en cas d'état inconnu jusqu'à ce que les états REST et WebSocket concordent à nouveau.

7. Comprendre le périmètre du lancement

La version Alpha sur le réseau principal est volontairement limitée.

• Marge : la marge standard est en service. La marge de portefeuille n'est pas activée de manière générale.
• Accès vendeur (writer) : l'exposition courte sur options nécessite un accès approuvé.
• Streaming indicatif : les flux de cotations indicatives (quote-provider) sont soumis à une liste d'autorisation et ne constituent pas encore une voie d'intégration publique générale.
• Outils de liquidation : la crate publique de liquidation est destinée aux flux de travail de liquidation en marge standard, pas à la tenue de marché ordinaire.
• Testnet : indisponible jusqu'à ce que Hypercall acquière davantage de HYPE de testnet.

Problèmes courants

Échec de la vérification de la signature

• Vérifiez que price et size sont des chaînes JSON.
• Vérifiez que les chaînes signées correspondent exactement aux chaînes soumises.
• Utilisez l'ID de chaîne 999 pour la production.
• Utilisez un nonce nouveau pour chaque écriture signée.
• Confirmez que le signataire est le portefeuille ou un agent approuvé.

Marge insuffisante

• Vérifiez GET /portfolio?wallet=....
• Ajoutez du collatéral ou réduisez la taille des cotations.
• Confirmez que votre portefeuille dispose du niveau d'accès requis pour la stratégie que vous cotez.

Vente rejetée pour raison d'accès ou de couverture

• Assurez-vous que la vente est couverte par un inventaire long exécuté, ou contactez Hypercall pour un accès vendeur (writer).
• Ne supposez pas que l'accès vendeur est activé pour un nouveau portefeuille.

Aucune exécution sur le WebSocket

• Envoyez un message Authenticate avant de vous abonner aux canaux authentifiés.
• Abonnez-vous à fills, pas seulement à order_updates.
• Repliez-vous sur GET /fills?wallet=... après une reconnexion.

Prochaines étapes

• Authentification : Authentication & Signing
• Protocole WebSocket : WebSocket API
• Limites de débit : Rate Limits
• Erreurs : Errors & Rejection Reasons
• Référence : API Reference