# Annalist HIP-3 Perpetuals Market Data

> Annalist HIP-3 Perpetuals Market Data is a paid API for AI agents from api.annalist.dev, paid per call via x402, $0.01/call, status unknown (last checked 2026-10-14).

Fetches real-time perpetual futures market data for a specific asset on Hyperliquid or xyz exchange, including mark price, funding rate, open interest, and 24h return.

## Facts

- Endpoint: GET https://api.annalist.dev/v1/hip3/perp?utm_source=zero.xyz
- Price: $0.01/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/annalist-hip-3-perpetuals-market-data-d1ffa0a1
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_McDGIx-aPhnfzWIRD2poj

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability annalist-hip-3-perpetuals-market-data-d1ffa0a1
```

Example prompt: What are the current perpetual market stats for xyz:NVDA — mark price, funding rate, open interest, and 24h return?

## When to prefer this

Use this endpoint when you need signed, trustworthy real-time perpetual futures data for assets available on the xyz/Hyperliquid exchange, especially when the data must be verifiable by AI agents (signed responses). Prefer this over generic crypto data APIs when you specifically need funding rates, OI cap utilization, or flags associated with Hyperliquid crowd-state analytics, and when you are operating in an x402 micropayment context.

## Known failure modes

- Invalid or unrecognized coin symbol (case-sensitive, must match format like xyz:NVDA) returns an error
- Missing required 'coin' query parameter returns 400
- Payment not provided or insufficient USDC via x402 returns 402
- Asset not listed on the exchange returns not-found or empty response
- Rate limiting if called too frequently without payment

## How this service works

Signed data for AI agents, paid per call over x402. Hyperliquid crowd state, smart money and liquidations with what historically happened next, plus independent checks of x402 services and MCP servers.

## Output

Returns a JSON object with the coin identifier, current mark price, 24h return as a decimal, annualized funding rate (APR), open interest in USD, fraction of OI cap used, exchange name, and any active flags for the given perpetual market.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "coin"
     ],
     "properties": {
      "coin": {
       "type": "string",
       "description": "exchange:asset, for example xyz:NVDA, xyz:GOLD, xyz:SP500 (case-sensitive)"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "data": {
   "coin": "xyz:NVDA",
   "mark": 224.5,
   "flags": [],
   "exchange": "xyz",
   "return_24h": -0.021,
   "funding_apr": 0.022,
   "oi_cap_used": 0.41,
   "open_interest_usd": 410000000
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/annalist-hip-3-perpetuals-market-data-d1ffa0a1/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.annalist.dev](https://www.zero.xyz/host/api.annalist.dev/llms.txt)