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

# RWA Perps API

> Retrieve funding and carry for real-world-asset perpetuals across 13 venues: interval-true, mechanism-true, with session-tagged settlement history.

RWA perps are perpetual futures on real-world assets: equities like TSLA and NVDA, pre-IPO names, ETFs, indices, commodities and FX. They trade 24/7 while the underlying prints \~32.5 market hours a week. The Sharpe API normalizes funding and carry across **13 venues** into one interval-true, mechanism-true endpoint: CEXs (Binance, Bybit, OKX, Bitget, Gate, Kraken), perp DEXs (Aster, Lighter, Extended, GRVT, ApeX, Pacifica) and Hyperliquid's HIP-3 builder markets. Settlement intervals genuinely differ per venue and per market (the same stock can fund every 4 hours on one venue and every 8 on another), so every rate is annualized from the venue's own reported interval.

***

## Get rwa-perp rates

`GET /v1/rwa-perps/rates`

A single endpoint that returns current per-market snapshots, session-tagged settlement history, or summary stats depending on the `type` parameter.

### Query parameters

**type** `string`

The kind of rwa-perp data to return. One of `current`, `history`, `stats`. Defaults to `current`.

**symbol** `string`

Underlying ticker (e.g., `TSLA`, `NVDA`, `XAU`, `US500`), case-insensitive. Optional filter for `current`. **Required** for `history`. `GOOG` and `GOOGL` are different share classes and are never merged. An unlisted symbol returns an empty list.

**venue** `string`

Filter to a single venue, case-insensitive: `Binance`, `Bybit`, `OKX`, `Bitget`, `Gate`, `Kraken`, `Aster`, `Lighter`, `Extended`, `GRVT`, `ApeX`, `Pacifica`, or the Hyperliquid HIP-3 builder venue (`Hyperliquid`, the trade.xyz dex). Registry-driven rather than a fixed enum; an unknown venue returns `400` with the list of valid venues.

**days** `integer`

Lookback window in days for `type=history`. Integer from `1` to `90`. Defaults to `7`. Ignored for other types.

**limit** `integer`

Maximum records per page (`1` to `5000`). Enables cursor pagination.

**cursor** `string`

Opaque pagination cursor from a previous response.

**format** `string`

Response format. One of `json`, `csv`. Defaults to `json`. CSV applies to row responses (type current or history); a stats response stays JSON.

### Mechanism semantics

Every row carries a `mechanism` field:

* `builder_set` (the Hyperliquid HIP-3 builder venue, `Hyperliquid`: the trade.xyz dex): the market deployer runs the oracle; funding is Hyperliquid-standard, settled hourly. `funding_rate` is the fraction per interval; positive means longs pay shorts.
* `standard` (most CEXs and perp DEXs): classic long-pays-short perp funding, clamped per instrument where the venue publishes a cap. This covers Binance, Bybit, OKX, Bitget, Gate, Kraken, Aster, Lighter, Extended, GRVT, ApeX and Pacifica. Venue-internal caps are retained for product calculations but the default API payload intentionally omits internal `meta`.
* `funding_plus_borrow`: a rollover venue's holding cost, charged to **both sides** instead of funding. It is reported as `borrow_apr_annual` and excluded from cross-venue funding spreads, since a both-sides cost is not sign-comparable with a long-pays-short transfer. No venue Sharpe covers uses it today; the value stays in the schema.

`funding_apr` annualizes each venue's own settlement interval (`rate × 8760 / interval_hours`), never an assumed 8-hour interval. `funding_rate` is the in-progress rate for the settlement at `next_funding_time`, charged over `interval_hours`: Lighter publishes an 8-hour-basis figure and charges an eighth of it every hour, so its rows carry that hourly charge at `interval_hours: 1`, the same numbers `/v1/funding/rates` serves.

### Zero funding

Many rows read a funding rate of exactly 0 (1,762 of 2,204 on Saturday 2026-10-31, with every home market closed), and a 0 is not always a real 0. `funding_status` says which: `live` (non-zero), `zero` (exactly 0 while the underlying's home market is open, on a market that has printed non-zero funding: often the formula's dead band), `paused` (exactly 0 while the home market is closed: Bitget and Bybit stock perps settle 0 for every period outside US hours), `zero_by_design` (the market has never printed non-zero funding: the venue runs no funding market on it) and `none` (rollover venues). Only `live` and `zero` count as spread legs in `type=stats`.

### Stats

`bestCarry` is realised funding, not one print: the market's settlements over the trailing 24 hours summed and annualised (`× 8760 / 24`), on a market with at least \$1M of open interest and 90% of its expected settlements stored. Settlement history is stored for Hyperliquid and Kraken only, so best carry ranks those venues. `topSpread` is this period's widest cross-venue spread between comparable funding rates, annualised.

