Skip to main content
Glama
Sign In

Ironflow: Hyperliquid data

by io.github.ironflowsh
OverviewDiscussionsAdmin

Mark against oracle premium

get_premium
Read-only

A Hyperliquid perp's mark price against its oracle price over time, with the premium in basis points ((mark / oracle - 1) x 10,000) per bucket and a summary (latest, mean, min, max). On HIP-3 stock, index and commodity perps such as xyz:NVDA-PERP, xyz:GOLD-PERP or xyz:SP500-PERP the oracle follows the underlying, so this shows how far the perp trades from what it tracks, weekends included. Default 1h buckets over the last 7 days. For funding payments use get_funding_rates.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "market": "<market>"
    },
    "name": "get_premium"
  }
}

Input Schema

NameRequiredDescriptionDefault
daysNoHow many days back (default 7; limited by your key's history window)
marketYesMarket: BTC-PERP, xyz:NVDA-PERP, HYPE/USDC, or a Hyperliquid name (BTC, @107, xyz:NVDA)
intervalNoBucket size (default 1h)

Output Schema

NameRequiredDescriptionDefault
dataNoBuckets, oldest first
marketNoDisplay symbol, e.g. "BTC-PERP" or "xyz:NVDA-PERP"
noticeNoPresent when the API added a note: how a market name was read, that data starts later than asked because of the history window, or a next step such as a free key
summaryNoPremium over the window, in basis points
intervalNoBucket size

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds the analytical semantics (basis-point premium per bucket, summary statistics) and the default window. It does not mention the key's history-window limit that constrains how far back results go — that constraint lives only in the schema field for days.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core computation, then interpretation guidance, then the default window and the sibling pointer. Dense but each clause carries information; the HIP-3 example list is slightly long but justifies itself by clarifying the oracle behavior for those markets.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description needn't explain return values, and it correctly focuses on interpretation, defaults, and alternatives. The only meaningful omission is the history-window constraint on the days parameter, though that is at least visible in the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and all three parameters are documented in the schema, including the enum for interval and the flexible market-name forms. The description restates the defaults (1h buckets, last 7 days) and shows market-format examples, but adds no format or behavior detail beyond what the schema already provides — baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource and computation: a perp's mark price against its oracle price over time, with the premium in basis points defined by an explicit formula ((mark / oracle - 1) x 10,000) plus a summary of latest/mean/min/max. It also names the concrete use case for HIP-3 stock/index/commodity perps, which separates it from generic price tools like get_price or get_mark_prices.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent away from this tool for one adjacent need: 'For funding payments use get_funding_rates.' It also supplies context on when the oracle-following behavior matters (HIP-3 stock/index/commodity perps, weekends included). It stops short of stating exclusions for the many other siblings (get_candles, get_price, get_mark_prices), so it is clear but not exhaustive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Ironflow: Hyperliquid data toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources