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

# Order book APY-range exposure

> Retrieve orderbook exposure at a chosen timestamp, including each order's APY range status.

export const ApiResponse = ({children, errors = {}}) => {
  const [status, setStatus] = useState("200");
  const statuses = ["200", ...Object.keys(errors)];
  return <section className="api-response" aria-label="Response">
      <div className="api-response-header not-prose">
        <h2>Response</h2>
        <div className="api-response-format">
          {statuses.length > 1 ? <select aria-label="Response status" value={status} onChange={event => setStatus(event.target.value)}>
              {statuses.map(code => <option key={code} value={code}>{code}</option>)}
            </select> : <span>200</span>}
          <span className="api-response-mime">application/json</span>
        </div>
      </div>
      <div hidden={status !== "200"}>{children}</div>
      {status !== "200" && <div aria-live="polite">
          {Object.entries(errors[status]).map(([name, value]) => <ResponseField key={name} name={name} type={value === null ? "null" : Array.isArray(value) ? "array" : typeof value}>
              {name === "error" ? "Error message describing why the request failed." : "Additional error details."}
            </ResponseField>)}
        </div>}
    </section>;
};

<RequestExample dropdown>
  ```bash cURL theme={null}
  curl https://api.exponent.finance/in-range/orderbook/vault/Cmry6B5824MGAKrtL2u7YG9PiLZLoTBWs8hVaCJeUFaH
  ```

  ```python Python theme={null}
  import requests

  response = requests.get("https://api.exponent.finance/in-range/orderbook/vault/Cmry6B5824MGAKrtL2u7YG9PiLZLoTBWs8hVaCJeUFaH", timeout=30)
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.exponent.finance/in-range/orderbook/vault/Cmry6B5824MGAKrtL2u7YG9PiLZLoTBWs8hVaCJeUFaH");
  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

## Path parameters

<ParamField path="vaultAddress" type="string" required>
  Base58 Solana vault public key.
</ParamField>

## Query parameters

<ParamField query="at" type="string">
  Past or present ISO 8601 timestamp with an explicit timezone and up to three fractional-second digits. Defaults to request time. Use the same explicit timestamp for both snapshot endpoints to align results. URL-encode `+` in timezone offsets or use UTC (`Z`).
</ParamField>

<ParamField query="bufferApyPercentagePoints" type="number" default="1">
  Inclusive APY buffer, from `0` to `100`. A value of `1` means one percentage point, not a 1% relative change.
</ParamField>

No maximum reference age is enforced. Range checks use the latest available market observation at or before `at`, regardless of age.

## Common response fields

<ApiResponse errors={{}}>
  | Field | Type | Description |
  | - | - | - |
  | `vaultAddress` | string | Requested vault. |
  | `at` | string | Effective inclusive snapshot timestamp. |
  | `bufferApyPercentagePoints` | number | Applied APY buffer. |
  | `syMint` | string | Vault's SY token mint. |
  | `tokenDecimals` | number | Decimals for the vault token amounts. Divide raw balances by `10^tokenDecimals` to obtain token units. |
  | `vaultEndTimestamp` | string | Vault maturity timestamp. |
  | `isExpired` | boolean | Whether maturity has been reached at `at`. Proximity alone does not establish reward eligibility after maturity. |
</ApiResponse>

## Orderbook response

The common fields are accompanied by `openOrders` and `filledBalances` arrays.

### Open orders

| Field | Type | Description |
| - | - | - |
| `orderId`, `postOfferEventId` | number | Indexed order and original posting event identities. |
| `offerIndex` | number | Reusable on-chain index; do not use this alone as a unique order ID. |
| `userAddress` | string | Owner's wallet. |
| `orderbookAddress` | string | Orderbook containing the order. |
| `orderType` | string | `buyPT`, `buyYT`, `sellPT`, or `sellYT`. |
| `balanceToken` | string | `SY` for buy orders, `PT` for `sellPT`, `YT` for `sellYT`. |
| `amountRemaining` | string | Reconstructed unfilled amount in `balanceToken`, including partial fills. |
| `orderApyPercent` | number | Order's APY as a percentage, already converted for comparison with `marketApyPercent`. |
| `marketApyPercent` | number or null | Last execution APY from the same orderbook at or before `at`. Only events containing fills can supply the reference. |
| `marketApyTimestamp` | string or null | Execution timestamp. |
| `marketApySource` | string | `orderbook_last_execution`; this is a last-trade reference, not a midpoint, TWAP, or external oracle. |
| `referenceStatus` | string | `available` or `missing_reference`. |
| `isWithinBuffer` | boolean or null | Whether `abs(orderApyPercent - marketApyPercent) <= bufferApyPercentagePoints`. Unknown when the reference is missing. |
| `updatedAt` | string | Latest posting or fill timestamp included in the snapshot. |
| `expiresAt` | string or null | Order expiry, or no expiry. |

Orders outside the buffer remain in the response with `isWithinBuffer=false`. Expired, cancelled, fully filled, and below-threshold orders are excluded, following the [historical open-orders endpoint](/api-documentation/get-open-orders-vault). The reference uses only trades at or before the requested timestamp.

### Filled balances

| Field | Type | Description |
| - | - | - |
| `userAddress` | string | Owner's wallet. |
| `token` | string | `SY` or `YT`. Filled PT is not included. |
| `amount` | string | Unclaimed filled balance at `at`, aggregated across the vault's orderbooks. |
| `balanceTimestamp` | string | Latest indexed balance change at or before `at`. |
| `bufferApplies` | boolean | Always `false`. Filled holdings have no resting-order proximity test. |

Only positive, unclaimed filled balances are returned. Claims reduce or remove them from subsequent snapshots. These balances are separate from the unfilled amounts in `openOrders`. Wallet balances and holdings in the vault itself are outside these endpoints' scope; account for transfers between sources when combining holdings data.

## Using snapshots for rewards

Select open orders with `isWithinBuffer=true` when your rewards policy requires proximity to market APY. Apply your own valuation, points, and multipliers; check balance timestamps, vault maturity, and campaign dates separately.

`isWithinBuffer` has three possible values:

| Value | Meaning |
| - | - |
| `true` | Within the requested APY buffer. |
| `false` | Outside the requested APY buffer. |
| `null` | Insufficient reference data to determine range status. Retry later or handle this as unavailable data. |

Assign filled SY and filled YT multipliers separately. The API does not assume that filled SY earns the same multiplier as an eligible resting order. Snapshot responses do not calculate time-weighted balances; repeated snapshots or a separate integration are needed for interval rewards.

<ResponseExample>
  ```json 200 theme={null}
  {
    "at": "2026-10-14T15:52:02.211+00:00",
    "syMint": "kCYkdbTRqnXhr1JqVWJTMCRmztcBwpeJiPPvqfDrYLp",
    "isExpired": false,
    "openOrders": [
      {
        "orderId": 130370,
        "expiresAt": "2026-10-20T15:39:51+00:00",
        "orderType": "buyYT",
        "updatedAt": "2026-10-13T15:39:51+00:00",
        "offerIndex": 2,
        "userAddress": "HRt73vbP87cUmzJJAH5tWyCuwyN9Syws2RxqND9pTMs4",
        "balanceToken": "SY",
        "isWithinBuffer": true,
        "amountRemaining": "7152337",
        "marketApySource": "orderbook_last_execution",
        "orderApyPercent": 11.349976870905389,
        "referenceStatus": "available",
        "marketApyPercent": 11.370021670720014,
        "orderbookAddress": "8JtnQcProV3bF1KUF9ohqRrnGpQCmMjTS6XxXv1aoXam",
        "postOfferEventId": 35154,
        "marketApyTimestamp": "2026-10-13T15:37:42+00:00"
      },
      {
        "orderId": 130399,
        "expiresAt": "2026-10-21T01:34:49+00:00",
        "orderType": "buyYT",
        "updatedAt": "2026-10-14T01:34:49+00:00",
        "offerIndex": 6,
        "userAddress": "EeD5qkphoyGVmkfXLi3e1Rq3Hg2zdi7asMjVgXj1kdRq",
        "balanceToken": "SY",
        "isWithinBuffer": true,
        "amountRemaining": "6552030161",
        "marketApySource": "orderbook_last_execution",
        "orderApyPercent": 11.359998819804705,
        "referenceStatus": "available",
        "marketApyPercent": 11.370021670720014,
        "orderbookAddress": "8JtnQcProV3bF1KUF9ohqRrnGpQCmMjTS6XxXv1aoXam",
        "postOfferEventId": 35185,
        "marketApyTimestamp": "2026-10-13T15:37:42+00:00"
      }
    ],
    "vaultAddress": "Cmry6B5824MGAKrtL2u7YG9PiLZLoTBWs8hVaCJeUFaH",
    "tokenDecimals": 6,
    "filledBalances": [
      {
        "token": "SY",
        "amount": "17590",
        "userAddress": "8Y7ApemW5UHzczZNYHW3tU4yZZjML8ho87i1dnf7kvw7",
        "bufferApplies": false,
        "balanceTimestamp": "2026-09-28T12:41:45.812993+00:00"
      }
    ],
    "vaultEndTimestamp": "2027-02-25T10:00:00+00:00",
    "bufferApyPercentagePoints": 1
  }
  ```
</ResponseExample>


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