Developers

Public API, feeds & badges

Everything PerpEquities shows about stock perpetuals is available as machine-readable data: a stable JSON/CSV API, Atom feeds for new listings and trade ideas, and an SVG badge you can embed anywhere. No API key, no sign-up, CORS open.

JSON CSV Atom new Atom trade-ideas Badge

Overview

The API mirrors the site: the same snapshot that renders the ranking, the funding screener, the new-listings page and every asset page is exposed under /api/v1/. Coverage — which venues, which asset classes, how freshness is judged — is described on the methodology page and the venue directory.

Base URL: https://perpequities.com. All endpoints are GET over HTTPS.
Version: v1 is stable. Fields are only added, never renamed or removed; breaking changes would ship as v2 and be announced in the changelog.
Freshness: market data refreshes about once a minute; responses are edge-cached for 5 minutes (see caching). Every payload carries its generatedAt.
Formats: JSON by default, ?format=csv on list endpoints, Atom 1.0 for the feeds, SVG for the badge.

Quick start

curl -s "https://perpequities.com/api/v1/assets?assetClass=equity&live=1&limit=3" | jq '.data[] | {slug, price, change24h, venueCount}'

const res = await fetch("https://perpequities.com/api/v1/funding?limit=20");
const { generatedAt, data } = await res.json();
for (const row of data) {
  console.log(row.ticker, (row.spreadApr * 100).toFixed(1) + "% APR", row.longVenue, "->", row.shortVenue);
}

Conventions

Envelope. JSON responses are { generatedAt, count, total, ...meta, data }. generatedAt is the ISO-8601 UTC time of the underlying snapshot, count the rows in data, total the rows before ?limit=. Single-resource endpoints return count: 1 and an object in data.
Rates and changes are fractions, never percent: 0.0124 means +1.24 %, fundingApr: 0.1095 means 10.95 % per year. Multiply by 100 to display.
Money is USD as plain numbers (volume24hUsd: 42310000), no formatting, no currency symbols.
Timestamps are ISO-8601 in UTC with millisecond precision (2026-09-02T09:59:41.000Z).
Unknown is null, never 0 or an empty string. Sums over live venues are numbers and may be 0.
Identifiers. Assets use slugs such as aapl-perp; venues use short slugs such as bybit or hyperliquid. Both are stable and appear in the site's URLs. Asset endpoints also accept the bare ticker (aapl, AAPL) and legacy aliases.
Funding annualization is linear: native rate ÷ interval hours × 24 × 365. It is a comparison figure — funding re-prices every interval.
Live means the venue observation is inside the venue's freshness SLA. Stale contracts are still listed (with live: false) but excluded from sums and rankings.

GET `/api/v1/assets`

The ranking universe: one row per asset, market cap descending (unknown caps last), with every trading contract nested under venues. Same construction as the home ranking.

Examples

Parameters

Query parameter	Meaning
`assetClass`	equity · etf · index · commodity · fx · pre_ipo · preferred.
`venue`	Only assets with a trading contract on this venue slug.
`live`	1 — only assets with at least one live market.
`limit`	Rows to return, 1–2000 (default 500). The envelope's total reports the unlimited count.
`format`	json (default) or csv.

Sample response

