API Documentation — CEX Listings Monitor

Introduction

The CEX Listings Monitor API gives you machine-readable access to the same data the bots deliver in real time. Use it to build trading bots, dashboards, or data pipelines on top of our 9-exchange monitoring infrastructure.

Base URL

https://cex.holits.com/api

Format

All responses are application/json. All timestamps are ISO 8601 UTC.

Versioning

The current version is v1. Breaking changes will be announced in the bot changelog.

OpenAPI Spec

Machine-readable spec available at openapi.yaml (OpenAPI 3.0.3). Try it interactively →

Authentication

Every protected endpoint requires a Bearer token in the Authorization header. Generate keys from the bot — you need an active Basic or Pro subscription.

# Telegram
/apikey generate myapp

# Discord (ephemeral — only you see the response)
/apikey action:generate label:myapp

The key is shown exactly once. Store it immediately in an environment variable or secrets manager — it cannot be retrieved again.

# All API requests
curl https://cex.holits.com/api/pairs/new \
  -H "Authorization: Bearer cex_your_key_here"

To view or revoke your keys:

/apikey list
/apikey revoke cex_ab12

You can hold up to 3 API keys per account at any time.

Rate Limits

Rate limits are enforced per API key using a 60-second fixed window. The window resets automatically — no action required.

Tier	Requests / minute	Monthly price
Basic	60	$14.99
Pro	1,000	$34.99

When the limit is exceeded the API returns HTTP 429:

{
  "error": "Rate limit exceeded",
  "retryAfterMs": 42000
}

retryAfterMs is the exact number of milliseconds until the window resets.

Error Responses

All error responses follow the same shape:

{ "error": "Human-readable message" }

Status	Meaning
`401`	Missing, malformed, or invalid API key. The same error is returned whether the key is absent or wrong — no information leakage.
`403`	Valid key but your subscription tier is below the minimum for this endpoint.
`429`	Rate limit exceeded. Body includes `retryAfterMs`.
`500`	Internal server error.

Endpoints

GET /api/health Public

Returns the service health status and API version. No authentication required. Suitable for uptime monitors.

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2024-01-15T12:00:00.000Z"
}

GET /api/pairs/new Pro+

Returns trading pairs recently detected across monitored exchanges, sorted by detection time descending. Use since to implement incremental polling.

Query Parameters

Parameter	Type	Description
since	date-time	ISO 8601 lower-bound timestamp. Defaults to 24 hours ago.
exchange	string	Filter by exchange: `binance`, `okx`, `bybit`, `mexc`, `bitget`, `coinbase`, `bingx`, `bitfinex`, `deribit`.
limit	integer	Results per page. Default `50`, max `200`.
offset	integer	Skip N results. Default `0`.

{
  "data": [
    {
      "symbol":      "XYZUSDT",
      "baseAsset":   "XYZ",
      "quoteAsset":  "USDT",
      "exchange":    "binance",
      "tradingMode": "spot",
      "listedAt":    "2024-01-15T10:30:00.000Z"
    }
  ],
  "total":  1,
  "since":  "2024-01-14T10:30:00.000Z",
  "limit":  50,
  "offset": 0
}

{ "error": "Invalid API key" }

{ "error": "Rate limit exceeded", "retryAfterMs": 42000 }

Example

curl "https://cex.holits.com/api/pairs/new?exchange=binance&limit=10" \
  -H "Authorization: Bearer cex_your_key"

GET /api/announcements Pro+

Returns exchange announcements with extracted asset tickers and LLM sentiment classification. Scraped from official exchange pages every 15 seconds. Sorted by announcement date descending.

Query Parameters

Parameter	Type	Description
exchange	string	Filter by exchange name.
since	date-time	Only return announcements published after this timestamp.
limit	integer	Default `50`, max `200`.
offset	integer	Default `0`.

{
  "data": [
    {
      "title":     "Binance Will List XYZ Token (XYZ)",
      "link":      "https://www.binance.com/en/support/announcement/abc",
      "exchange":  "binance",
      "date":      "2024-01-15T09:00:00.000Z",
      "tickers":   ["XYZ"],
      "sentiment": "positive"
    }
  ],
  "total":  1,
  "limit":  50,
  "offset": 0
}

{ "error": "Invalid API key" }

{ "error": "Rate limit exceeded", "retryAfterMs": 42000 }

Sentiment Values

Value	Emoji	Meaning
`positive`	🟢	Bullish signal — new listing, promotion, expansion
`neutral`	⚪	Informational — maintenance, schedule changes
`negative`	🔴	Bearish signal — delisting, restriction, suspension
`null`	—	Classification not yet complete

GET /api/prices/:symbol Pro+

Returns the current price of an asset simultaneously from all 9 monitored exchanges. Exchanges that do not list the asset return null. When at least 2 prices are available, a spread summary is included.

Accepts the symbol with or without a quote suffix: BTC, BTCUSDT, BTCUSDC are all equivalent — the quote suffix is stripped automatically.

Path Parameters

Parameter	Type	Required	Description
symbol	string	required	Asset symbol. Examples: `BTC`, `ETH`, `SOLUSDT`.

{
  "symbol": "BTC",
  "quote":  "USDT",
  "prices": {
    "binance":  { "price": 50000.5,  "updatedAt": "2024-01-15T12:00:00.000Z" },
    "okx":      { "price": 50050.0,  "updatedAt": "2024-01-15T12:00:00.000Z" },
    "bybit":    { "price": 49990.0,  "updatedAt": "2024-01-15T12:00:00.000Z" },
    "mexc":     null,
    "bitget":   { "price": 50010.25, "updatedAt": "2024-01-15T12:00:00.000Z" },
    "coinbase": { "price": 50005.0,  "updatedAt": "2024-01-15T12:00:00.000Z" },
    "bingx":    null,
    "bitfinex": { "price": 50030.0,  "updatedAt": "2024-01-15T12:00:00.000Z" },
    "deribit":  null
  },
  "spread": {
    "min":       49990.0,
    "max":       50050.0,
    "spreadPct": 0.12
  }
}

{
  "error": "This endpoint requires pro tier or above. Your key is basic tier."
}

{ "error": "Rate limit exceeded", "retryAfterMs": 42000 }

Example

# Symbol with USDT suffix — automatically stripped
curl "https://cex.holits.com/api/prices/BTCUSDT" \
  -H "Authorization: Bearer cex_your_key"

# Equivalent
curl "https://cex.holits.com/api/prices/BTC" \
  -H "Authorization: Bearer cex_your_key"

GET /api/exchanges/:symbol Pro+

Returns which exchanges list a given asset, along with its available trading modes (spot / futures), quote assets, and first-seen date.

Path Parameters

Parameter	Type	Required	Description
symbol	string	required	Base asset symbol, e.g. `BTC`, `SOL`. Case-insensitive.

{
  "symbol":       "SOL",
  "exchanges":    ["binance", "okx", "bybit", "mexc"],
  "tradingModes": ["spot", "futures"],
  "quoteAssets":  ["USDT", "USDC"],
  "firstListed":  "2024-01-10T08:00:00.000Z"
}

{ "error": "Asset not found" }

Example

curl "https://cex.holits.com/api/exchanges/SOL" \
  -H "Authorization: Bearer cex_your_key"

GET /api/simulations Pro+

Returns listing-pump simulations tracked by the bot — paper trades that buy at listing and hold until a target exchange also lists the asset. Useful for back-testing listing arbitrage performance.

Query Parameters

Parameter	Type	Description
status	string	Filter by `active` or `completed`. Omit for all.
limit	integer	Default `50`, max `200`.
offset	integer	Default `0`.

