Exchange 엔드포인트

Exchange 엔드포인트는 Hyperliquid 체인과 상호작용하고 거래하는 데 사용됩니다. 이러한 요청에 대한 서명을 생성하는 코드는 Python SDK를 참고하세요.

자산

많은 요청이 입력으로 asset을 받습니다. 무기한 선물(펍)의 경우 이는 meta 응답에서 반환되는 universe 필드의 인덱스입니다. 스팟 자산의 경우 10000 + index를 사용하며, 여기서 index는 spotMeta.universe의 해당 인덱스입니다. 예를 들어 PURR/USDC 주문을 제출할 때 사용해야 하는 asset은 10000입니다. 스팟 메타데이터에서 해당 자산의 인덱스가 0이기 때문입니다.

서브계정과 볼트

서브계정과 볼트에는 프라이빗 키가 없습니다. 서브계정 또는 볼트를 대신하여 작업을 수행하려면 마스터 계정이 서명해야 하며, vaultAddress 필드를 해당 서브계정 또는 볼트의 주소로 설정해야 합니다. Python SDK의 basic_vault.py 예제에서 이를 시연합니다.

Expires After

일부 액션은 선택적 필드 expiresAfter를 지원합니다. 이는 밀리초 단위의 타임스탬프로, 해당 시점 이후에는 액션이 거부됩니다. Core USDC transfer 같은 사용자 서명 액션은 expiresAfter 필드를 지원하지 않습니다. expiresAfter 필드가 만료되어 취소되는 액션은 일반 주소 기반 레이트 리밋의 5배를 소비한다는 점에 유의하세요.

서명 시 이 필드를 포함하는 방법에 대한 자세한 내용은 Python SDK를 참고하세요.

주문하기

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

주문 요청 필드에 대한 전체 기능을 갖춘 예제는 Python SDK를 참고하세요.

지정가 주문의 경우 TIF(time-in-force)는 주문이 오더북에 처음 닿았을 때의 동작을 결정합니다.

ALO(add liquidity only, 즉 "post only")는 즉시 체결되는 대신 취소됩니다.

IOC(immediate or cancel)는 미체결 부분이 오더북에 남는 대신 취소됩니다.

GTC(good til canceled) 주문에는 특별한 동작이 없습니다.

Client Order ID(cloid)는 선택적 128비트 16진수 문자열입니다. 예: 0x1234567890abcdef1234567890abcdef

헤더

요청 본문

{% tabs %}

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

{% endtab %}

{% tab title="200: OK 오류 응답" %}

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

{% endtab %}

{% tab title="200: OK 성공 응답 (filled)" %}

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

{% endtab %}

주문 취소

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

헤더

요청 본문

{% tabs %}

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

{% endtab %}

{% tab title="200: OK 오류 응답" %}

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

{% endtab %}

cancel과 cancelByCloid 액션 모두 선택적 fast 플래그를 포함하며, 액션에서 f로 인코딩됩니다. f: true인 주문은 트리거 주문을 참조하는 경우 거부됩니다. 현재 fast에는 다른 효과가 없습니다. 향후 네트워크 업그레이드에서는 fast = true인 경우에 한해서만 취소 액션이 멤풀에서 우선순위를 갖게 됩니다.

f가 false이면 생략해야 한다는 점에 유의하세요. 즉, f: false로 해싱된 액션은 거부됩니다.

cloid로 주문 취소

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

헤더

요청 본문

{% tabs %}

{% endtab %}

{% tab title="200: OK 오류 응답" %}

{% endtab %}

