batchPerpAnnotations

Get human-readable annotations for multiple perpetual assets in a single request.

Returns the human-readable annotation (category, description, display name, and keywords) for multiple perpetual assets in a single request. This is the batched form of perpAnnotation — results are returned as an object keyed by coin.

POST Request

Field	Type	Description
type	string	Must be "batchPerpAnnotations"
coins	array	Array of perp asset names, including the DEX prefix for builder-deployed perps (e.g. "xyz:TSLA"). Required, non-empty. Only perp assets are accepted — spot and outcome markets are rejected. Duplicates are de-duplicated.

Limits

You can query up to 100 coins at once. Requests exceeding this are rejected with a 400 error.

cURL

curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "batchPerpAnnotations",
    "coins": ["xyz:TSLA", "xyz:NVDA"]
  }'

Python

import requests
import os
import json

response = requests.post(
    'https://api.hydromancer.xyz/info',
    json={
        'type': 'batchPerpAnnotations',
        'coins': ['xyz:TSLA', 'xyz:NVDA']
    },
    headers={
        'Authorization': f'Bearer {os.environ["HYDROMANCER_API_KEY"]}',
        'Content-Type': 'application/json'
    }
)
print(json.dumps(response.json(), indent=2))

Javascript

import axios from 'axios';

const response = await axios.post(
  'https://api.hydromancer.xyz/info',
  {
    type: 'batchPerpAnnotations',
    coins: ['xyz:TSLA', 'xyz:NVDA']
  },
  {
    headers: {
      'Authorization': `Bearer ${process.env.HYDROMANCER_API_KEY}`,
      'Content-Type': 'application/json'
    }
  }
);

console.log(JSON.stringify(response.data, null, 2));

---

Response Fields

Field	Type	Description
annotations	object	Map of coin → annotation payload. Each value is the same object returned by perpAnnotation (category, description, displayName, keywords), or null if the perp has no annotation.
failed_coins	array	Coins whose underlying request failed (transport/HTTP error). Distinct from a successful null annotation.

A coin with no annotation appears in annotations with a null value — it is not a failure. Only coins whose node request errored land in failed_coins.

Response

{
  "annotations": {
    "xyz:TSLA": {
      "category": "stocks",
      "description": "TSLA tracks the value of 1 share of common stock in Tesla, Inc.",
      "displayName": "TSLA",
      "keywords": ["tesla", "ev"]
    },
    "xyz:NVDA": {
      "category": "stocks",
      "description": "NVDA tracks the value of 1 share of common stock in NVIDIA Corporation.",
      "displayName": "NVDA",
      "keywords": ["nvidia", "gpu", "ai"]
    }
  },
  "failed_coins": []
}