{
  "data": [
    {
      "id":             "65a1b2c3d4e5f6a7b8c9d0e1",
      "asset":          "XYZ",
      "targetExchange": "binance",
      "sourceExchange": "mexc",
      "newExchange":    "bybit",
      "buyPrice":       0.045,
      "mockBuyValue":   100,
      "status":         "completed",
      "finalProfitLoss": 23.5,
      "startedAt":      "2024-01-15T10:30:00.000Z",
      "updatedAt":      "2024-01-15T14:00:00.000Z"
    }
  ],
  "total":  1,
  "limit":  50,
  "offset": 0
}

Example

curl "https://cex.holits.com/api/simulations?status=completed&limit=20" \
  -H "Authorization: Bearer cex_your_key"

Watchlist

Manage the asset watchlist linked to your Telegram or Discord account. Watchlist endpoints require a platform-linked key (generated via the bot, not a standalone key). Standalone keys receive 422.

GET /api/watchlist Basic+

Returns all assets on your watchlist, including any price alert thresholds set.

{
  "data": [
    {
      "asset":          "BTC",
      "alertPrice":     55000,
      "alertDirection": "above",
      "alertTriggered": false,
      "addedAt":        "2024-01-15T08:00:00.000Z"
    }
  ],
  "total": 1
}

POST /api/watchlist Basic+

Add or update an asset on the watchlist. If the asset already exists, its alert settings are overwritten. Asset symbol is normalised to upper-case.

Request Body application/json

Field	Type	Required	Description
asset	string	required	Asset symbol, e.g. `"BTC"`.
alertPrice	number		Price threshold for alert. Must be a positive number.
alertDirection	string		`"above"` or `"below"`. Required if `alertPrice` is set.

{
  "asset":          "ETH",
  "alertPrice":     3000,
  "alertDirection": "below",
  "alertTriggered": false,
  "addedAt":        "2024-01-15T09:00:00.000Z"
}

{ "error": "alertDirection must be \"above\" or \"below\"" }

Example

curl -X POST "https://cex.holits.com/api/watchlist" \
  -H "Authorization: Bearer cex_your_key" \
  -H "Content-Type: application/json" \
  -d '{"asset":"ETH","alertPrice":3000,"alertDirection":"below"}'

DELETE /api/watchlist/:asset Pro+

Remove an asset from the watchlist.

Path Parameters

Parameter	Type	Required	Description
asset	string	required	Asset symbol to remove, e.g. `ETH`.

{ "deleted": "ETH" }

{ "error": "Asset not found in watchlist" }

Alert Rules

Configure per-account filters for listing notifications — minimum number of exchanges, allowed trading modes, and exchange allow/deny lists. Alert rule endpoints require a platform-linked key.

GET /api/alertrules Basic+

Returns the current alert rule for your account. If no rule has been configured, returns the default values.

{
  "minExchanges":    1,
  "tradingModes":    [],
  "exchanges":       [],
  "excludeExchanges": []
}

PUT /api/alertrules Basic+

Update alert rule fields. Send only the fields you want to change — all other fields are preserved. The rule is created on first call.

Request Body application/json

Field	Type	Description
minExchanges	integer	Only alert when a pair is listed on at least N exchanges simultaneously. Min `1`.
tradingModes	string[]	Restrict to `["spot"]`, `["futures"]`, or `["spot","futures"]`. Empty array = any.
exchanges	string[]	Only alert for listings on these exchanges. Empty array = all.
excludeExchanges	string[]	Never alert for listings on these exchanges.

{
  "minExchanges":    2,
  "tradingModes":    ["spot"],
  "exchanges":       ["binance", "okx"],
  "excludeExchanges": []
}

{ "error": "tradingModes must be an array of \"spot\" and/or \"futures\"" }

Example

curl -X PUT "https://cex.holits.com/api/alertrules" \
  -H "Authorization: Bearer cex_your_key" \
  -H "Content-Type: application/json" \
  -d '{"minExchanges":2,"tradingModes":["spot"]}'

