> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/rest-api/metadata/batchperpannotations.md).

# batchPerpAnnotations

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](/readme/rest-api/metadata/perpannotation.md) — results are returned as an object keyed by coin.

## POST Request

<table><thead><tr><th width="163">Field</th><th width="135">Type</th><th width="471">Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>string</td><td>Must be <code>"batchPerpAnnotations"</code></td></tr><tr><td><code>coins</code></td><td>array</td><td>Array of perp asset names, including the DEX prefix for builder-deployed perps (e.g. <code>"xyz:TSLA"</code>). Required, non-empty. Only perp assets are accepted — spot and outcome markets are rejected. Duplicates are de-duplicated.</td></tr></tbody></table>

### Limits

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

{% tabs %}
{% tab title="cURL" %}

```bash
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"]
  }'
```

{% endtab %}

{% tab title="Python" %}

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

{% endtab %}

{% tab title="Javascript" %}

```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));
```

{% endtab %}
{% endtabs %}

***

## Response Fields

| Field          | Type   | Description                                                                                                                                                                                                                                  |
| -------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `annotations`  | object | Map of `coin` → annotation payload. Each value is the same object returned by [perpAnnotation](/readme/rest-api/metadata/perpannotation.md) (`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`.

<details>

<summary>Response</summary>

```json
{
  "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": []
}
```

</details>