{
  "generatedAt": "2026-09-02T10:00:00.000Z",
  "count": 1,
  "total": 412,
  "data": [
    {
      "slug": "aapl-perp",
      "ticker": "AAPL",
      "name": "Apple Inc.",
      "assetClass": "equity",
      "sector": "Technology",
      "country": "US",
      "price": 231.42,
      "change24h": 0.0124,
      "change7d": -0.0087,
      "marketCapUsd": 3450000000000,
      "volume24hUsd": 69950000,
      "openInterestUsd": 28290000,
      "venueCount": 2,
      "liveMarkets": 2,
      "url": "https://perpequities.com/stocks/aapl-perp",
      "venues": [
        {
          "venue": "bybit",
          "venueName": "Bybit",
          "symbol": "AAPL-USD",
          "venueSymbol": "AAPLUSDT",
          "status": "trading",
          "live": true,
          "price": 231.42,
          "mark": 231.42,
          "last": 231.4,
          "index": 231.18,
          "fundingRate": 0.0001,
          "fundingIntervalMinutes": 480,
          "fundingApr": 0.1095,
          "openInterestUsd": 18420000,
          "volume24hUsd": 42310000,
          "spreadBps": 1.8,
          "depth1PctUsd": 1240000,
          "maxLeverage": 50,
          "updatedAt": "2026-09-02T09:59:41.000Z"
        },
        {
          "venue": "hyperliquid",
          "venueName": "Hyperliquid HIP-3",
          "symbol": "AAPL-USD",
          "venueSymbol": "xyz:AAPL",
          "status": "trading",
          "live": true,
          "price": 231.39,
          "mark": 231.39,
          "last": 231.35,
          "index": 231.18,
          "fundingRate": 0.0000125,
          "fundingIntervalMinutes": 60,
          "fundingApr": 0.1095,
          "openInterestUsd": 9870000,
          "volume24hUsd": 27640000,
          "spreadBps": 2.4,
          "depth1PctUsd": 610000,
          "maxLeverage": 20,
          "updatedAt": "2026-09-02T09:59:55.000Z"
        }
      ]
    }
  ]
}

When filters are active they are echoed back as filters in the envelope (for example "filters": { "assetClass": "etf", "live": true }).

Asset
Field	Type	Description
`slug`	`string`	Stable asset identifier, e.g. aapl-perp. Also the path segment of the asset page.
`ticker`	`string`	Underlying ticker (AAPL).
`name`	`string`	Company / instrument name.
`assetClass`	`string`	equity · etf · index · commodity · fx · pre_ipo · preferred.
`sector`	`string \| null`	GICS-style sector for equities; null otherwise.
`country`	`string`	ISO-3166 alpha-2 country of the underlying (US, KR, …).
`price`	`number \| null`	Mark of the best live venue (deepest ±1 % book), falling back to its last trade.
`change24h`	`number \| null`	24-hour price change as a fraction (0.0124 = +1.24 %).
`change7d`	`number \| null`	7-day price change as a fraction.
`marketCapUsd`	`number \| null`	Market capitalization in USD. Pre-IPO values are curated estimates.
`volume24hUsd`	`number`	24-hour perpetual volume in USD, summed over LIVE venues.
`openInterestUsd`	`number`	Open interest in USD, summed over LIVE venues.
`venueCount`	`number`	Distinct venues in the nested venues list.
`liveMarkets`	`number`	Number of nested venue markets that are currently live.
`url`	`string`	Canonical English asset page.
`venues`	`VenueMarket[]`	Every trading contract for the asset, best market first (see the VenueMarket table).

VenueMarket (each element of venues)
Field	Type	Description
`venue`	`string`	Venue slug (see /api/v1/venues).
`venueName`	`string`	Display name of the venue.
`symbol`	`string`	Display symbol as shown on the site, e.g. AAPL-USD.
`venueSymbol`	`string`	The venue's own contract symbol (what its API calls it).
`status`	`string`	trading · planned · watchlist. Delisted contracts are never returned.
`live`	`boolean`	Market data is within the venue's freshness SLA.
`price`	`number \| null`	Mark price, falling back to the last trade.
`mark`	`number \| null`	Mark price.
`last`	`number \| null`	Last trade price.
`index`	`number \| null`	Venue index / oracle reference (its spot anchor).
`fundingRate`	`number \| null`	The venue's native per-interval funding rate as a fraction (0.0001 = 0.01 %).
`fundingIntervalMinutes`	`number \| null`	Funding interval in minutes (60, 480, …).
`fundingApr`	`number \| null`	Current funding linearly annualized, as a fraction (0.1095 = 10.95 % APR).
`openInterestUsd`	`number \| null`	Open interest in USD.
`volume24hUsd`	`number \| null`	24-hour traded volume in USD.
`spreadBps`	`number \| null`	Best bid/ask spread in basis points.
`depth1PctUsd`	`number \| null`	Order-book depth within ±1 % of mid, in USD (both sides).
`maxLeverage`	`number \| null`	Maximum leverage offered for the contract.
`updatedAt`	`string \| null`	ISO-8601 UTC timestamp of the venue observation.

GET `/api/v1/assets/{slug}`

One asset with every venue market, the cross-venue funding summary, a 7-day funding-history summary per venue and the perp-vs-spot basis rows — the data behind an asset page such as /stocks/aapl-perp. ?format=csv returns the venue markets, one line each.

Examples

Parameters

Query parameter	Meaning
`format`	json (default) or csv (venue markets, one line per contract).

Sample response

{
  "generatedAt": "2026-09-02T10:00:00.000Z",
  "count": 1,
  "data": {
    "slug": "aapl-perp",
    "ticker": "AAPL",
    "name": "Apple Inc.",
    "assetClass": "equity",
    "sector": "Technology",
    "country": "US",
    "price": 231.42,
    "change24h": 0.0124,
    "change7d": -0.0087,
    "marketCapUsd": 3450000000000,
    "volume24hUsd": 69950000,
    "openInterestUsd": 28290000,
    "venueCount": 2,
    "liveMarkets": 2,
    "url": "https://perpequities.com/stocks/aapl-perp",
    "venues": [
      {
        "venue": "bybit",
        "venueName": "Bybit",
        "symbol": "AAPL-USD",
        "venueSymbol": "AAPLUSDT",
        "status": "trading",
        "live": true,
        "price": 231.42,
        "mark": 231.42,
        "last": 231.4,
        "index": 231.18,
        "fundingRate": 0.0001,
        "fundingIntervalMinutes": 480,
        "fundingApr": 0.1095,
        "openInterestUsd": 18420000,
        "volume24hUsd": 42310000,
        "spreadBps": 1.8,
        "depth1PctUsd": 1240000,
        "maxLeverage": 50,
        "updatedAt": "2026-09-02T09:59:41.000Z"
      },
      {
        "venue": "hyperliquid",
        "venueName": "Hyperliquid HIP-3",
        "symbol": "AAPL-USD",
        "venueSymbol": "xyz:AAPL",
        "status": "trading",
        "live": true,
        "price": 231.39,
        "mark": 231.39,
        "last": 231.35,
        "index": 231.18,
        "fundingRate": 0.0000125,
        "fundingIntervalMinutes": 60,
        "fundingApr": 0.1095,
        "openInterestUsd": 9870000,
        "volume24hUsd": 27640000,
        "spreadBps": 2.4,
        "depth1PctUsd": 610000,
        "maxLeverage": 20,
        "updatedAt": "2026-09-02T09:59:55.000Z"
      }
    ],
    "isin": "US0378331005",
    "currency": "USD",
    "exchange": "NASDAQ",
    "funding": {
      "medianApr": 0.1095,
      "minApr": 0.0876,
      "maxApr": 0.1314,
      "venuesUsed": 2
    },
    "fundingHistory": [
      {
        "venue": "bybit",
        "venueName": "Bybit",
        "symbol": "AAPL-USD",
        "range": "7d",
        "points": 21,
        "from": "2026-08-26T08:00:00.000Z",
        "to": "2026-09-02T08:00:00.000Z",
        "latestApr": 0.1095,
        "averageApr": 0.0821,
        "minApr": -0.0219,
        "maxApr": 0.1971
      }
    ],
    "basis": [
      {
        "venue": "bybit",
        "venueName": "Bybit",
        "symbol": "AAPL-USD",
        "mark": 231.42,
        "spotRef": 231.18,
        "basis": 0.00104,
        "fundingApr": 0.1095,
        "volume24hUsd": 42310000,
        "openInterestUsd": 18420000
      }
    ]
  }
}

Unknown slugs answer 404 with a JSON error. All fields of the asset row are present, plus:

Additional fields
Field	Type	Description
`isin`	`string \| null`	ISIN of the underlying when known.
`currency`	`string`	Quote currency of the underlying's home listing (USD, KRW, …).
`exchange`	`string \| null`	Home stock exchange (NASDAQ, NYSE, KRX, …).
`funding`	`object \| null`	Cross-venue funding summary: medianApr, minApr, maxApr (fractions) and venuesUsed. Venue-deduplicated; null when no live venue publishes funding.
`fundingHistory`	`object[]`	7-day stored funding summary for up to four of the most liquid venues: venue, venueName, symbol, range, points, from, to, latestApr, averageApr, minApr, maxApr.
`basis`	`object[]`	Perp-vs-spot basis per live venue: venue, venueName, symbol, mark, spotRef, basis (mark/spot − 1 as a fraction), fundingApr, volume24hUsd, openInterestUsd. Equities and ETFs only.

