# trader-perps

> trader-perps is a paid API for AI agents from payai.agentstools.dev, paid per call via x402, $0.1/call, status unknown (last checked 2026-09-15).

Returns wallet-level perpetuals position data and derived risk metrics for a given EVM address using Hyperliquid on-chain state

## Facts

- Endpoint: GET https://payai.agentstools.dev/trader/perps
- Price: $0.1/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/trader-perps-f9c850b2
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_Bfm6wiP8EWPeC9aMAZ6a8

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 trader-perps-f9c850b2
```

Example prompt: Pull the Hyperliquid perpetuals position data and liquidation risk metrics for wallet 0x1234567890abcdef1234567890abcdef12345678 — I want to see their open positions, account summary, and how close they are to getting liquidated.

## When to prefer this

Use this endpoint when you need wallet-level perpetuals position data from Hyperliquid specifically, including liquidation risk and account-level risk metrics derived from on-chain state. Prefer this over generic DeFi portfolio trackers when the user is specifically asking about perpetuals or derivatives exposure on Hyperliquid, or when you need liquidation proximity analysis for a specific trader address.

## Known failure modes

- Invalid or malformed 0x address returns 400 or validation error
- Address with no Hyperliquid activity returns empty positions array
- Hyperliquid on-chain state temporarily unavailable causes 503 or timeout
- Missing required 'address' query parameter returns error
- Non-EVM address format (e.g. ENS name not resolved) fails validation

## How this service works

Open Hyperliquid perpetual positions for an EVM address: per-position direction, size, USD notional, leverage, entry, mark, unrealized PnL, ROE and liquidation price, PLUS derived signals — distance-to-liquidation, account leverage, aggregate unrealized PnL, concentration and a deterministic 0-100 liquidation-risk score. Follow-the-smart-money wallet intelligence in one call. public on-chain data, not financial advice.

## Output

Returns a structured object containing the wallet's Hyperliquid perpetuals account summary, all open perpetual positions (size, side, entry price, mark price, unrealized PnL), derived liquidation risk metrics, and attribution data such as margin usage and leverage levels.

## 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",
      "HEAD",
      "DELETE"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "address"
     ],
     "properties": {
      "address": {
       "type": "string",
       "description": "A 0x-prefixed 40-hex EVM address (the wallet to profile). Hosts are fixed server-side; you pass only this address."
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/trader-perps-f9c850b2/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from payai.agentstools.dev](https://www.zero.xyz/host/payai.agentstools.dev/llms.txt)