예약 취소(dead man's switch)

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

헤더

요청 본문

미래의 특정 시점에 전체 주문 취소 작업을 예약합니다. time을 포함하지 않으면 예약된 취소 작업이 제거됩니다. time은 현재 시간보다 최소 5초 이후여야 합니다. 해당 시각이 되면 미체결 주문이 모두 취소되고 트리거 횟수가 증가합니다. 하루 최대 트리거 횟수는 10회이며, 이 트리거 횟수는 00:00 UTC에 초기화됩니다.

주문 수정

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

헤더

요청 본문

{% tabs %}

{% endtab %}

{% tab title="200: OK 오류 응답" %}

{% endtab %}

단일 및 배치 수정 액션 모두 선택적 always_place 플래그를 포함하며, 액션에서 a로 인코딩됩니다. always_place = true이면 취소 성공 여부와 관계없이 새 주문이 제출됩니다. always_place = false이면 새 주문은 트리거 주문이 아니어야 하며, TIF = ALO이거나 체결 불가능한 TIF = GTC 주문이어야 합니다. 후자의 경우 새 주문의 TIF는 ALO로 재정의됩니다.

a가 false이면 생략해야 한다는 점에 유의하세요. 즉, a: false로 해싱된 액션은 거부됩니다.

여러 주문 수정

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

헤더

요청 본문

레버리지 업데이트

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

코인의 크로스 또는 격리 레버리지를 업데이트합니다.

헤더

요청 본문

{% tabs %}

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

{% endtab %}

격리 마진 업데이트

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

격리 포지션에서 마진을 추가하거나 제거합니다.

마진 변경의 USDC 값 대신 특정 레버리지를 목표로 하려면 대체 액션 {"type": "topUpIsolatedOnlyMargin", "asset": <asset>, "leverage": <float string>}을 사용할 수 있습니다.

헤더

요청 본문

{% tabs %}

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

{% endtab %}

자산 전송

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

이 범용 메서드는 서로 다른 펍 DEX, 스팟 잔고, 사용자 및/또는 서브계정 간에 토큰을 전송하는 데 사용됩니다. 기본 USDC 펍 DEX를 지정하려면 ""를, 스팟을 지정하려면 "spot"을 사용하세요. 펍 DEX로 또는 펍 DEX에서 전송할 수 있는 것은 담보 토큰뿐입니다.

헤더

본문

응답

{% tabs %}

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

{% endtab %}

에이전트 자산 전송

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

자산 전송과 유사하지만 에이전트가 서명할 수 있습니다. destination은 반드시 소스 주소와 일치해야 합니다. 기본 USDC 펍 DEX를 지정하려면 ""를, 스팟을 지정하려면 "spot"을 사용하세요. 펍 DEX로 또는 펍 DEX에서 전송할 수 있는 것은 담보 토큰뿐입니다.

헤더

본문

응답

{% tabs %}

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

{% endtab %}

데이터와 함께 EVM으로 전송

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

추가 데이터 페이로드를 포함하는 Core에서 EVM으로의 전송을 위한 전문 액션입니다. 자세한 내용은 HyperCore <> HyperEVM 전송을 참고하세요. 사용 시 연결된 컨트랙트에서 transfer 대신 coreReceiveWithData가 호출됩니다. 중요: 토큰이 올바르게 연결(link)되어 있고 연결된 컨트랙트가 다음 인터페이스를 지원하는지 확인하는 것은 호출자의 책임입니다:

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

헤더

본문

응답

{% tabs %}

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

{% endtab %}

Core USDC 전송

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

다른 주소로 USD를 전송합니다. 이 전송은 EVM 브리지를 거치지 않습니다. 서명 형식은 지갑 인터페이스용으로 사람이 읽을 수 있는 형식입니다.

헤더

요청 본문

{% tabs %}

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

{% endtab %}

Core 스팟 전송

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

다른 주소로 스팟 자산을 전송합니다. 이 전송은 EVM 브리지를 거치지 않습니다. 서명 형식은 지갑 인터페이스용으로 사람이 읽을 수 있는 형식입니다.

헤더

요청 본문

{% 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"
  }
}

출금 요청 시작

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

이 메서드는 출금 플로우를 시작하는 데 사용됩니다. 이 요청을 하면 L1 검증인들이 서명하여 출금 요청을 브리지 컨트랙트로 전송합니다. 작성 시점 기준 출금 수수료는 $1이며, 출금이 최종 확정되기까지 약 5분이 걸립니다.

헤더

요청 본문

{% tabs %}

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

{% endtab %}

스팟 계정에서 펍 계정으로 전송(및 그 반대)

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

이 메서드는 사용자의 스팟 지갑에서 펍 지갑으로 USDC를 전송하거나 그 반대로 전송하는 데 사용됩니다.

헤더

본문

응답

{% tabs %}

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

{% endtab %}

스테이킹 입금

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

이 메서드는 사용자의 스팟 계정에서 검증인에게 위임하기 위한 스테이킹으로 네이티브 토큰을 전송하는 데 사용됩니다.

헤더

본문

응답

{% tabs %}

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

{% endtab %}

스테이킹 입금(에이전트)

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

스테이킹 입금과 유사하지만 에이전트가 서명할 수 있습니다.

헤더

본문

응답

{% tabs %}

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

{% endtab %}

스테이킹 출금

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

이 메서드는 스테이킹에서 사용자의 스팟 계정으로 네이티브 토큰을 전송하는 데 사용됩니다. 스테이킹에서 스팟 계정으로의 전송은 7일간의 언스테이킹 대기열을 거친다는 점에 유의하세요.

헤더

본문

응답

{% tabs %}

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

{% endtab %}

검증인에게 스테이크 위임 또는 위임 취소

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

검증인에게 네이티브 토큰을 위임하거나 위임을 취소합니다. 특정 검증인에 대한 위임에는 1일의 잠금 기간이 있다는 점에 유의하세요.

헤더

본문

응답

{% tabs %}

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

{% endtab %}

볼트 입금 또는 출금

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

볼트에서 자금을 추가하거나 제거합니다.