### History and session phases

`type=history` returns stored settlements for **Hyperliquid (the trade.xyz HIP-3 dex) and Kraken only**. Stored history begins 2026-07-28, so `days` reaches no further back than that. Other venues' settlement history is not served by the API: the terminal's symbol page (for example `/rwa-perps/TSLA`) fetches it live from each venue for display only. Each settlement is tagged with the session phase it occurred in on the underlying's home exchange, in that exchange's own time zone (DST-correct): `market`, `after_hours`, `weekend`, or `holiday`. US stocks and ETFs follow NYSE hours, Korean names KRX, Hong Kong names HKEX, Japanese names the TSE, A shares Shanghai/Shenzhen, and commodities, FX and rates the CME's Sunday-to-Friday futures week. A lunch break counts as `after_hours`. This is the raw material for weekend-carry analysis, because perps trade 168 hours a week against \~32.5 hours of underlying price discovery.

### Freshness

Current rows refresh every 30 minutes, at :09 and :39 past each hour (UTC). A row is flagged `is_stale` after 1 hour without a sync (the 30-minute sync plus one skipped run).

`current` and `stats` responses carry `X-Data-As-Of` (the newest row's update), `X-Freshness-Sla-Seconds` (`3600`), and `X-Data-Stale`, which is `true` only when the whole snapshot is past 1 hour (the sync itself stopped). A single venue falling behind does not flip it: that venue is named in `X-Data-Lagging-Venues` (comma-separated, sent only when a venue lags) and, for `stats`, in `laggingVenues` with its own as-of time. `history` responses carry `X-Data-Source` but no freshness headers.

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/rwa-perps/rates \
  -H "Authorization: Bearer $SHARPE_API_KEY" \
  -d type=current \
  -d symbol=TSLA
```

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

response = requests.get(
    "https://www.sharpe.ai/api/v1/rwa-perps/rates",
    headers={"Authorization": f"Bearer {api_key}"},
    params={"type": "current", "symbol": "TSLA"},
)
rows = response.json()["data"]
```

```javascript JavaScript theme={null}
const response = await fetch(
  "https://www.sharpe.ai/api/v1/rwa-perps/rates?type=current&symbol=TSLA",
  { headers: { Authorization: `Bearer ${apiKey}` } },
);
const { data } = await response.json();
```

```json title="Response (type=current)" theme={null}
{
  "data": [
    {
      "venue": "Hyperliquid",
      "market": "xyz:TSLA",
      "symbol": "TSLA",
      "asset_class": "equity",
      "mechanism": "builder_set",
      "funding_rate": 0.00000625,
      "interval_hours": 1,
      "funding_apr": 0.05475,
      "borrow_apr_annual": null,
      "mark_price": 356.76,
      "oracle_price": 356.72,
      "open_interest_usd": 49750458.85,
      "next_funding_time": "2026-09-29T05:00:00+00:00",
      "price_deviation": -0.0005,
      "is_price_suspect": false,
      "last_nonzero_funding_apr": 0.05475,
      "last_nonzero_funding_at": "2026-09-29T04:09:17.1+00:00",
      "updated_at": "2026-09-29T04:09:17.1+00:00",
      "is_stale": false,
      "funding_status": "live"
    }
  ],
  "meta": { "request_id": "…", "timestamp": "…", "elapsed_ms": 12 }
}
```

```json title="Response (type=history)" theme={null}
{
  "data": [
    {
      "venue": "Kraken",
      "market": "PF_TSLAXUSD",
      "symbol": "TSLA",
      "rate": 0.0000205685,
      "interval_hours": 1,
      "session_phase": "market",
      "settled_at": "2026-09-28T14:00:00+00:00"
    }
  ],
  "meta": { "request_id": "…", "timestamp": "…", "elapsed_ms": 12 }
}
```

```json title="Response (type=stats)" theme={null}
{
  "data": {
    "bestCarry": { "symbol": "INTC", "venue": "Kraken", "fundingApr": 1.733443, "mechanism": "standard", "windowHours": 24, "settlements": 24 },
    "topSpread": {
      "symbol": "UNITREE",
      "spreadApr": 0.657714,
      "maxVenue": "Hyperliquid",
      "minVenue": "OKX",
      "maxApr": 0.05475,
      "minApr": -0.602964
    },
    "weekendPremiumApr": -0.099097,
    "totalOpenInterestUsd": 12827809588.81,
    "venues": 13,
    "symbols": 603,
    "markets": 2191,
    "asOf": "2026-10-31T11:39:06.523Z",
    "stale": false,
    "laggingVenues": []
  },
  "meta": { "request_id": "…", "timestamp": "…", "elapsed_ms": 12 }
}
```


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