GET `/api/v1/venues`

Every tracked venue with instrument and asset counts and 24-hour totals, busiest first. Mirrors the venue directory.

Examples

Parameters

Query parameter	Meaning
`limit`	Rows to return, 1–2000 (default 500). The envelope's total reports the unlimited count.
`format`	json (default) or csv.

Sample response

{
  "generatedAt": "2026-09-02T10:00:00.000Z",
  "count": 1,
  "total": 23,
  "data": [
    {
      "venue": "bybit",
      "name": "Bybit",
      "type": "cex",
      "website": "https://www.bybit.com",
      "status": "active",
      "coverageMode": "live",
      "instruments": 128,
      "liveMarkets": 126,
      "assets": 121,
      "volume24hUsd": 812400000,
      "openInterestUsd": 236900000,
      "url": "https://perpequities.com/venues/bybit"
    }
  ]
}

Venue
Field	Type	Description
`venue`	`string`	Venue slug used in every other endpoint.
`name`	`string`	Display name.
`type`	`string`	cex · dex · builder-dex.
`website`	`string`	The venue's public website.
`status`	`string`	active · integration · watchlist (delisted venues are omitted).
`coverageMode`	`string`	live · hybrid · seeded — how the venue's market data is collected.
`instruments`	`number`	Contracts tracked on the venue.
`liveMarkets`	`number`	Contracts within the freshness SLA right now.
`assets`	`number`	Distinct underlying assets on the venue.
`volume24hUsd`	`number`	24-hour volume in USD over live contracts.
`openInterestUsd`	`number`	Open interest in USD over live contracts.
`url`	`string`	Canonical venue page.

GET `/api/v1/venues/{venue}`

Every contract a venue lists, best markets first (live, then depth, volume and open interest). The envelope carries venue and venueName.

Examples

Parameters

Query parameter	Meaning
`limit`	Rows to return, 1–2000 (default 500). The envelope's total reports the unlimited count.
`format`	json (default) or csv.

Sample response

{
  "generatedAt": "2026-09-02T10:00:00.000Z",
  "count": 1,
  "total": 128,
  "venue": "bybit",
  "venueName": "Bybit",
  "data": [
    {
      "slug": "aapl-perp",
      "ticker": "AAPL",
      "name": "Apple Inc.",
      "assetClass": "equity",
      "url": "https://perpequities.com/stocks/aapl-perp",
      "venue": "bybit",
      "venueName": "Bybit",
      "symbol": "AAPL-USD",
      "venueSymbol": "AAPLUSDT",
      "status": "trading",
      "live": true,
      "price": 231.42,
      "mark": 231.42,
      "last": 231.4,
      "index": 231.18,
      "fundingRate": 0.0001,
      "fundingIntervalMinutes": 480,
      "fundingApr": 0.1095,
      "openInterestUsd": 18420000,
      "volume24hUsd": 42310000,
      "spreadBps": 1.8,
      "depth1PctUsd": 1240000,
      "maxLeverage": 50,
      "updatedAt": "2026-09-02T09:59:41.000Z"
    }
  ]
}

Each row is a VenueMarket with the asset identity attached:

Additional fields
Field	Type	Description
`slug`	`string`	Asset slug (join key for /api/v1/assets/{slug}).
`ticker`	`string`	Underlying ticker.
`name`	`string`	Underlying name.
`assetClass`	`string`	Asset class of the underlying.
`url`	`string`	Canonical asset page.

GET `/api/v1/funding`

The current cross-venue funding matrix, spread-ranked: one row per asset with every venue's native rate, its hourly-normalized rate and APR. Same construction as the funding screener. The CSV form explodes the matrix into one line per (asset, venue) cell.

Examples

Parameters

Query parameter	Meaning
`limit`	Rows to return, 1–2000 (default 500). The envelope's total reports the unlimited count.
`format`	json (default) or csv.

Sample response