DELETE /api/alertrules Basic+

Reset the alert rule to defaults. Returns the default rule after deletion.

{
  "minExchanges":    1,
  "tradingModes":    [],
  "exchanges":       [],
  "excludeExchanges": []
}

API Keys

Manage API keys for your account programmatically. These endpoints require a platform-linked key and mirror the /apikey bot commands. You can hold up to 3 keys per account.

GET /api/apikeys Basic+

List all API keys associated with your account. Key values are never returned — only prefixes, labels, and metadata.

{
  "data": [
    {
      "keyPrefix":   "cex_ab12",
      "label":       "myapp",
      "tier":        "pro",
      "rateLimit":   1000,
      "requestCount": 142,
      "lastUsedAt":  "2024-01-15T11:00:00.000Z",
      "createdAt":   "2024-01-10T08:00:00.000Z"
    }
  ],
  "total": 1
}

POST /api/apikeys Basic+

Generate a new API key for your account. The plaintext key is returned exactly once — store it immediately. Returns 422 if you already have 3 keys.

Request Body application/json

Field	Type	Required	Description
label	string		Human-readable label for this key (e.g. `"trading-bot"`).

{
  "key":  "cex_ab12xxxxxxxxxxxxxxxxxxxxxxxx",
  "note": "Store this key securely — it will not be shown again."
}

{ "error": "Maximum 3 API keys per account" }

Example

curl -X POST "https://cex.holits.com/api/apikeys" \
  -H "Authorization: Bearer cex_your_key" \
  -H "Content-Type: application/json" \
  -d '{"label":"trading-bot"}'

DELETE /api/apikeys/:prefix Pro+

Revoke an API key by its prefix (e.g. cex_ab12). The deleted key will stop working immediately.

Path Parameters

Parameter	Type	Required	Description
prefix	string	required	Key prefix shown in `GET /apikeys`, e.g. `cex_ab12`.

{ "deleted": "cex_ab12" }

{ "error": "API key not found" }

Portfolio (Paper Trading)

Track simulated crypto positions with live P/L calculations. No real trades are executed. Available on Basic+ tier.

GET /portfolio Basic+

Get all simulated positions with live P/L calculations. Paper trading only — no real trades.

{
  "totalValue": 52500,
  "totalCost": 50000,
  "totalUnrealizedPnL": 2500,
  "totalUnrealizedPnLPercent": 5,
  "totalRealizedPnL": 0,
  "positions": [
    {
      "asset": "BTC",
      "quantity": 0.5,
      "entryPrice": 50000,
      "currentPrice": 105000,
      "entryValue": 25000,
      "currentValue": 52500,
      "unrealizedPnL": 27500,
      "unrealizedPnLPercent": 110,
      "realizedPnL": 0,
      "openedAt": "2024-01-15T10:00:00Z"
    }
  ]
}

POST /portfolio Basic+

Add a new simulated position to your paper trading portfolio. Uses upsert logic — updates if asset exists. No real trades are executed.

Param	Type	Required	Description
asset	string	yes	Asset symbol (e.g., BTC, ETH)
quantity	number	yes	Quantity held
entryPrice	number	yes	Your entry price in USD

{
  "platformType": "discord",
  "platformId": "123456789",
  "asset": "BTC",
  "quantity": 0.5,
  "entryPrice": 50000,
  "openedAt": "2024-01-15T10:00:00Z"
}

DELETE /portfolio/:asset Basic+

Close a position and realize P/L based on current market price.

Param	Type	Required	Description
asset	string	yes	Asset symbol to close (e.g., BTC)

{
  "realizedPnL": 2500,
  "entryValue": 50000,
  "exitValue": 52500
}

{ "error": "Position not found" }

API Reference

Introduction

Base URL

Format

Versioning

OpenAPI Spec

Authentication

Rate Limits

Error Responses

Endpoints

Watchlist

Alert Rules

API Keys

Portfolio (Paper Trading)