Endpoint exchange

L'endpoint exchange viene utilizzato per interagire con la chain Hyperliquid e per effettuare trading su di essa. Il codice per generare le firme relative a queste richieste è disponibile nel Python SDK.

Asset

Molte delle richieste accettano asset come input. Per i perpetual corrisponde all'indice nel campo universe restituito dalla risposta meta. Per gli asset spot, utilizzare 10000 + index, dove index è l'indice corrispondente in spotMeta.universe. Ad esempio, quando si invia un ordine per PURR/USDC, l'asset da utilizzare è 10000 perché il suo indice nei metadata spot è 0.

Subaccount e vault

I subaccount e i vault non dispongono di chiavi private. Per eseguire azioni per conto di un subaccount o di un vault, la firma deve essere effettuata dall'account master e il campo vaultAddress deve essere impostato sull'indirizzo del subaccount o del vault. L'esempio basic_vault.py nel Python SDK illustra questa procedura.

Scadenza

Alcune azioni supportano un campo facoltativo expiresAfter, un timestamp in millisecondi oltre il quale l'azione viene rifiutata. Le azioni firmate dall'utente, come il trasferimento Core USDC, non supportano il campo expiresAfter. Si noti che le azioni consumano 5 volte il consueto limite di frequenza basato sull'indirizzo quando vengono annullate a causa di un campo expiresAfter obsoleto.

Per i dettagli su come integrare questo campo durante la firma, consultare il Python SDK.

Inserire un ordine

POST https://api.hyperliquid.xyz/exchange

Per esempi completi sui campi della richiesta di ordine, consultare il Python SDK.

Per gli ordini limite, il TIF (time-in-force) determina il comportamento dell'ordine quando raggiunge per la prima volta il book degli ordini.

ALO (add liquidity only, ovvero "post only") viene annullato invece di essere abbinato immediatamente.

IOC (immediate or cancel) annulla la parte non eseguita invece di lasciarla in attesa nel book.

Gli ordini GTC (good til canceled) non presentano comportamenti particolari.

Il Client Order ID (cloid) è una stringa esadecimale facoltativa a 128 bit, ad es. 0x1234567890abcdef1234567890abcdef

Intestazioni

Corpo della richiesta

{% tabs %}

{
   "status":"ok",
   "response":{
      "type":"order",
      "data":{
         "statuses":[
            {
               "resting":{
                  "oid":77738308
               }
            }
         ]
      }
   }
}

{% endtab %}

{% tab title="200: OK Error Response" %}

{
   "status":"ok",
   "response":{
      "type":"order",
      "data":{
         "statuses":[
            {
               "error":"Order must have minimum value of $10."
            }
         ]
      }
   }
}

{% endtab %}

{% tab title="200: OK Successful Response (filled)" %}

{
   "status":"ok",
   "response":{
      "type":"order",
      "data":{
         "statuses":[
            {
               "filled":{
                  "totalSz":"0.02",
                  "avgPx":"1891.4",
                  "oid":77747314
               }
            }
         ]
      }
   }
}

{% endtab %}

Annullare gli ordini

POST https://api.hyperliquid.xyz/exchange

Intestazioni

Corpo della richiesta

{% tabs %}

{
   "status":"ok",
   "response":{
      "type":"cancel",
      "data":{
         "statuses":[
            "success"
         ]
      }
   }
}

{% endtab %}

{% tab title="200: OK Error Response" %}

{
   "status":"ok",
   "response":{
      "type":"cancel",
      "data":{
         "statuses":[
            {
               "error":"Order was never placed, already canceled, or filled."
            }
         ]
      }
   }
}

{% endtab %}

Sia l'azione cancel sia cancelByCloid includono un flag fast facoltativo, codificato come f nell'azione. Gli ordini con f: true vengono rifiutati se si riferiscono a ordini trigger. Attualmente fast non ha altri effetti. In un futuro aggiornamento della rete, le azioni di annullamento saranno trattate con priorità nel mempool se e solo se fast = true.

Si noti che f deve essere omesso se false, ovvero le azioni con hash f: false verranno rifiutate.

Annullare gli ordini per cloid

POST https://api.hyperliquid.xyz/exchange

Intestazioni

Corpo della richiesta

{% tabs %}

{% endtab %}

{% tab title="200: OK Error Response" %}

{% endtab %}