{
  "generatedAt": "2026-09-02T10:00:00.000Z",
  "count": 1,
  "total": 187,
  "data": [
    {
      "slug": "aapl-perp",
      "ticker": "AAPL",
      "assetClass": "equity",
      "spreadHourly": 0.0000275,
      "spreadApr": 0.2409,
      "longVenue": "bybit",
      "shortVenue": "mexc",
      "volume24hUsd": 84120000,
      "url": "https://perpequities.com/stocks/aapl-perp",
      "venues": [
        {
          "venue": "bybit",
          "venueName": "Bybit",
          "symbol": "AAPLUSDT",
          "fundingRate": 0.0001,
          "interval": "8h",
          "fundingHourly": 0.0000125,
          "fundingApr": 0.1095,
          "volume24hUsd": 42310000,
          "openInterestUsd": 18420000
        },
        {
          "venue": "hyperliquid",
          "venueName": "Hyperliquid HIP-3",
          "symbol": "xyz:AAPL",
          "fundingRate": 0.0000125,
          "interval": "1h",
          "fundingHourly": 0.0000125,
          "fundingApr": 0.1095,
          "volume24hUsd": 27640000,
          "openInterestUsd": 9870000
        },
        {
          "venue": "mexc",
          "venueName": "MEXC",
          "symbol": "AAPL_USDT",
          "fundingRate": 0.00032,
          "interval": "8h",
          "fundingHourly": 0.00004,
          "fundingApr": 0.3504,
          "volume24hUsd": 14170000,
          "openInterestUsd": 3210000
        }
      ]
    }
  ]
}

Funding row
Field	Type	Description
`slug`	`string`	Asset slug.
`ticker`	`string`	Underlying ticker.
`assetClass`	`string`	Asset class.
`spreadHourly`	`number \| null`	max(hourly) − min(hourly) funding across liquid venues, as a fraction per hour. null with fewer than two liquid venues.
`spreadApr`	`number \| null`	spreadHourly × 24 × 365 — the comparison figure shown on /funding.
`longVenue`	`string \| null`	Venue with the lowest funding (the long leg of the spread).
`shortVenue`	`string \| null`	Venue with the highest funding (the short leg).
`volume24hUsd`	`number`	Summed 24-hour volume over the asset's venues.
`url`	`string`	Canonical asset page.
`venues`	`FundingCell[]`	One cell per venue, most liquid first: venue, venueName, symbol, fundingRate (native, per interval), interval ("1h", "8h"), fundingHourly, fundingApr, volume24hUsd, openInterestUsd.

GET `/api/v1/listings`

New perpetual listings grouped per asset — the /new page as data. The default window is 30 days (max 90); the envelope reports days, windowStart and totalInWindow.

Examples

Parameters

Query parameter	Meaning
`days`	Window in days, 1–90 (default 30).
`limit`	Rows to return, 1–2000 (default 500). The envelope's total reports the unlimited count.
`format`	json (default) or csv.

Sample response

{
  "generatedAt": "2026-09-02T10:00:00.000Z",
  "count": 1,
  "total": 64,
  "days": 30,
  "windowStart": "2026-08-03T10:00:00.000Z",
  "totalInWindow": 64,
  "data": [
    {
      "slug": "shein-perp",
      "ticker": "SHEIN",
      "name": "Shein",
      "assetClass": "pre_ipo",
      "firstEver": true,
      "listedAt": "2026-09-01T14:05:12.000Z",
      "venueCount": 2,
      "url": "https://perpequities.com/stocks/shein-perp",
      "venues": [
        {
          "venue": "aster",
          "venueName": "Aster",
          "firstSeenAt": "2026-09-01T14:05:12.000Z"
        },
        {
          "venue": "hyperliquid",
          "venueName": "Hyperliquid HIP-3",
          "firstSeenAt": "2026-08-31T22:40:03.000Z"
        }
      ]
    }
  ]
}

Listing
Field	Type	Description
`slug`	`string`	Asset slug.
`ticker`	`string`	Underlying ticker.
`name`	`string`	Underlying name.
`assetClass`	`string`	Asset class.
`firstEver`	`boolean`	true when the asset's very first perpetual anywhere appeared inside the window.
`listedAt`	`string`	ISO-8601 time of the newest listing inside the window.
`venueCount`	`number`	Venues that listed the asset inside the window.
`url`	`string`	Canonical asset page.
`venues`	`object[]`	venue, venueName, firstSeenAt (ISO-8601) per new listing, newest first.

CSV export

Add ?format=csv to any list endpoint (and to /api/v1/assets/{slug} for its venue markets). The response is text/csv; charset=utf-8, served inline with a dated filename in Content-Disposition (for example perpequities-assets-2026-09-02.csv), so browsers display it and spreadsheet tools save it with a sensible name.

RFC 4180: header row first, CRLF line endings, fields quoted only when they contain a comma, quote or line break; embedded quotes are doubled.
Numbers are written unquoted and unformatted; booleans as true/false; unknown values as empty cells.
Nested lists are flattened: venues becomes a pipe-joined list of venue slugs (bybit|hyperliquid) on the asset and listing exports, and the funding export is in long format (one line per asset-venue cell).
?limit= applies before rendering, so ?format=csv&limit=2000 is the complete universe.

slug,ticker,name,assetClass,sector,country,price,change24h,change7d,marketCapUsd,volume24hUsd,openInterestUsd,venueCount,liveMarkets,venues,url
aapl-perp,AAPL,Apple Inc.,equity,Technology,US,231.42,0.0124,-0.0087,3450000000000,69950000,28290000,2,2,bybit|hyperliquid,https://perpequities.com/stocks/aapl-perp
brk-b-perp,BRK.B,"Berkshire Hathaway, Inc.",equity,Financial Services,US,472.1,-0.0031,0.0112,1020000000000,3120000,1450000,1,1,bybit,https://perpequities.com/stocks/brk-b-perp

Atom feeds

Two Atom 1.0 feeds (RFC 4287), auto-discoverable from every page via <link rel="alternate" type="application/atom+xml">. Entry ids are tag: URIs (RFC 4151) and never change; updated moves when an entry gains a venue or a signal is refreshed. Both feeds are English-only.

/feeds/new.xml — PerpEquities: new stock perpetual listings. One entry per asset listed in the last 30 days (up to 100), categories: first-listing / venue-expansion, the asset class and each venue slug.
/feeds/trade-ideas.xml — PerpEquities: trade ideas. The latest 50 public trade-idea signals (funding spreads, volume spikes, new listings, after-hours moves, open-interest shifts, analyst moves, congressional trades, 13F filings), categories: signal type and status. Observations, not advice.

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <id>tag:perpequities.com,2026-09-02:feed/new</id>
  <title>PerpEquities — new stock perpetual listings</title>
  <link rel="alternate" type="text/html" href="https://perpequities.com/new"/>
  <link rel="self" type="application/atom+xml" href="https://perpequities.com/feeds/new.xml"/>
  <updated>2026-09-01T14:05:12.000Z</updated>
  <author><name>PerpEquities</name><uri>https://perpequities.com</uri></author>
  <entry>
    <id>tag:perpequities.com,2026-09-01:listing/shein-perp/2026-09-01</id>
    <title>SHEIN: first perpetual listing — Aster, Hyperliquid HIP-3</title>
    <link rel="alternate" type="text/html" href="https://perpequities.com/stocks/shein-perp"/>
    <updated>2026-09-01T14:05:12.000Z</updated>
    <published>2026-08-31T22:40:03.000Z</published>
    <category term="first-listing"/>
    <category term="pre_ipo"/>
    <summary type="text">SHEIN (Shein) pre-IPO perpetual listed for the first time on 2 venues: Aster, Hyperliquid HIP-3.</summary>
  </entry>
</feed>

SVG badge & embed

/badge/{slug}.svg renders a 240×64 badge with the ticker, price, 24-hour change, the cheapest current funding rate with its venue and the PerpEquities wordmark. Add ?theme=light for light backgrounds (dark is the default). The bare slug without .svg works too. Unknown slugs answer 404.

Embed

<a href="https://perpequities.com/stocks/aapl-perp"><img src="https://perpequities.com/badge/aapl-perp.svg" width="240" height="64" alt="AAPL perpetuals · perpequities.com" loading="lazy"></a>

