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

Shell
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"type": "perpAnnotation", "coin": "xyz:GOLD"}' \
  https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info

​
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 February 17, 2026