Pianificare l'annullamento (dead man's switch)

POST https://api.hyperliquid.xyz/exchange

Intestazioni

Corpo della richiesta

Pianificare un'operazione di annullamento totale per un istante futuro. Se non si include time, l'annullamento pianificato viene rimosso. L'istante deve essere almeno 5 secondi successivo a quello corrente. Al sopraggiungere dell'istante, tutti gli ordini aperti vengono annullati e un contatore di attivazioni viene incrementato. Il numero massimo di attivazioni al giorno è 10. Questo contatore viene azzerato alle 00:00 UTC.

Modificare un ordine

POST https://api.hyperliquid.xyz/exchange

Intestazioni

Corpo della richiesta

{% tabs %}

{% endtab %}

{% tab title="200: OK Error Response" %}

{% endtab %}

Sia le azioni di modifica singole sia quelle in batch includono un flag always_place facoltativo, codificato come a nell'azione. Quando always_place = true, il nuovo ordine viene inserito indipendentemente dall'esito dell'annullamento. Quando always_place = false, il nuovo ordine deve essere un ordine non trigger e deve avere TIF = ALO oppure essere un ordine non eseguibile con TIF = GTC. In quest'ultimo caso, il TIF del nuovo ordine viene sovrascritto ad ALO.

Si noti che a deve essere omesso se false, ovvero le azioni con hash a: false verranno rifiutate.

Modifica di più ordini

POST https://api.hyperliquid.xyz/exchange

Intestazioni

Corpo della richiesta

Aggiornamento della leva

POST https://api.hyperliquid.xyz/exchange

Aggiornare la leva incrociata o isolata su un coin.

Intestazioni

Corpo della richiesta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Aggiornamento del margine isolato

POST https://api.hyperliquid.xyz/exchange

Aggiungere o rimuovere margine da una posizione isolata

Si noti che, per puntare a una leva specifica invece che a un valore USDC di variazione del margine, è disponibile un'action alternativa {"type": "topUpIsolatedOnlyMargin", "asset": <asset>, "leverage": <float string>}

Intestazioni

Corpo della richiesta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Invio di asset

POST https://api.hyperliquid.xyz/exchange

Questo metodo generalizzato consente di trasferire token tra diversi perp DEX, il saldo spot, utenti e/o sub-account. Utilizzare "" per specificare il perp DEX USDC predefinito e "spot" per specificare lo spot. Solo il token collateral può essere trasferito verso o da un perp DEX.

Intestazioni

Corpo

Risposta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Invio di asset tramite agent

POST https://api.hyperliquid.xyz/exchange

Simile a send asset, ma può essere firmato da un agent. La destination deve corrispondere all'indirizzo di origine. Utilizzare "" per specificare il perp DEX USDC predefinito e "spot" per specificare lo spot. Solo il token collateral può essere trasferito verso o da un perp DEX.

Intestazioni

Corpo

Risposta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Invio a EVM con dati

POST https://api.hyperliquid.xyz/exchange

Action specializzata per il trasferimento da Core a EVM che include un payload di dati aggiuntivo. Per ulteriori dettagli, consultare Trasferimenti HyperCore <> HyperEVM. Quando utilizzata, sul contratto collegato verrà chiamata coreReceiveWithData invece di transfer. IMPORTANTE: è responsabilità del chiamante assicurarsi che il token sia correttamente collegato e che il contratto collegato supporti la seguente interfaccia:

interface ICoreReceiveWithData {
  function coreReceiveWithData(
    address from,
    bytes32 destinationRecipient,
    uint32 destinationChainId,
    uint256 amount,
    uint64 nonce,
    bytes calldata data
  ) external;
}

Intestazioni

Corpo

Risposta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Trasferimento di USDC su Core

POST https://api.hyperliquid.xyz/exchange

Inviare usd a un altro indirizzo. Questo trasferimento non interessa il bridge EVM. Il formato della firma è leggibile per le interfacce wallet.

Intestazioni

Corpo della richiesta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Trasferimento spot Core

POST https://api.hyperliquid.xyz/exchange

Inviare asset spot a un altro indirizzo. Questo trasferimento non interessa il bridge EVM. Il formato della firma è leggibile in chiaro per le interfacce wallet.

Intestazioni