[![AAPL perpetuals · perpequities.com](https://perpequities.com/badge/aapl-perp.svg)](https://perpequities.com/stocks/aapl-perp)

Badges are cached for 5 minutes at the edge and in the browser, so an embedded badge never costs your page a slow request. Every asset page has a copy-ready snippet in its Embed this asset block.

Caching, ETags & rate limits

Header	Value	Meaning
`Cache-Control`	`public, max-age=60, s-maxage=300`	Browsers may reuse a response for 60 s, the CDN edge for 5 min (badges: 5 min in both).
`ETag`	`"<sha-256 of the body>"`	Strong validator. Send it back as `If-None-Match` and unchanged data answers `304` without a body.
`Access-Control-Allow-Origin`	`*`	Call the API straight from the browser. `ETag`, `Content-Disposition` and `Retry-After` are exposed to scripts.
`Retry-After`	`60` / `30`	Sent with `429` (rate limited) and `503` (snapshot unavailable).

curl -si "https://perpequities.com/api/v1/venues" -H 'If-None-Match: "<etag from the previous response>"'
# HTTP/2 304 — nothing changed, no body transferred

Rate limit: 60 requests per minute per IP at the origin, across all public endpoints. Edge cache hits do not count, so a poller that respects the 5-minute TTL and sends If-None-Match practically never sees a 429. Need more? Fetch the full universe with ?limit=2000 instead of one request per asset, or get in touch.

The default page size is 500 rows; the maximum is 2000. There is no cursor — the universe fits in one response.

Errors

Errors are JSON with a machine-readable error code and a human-readable message, always sent with Cache-Control: no-store and the CORS headers.

Status	`error`	When
`404`	`not_found`	Unknown asset or venue slug (the badge answers with plain text).
`429`	`rate_limited`	More than 60 origin requests in a minute from one IP. `Retry-After: 60`.
`503`	`unavailable`	No market snapshot can be served (never a cacheable empty universe). `Retry-After: 30`.

{
  "error": "not_found",
  "message": "Unknown asset \"foo\" — list the universe at https://perpequities.com/api/v1/assets."
}

{
  "error": "rate_limited",
  "message": "Limit is 60 requests per minute per IP; responses are cacheable for 5 minutes — honour ETag / If-None-Match."
}

{
  "error": "unavailable",
  "message": "Market snapshot temporarily unavailable — retry shortly."
}

Attribution & licence

The API, feeds and badges are free to use — personal, academic and commercial — as long as you credit PerpEquities as the source with a link. In an app, a chart or a dataset, “Data: PerpEquities (perpequities.com)” linking to https://perpequities.com is enough; the badge counts as attribution on its own.

Do not present the data as your own or strip the attribution when redistributing it.
Do not mirror the whole API as a competing feed at higher frequency than the cache allows; bulk users should honour the 5-minute TTL.
Market data comes from the venues' public APIs; reference data (market caps, sectors, identifiers) from licensed providers and curated estimates (pre-IPO). Numbers can be delayed, incomplete or wrong — verify with the venue before acting. Nothing here is investment advice. See the methodology and disclosures.
The service is provided as-is, without uptime or accuracy guarantees, and may change or be withdrawn with notice in the changelog.

Changelog

2026-09-02 — v1 launch: JSON + CSV endpoints: /api/v1/assets, /api/v1/assets/{slug}, /api/v1/venues, /api/v1/venues/{venue}, /api/v1/funding, /api/v1/listings.
Atom 1.0 feeds: /feeds/new.xml (new perpetual listings) and /feeds/trade-ideas.xml (public trade-idea signals).
Embeddable SVG badges: /badge/{slug}.svg with ?theme=dark|light.
Contract: 5-minute edge cache with strong ETags, 60 origin requests/minute/IP, CORS open for GET.

Overview

Quick start

Conventions

GET /api/v1/assets

Examples

Parameters

Sample response

GET /api/v1/assets/{slug}

Examples

Parameters

Sample response

GET /api/v1/venues

Examples

Parameters

Sample response

GET /api/v1/venues/{venue}

Examples

Parameters

Sample response

GET /api/v1/funding

Examples

Parameters

Sample response

GET /api/v1/listings

Examples

Parameters

Sample response

CSV export

Atom feeds

SVG badge & embed

Embed

Caching, ETags & rate limits

Errors

Attribution & licence

Changelog

GET `/api/v1/assets`

GET `/api/v1/assets/{slug}`

GET `/api/v1/venues`

GET `/api/v1/venues/{venue}`

GET `/api/v1/funding`

GET `/api/v1/listings`