> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# perpAnnotation | Hyperliquid info

> The info endpoint with type: "perpAnnotation" retrieves the annotation metadata for a specific HIP-3 deployed perpetual asset. On Hyperliquid info.

<Info>
  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](/docs/hyperliquid-methods) for the full availability breakdown.
</Info>

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`.

## 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

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

  ```python Python (hyperliquid-python-sdk) theme={"system"}
  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)
  ```

  ```typescript TypeScript (@nktkas/hyperliquid) theme={"system"}
  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);
  ```
</CodeGroup>

<Note>
  **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](https://console.chainstack.com/). The curl above uses a shared public endpoint for quick checks only; do not use it in production.
</Note>

## Example response

When an annotation exists:

```json theme={"system"}
{
  "category": "commodities",
  "description": "Gold spot price tracking contract"
}
```

When no annotation has been set (or for native perps like BTC):

```json theme={"system"}
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


## OpenAPI

````yaml openapi/hyperliquid_node_api/hypercore_info/info_perp_annotation.json post /4f8d8f4040bdacd1577bff8058438274/info
openapi: 3.0.0
info:
  title: Hyperliquid Node API
  version: 1.0.0
  description: This is an API for interacting with Chainstack Hyperliquid node.
servers:
  - url: https://hyperliquid-mainnet.core.chainstack.com
security: []
paths:
  /4f8d8f4040bdacd1577bff8058438274/info:
    post:
      tags:
        - hyperliquid operations
      summary: info (perpAnnotation)
      operationId: infoPerpAnnotation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: Request type
                  default: perpAnnotation
                  enum:
                    - perpAnnotation
                coin:
                  type: string
                  description: >-
                    HIP-3 asset symbol in deployer:TICKER format (e.g.,
                    "xyz:GOLD"). Native perps like "BTC" always return null.
                  default: xyz:GOLD
              required:
                - type
                - coin
      responses:
        '200':
          description: Annotation metadata for the perpetual or null
          content:
            application/json:
              schema:
                nullable: true
                type: object
                properties:
                  category:
                    type: string
                    description: Category label, at most 15 characters
                  description:
                    type: string
                    description: Description text, at most 400 characters

````