Corpo della richiesta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Example sign typed data for generating the signature:
{
  "types": {
    "HyperliquidTransaction:SpotSend": [
      {
        "name": "hyperliquidChain",
        "type": "string"
      },
      {
        "name": "destination",
        "type": "string"
      },
      {
        "name": "token",
        "type": "string"
      },
      {
        "name": "amount",
        "type": "string"
      },
      {
        "name": "time",
        "type": "uint64"
      }
    ]
  },
  "primaryType": "HyperliquidTransaction:SpotSend",
  "domain": {
    "name": "HyperliquidSignTransaction",
    "version": "1",
    "chainId": 42161,
    "verifyingContract": "0x0000000000000000000000000000000000000000"
  },
  "message": {
    "destination": "0x0000000000000000000000000000000000000000",
    "token": "PURR:0xc1fb593aeffbeb02f85e0308e9956a90",
    "amount": "0.1",
    "time": 1716531066415,
    "hyperliquidChain": "Mainnet"
  }
}

Avviare una richiesta di prelievo

POST https://api.hyperliquid.xyz/exchange

Questo metodo viene utilizzato per avviare il flusso di prelievo. Dopo questa richiesta, i validatori L1 firmano e inviano la richiesta di prelievo al contratto bridge. Al momento della stesura di questo documento è prevista una commissione di $1 per il prelievo e i prelievi richiedono circa 5 minuti per essere finalizzati.

Intestazioni

Corpo della richiesta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Trasferimento dall'account spot all'account perp (e viceversa)

POST https://api.hyperliquid.xyz/exchange

Questo metodo viene utilizzato per trasferire USDC dal wallet spot dell'utente al wallet perp e viceversa.

Intestazioni

Corpo

Risposta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Deposito in staking

POST https://api.hyperliquid.xyz/exchange

Questo metodo viene utilizzato per trasferire il token nativo dall'account spot dell'utente allo staking per la delega ai validatori.

Intestazioni

Corpo

Risposta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Deposito in staking (agent)

POST https://api.hyperliquid.xyz/exchange

Simile al deposito in staking, ma può essere firmato da un agent.

Intestazioni

Corpo

Risposta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Prelievo dallo staking

POST https://api.hyperliquid.xyz/exchange

Questo metodo viene utilizzato per trasferire il token nativo dallo staking all'account spot dell'utente. Si noti che i trasferimenti dallo staking all'account spot passano attraverso una coda di unstaking di 7 giorni.

Intestazioni

Corpo

Risposta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Delegare o revocare lo stake da un validatore

POST https://api.hyperliquid.xyz/exchange

Delegare o revocare la delega di token nativi a o da un validatore. Si noti che le deleghe a un determinato validatore hanno una durata di blocco di 1 giorno.

Intestazioni

Corpo

Risposta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Deposito o prelievo da un vault

POST https://api.hyperliquid.xyz/exchange

Aggiungere o rimuovere fondi da un vault.

Intestazioni

Corpo

Risposta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Deposito o prelievo dal backstop liquidator di una HIP-3 DEX

POST https://api.hyperliquid.xyz/exchange

Aggiungere o rimuovere fondi dall'indirizzo del backstop liquidator HIP-3. ntl è un numero intero in unità di 1e-6 token di quotazione. L'importo deve essere un multiplo di 1000 token di quotazione (ovvero ntl % 1000000000 == 0).

È prelevabile solo l'importo del capitale, non il pnl.

Intestazioni

Corpo

Risposta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Approvare un wallet API

POST https://api.hyperliquid.xyz/exchange

Approva un wallet API (talvolta indicato anche come wallet agent). Per ulteriori dettagli, consultare qui.

Intestazioni

Corpo

Risposta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Approvare una commissione builder

POST https://api.hyperliquid.xyz/exchange

Approvare un tasso di commissione massimo per un builder.

Intestazioni

Corpo della richiesta

Risposta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Inserire un ordine TWAP

POST https://api.hyperliquid.xyz/exchange

Intestazioni

Corpo della richiesta

{% tabs %}

{
   "status":"ok",
   "response":{
      "type":"twapOrder",
      "data":{
         "status": {
            "running":{
               "twapId":77738308
            }
         }
      }
   }
}

{% endtab %}

{% tab title="200: OK Error Response" %}

{
   "status":"ok",
   "response":{
      "type":"twapOrder",
      "data":{
         "status": {
            "error":"Invalid TWAP duration: 1 min(s)"
         }
      }
   }
}

