info (perpAnnotation)
curl --request POST \
--url https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info \
--header 'Content-Type: application/json' \
--data '
{
"type": "perpAnnotation",
"coin": "xyz:GOLD"
}
'import requests
url = "https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info"
payload = {
"type": "perpAnnotation",
"coin": "xyz:GOLD"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({type: 'perpAnnotation', coin: 'xyz:GOLD'})
};
fetch('https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'type' => 'perpAnnotation',
'coin' => 'xyz:GOLD'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info"
payload := strings.NewReader("{\n \"type\": \"perpAnnotation\",\n \"coin\": \"xyz:GOLD\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info")
.header("Content-Type", "application/json")
.body("{\n \"type\": \"perpAnnotation\",\n \"coin\": \"xyz:GOLD\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"type\": \"perpAnnotation\",\n \"coin\": \"xyz:GOLD\"\n}"
response = http.request(request)
puts response.read_body{
"category": "<string>",
"description": "<string>"
}Hyperliquid node API
perpAnnotation | Hyperliquid info
The info endpoint with type: “perpAnnotation” retrieves the annotation metadata for a specific HIP-3 deployed perpetual asset. On Hyperliquid info.
POST
/
4f8d8f4040bdacd1577bff8058438274
/
info
info (perpAnnotation)
curl --request POST \
--url https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info \
--header 'Content-Type: application/json' \
--data '
{
"type": "perpAnnotation",
"coin": "xyz:GOLD"
}
'import requests
url = "https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info"
payload = {
"type": "perpAnnotation",
"coin": "xyz:GOLD"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({type: 'perpAnnotation', coin: 'xyz:GOLD'})
};
fetch('https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'type' => 'perpAnnotation',
'coin' => 'xyz:GOLD'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info"
payload := strings.NewReader("{\n \"type\": \"perpAnnotation\",\n \"coin\": \"xyz:GOLD\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info")
.header("Content-Type", "application/json")
.body("{\n \"type\": \"perpAnnotation\",\n \"coin\": \"xyz:GOLD\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"type\": \"perpAnnotation\",\n \"coin\": \"xyz:GOLD\"\n}"
response = http.request(request)
puts response.read_body{
"category": "<string>",
"description": "<string>"
}This method is available on Chainstack. Not all Hyperliquid methods are available on Chainstack, as the open-source node implementation does not support them yet — see Hyperliquid methods for the full availability breakdown.
info endpoint with type: "perpAnnotation" retrieves the annotation metadata for a specific HIP-3 deployed perpetual asset. Returns the deployer-set category and description for the given coin, or null if no annotation has been set.
Annotations are set by HIP-3 deployers using the setPerpAnnotation deployer action. Native Hyperliquid perps (BTC, ETH, etc.) are not HIP-3 deployed and will always return null.
Get your own node endpoint todayStart for free and get your app to production levels immediately. No credit card required.You can sign up with your GitHub, X, Google, or Microsoft account.
Parameters
Request body
type(string, required) — The request type. Must be"perpAnnotation".coin(string, required) — HIP-3 asset symbol indeployer:TICKERformat (e.g.,"xyz:GOLD","birb:PENGU"). Native perps like"BTC"always returnnull.
Response
Returns an annotation object when the deployer has set metadata, ornull if no annotation exists:
category(string) — Category label, at most 15 characters. The official Hyperliquid UI only displays categories from a predefined set (e.g.,"indices","commodities","ai","meme","defi").description(string) — Description text, at most 400 characters. Deployers can use this as an onchain spec or link to external documentation.
Example request
curl -X POST \
-H "Content-Type: application/json" \
-d '{"type": "perpAnnotation", "coin": "xyz:GOLD"}' \
https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info
from hyperliquid.info import Info
# The hyperliquid-python-sdk Info class has no dedicated perpAnnotation
# helper, so post the request type directly with the low-level post method.
info = Info("YOUR_CHAINSTACK_ENDPOINT", skip_ws=True)
annotation = info.post("/info", {"type": "perpAnnotation", "coin": "xyz:GOLD"})
print(annotation)
import { HttpTransport, InfoClient } from "@nktkas/hyperliquid";
const transport = new HttpTransport({ apiUrl: "YOUR_CHAINSTACK_ENDPOINT" });
const info = new InfoClient({ transport });
const annotation = await info.perpAnnotation({ coin: "xyz:GOLD" });
console.log(annotation);
Use your own endpoint in your code. The code examples use a placeholder Chainstack endpoint (YOUR_CHAINSTACK_ENDPOINT) — replace it with your own Hyperliquid node endpoint from the Chainstack console. The curl above uses a shared public endpoint for quick checks only; do not use it in production.
Example response
When an annotation exists:{
"category": "commodities",
"description": "Gold spot price tracking contract"
}
null
Use case
Theinfo endpoint with type: "perpAnnotation" is useful for:
- Displaying deployer-provided metadata about HIP-3 perpetual assets
- Building informational pages for deployed perpetual contracts
- Checking whether a perpetual has custom annotations before rendering UI
- Filtering HIP-3 assets by their deployer-assigned categories
Body
application/json
Last modified on June 24, 2026
Was this page helpful?