헤더

본문

응답

{% tabs %}

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

{% endtab %}

HIP-3 DEX 백스톱 청산인 입금 또는 출금

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

HIP-3 백스톱 청산인 주소에서 자금을 추가하거나 제거합니다. ntl은 1e-6 호가 자산 단위의 정수입니다. 금액은 1000 호가 자산의 배수여야 합니다(즉, ntl % 1000000000 == 0).

원금만 출금할 수 있으며 PnL은 출금할 수 없습니다.

헤더

본문

응답

{% tabs %}

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

{% endtab %}

API 지갑 승인

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

API 지갑(때때로 에이전트 지갑이라고도 불림)을 승인합니다. 자세한 내용은 여기를 참고하세요.

헤더

본문

응답

{% tabs %}

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

{% endtab %}

Builder 수수료 승인

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

Builder에 대한 최대 수수료율을 승인합니다.

헤더

본문

응답

{% tabs %}

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

{% endtab %}

TWAP 주문 제출

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

헤더

요청 본문

{% tabs %}

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

{% endtab %}

{% tab title="200: OK 오류 응답" %}

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

{% endtab %}

TWAP 주문 취소

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

헤더

요청 본문

{% tabs %}

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

{% endtab %}

{% tab title="200: OK 오류 응답" %}

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

{% endtab %}

트레일링 스톱 주문 제출

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

헤더

요청 본문

{% tabs %}

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

{% endtab %}

추가 액션 예약

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

거래를 통해 주소 기반 레이트 리밋을 늘리는 대신, 이 액션은 요청당 0.0005 USDC의 비용으로 추가 액션을 예약할 수 있게 합니다. 비용은 펍(Perps) 잔고에서 지불됩니다.

destination을 설정하면 다른 L1 사용자의 비용을 지불할 수 있습니다. 대상 사용자가 이미 존재해야 합니다. 이 필드는 설정되지 않은 경우 해싱에서 생략됩니다.

헤더

요청 본문

{% tabs %}

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

{% endtab %}

대기 중인 Nonce 무효화(noop)

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

이 액션은 아무 작업도 수행하지 않지만(no operation) nonce가 사용된 것으로 표시됩니다. 이는 취소 액션보다 진행 중인 주문을 취소하는 더 효과적인 방법이 될 수 있습니다.

헤더

요청 본문

{% tabs %}

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

{% endtab %}

HIP-3 DEX 추상화 활성화

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

참고: 지원 중단되었습니다. userSetAbstraction을 사용하는 것을 권장합니다.

설정하면 HIP-3 펍에 대한 액션 시, USDC가 담보 토큰인 HIP-3 DEX의 경우 검증인이 운영하는 USDC 펍 잔고에서, 그 외의 경우 스팟에서 담보가 자동으로 전송됩니다. HIP-3 DEX 추상화가 활성화되어 있으면 포지션 또는 미체결 주문에서 해제될 때 담보는 동일한 출처(검증인 운영 USDC 펍 또는 스팟 잔고)로 반환됩니다.

헤더

요청 본문

{% tabs %}

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

{% endtab %}

HIP-3 DEX 추상화 활성화(에이전트)

참고: 지원 중단되었습니다. agentSetAbstraction을 사용하는 것을 권장합니다.

위의 UserDexAbstraction와 동일한 효과이지만, 값을 null에서 true로 설정하는 경우에만 작동합니다.

헤더

요청 본문

{% tabs %}

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

{% endtab %}

사용자 추상화 설정

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

헤더

요청 본문

{% tabs %}

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

{% endtab %}

사용자 추상화 설정(에이전트)

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

헤더

요청 본문

{% tabs %}

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

{% endtab %}

결과 분할

X 호가 자산을 X Yes와 X No shares로 분할합니다.

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

헤더

요청 본문

{% tabs %}

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

{% endtab %}

결과 병합

X Yes와 X No shares를 X 호가 자산으로 병합합니다.

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

헤더

요청 본문

{% tabs %}

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

{% endtab %}

질문 병합

동일한 질문에 연결된 각 결과의 Yes shares X개를 X 호가 자산으로 병합합니다.

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

헤더

요청 본문

{% tabs %}

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

{% endtab %}

결과 반전

질문에 연결된 한 결과의 No shares X개를 해당 질문에 연결된 다른 모든 결과의 Yes shares X개로 변환합니다.

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

헤더

요청 본문

{% tabs %}

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

{% endtab %}

정렬된 호가 자산의 무위험 이자율에 대한 검증인 투표

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

헤더

요청 본문

{% tabs %}

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

{% endtab %}

AQAv2 역할 승인

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

헤더

요청 본문

{% tabs %}

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

{% endtab %}

리워드 청구

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

헤더

요청 본문

{% tabs %}

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

{% endtab %}