{% endtab %}

Annullare un ordine TWAP

POST https://api.hyperliquid.xyz/exchange

Intestazioni

Corpo della richiesta

{% tabs %}

{
   "status":"ok",
   "response":{
      "type":"twapCancel",
      "data":{
         "status": "success"
      }
   }
}

{% endtab %}

{% tab title="200: OK Error Response" %}

{
   "status":"ok",
   "response":{
      "type":"twapCancel",
      "data":{
         "status": {
            "error": "TWAP was never placed, already canceled, or filled."
         }
      }
   }
}

{% endtab %}

Inserire un ordine trailing stop

POST https://api.hyperliquid.xyz/exchange

Intestazioni

Corpo della richiesta

{% tabs %}

{
   "status":"ok",
   "response":{
      "type":"trailingStop",
      "data":{
         "oid":77738308
      }
   }
}

{% endtab %}

Riservare action aggiuntive

POST https://api.hyperliquid.xyz/exchange

Invece di effettuare trading per aumentare i limiti di frequenza basati sull'indirizzo, questa action consente di riservare action aggiuntive al costo di 0.0005 USDC per richiesta. Il costo viene addebitato al saldo Perps.

destination può essere impostato per pagare per conto di un altro utente L1. L'utente di destinazione deve già esistere. Questo campo viene ignorato nell'hashing se non è impostato.

Intestazioni

Corpo della richiesta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Invalidare il nonce in sospeso (noop)

POST https://api.hyperliquid.xyz/exchange

Questa action non esegue alcuna operazione (no operation), ma fa sì che il nonce venga contrassegnato come utilizzato. Può essere un modo più efficace per annullare gli ordini in corso rispetto all'action di annullamento.

Intestazioni

Corpo della richiesta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Abilitare l'astrazione HIP-3 DEX

POST https://api.hyperliquid.xyz/exchange

NOTA: deprecato. Preferire userSetAbstraction.

Se impostata, le action sui perpetual HIP-3 trasferiranno automaticamente le garanzie dal saldo perpetual USDC gestito dai validatori per gli HIP-3 DEX in cui USDC è il token di garanzia, e da spot negli altri casi. Quando l'astrazione HIP-3 DEX è attiva, le garanzie vengono restituite alla stessa origine (saldo perpetual USDC gestito dai validatori o saldo spot) quando vengono liberate da posizioni o ordini aperti.

Intestazioni

Corpo della richiesta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Abilitare l'astrazione HIP-3 DEX (agent)

NOTA: deprecato. Preferire agentSetAbstraction.

Stesso effetto di UserDexAbstraction sopra, ma funziona solo se si imposta il valore da null a true.

Intestazioni

Corpo della richiesta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Impostare l'astrazione utente

POST https://api.hyperliquid.xyz/exchange

Intestazioni

Corpo della richiesta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Impostare l'astrazione utente (agent)

POST https://api.hyperliquid.xyz/exchange

Intestazioni

Corpo della richiesta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Suddividere outcome

Suddividere X token di quotazione in X quote Yes e X quote No.

POST https://api.hyperliquid.xyz/exchange

Intestazioni

Corpo della richiesta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Unire outcome

Unire X quote Yes e X quote No in X token di quotazione.

POST https://api.hyperliquid.xyz/exchange

Intestazioni

Corpo della richiesta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Unire question

Unire le X quote Yes di ogni outcome associato alla stessa question in X token di quotazione.

POST https://api.hyperliquid.xyz/exchange

Intestazioni

Corpo della richiesta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Negazione dell'outcome

Converti X azioni No da un outcome associato a una domanda in X azioni Yes di ogni altro outcome associato alla domanda.

POST https://api.hyperliquid.xyz/exchange

Intestazioni

Corpo della richiesta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Voto del validatore sul tasso privo di rischio per l'asset di quotazione allineato

POST https://api.hyperliquid.xyz/exchange

Intestazioni

Corpo della richiesta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Autorizzazione del ruolo AQAv2

POST https://api.hyperliquid.xyz/exchange

Intestazioni

Corpo della richiesta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}

Riscossione delle ricompense

POST https://api.hyperliquid.xyz/exchange

Intestazioni

Corpo della richiesta

{% tabs %}

{'status': 'ok', 'response': {'type': 'default'}}

{% endtab %}