> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get HIP-3 cumulative volume delta JSON Schema

> Get HIP-3 cumulative volume delta JSON Schema contract. Includes parameters, response shapes, examples, and implementation notes from the 0xArchive contract.

Source OpenAPI: 0xArchive API 1.8.0; 227 paths; 217 component schemas.

Get cumulative volume delta buckets for a HIP-3 builder-perp symbol: taker buy and sell notional per bucket, their difference, and a running total. Intervals of 1h and longer roll up hourly totals; 1m, 5m, 15m and 30m are summed from taker fills. Live responses currently meter this route at 1 credit per request. Preserve the builder prefix and symbol case. **Buckets:** each bucket is labelled by its open time in UTC and is omitted when it holds no trades. 4h, 1d and 1w buckets open on UTC epoch boundaries, so 1w buckets open on Thursdays. Below 1h, a bucket is returned when it opens inside `[start, end]`, and it always covers its full interval. From 1h up, each bucket sums the hours that open inside `[start, end]`, so at 4h, 1d and 1w the first and last buckets of a window can be partial. **Pagination:** a page holds up to `limit` buckets (default 500, max 10000). While more buckets may follow inside `[start, end]`, `meta.next_cursor` is set: pass it back as `cursor` with `start`, `end` and `interval` unchanged, and stop when it is absent. Below 1h a page can hold fewer than `limit` buckets and still carry a cursor, so stop on the cursor, not on a short page. At the default `limit`, a window of up to 500 buckets is always one page. Without `start` or `cursor`, the response is the newest `limit` buckets of the 24 hours before `end` (or before now, when `end` is later), with no cursor. **Running total:** `cumulative_delta` is a running total of `delta` from the first bucket of each response, so it restarts on every page. To join pages, rebuild it from `delta`. A response that is one page of several says so in `meta.notice`.

## Route Metadata

| Field | Value |
| - | - |
| Method | `GET` |
| Path | `/v1/hyperliquid/hip3/cvd/{symbol}` |
| operationId | `getHip3Cvd` |
| Tag | HIP-3 Builder Perps - Convenience |
| Family | HIP-3 |
| Deprecated or legacy | no |

## Human endpoint reference

Open [`GET /v1/hyperliquid/hip3/cvd/{symbol}`](/api-reference/hip-3-builder-perps--convenience/get-hip-3-cumulative-volume-delta) for authentication, parameters, responses, and examples.

## Request Parameters

### Path Parameters

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHip3Cvd path parameters",
  "type": "object",
  "required": [
    "symbol"
  ],
  "properties": {
    "symbol": {
      "description": "HIP-3 symbol with builder prefix. Case-sensitive.",
      "type": "string",
      "example": "km:US500",
      "x-parameter-location": "path"
    }
  }
}
```

### Query Parameters

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHip3Cvd query parameters",
  "type": "object",
  "properties": {
    "start": {
      "description": "Start timestamp in Unix milliseconds. When omitted, and no `cursor` is sent, the window is the 24 hours before `end` and the newest `limit` buckets of it are returned.",
      "type": "integer",
      "format": "int64",
      "x-parameter-location": "query"
    },
    "end": {
      "description": "End timestamp in Unix milliseconds. Defaults to now.",
      "type": "integer",
      "format": "int64",
      "x-parameter-location": "query"
    },
    "interval": {
      "description": "Bucket width (default: 1h). Intervals of 1h and longer roll up hourly totals; 1m, 5m, 15m and 30m are summed from taker fills. Any other value returns 400.",
      "type": "string",
      "enum": [
        "1m",
        "5m",
        "15m",
        "30m",
        "1h",
        "4h",
        "1d",
        "1w"
      ],
      "default": "1h",
      "x-parameter-location": "query"
    },
    "cursor": {
      "description": "Resume point: the previous page's `meta.next_cursor`, a Unix millisecond timestamp. Returns the buckets that open after it. Send it with the same `start`, `end` and `interval`.",
      "type": "integer",
      "format": "int64",
      "x-parameter-location": "query"
    },
    "limit": {
      "description": "Buckets per page (default: 500, max: 10000)",
      "type": "integer",
      "default": 500,
      "maximum": 10000,
      "x-parameter-location": "query"
    }
  }
}
```

## Response Contracts

### Status 200

HIP-3 CVD buckets

#### application/json

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHip3Cvd response 200",
  "description": "API response containing CVD buckets.",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "description": "Cumulative volume delta bucket.",
        "type": "object",
        "required": [
          "buy_volume",
          "cumulative_delta",
          "delta",
          "sell_volume",
          "timestamp"
        ],
        "properties": {
          "buy_volume": {
            "description": "Buy-side volume for the bucket.",
            "type": "number",
            "example": 30160211.46768
          },
          "cumulative_delta": {
            "description": "Running total of `delta` from the first bucket of this response. It restarts on every page, so rebuild it from `delta` when joining pages.",
            "type": "number",
            "example": -2740918.55881
          },
          "delta": {
            "description": "buy_volume minus sell_volume for this bucket.",
            "type": "number",
            "example": -2740918.55881
          },
          "sell_volume": {
            "description": "Sell-side volume for the bucket.",
            "type": "number",
            "example": 32901130.02649
          },
          "timestamp": {
            "description": "Bucket open time in Unix milliseconds (UTC).",
            "type": "integer",
            "format": "int64",
            "example": 1781593200000
          }
        }
      }
    },
    "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

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHip3Cvd 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

```json theme={"theme":"github-dark"}
{
  "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

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHip3Cvd 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

```json theme={"theme":"github-dark"}
{
  "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 429

Rate limit exceeded

#### application/json

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHip3Cvd 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

```json theme={"theme":"github-dark"}
{
  "code": 429,
  "error": "Rate limit exceeded"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.