Arcus Vaults · Public API

Read-only JSON API for pToken vaults: metadata, live NAV, performance, and history.

Conventions

Convention	Detail
Base path	All data endpoints live under `/v1`. Responses are JSON.
Money & prices	Numbers in USD (`...Usd` suffix). Percentages carry a `...Pct` suffix; fees use basis points (`...Bps`, 100 bps = 1%).
Time	Timestamps are epoch milliseconds (`t`, `from`, `to`, `now`); static metadata uses ISO 8601 (`createdAt`).
Null	Any field can be `null` when its upstream source (chain RPC, exchange gateway, snapshot history) is unavailable or not yet populated. Nulls mean "unknown right now", never zero.
Caching	Responses are cached server-side for a few seconds and carry a matching `Cache-Control: public, max-age`. Do not poll faster than 1/s per endpoint.
CORS	`Access-Control-Allow-Origin: *` on every response; safe to call directly from a browser.
Auth	None. Everything served here is public information.

Endpoints

List vaults

GET/v1/vaults

Every vault this deployment manages, with the fields the vaults list page needs. Response: { "now": epochMs, "vaults": [VaultSummary] }.

Field	Meaning
address	pToken (vault share token) contract address, lowercase.
name, symbol	On-chain ERC-20 metadata (e.g. "3x HOOD", "pHOOD3x").
market, direction, leverage	The perp market the vault trades, the exposure direction, and the target leverage multiple.
description, createdAt, ageDays	Display copy and creation time (ISO 8601; ageDays derived from it).
manager	Vault manager address (on-chain).
depositFeeBps, profitShareBps	Deposit fee (on-chain) and manager profit share (static config).
depositsPaused	Whether the vault currently accepts deposits.
tvlUsd	Vault NAV in USD (the on-chain oracle-attested value).
navPriceUsd	NAV per minted share - the price one share is worth.
netDepositedUsd, allTimePnlUsd	Net deposits since inception, and NAV minus net deposits (all-time trading PnL).
aprPct	Annualized return from share-price growth since inception.
performance24hPct	Share-price change over the trailing 24 hours.
sparkline24h	Trailing-24h share-price points (15-minute buckets): `[{ t, navPriceUsd }]`.

Vault detail

GET/v1/vaults/{address|symbol}

The vault is addressed by its pToken contract address or its on-chain symbol (case-insensitive), e.g. /v1/vaults/pHOOD3x. Everything in the list entry, plus:

Field	Meaning
markPriceUsd	Live perp mark price of the vault's market.
allTimeReturnPct	Share-price return since inception.
maxDrawdownPct	Largest share-price peak-to-trough since inception (≤ 0).
equityUsd, freeCollateralUsd	Live exchange account state backing the vault.
capacity	`{ maxNetDepositUsd, utilizationPct }` - the deposit cap and how much of it is used.
positions	Live open positions: market, side, size, entry/mark price, notional, unrealized PnL, leverage, margin.

Returns 404 for vaults this deployment does not manage, 400 for malformed addresses or symbols.

Vault history

GET/v1/vaults/{address|symbol}/history

Time series behind the NAV / TVL / PnL / Return charts. One point per bucket; each point is the freshest sample in its bucket.

Query param	Meaning
from, to	Epoch-ms bounds. Defaults: first recorded sample → now.
resolution	Bucket size: `1m`, `5m`, `15m`, `1h`, `4h`, `1d`. Omit to auto-select from the span (at most 2000 points per response).

Point field	Meaning
t	Sample time, epoch ms.
navPriceUsd	Share price at the sample.
tvlUsd	Vault NAV at the sample.
equityUsd, markPriceUsd	Live exchange equity and the market's mark price at the sample (may be null).
pnlUsd	NAV minus net deposits at the sample (cumulative trading PnL).
returnPct	Share-price return vs the first point of the returned series.

Health

GET/health

Process readiness: { ok, process, version, uptime_s, checks }, status 200/503.

Example

$ curl -s https://<this-host>/v1/vaults | jq '.vaults[0]'
{
  "address": "0xe24cabdf76dd1c2576049167eb1755c84b985c36",
  "name": "3x HOOD",
  "symbol": "pHOOD3x",
  "market": "HOOD-USD",
  "direction": "long",
  "leverage": 3,
  "tvlUsd": 101000.0,
  "navPriceUsd": 101.29,
  "aprPct": 8.0,
  "performance24hPct": 1.23,
  ...
}

$ curl -s https://<this-host>/v1/vaults/pHOOD3x | jq '.navPriceUsd'

$ curl -s "https://<this-host>/v1/vaults/0xe24c.../history?resolution=1h" | jq '.points | length'

History starts when NAV snapshotting was enabled for a vault, not at the vault's on-chain creation. APR, drawdown, and return figures are computed over the recorded window.