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 obtienne 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 blanche

Le streaming de cotations indicatives pour les fournisseurs de prix n'est pas encore disponible pour tous. Hypercall peut l'activer pour les intégrations approuvées, mais l'intégration standard d'un teneur de marché doit utiliser les données de marché REST ainsi que les canaux WebSocket authentifiés pour les ordres, les exécutions et le portefeuille.

Liste de contrôle d'intégration

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

Modes d'intégration

SDK TypeScript

Installez le package TypeScript officiel pour disposer de clients REST typés, de la validation des requêtes à l'exécution et d'utilitaires de signature EIP-712 :

npm install @hypercallxyz/sdk

Consultez le guide du SDK TypeScript pour la lecture des données de marché, les requêtes de compte, les écritures signées, la gestion des erreurs et les points d'entrée du package. Le SDK TypeScript couvre actuellement REST et la signature. Connectez-vous directement à l'API WebSocket pour les mises à jour en streaming.

Crates Rust

Hypercall publie des crates Rust publiques pour la surface d'intégration prise en charge sur github.com/hypercall-public/hypercall-rust. Elles ne sont pas publiées sur crates.io. Ajoutez-les comme dépendances git et fixez un tag ou un commit.

Crate	Usage
`hypercall-client`	Client REST, client WebSocket, utilitaires de signature EIP-712, signature locale et signature via AWS KMS
`hypercall-sdk-types`	DTO publics de requêtes et de réponses partagés par le client
`hypercall-ws-protocol`	Types publics de messages WebSocket
`hypercall-hyperliquid`	Crate utilitaire Hyperliquid optionnelle pour les intégrations qui assurent aussi leur couverture sur Hyperliquid
`hypercall-liquidator`	Client de référence pour la liquidation en Standard Margin. Il n'est pas nécessaire pour une activité de tenue de marché normale

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 des chaînes, faciles à mal implémenter à la main.

REST et WebSocket bruts

Si vous n'utilisez pas Rust, considérez les pages Référence de l'API, Authentification et signature et API WebSocket comme la source de référence.

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 de sous-jacents et d'échéances listés.
GET /instrument-specs?currency=BTC pour les spécifications des options négociables.
GET /options-summary?currency=BTC pour les champs récapitulatifs au niveau de la chaîne : meilleur bid, meilleur ask, prix de marque et grecques.

2. Configurer la signature

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

Chain ID de production : 999
Nom du domaine : Hypercall
Version du domaine : 1
Contrat de vérification : 0x0000000000000000000000000000000000000000

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

Le portefeuille propriétaire approuve un agent via POST /approve-agent.
Le portefeuille agent signe les ordres et les annulations pour le compte du portefeuille propriétaire.
Le portefeuille propriétaire reste l'identité de portefeuille, de financement et de risque.

Consultez Authentification et signature pour les structures et noms de champs exacts.

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

Règles importantes :

price et size sont des chaînes, à la fois dans la charge utile signée et dans le corps JSON.
Le formatage des chaînes doit correspondre exactement entre la signature et le corps JSON.
Un ordre groupé est limité à 50 ordres par requête.
La route groupée passe uniquement par le carnet d'ordres. route peut valoir book_only ou être omis. route: "best_execution" est rejeté sur les ordres groupés ; utilisez POST /order dans ce cas. route: "rfq_only" est actuellement rejeté sur tous les endpoints d'ordres.
Les nonces sont des horodatages en millisecondes. Un nonce situé en dehors de la fenêtre allant de deux jours avant à un jour après l'heure du serveur est rejeté. Consultez Gestion des nonces.
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 leurs remplaçants 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",
        "client_id": "mm-bid-1",
        "mmp_enabled": true,
        "nonce": 1791273600002,
        "signature": "0x..."
      }
    ]
  }'

Les remplacements ne comportent pas de champ route et sont signés en tant que ReplaceOrder, qui ajoute l'ancien orderId aux champs de l'ordre. Consultez Authentification et signature.

PUT /bulk_order annule l'ancien lot avant de créer le nouveau. Les résultats sont renvoyés pour chaque remplacement, dans l'ordre de la requête. Une annulation en échec 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, y compris PARTIALLY_FILLED. Son champ filled_size correspond à la quantité cumulée exécutée pour l'ordre.
fills pour les exécutions individuelles et leurs quantités respectives.
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 API WebSocket pour les formats des canaux et le comportement de maintien de connexion.

6. Rapprocher l'état

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

État	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 :

Chargez les marchés au démarrage.
Chargez les ordres ouverts et les dernières exécutions avant de coter.
Abonnez-vous aux mises à jour WebSocket.
Cotez avec des identifiants client déterministes.
Interrogez REST périodiquement pour récupérer après une déconnexion ou des messages manqués.
Arrêtez de coter en cas d'état inconnu jusqu'à ce que les états REST et WebSocket concordent à nouveau.

7. Comprendre le périmètre de lancement

Mainnet Alpha est volontairement restreint.

Marge : Standard Margin et Portfolio Margin sont tous deux actifs. Tout compte peut passer en Portfolio Margin dès que son compte HyperCore est en mode unifié.
Ventes d'options à découvert : les positions courtes sur options en Standard Margin sont activées, sous réserve de la marge et des limites de votre niveau. Vérifiez standard_margin_shorts_enabled via GET /risk/limits?wallet=....
Perpétuels : les ordres sur contrats perpétuels utilisent un domaine de signature et un endpoint distincts. Consultez Authentification et signature.
Streaming indicatif : les flux des fournisseurs de cotations sont sur liste blanche et ne constituent pas encore un mode d'intégration public général.
Outils de liquidation : la crate publique de liquidation est destinée aux processus de liquidation en Standard Margin, pas à la tenue de marché ordinaire.
Testnet : indisponible jusqu'à ce que Hypercall obtienne davantage de HYPE de testnet.

Problèmes courants

Échec de la vérification de 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 envoyées.
Utilisez le chain ID 999 pour la production.
Utilisez un nonce nouveau pour chaque écriture signée.
Confirmez que le signataire est le portefeuille lui-même ou un agent approuvé.

Marge insuffisante

Consultez 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 accès ou couverture

Consultez GET /risk/limits?wallet=.... Certains niveaux n'autorisent que les ventes couvertes par un inventaire long déjà exécuté.
Contactez Hypercall si votre portefeuille a besoin d'un autre niveau.

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.

Étapes suivantes

Authentification : Authentification et signature
Protocole WebSocket : API WebSocket
Limites de débit : Limites de débit
Erreurs : Erreurs et motifs de rejet
Référence : Référence de l'API

Liste de contrôle d'intégration​

Modes d'intégration​

SDK TypeScript​

Crates Rust​

REST et WebSocket bruts​

1. Découvrir les marchés​

2. Configurer la signature​

3. Coter avec des ordres groupés​

4. Rafraîchir les cotations​

5. S'abonner aux mises à jour​

6. Rapprocher l'état​

7. Comprendre le périmètre de lancement​

Problèmes courants​

Échec de la vérification de signature​

Marge insuffisante​

Vente rejetée pour accès ou couverture​

Aucune exécution sur le WebSocket​

Étapes suivantes​