# Hyperliquid Trader Position Lifecycles

> Hyperliquid Trader Position Lifecycles is a paid API for AI agents from hyperliquid-data.v1337.org, paid per call via x402, $0.001/call, status unknown (last checked 2026-09-15).

Returns the full position lifecycle history for a given Hyperliquid wallet address, including open, closed, and liquidated perpetual positions derived from the node_fills ledger.

## Facts

- Endpoint: POST https://hyperliquid-data.v1337.org/v1/traders/%7Baddress%7D/lifecycles
- Price: $0.001/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/hyperliquid-trader-position-lifecycles-d1c16523
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_ymaxkSkQBthf22_0CGbnt

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 hyperliquid-trader-position-lifecycles-d1c16523 -d '<json body>'
```

Example prompt: Pull the full position lifecycle history for Hyperliquid wallet 0x1234567890abcdef1234567890abcdef12345678 — I want to see every perp position they've opened, closed, or got liquidated on.

## When to prefer this

Choose this endpoint when you need the complete cradle-to-grave lifecycle of every perpetual position for a specific Hyperliquid wallet, sourced first-party from the node_fills ledger rather than third-party aggregators. It is preferable over generic on-chain explorers because it provides Hyperliquid-specific position semantics (entry, exit, liquidation events) in a single structured response, and requires no API key — only a micropayment of $0.001 USDC via x402 on Base.

## Known failure modes

- Invalid or malformed wallet address returns a 4xx error
- Address with no trading history returns an empty result set
- x402 payment failure (insufficient USDC balance or incorrect payment header) results in 402 Payment Required
- Rate limiting or node unavailability may return 5xx errors
- Address with extremely large fill history may result in slow or truncated responses

## How this service works

First-party Hyperliquid trading intelligence: perp fills, position lifecycles, all-wallet leaderboards, trader cohorts, liquidation risk and HIP-4 prediction markets - computed from our own node_fills ledger plus the Hyperliquid public info API (no third-party data source). Free discovery (/healthz, /v1/stats, /.well-known/x402, /v1/openapi.json) and free sample routes (/v1/markets/overview, /v1/assets); all other API calls are $0.001 USDC per request via x402 on Base (no account, no API key).

## Output

A structured list of position lifecycle records for the specified wallet address, each including the asset traded, entry and exit timestamps, fill prices, realized PnL, and whether the position was closed voluntarily or via liquidation — all sourced directly from Hyperliquid's node_fills ledger.

## 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",
    "bodyType",
    "body"
   ],
   "properties": {
    "body": {
     "type": "object",
     "description": "Operator-defined JSON payload. Probe the upstream or consult the operator's /openapi.json for the concrete shape.",
     "additionalProperties": true
    },
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "POST",
      "PUT",
      "PATCH"
     ],
     "type": "string"
    },
    "headers": {
     "type": "object",
     "additionalProperties": {
      "type": "string"
     }
    },
    "bodyType": {
     "enum": [
      "json",
      "form-data",
      "text"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "additionalProperties": {
      "type": "string"
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {}
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/hyperliquid-trader-position-lifecycles-d1c16523/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from hyperliquid-data.v1337.org](https://www.zero.xyz/host/hyperliquid-data.v1337.org/llms.txt)