> ## 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.

# New Listings API

> Track new Spot listings, Perp listings, delistings, suspensions, and scheduled starts across major exchanges with source confidence.

Track new Spot listings, Perp listings, delistings, suspensions, resumptions, and scheduled trading starts across major CEXs and Perp DEXs. Enabled connectors refresh hourly and every canonical event carries verification metadata.

The canonical dataset is `exchange_listing_events`. The legacy `exchange_listings` aggregate remains available for backward-compatible recent and hub payloads while new event APIs expose the richer lifecycle model.

***

## Listing events

`GET /v1/listings/events`

Returns the canonical event feed used by the listings feed and calendar views. Supports CEX Spot markets, derivatives markets, and Perp DEX venues.

### Query parameters

**exchange** `string`

Filter to a single venue, for example `binance`, `okx`, `bitget`, `bybit`, or `aster`. A venue with no enabled connector sets `partial: true` with a reason in `partial_reasons`; `GET /v1/listings/exchanges` shows which venues and market types are enabled.

**venue\_type** `string`

`cex`, `perp_dex`, or `dex`.

**market\_type** `string`

`spot`, `perp`, `futures`, `options`, or `margin`.

**event\_type** `string`

`listing`, `delisting`, `suspension`, `resumption`, or `prelaunch`.

**asset\_class** `string`

`token`, `spot_pair`, `perp_contract`, `futures_contract`, or `options_contract`.

**status** `string`

`announced`, `scheduled`, `live`, `completed`, `cancelled`, or `needs_review`.

**confidence** `string`

`authoritative`, `high`, `medium`, `low`, `proxy`, or `manual`.

**narrative** `string`

Filter by Sharpe narrative slug.

**from** `string`

ISO date or datetime lower bound.

**to** `string`

ISO date or datetime upper bound.

**days** `integer`

Lookback window in days. Range 1-365. Default 90.

**limit** `integer`

Max rows returned. Range 1-1000. Default 200.

**cursor** `string`

Opaque cursor returned as `next_cursor`. Pass it through unchanged; it advances database and official-overlay rows independently.

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/listings/events \
  -H "Authorization: Bearer sk_live_your_key_here" \
  --data-urlencode "market_type=perp" \
  --data-urlencode "event_type=listing" \
  --data-urlencode "confidence=authoritative"
```

```json Response shape theme={null}
{
  "data": {
    "rows": [
      {
        "event_uid": "f9cf0df0c3e214f0bb3b5fa63ab76787",
        "exchange": "aster",
        "venue_type": "perp_dex",
        "market_type": "perp",
        "event_type": "listing",
        "instrument_id": "ASTERUSDT",
        "token_symbol": "ASTER",
        "effective_at": "2026-05-21T08:00:00.000Z",
        "status": "live",
        "source_kind": "official_api",
        "source_confidence": "authoritative",
        "source_url": "https://fapi.asterdex.com/fapi/v1/exchangeInfo"
      }
    ],
    "next_cursor": null,
    "window_days": 90,
    "generated_at": "2026-05-21T12:00:00.000Z",
    "last_updated_at": "2026-05-21T08:00:00.000Z",
    "partial": false,
    "partial_reasons": [],
    "provider_coverage": [
      {
        "provider": "exchange_listing_events",
        "kind": "database",
        "status": "ok",
        "row_count": 0,
        "last_observed_at": null
      },
      {
        "provider": "aster_perp",
        "kind": "official_overlay",
        "status": "ok",
        "row_count": 1,
        "last_observed_at": "2026-05-21T08:00:00.000Z"
      }
    ],
    "source": "events"
  },
  "meta": {
    "request_id": "req_abc123def456ghij",
    "timestamp": "2026-05-21T12:00:00.000Z",
    "elapsed_ms": 8
  }
}
```

`generated_at` is when the API assembled the response; do not use it as market-data freshness. Use `last_updated_at` for the freshest real row observation and inspect `partial`, `partial_reasons`, and `provider_coverage` before acting on an apparently quiet feed.

`partial` is true exactly when `partial_reasons` is non-empty. Each reason is one sentence naming the gap:

* a provider whose request failed;
* a live exchange instrument feed whose newest listing is more than 60 days old;
* the hourly spot-listings ingest, when the query covers its venues and its last completed run is more than 2 hours old (or no completed run is logged);
* the canonical events table being unavailable, in which case rows come from the compatibility table and `source` is `compatibility`;
* a requested `exchange`, `venue_type`, or `market_type` that no enabled connector covers, so an empty or short result is not evidence that nothing was listed.

A provider flagged as failed or stale reports `status: "error"` in `provider_coverage`; the rows that did arrive are still usable.

***

## Exchange coverage

`GET /v1/listings/exchanges`

Returns the typed connector registry: supported market types, source URLs, parser confidence, enabled status, and polling group for each exchange.

### Query parameters

**venue\_type** `string`

Optional filter: `cex`, `perp_dex`, or `dex`.

**market\_type** `string`

Optional filter: `spot`, `perp`, `futures`, `options`, or `margin`.

**enabled** `string`

`true` or `false`.

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/listings/exchanges \
  -H "Authorization: Bearer sk_live_your_key_here" \
  --data-urlencode "market_type=perp"
```

***

## Hub payload

`GET /v1/listings/data`

Returns the full New Listings hub payload: weekly and monthly aggregated counts by narrative and by exchange, recent listings for the last 90 days, and summary stats. This is the same data that powers the /new-listings terminal page.

### Query parameters

**narrative** `string`

Filter to a single narrative slug (e.g. `ai-agents`, `memes`, `layer-1`, `rwa`, `defi`). When set, all returned counts are scoped to that narrative.

**exchange** `string`

Filter to a single exchange. Legacy aggregates currently contain enabled compatibility venues; event APIs expose the full registry.

### Response fields

**weekly** `array`

Weekly buckets, last 26 weeks. Each element: `{ bucket_date, exchange, narrative_slug, listing_count }`. `bucket_date` is ISO-week Monday (UTC).

**monthly** `array`

Monthly buckets, last 12 months. Same shape as `weekly` but with month-start `bucket_date`.

**recent** `array`

Raw rows from the last 90 days, newest first. Each: `{ id, token_symbol, token_name, token_coingecko_id, exchange, listing_date, listing_date_source, narrative_slug }`.

**totals** `object`

`{ thisWeek, lastWeek, thisMonth, lastMonth }`: listing counts for UI delta calculations.

**topNarrativesThisMonth** `array`

Top 5 narratives ranked by listing count in the current month. Each: `{ narrative_slug, count }`.

**topExchangesThisMonth** `array`

Top 5 exchanges ranked by listing count in the current month. Each: `{ exchange, count }`.

**lastListingAt** `string`

Freshest `listing_date` across active rows (ISO date). Null if no data yet.

**lastUpdatedAt** `string`

Latest `categorized_at` timestamp (when any row was last triaged or refreshed).

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/listings/data \
  -H "Authorization: Bearer sk_live_your_key_here" \
  --data-urlencode "narrative=ai-agents"
```

```ts TypeScript theme={null}
const res = await fetch(
  'https://www.sharpe.ai/api/v1/listings/data?narrative=ai-agents',
  { headers: { Authorization: 'Bearer sk_live_your_key_here' } },
);
const { data } = await res.json();
```

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

resp = requests.get(
    "https://www.sharpe.ai/api/v1/listings/data",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
    params={"narrative": "ai-agents"},
)
data = resp.json()["data"]
```

```json title="Response (truncated)" theme={null}
{
  "data": {
    "weekly": [
      { "bucket_date": "2026-03-30", "exchange": "mexc",
        "narrative_slug": "ai-agents", "listing_count": 5 }
    ],
    "monthly": [
      { "bucket_date": "2026-03-01", "exchange": "mexc",
        "narrative_slug": "ai-agents", "listing_count": 12 }
    ],
    "recent": [
      { "token_symbol": "GRASS", "token_name": "Grass",
        "token_coingecko_id": "grass", "exchange": "mexc",
        "listing_date": "2024-12-07",
        "listing_date_source": "exchange_kline",
        "narrative_slug": "ai-agents" }
    ],
    "totals": { "thisWeek": 0, "lastWeek": 2,
      "thisMonth": 14, "lastMonth": 36 },
    "topNarrativesThisMonth": [
      { "narrative_slug": "ai-agents", "count": 3 },
      { "narrative_slug": "memes", "count": 3 }
    ],
    "topExchangesThisMonth": [
      { "exchange": "mexc", "count": 9 }
    ],
    "lastListingAt": "2026-04-13",
    "lastUpdatedAt": "2026-04-21T00:08:32Z"
  },
  "meta": {
    "request_id": "req_abc123def456ghij",
    "timestamp": "2026-04-21T00:09:00.000Z",
    "elapsed_ms": 10
  }
}
```

***

## Recent listings feed

`GET /v1/listings/recent`

A flat list of recent token listings. Defaults remain compatible with the legacy spot feed. The legacy feed holds only resolved spot listings (a CoinGecko id and a mapped narrative), so brand-new tokens awaiting resolution and perps are missing, and it returns no `next_cursor`: `limit` truncates it. Event-specific filters such as `market_type`, `event_type`, `status`, and `confidence`, a `from`/`to`/`cursor`, or an exchange outside binance, okx, bybit, gateio and mexc switch the endpoint to the canonical event feed (spot and perp, every status, cursor-paged) while preserving the old row shape.

### Query parameters

**narrative** `string`

Filter to a single narrative slug.

**exchange** `string`

Filter to a single exchange, including enabled compatibility venues and event-registry venues such as `bitget`, `bingx`, or `aster`.

**venue\_type** `string`

Optional event-feed filter: `cex`, `perp_dex`, or `dex`.

**market\_type** `string`

Optional event-feed filter: `spot`, `perp`, `futures`, `options`, or `margin`.

**event\_type** `string`

Optional event-feed filter: `listing`, `delisting`, `suspension`, `resumption`, or `prelaunch`.

**asset\_class** `string`

