Skip to main content
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.
The 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 in deployer:TICKER format (e.g., "xyz:GOLD", "birb:PENGU"). Native perps like "BTC" always return null.

Response

Returns an annotation object when the deployer has set metadata, or null 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"
}
When no annotation has been set (or for native perps like BTC):
null

Use case

The info 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
type
enum<string>
default:perpAnnotation
required

Request type

Available options:
perpAnnotation
coin
string
default:xyz:GOLD
required

HIP-3 asset symbol in deployer:TICKER format (e.g., "xyz:GOLD"). Native perps like "BTC" always return null.

Response

200 - application/json
object | null

Annotation metadata for the perpetual or null

category
string

Category label, at most 15 characters

description
string

Description text, at most 400 characters

Last modified on June 24, 2026