# Laevitas Hyperliquid Node Wallet Positions

> Laevitas Hyperliquid Node Wallet Positions is a paid API for AI agents from apiv2.laevitas.ch, paid per call via x402, $0.1/call, status unknown (last checked 2026-09-14).

Retrieves wallet-level position data from Hyperliquid HyperCore node, including trade history and position details filterable by wallet address, market type, and time range.

## Facts

- Endpoint: GET https://apiv2.laevitas.ch/api/v1/hyperliquid/node/wallet-positions
- Price: $0.1/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/laevitas-hyperliquid-node-wallet-positions-afc52b97
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_NMYLiFtfSeafE2o9u55Ka

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 laevitas-hyperliquid-node-wallet-positions-afc52b97
```

Example prompt: Show me the perpetual positions and realized PnL for Hyperliquid wallet 0xAbC123... — sort by realized_pnl, limit to 100 results, and filter to perp market type.

## When to prefer this

Use this endpoint when you need wallet-level position or trade data specifically from the Hyperliquid HyperCore decentralized exchange node. Prefer this over generic crypto portfolio endpoints when the user is focused on Hyperliquid-native perp, spot, or prediction market positions with on-chain wallet granularity.

## Known failure modes

- Missing or invalid wallet address returns empty data array
- Invalid market_type enum value returns 400 error
- limit out of range (must be 1–1000) returns validation error
- Invalid sort_by enum value returns 400 error
- Unpaid or expired x402 payment returns 402 Payment Required
- Invalid API key returns 401 Unauthorized
- No data found for the given wallet/time range returns empty data array

## How this service works

Professional market data API for crypto derivatives, spot markets, prediction markets, Hyperliquid HyperCore data, proprietary volatility surfaces, and analytics.

## Authentication

Use an API key for authenticated REST requests:

```http
X-API-Key: your-api-key-here
```

Most data endpoints also support x402 pay-per-request without an API key.

| Resource | Path |
| --- | --- |
| OpenAPI JSON | `GET /openapi.json` |
| x402 discovery | `GET /.well-known/x402` |
| Changelog | `GET /api/v1/changelog` |
| WebSocket docs | `GET /websocket` |

## REST Surfaces

| Surface | Examples |
| --- | --- |
| Instruments | Cross-market contract reference data |
| Futures | OHLCVT, trades, tickers, orderbook, liquidations, carry |
| Perpetuals | OHLCVT, trades, funding, open interest, orderbook, liquidations |
| Options | OHLCVT, trades, Greeks, volatility, flow, dealer GEX |
| Vol Surface | Proprietary surface snapshots, slices, strikes, term structure, risk |
| Spot | OHLCVT, ticker, trades, volume, L2 orderbook, snapshots |
| Predictions | Polymarket instruments, categories, trades, ticker history |
| Hyperliquid - HyperCore | Node-derived fills, liquidations, positions, funding, TWAPs, resting orders, L2 books |
| Analytics | Realized volatility and derived metrics |

## Pagination

Paginated endpoints return the cursor at `meta.next_cursor`. Pass that value back as the `cursor` query parameter to fetch the next page.

## WebSocket Streaming

Real-time streams are documented at `/websocket`.

| Data | Channel pattern |
| --- | --- |
| Trades | `trades.{market}.{exchange}.{instrument}` |
| OHLC ticker | `ohlc.ticker.{market}.{exchange}.{instrument}.{timeframe}` |
| OHLCVT | `ohlc.vt.{market}.{exchange}.{instrument}.{timeframe}` |

Variables: `market` is one of `perpetuals`, `futures`, `options`, or `spot`; `timeframe` is one of `1m`, `5m`, `15m`, `1h`, `4h`, or `1d`.

## Quick Start

```bash
curl "https://apiv2.laevitas.ch/api/v1/futures/ohlcvt?exchange=deribit&instrument_name=BTC-PERPETUAL" \
  -H "X-API-Key: your-api-key-here"
```

## Output

Returns a JSON object with a `data` array of wallet position records from the Hyperliquid HyperCore node, including fields for trade notional, buy/sell notional, net notional, realized PnL, and trade count, plus a `success` boolean indicating request status.

## 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"
    },
    "pathParams": {
     "type": "object"
    },
    "queryParams": {
     "type": "object",
     "properties": {
      "end": {
       "type": "string"
      },
      "limit": {
       "type": "integer",
       "maximum": 1000,
       "minimum": 1
      },
      "start": {
       "type": "string"
      },
      "cursor": {
       "type": "string"
      },
      "dedupe": {
       "type": "boolean"
      },
      "wallet": {
       "type": "string"
      },
      "sort_by": {
       "enum": [
        "time",
        "total_notional",
        "buy_notional",
        "sell_notional",
        "net_notional",
        "realized_pnl",
        "trade_count"
       ],
       "type": "string"
      },
      "currency": {
       "type": "string"
      },
      "exchange": {
       "type": "string"
      },
      "resolution": {
       "enum": [
        "1m",
        "5m",
        "15m",
        "1h",
        "4h",
        "1d"
       ],
       "type": "string"
      },
      "market_type": {
       "enum": [
        "perp",
        "perp_hip3",
        "spot",
        "prediction"
       ],
       "type": "string"
      },
      "min_notional": {
       "type": "number"
      },
      "instrument_name": {
       "type": "string"
      },
      "instrument_name_raw": {
       "type": "string"
      },
      "min_target_notional": {
       "type": "number"
      },
      "max_distance_from_mark": {
       "type": "number"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "data": [],
  "success": true
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/laevitas-hyperliquid-node-wallet-positions-afc52b97/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from apiv2.laevitas.ch](https://www.zero.xyz/host/apiv2.laevitas.ch/llms.txt)