Optional event-feed instrument filter: `token`, `spot_pair`, `perp_contract`, `futures_contract`, or `options_contract`.

**status** `string`

Optional event-feed status filter: `announced`, `scheduled`, `live`, `completed`, `cancelled`, or `needs_review`.

**confidence** `string`

Optional source confidence filter.

**from** `string`

ISO date or datetime lower bound.

**to** `string`

ISO date or datetime upper bound.

**days** `integer`

Lookback window in days. Range 1-365. Default 90.

**limit** `integer`

Max rows returned. Range 1-1000. Default 200.

**cursor** `string`

Cursor returned as `next_cursor` for pagination.

### Response fields

**rows** `array`

Array of listing rows sorted by `listing_date` descending. Each: `{ token_symbol, token_name, token_id, exchange, listing_date, listing_date_source, narrative_slug }`.

**count** `integer`

Number of rows returned.

**window\_days** `integer`

Echo of the `days` parameter for clarity.

**next\_cursor** `string | null`

Present on event-feed responses; pass it as `cursor` to request the next page.

**generated\_at** `string`

Event-feed response assembly time, not source freshness.

**last\_updated\_at** `string | null`

Freshest real source observation on event-feed responses. Do not substitute `generated_at`.

**partial** `boolean`

Present on event-feed responses; true exactly when `partial_reasons` is non-empty.

**partial\_reasons** `array`

Present on event-feed responses. One sentence per coverage gap (a failed or stale provider, or a requested venue or market type with no enabled connector), as described under listing events. Empty when coverage is whole.

**provider\_coverage** `array`

Per-database and official-overlay health on event-feed responses.

### Source values

Legacy rows carry `listing_date_source`; canonical event rows carry `source_kind` and `source_confidence`:

* `exchange_kline`: derived from the exchange's own k-line first-trade timestamp (authoritative)
* `official_api` / `official_status`: parsed from an exchange or perp DEX public endpoint
* `official_announcement`: parsed from an exchange announcement source
* `market_data`: inferred from market data when no announcement source exists
* `proxy` / `first_seen`: when Sharpe first observed the instrument
* `manual`: admin-set

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/listings/recent \
  -H "Authorization: Bearer sk_live_your_key_here" \
  --data-urlencode "exchange=binance" \
  --data-urlencode "days=30"
```

```ts TypeScript theme={null}
const res = await fetch(
  'https://www.sharpe.ai/api/v1/listings/recent?exchange=binance&days=30',
  { headers: { Authorization: 'Bearer sk_live_your_key_here' } },
);
const { data } = await res.json();
```

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

resp = requests.get(
    "https://www.sharpe.ai/api/v1/listings/recent",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
    params={"exchange": "binance", "days": 30},
)
data = resp.json()["data"]
```

```json title="Response (truncated)" theme={null}
{
  "data": {
    "rows": [
      { "token_symbol": "TRUMP", "token_name": "Official Trump",
        "token_id": "official-trump",
        "exchange": "binance",
        "listing_date": "2025-01-19",
        "listing_date_source": "exchange_kline",
        "narrative_slug": "memes" }
    ],
    "count": 1,
    "window_days": 30
  },
  "meta": {
    "request_id": "req_abc123def456ghij",
    "timestamp": "2026-05-21T12:00:00.000Z",
    "elapsed_ms": 9
  }
}
```

***

## Narratives

Every listing is tagged to one of Sharpe's 30 canonical narrative slugs (same taxonomy as `/v1/narratives/data`). The hub (`/v1/listings/data`) and the default recent feed count only rows with `status = 'active'` and a resolved narrative, so they undercount the newest listings. The event feed (`/v1/listings/events`) also returns unresolved listings as `status = needs_review`, usually with narrative `uncategorized`.

### Supported narrative slugs

`layer-1` · `layer-2` · `defi` · `ai-agents` · `defai` · `depin` · `desci` · `gaming` · `dex-tokens` · `cex-tokens` · `lending` · `memes` · `nfts` · `oracles` · `privacy` · `rwa` · `stablecoins` · `restaking` · `liquid-staking` · `modular` · `socialfi` · `intent` · `prediction-markets` · `perps` · `bridges` · `account-abstraction` · `tap-to-earn` · `telegram-apps` · `zk` · `yield-farming`

***

## Update cadence

Listing announcements are not high-frequency market data, but launch workflows benefit from tighter freshness. Enabled connectors run hourly in grouped cron windows, and the rollup cron follows after ingestion to refresh compatibility and event-derived materialized views.

| Component | Schedule |
| - | - |
| Core listing events ingest | `7 * * * *` UTC |
| Rollup (compatibility + event matviews) | `55 * * * *` UTC |
| Official overlays (exchange instrument lists and announcement feeds; a copy older than 2 hours is never served) | `11 * * * *` UTC |

The core ingest runs every enabled snapshot connector. Venues in the registry's extended group have no enabled connector, so no ingest runs for them; their listings come only from an official overlay where the venue has one. Disabled connectors stay out of cron until fixture parsing and rate-limit behavior pass validation.


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