> For the complete documentation index, see [llms.txt](https://docs.blockscholes.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blockscholes.com/data-access/rest-api/request-options.md).

# Request Options

Request options for the Block Scholes REST API: choose timestamp precision, hex encoding and decimal places, and optionally request EIP-712 signed responses for on-chain verification.

Every REST API request takes an `options` object next to its data parameters. It controls how numbers and timestamps are returned, and whether the response is signed for on-chain verification.

Request fields that shape *which* data you get live on their own pages: [Time Range Limits](https://docs.blockscholes.com/data-access/rest-api/time-range-limits.md), [Forward Fill](https://docs.blockscholes.com/data-access/rest-api/forward-fill.md) and [The blockscholes Exchange](https://docs.blockscholes.com/data-access/rest-api/blockscholes-exchange.md).

## Request example

`options` sits alongside the endpoint's own fields, such as `base_asset`, `start`, `end` and `frequency`:

```json
{
    "base_asset": "BTC",
    "start": "LATEST",
    "end": "LATEST",
    "frequency": "1m",
    "options": {
        "format": {
            "timestamp": "ms",
            "hexify": false,
            "decimals": 4
        }
    }
}
```

To request a signed response, add `signature` (see [Signed Responses](https://docs.blockscholes.com/data-access/rest-api/signed-responses.md)):

```json
{
    "options": {
        "format": {
            "timestamp": "ms",
            "hexify": true,
            "decimals": 9
        },
        "signature": {
            "domain": {
                "name": "TRIAL",
                "version": "1",
                "chain_id": "50000",
                "verifying_contract": "0x1111111111111111111111111111111111111111"
            }
        }
    }
}
```

## Options object

| Field              | Type    | Required | Description                                                                                                                                              |
| ------------------ | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `format`           | Object  | Yes      | Formatting preferences for the response.                                                                                                                 |
| `format.timestamp` | String  | Yes      | Precision of returned timestamps. See [Timestamp precision](#timestamp-precision).                                                                       |
| `format.hexify`    | Boolean | Yes      | Return numeric values as hexadecimal strings. See [Hex encoding and decimals](#hex-encoding-and-decimals).                                               |
| `format.decimals`  | Integer | Yes      | Number of decimal places. Rounds unsigned values and scales signed values. See [Hex encoding and decimals](#hex-encoding-and-decimals).                  |
| `signature`        | Object  | No       | Signing configuration. Omit it for an unsigned response. See [Signed Responses](https://docs.blockscholes.com/data-access/rest-api/signed-responses.md). |

## Timestamp precision

`format.timestamp` sets the unit of every timestamp in the response. Timestamps are always integers.

| Value  | Unit         |
| ------ | ------------ |
| `"s"`  | Seconds      |
| `"ms"` | Milliseconds |
| `"us"` | Microseconds |
| `"ns"` | Nanoseconds  |

Choose `"s"` or `"ms"` for most applications. Use `"ns"` when you join the response against tick-level data that carries nanosecond timestamps.

## Hex encoding and decimals

These two fields work together, and their effect depends on whether you request a signature.

|                 | Unsigned request                                    | Signed request                                                                         |
| --------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `decimals`      | Values are **rounded** to this many decimal places. | Values are **scaled** by 10<sup>decimals</sup> into integers, so no precision is lost. |
| `hexify: false` | Numbers are returned as JSON numbers.               | Scaled integers are returned in the response.                                          |
| `hexify: true`  | Every numeric value is returned as a hex string.    | Every numeric value is returned as a hex string.                                       |

For example, with `"decimals": 4` an unsigned request returns a price as `67000.5013`. With `"decimals": 9` on a signed request, the same price is returned as the integer `67000501300000`, which is what the contract verifies.

Use `hexify: true` when you pass the values straight to an EVM contract. Leave it `false` for analytics and charting.

## EIP-712 Signatures

Add a `signature` object to receive a response signed for on-chain verification. Signing is optional, and the request example above shows the shape. The signature domain, the signed response format and verification are covered on [Signed Responses](https://docs.blockscholes.com/data-access/rest-api/signed-responses.md).

## Frequently asked questions

**Do I have to send `options`?**\
Yes. `format` and its three fields are required on every request. `signature` is the only optional part.

**Which timestamp precision should I pick?**\
`"ms"` is a good default. It matches most JavaScript and trading-system clocks.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.blockscholes.com/data-access/rest-api/request-options.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
