Ironflow: Hyperliquid data

Wallet positions at a past time

get_positions_at

Read-only

Exact perp positions one Hyperliquid wallet held at a past moment, up to 90 days back: market, side, signed size, mark price and notional at that moment, plus today's size and how many fills it made since. Built from Hyperliquid's live positions minus the wallet's fills after that moment, so sizes are exact across native and HIP-3 perps. Needs a free API key; how far back you can go follows the key's history window. Use it for questions like 'what was this wallet holding before the crash'. For positions right now use get_user_state; for trades in between use get_fills.

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": {
      "address": "<address>",
      "at": "<at>"
    },
    "name": "get_positions_at"
  }
}

Input Schema

Name	Required	Description	Default
`at`	Yes	The past moment: ISO 8601 (2026-11-01T12:00:00Z), unix seconds or unix milliseconds
`address`	Yes	0x-prefixed 20-byte hex address

Output Schema

Name	Required	Description
`at`	No	The moment, Unix milliseconds
`count`	No	Positions returned
`method`	No	How the sizes were rebuilt
`notice`	No	Present 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
`address`	No	Wallet address (0x…)
`positions`	No	Positions, largest notional first

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 4, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only declare readOnlyHint and openWorldHint, but the description adds material context beyond them: a free API key is required, the lookback is bounded (up to 90 days, following the key's history window), and the values are derived ('live positions minus the wallet's fills after that moment') with an exactness claim across native and HIP-3 perps. These are exactly the auth, limit, and derivation caveats an agent needs to avoid misusing the result.

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?

Purpose is front-loaded and every sentence carries information — no filler or restated title. The main cost is density: the opening sentence packs five returned fields plus a derivation caveat into one long clause chain, which slows parsing slightly.

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

Completeness5/5

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

An output schema exists, so return-format explanation is unnecessary, and the description instead covers the things structured fields cannot: auth requirement, lookback limit, derivation method, and sibling routing. For a two-parameter read tool this leaves no meaningful gap for correct invocation.

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

Parameters4/5

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

Schema coverage is 100% (both `address` and `at` are documented with formats), so the schema does the heavy lifting and baseline is 3. The description adds one constraint absent from the schema: the `at` moment must fall within the 90-day/history-window bound, which meaningfully qualifies valid values for that parameter.

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?

The description opens with a precise verb and resource ('Exact perp positions one Hyperliquid wallet held at a past moment') and enumerates the returned fields, so an agent knows exactly what this produces. It also explicitly distinguishes itself from two relevant siblings (get_user_state for current positions, get_fills for intervening trades).

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

Usage Guidelines5/5

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

It gives both a use-case framing ('what was this wallet holding before the crash') and a direct routing rule: 'For positions right now use get_user_state; for trades in between use get_fills.' When-to-use, when-not, and the named alternatives are all present.

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 tools Inspect

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.