Get Hyperliquid wallet profile JSON Schema

Source OpenAPI: 0xArchive API 1.8.0; 227 paths; 217 component schemas. Behavioral metrics for one wallet on Hyperliquid perpetuals over the last hours: order mix (cancel, fill, IOC, post-only, TP/SL, and trigger ratios), order sizes, cancel speed, fill volume and maker share, fees, realized PnL, liquidations, and TWAP, client order ID, priority gas, and builder usage. Without coin, metrics come from daily aggregates: every UTC day that overlaps the window counts in full, and unique_coins_traded and unique_fill_coins are the largest single-day counts. With coin, the window is exact.

Route Metadata

Field	Value
Method	`GET`
Path	`/v1/hyperliquid/wallets/{address}/profile`
operationId	`getHyperliquidWalletProfile`
Tag	Hyperliquid - Wallets
Family	Hyperliquid Core
Deprecated or legacy	no

Human endpoint reference

Open GET /v1/hyperliquid/wallets/{address}/profile for authentication, parameters, responses, and examples.

Request Parameters

Path Parameters

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHyperliquidWalletProfile path parameters",
  "type": "object",
  "required": [
    "address"
  ],
  "properties": {
    "address": {
      "description": "Wallet address: 0x followed by 40 hex characters (case-insensitive).",
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "example": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
      "x-parameter-location": "path"
    }
  }
}

Query Parameters

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHyperliquidWalletProfile query parameters",
  "type": "object",
  "properties": {
    "coin": {
      "description": "Limit the metrics to one perpetual market (case-insensitive, e.g., BTC). Omit for all markets.",
      "type": "string",
      "example": "BTC",
      "x-parameter-location": "query"
    },
    "hours": {
      "description": "Lookback window in hours, from 1 to 168 (7 days). Larger values are capped at 168.",
      "type": "integer",
      "default": 24,
      "minimum": 1,
      "maximum": 168,
      "x-parameter-location": "query"
    }
  }
}

Response Contracts

Status 200

Wallet behavioral metrics

application/json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHyperliquidWalletProfile response 200",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "address": {
          "description": "Wallet address, lowercase.",
          "type": "string"
        },
        "metrics": {
          "description": "Behavioral metrics for one wallet. Ratios run from 0 to 1 unless noted; USD values use fill or order price times size.",
          "type": "object",
          "properties": {
            "active_hours": {
              "description": "Hours with at least one order.",
              "type": "integer"
            },
            "avg_order_size_usd": {
              "description": "Average order notional in USD.",
              "type": "number"
            },
            "buy_volume_usd": {
              "description": "Buy fill volume in USD.",
              "type": "number"
            },
            "cancel_rate": {
              "description": "Share of orders canceled.",
              "type": "number"
            },
            "cloid_ratio": {
              "description": "Share of fills that carried a client order ID.",
              "type": "number"
            },
            "fill_rate": {
              "description": "Share of orders filled.",
              "type": "number"
            },
            "ioc_ratio": {
              "description": "Share of orders that are immediate-or-cancel.",
              "type": "number"
            },
            "liquidation_count": {
              "description": "Fills that were liquidations.",
              "type": "integer"
            },
            "long_short_ratio": {
              "description": "Buy volume divided by sell volume (0 when there is no sell volume). Not bounded by 1.",
              "type": "number"
            },
            "maker_ratio": {
              "description": "Share of fill volume that was maker volume.",
              "type": "number"
            },
            "max_order_size_usd": {
              "description": "Largest order notional in USD.",
              "type": "number"
            },
            "max_single_fill_usd": {
              "description": "Largest single fill in USD.",
              "type": "number"
            },
            "median_cancel_speed_ms": {
              "description": "Median time from placement to cancel, in milliseconds.",
              "type": "number"
            },
            "order_to_trade_ratio": {
              "description": "Orders placed per fill (0 when there are no fills).",
              "type": "number"
            },
            "post_only_ratio": {
              "description": "Share of orders that are post-only.",
              "type": "number"
            },
            "realized_pnl_usd": {
              "description": "Realized PnL from closing fills.",
              "type": "number"
            },
            "sell_volume_usd": {
              "description": "Sell fill volume in USD.",
              "type": "number"
            },
            "top_builder": {
              "description": "Builder address with the most orders. Omitted when no order used a builder.",
              "type": "string"
            },
            "total_builder_fees_paid": {
              "description": "Builder and deployer fees paid.",
              "type": "number"
            },
            "total_fees_usd": {
              "description": "Fees paid, net of rebates.",
              "type": "number"
            },
            "total_fills": {
              "description": "Fills.",
              "type": "integer"
            },
            "total_orders": {
              "description": "Orders placed.",
              "type": "integer"
            },
            "total_priority_gas_paid": {
              "description": "Priority gas paid.",
              "type": "number"
            },
            "total_volume_usd": {
              "description": "Fill volume in USD.",
              "type": "number"
            },
            "tpsl_ratio": {
              "description": "Share of orders that are position TP/SL orders.",
              "type": "number"
            },
            "trigger_order_ratio": {
              "description": "Share of orders that are trigger orders.",
              "type": "number"
            },
            "twap_fill_ratio": {
              "description": "Share of fills that came from a TWAP.",
              "type": "number"
            },
            "unique_coins_traded": {
              "description": "Markets with orders.",
              "type": "integer"
            },
            "unique_fill_coins": {
              "description": "Markets with fills.",
              "type": "integer"
            },
            "uses_builder": {
              "description": "True when any order went through a builder.",
              "type": "boolean"
            },
            "uses_cloid": {
              "description": "True when any fill carried a client order ID.",
              "type": "boolean"
            },
            "uses_priority_gas": {
              "description": "True when any fill paid priority gas.",
              "type": "boolean"
            },
            "uses_tpsl": {
              "description": "True when the wallet placed any position TP/SL order.",
              "type": "boolean"
            },
            "uses_twap": {
              "description": "True when any fill came from a TWAP.",
              "type": "boolean"
            }
          }
        },
        "period": {
          "description": "Lookback window that was applied, for example `24h`.",
          "type": "string",
          "example": "24h"
        }
      }
    },
    "meta": {
      "description": "Response metadata",
      "type": "object",
      "properties": {
        "count": {
          "description": "Number of records returned",
          "type": "integer"
        },
        "coverage_from": {
          "description": "Earliest coverage for the requested symbol and data type. Present only when the requested window ends before coverage begins.",
          "type": "string",
          "format": "date-time"
        },
        "has_more": {
          "description": "Present on cursor-paged routes: true when another page exists. `next_cursor` is present exactly when it is true.",
          "type": "boolean"
        },
        "next_cursor": {
          "description": "Cursor for pagination (timestamp). Use this value as the `cursor` parameter to fetch the next page of results.",
          "type": "string",
          "nullable": true
        },
        "notice": {
          "description": "Human-readable advisory about the response. Used when the requested window ends before coverage begins for the symbol, and on CVD responses that are one page of several; may carry other advisories in future.",
          "type": "string"
        },
        "request_id": {
          "description": "Unique request ID for support",
          "type": "string",
          "format": "uuid"
        },
        "symbol": {
          "description": "Present on per-symbol routes: the symbol the response covers.",
          "type": "string"
        },
        "venue": {
          "description": "Present on per-symbol routes: the venue the response covers, for example `hyperliquid` or `hip3`.",
          "type": "string"
        }
      }
    },
    "success": {
      "type": "boolean",
      "example": true
    }
  }
}

Status 400

Invalid request

application/json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHyperliquidWalletProfile response 400",
  "description": "Error response",
  "type": "object",
  "properties": {
    "code": {
      "description": "HTTP status code",
      "type": "integer"
    },
    "error": {
      "description": "Error message",
      "type": "string"
    },
    "error_code": {
      "description": "Machine-readable error code. Common values: `invalid_query_params` (a query parameter failed to parse or validate) and `invalid_path_params` (a path parameter failed to parse). Other endpoint-specific codes exist; treat unknown codes as generic errors of the given HTTP status.",
      "type": "string"
    },
    "param": {
      "description": "The parameter at fault, when the error is about one parameter.",
      "type": "string"
    },
    "request_id": {
      "description": "Unique request ID for support",
      "type": "string",
      "format": "uuid"
    },
    "success": {
      "description": "Always false on an error.",
      "type": "boolean",
      "example": false
    }
  }
}

OpenAPI example

{
  "code": 400,
  "error": "Failed to deserialize query string: limit: invalid digit found in string",
  "error_code": "invalid_query_params",
  "param": "limit",
  "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05",
  "success": false
}

Status 401

Authentication required

application/json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHyperliquidWalletProfile response 401",
  "description": "Error response",
  "type": "object",
  "properties": {
    "code": {
      "description": "HTTP status code",
      "type": "integer"
    },
    "error": {
      "description": "Error message",
      "type": "string"
    },
    "error_code": {
      "description": "Machine-readable error code. Common values: `invalid_query_params` (a query parameter failed to parse or validate) and `invalid_path_params` (a path parameter failed to parse). Other endpoint-specific codes exist; treat unknown codes as generic errors of the given HTTP status.",
      "type": "string"
    },
    "param": {
      "description": "The parameter at fault, when the error is about one parameter.",
      "type": "string"
    },
    "request_id": {
      "description": "Unique request ID for support",
      "type": "string",
      "format": "uuid"
    },
    "success": {
      "description": "Always false on an error.",
      "type": "boolean",
      "example": false
    }
  }
}

OpenAPI example

{
  "code": 401,
  "error": "Missing authentication credentials. Provide X-API-Key header or Bearer token.",
  "error_code": "unauthorized",
  "request_id": "71ed4b6f-63ef-4ae1-a123-07ffa47c1c14",
  "success": false
}

Status 404

Without coin: the wallet placed no orders in the window.

application/json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHyperliquidWalletProfile response 404",
  "description": "Error response",
  "type": "object",
  "properties": {
    "code": {
      "description": "HTTP status code",
      "type": "integer"
    },
    "error": {
      "description": "Error message",
      "type": "string"
    },
    "error_code": {
      "description": "Machine-readable error code. Common values: `invalid_query_params` (a query parameter failed to parse or validate) and `invalid_path_params` (a path parameter failed to parse). Other endpoint-specific codes exist; treat unknown codes as generic errors of the given HTTP status.",
      "type": "string"
    },
    "param": {
      "description": "The parameter at fault, when the error is about one parameter.",
      "type": "string"
    },
    "request_id": {
      "description": "Unique request ID for support",
      "type": "string",
      "format": "uuid"
    },
    "success": {
      "description": "Always false on an error.",
      "type": "boolean",
      "example": false
    }
  }
}

OpenAPI example

{
  "code": 404,
  "error": "No data found for 0x0000000000000000000000000000000000000001",
  "error_code": "not_found",
  "request_id": "01883301-c6eb-4b06-9f0e-cd568ec81309",
  "success": false
}

Status 429

Rate limit exceeded

application/json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHyperliquidWalletProfile response 429",
  "description": "Error response",
  "type": "object",
  "properties": {
    "code": {
      "description": "HTTP status code",
      "type": "integer"
    },
    "error": {
      "description": "Error message",
      "type": "string"
    },
    "error_code": {
      "description": "Machine-readable error code. Common values: `invalid_query_params` (a query parameter failed to parse or validate) and `invalid_path_params` (a path parameter failed to parse). Other endpoint-specific codes exist; treat unknown codes as generic errors of the given HTTP status.",
      "type": "string"
    },
    "param": {
      "description": "The parameter at fault, when the error is about one parameter.",
      "type": "string"
    },
    "request_id": {
      "description": "Unique request ID for support",
      "type": "string",
      "format": "uuid"
    },
    "success": {
      "description": "Always false on an error.",
      "type": "boolean",
      "example": false
    }
  }
}

OpenAPI example

{
  "code": 429,
  "error": "Rate limit exceeded"
}

API reference

Endpoint reference

Schema reference

SDKs & tooling

AI & agents

Get Hyperliquid wallet profile JSON Schema

Route Metadata

Human endpoint reference

Request Parameters

Path Parameters

Query Parameters

Response Contracts

Status 200

application/json

Status 400

application/json

OpenAPI example

Status 401

application/json

OpenAPI example

Status 404

application/json

OpenAPI example

Status 429

application/json

OpenAPI example

​Route Metadata

​Human endpoint reference

​Request Parameters

​Path Parameters

​Query Parameters

​Response Contracts

​Status 200

​application/json

​Status 400

​application/json

OpenAPI example

​Status 401

​application/json

OpenAPI example

​Status 404

​application/json

OpenAPI example

​Status 429

​application/json

OpenAPI example

Route Metadata

Human endpoint reference

Request Parameters

Path Parameters

Query Parameters

Response Contracts

Status 200

application/json

Status 400

application/json

Status 401

application/json

Status 404

application/json

Status 429

application/json