Skip to content

CoinLobster/agent-skills / skills/coinlobster-api

coinlobster-api

Verified

Build apps and agents on CoinLobster's crypto whale data, including the free keyless REST endpoints, the hosted MCP server, API keys and credit plans. Use when a developer asks how to integrate live whale trades, whale alerts, liquidations or the Smart Money Radar into their bot, app, dashboard or agent, or asks about the CoinLobster API or MCP server.

FileKindSize
SKILL.mdskill md4.4 KB
references/endpoints.mdmarkdown11.8 KB

references/endpoints.md

View on GitHub
# CoinLobster keyless endpoints used by this pack

All GET, JSON, no auth. Rate limit: 60 requests/min per IP on `/api/public/*`; the
61st returns 429. The MCP has its own layered budget, so back off on `Retry-After`
rather than assuming a rate. Be polite anyway: one call per question, not per
token. Base: `https://coinlobster.com`

## REST

| Endpoint | Params | Returns |
| --- | --- | --- |
| `/api/public/crypto-whales` | `coin` (base symbol, e.g. BTC), `limit` (max 100 keyless) | `whales[]`: pair, exchange, price, quantity_base, quantity_quote (USD), isBuy, timestamp (ms), `marketConditions` (funding + OI across venues at trade time). CEX lane only. |
| `/api/public/onchain-whales` | `chain` (ethereum\|base\|arbitrum), `limit` (max 200; keyless returns up to 10 teaser rows, $250K+ only) | `whales[]`: tokenSymbol, amountUsd, isBuy, dex, chain, txHash, timestamp |
| `/api/public/whale-flow-history` | `coin` (default BTC), `hours` (24 to 168 keyless; 720 on a coinlobster.com website subscription, which an API key does not grant. For 30 days on an agent surface use the `whale_flow` MCP tool on a developer plan.) | `rows[]`: { t, buyUsd, sellUsd, netUsd, count, price }, hourly flow on the same grid as the hourly close, plus `coverage` { hoursReturned, hoursWithPrice }, `maxFreeHours` (168) and `proHours` (720). `available: false` = no recorded whale hours for that coin yet. |
| `/api/public/whale-context` | `coin` (**required**; 400 without it) | Is this coin's whale volume unusual for THIS coin. `ctx` { mult (x its own daily average), usd24, net24, avgDayUsd, days, record, highestInDays, buyShare24, buyShare7d, buyShare30d }, plus `chips` (pre-composed label strings) and `breadth` { elevated, total } for how many coins are running hot market-wide. Fully keyless including the USD: the `whale_context` MCP tool withholds `usd_24h`/`net_usd_24h` without a key, this endpoint does not, so it is the keyless way to get the magnitude behind a multiple. |
| `/api/public/whale-radar` | `window` (1h\|4h\|24h) | `rows[]`: coin, direction, unusual, count. Keyless keeps magnitudes on the free pair (BTC) only; other unusual coins come back `blurred: true`, and locked coins that are not unusual are omitted (`lockedCount`, `lockedUnusualCount`). |
| `/api/public/receipts/:type/:coin` | path params, e.g. `/whale-spike/BTC` | past firings of one signal type on one coin with price outcomes |
| `/api/public/overview` | `q` (search base symbol or name), `limit` (max 200), `offset`, `tab`, `sort`, `dir` | market totals, regime, BTC price, whale net 24h, and `page` { total, offset, limit, rows[] }. Use `q` to find one coin; do not page for it. |
| `/api/public/liquidation-history` | `pair`, `limit` | Recorded perp liquidation events for one pair, under `history[]` (not `liquidations[]`), each row { timestamp, price, quantity_base, quantity_quote, isBuy, exchange, pair }, plus `count`. **The field names differ from the `liquidations` MCP tool**: size is `quantity_quote` here and `size_quote` there, and the side arrives as `isBuy` rather than a `side` string, so `isBuy: false` (a forced SELL) is a long liquidation. **Pair-gated**: keyless works on the free pairs (BTC/USD); other pairs return 403 with `free_pairs` and `recorded_days` stated. |
| `/api/public/defi-summary` | none | per-chain DEX volume + TVL, top tokens, whale swap activity (free withholds swap USD) |
| `/api/public/defi-liquidations` | `chain`, `protocol`, `limit` | lending liquidations from Aave V3 and Morpho Blue; each row names `liquidator` AND `liquidatee`. `protocols_covered` is derived from the live producer list, so read it rather than assuming. `count`/`total_usd` sum exactly the page returned, whose span is `window`; the 24h lending total lives on `/api/public/liquidations`. |
| `/api/public/liquidations` | none | Market-wide force-closed positions. `perp_liquidations` combines the CEX futures venues that publish a liquidation feed plus Hyperliquid, and the payload states the count in `venue_coverage` (24h `total_usd`, `long_usd`/`short_usd`, counts, `long_share_pct`, `peak_hour`, `hourly[]`, `top_coins[]`); `named_liquidations[]` names the Hyperliquid accounts closed out; `lending_liquidations` is a SEPARATE lane, never summed with the perp numbers. `long_share_pct` is null on an empty window (not 50). `stale: true` means the snapshot is behind. |
| `/api/public/onchain-top-tokens` | none | highest-volume tokens per chain with price, 24h change, volume, TVL |
| `/api/public/hyperliquid/whales` | `coin`, `limit` | Hyperliquid whale fills with the wallet address attached (free = $1M+ prints, 10-row teaser) |
| `/api/public/hyperliquid/board` | none | tracked HL whale accounts: equity, leverage, net bias (free = top rows + `withheld`) |
| `/api/public/hyperliquid/wallet/{address}` | path | one HL account live book, positions and recent fills |

## Markdown mirrors (fetch and read, no parsing)

- `/crypto-whales.md`: latest whale trades table
- `/radar.md`: unusual flow now + recent flag outcomes
- `/whale-statistics.md`: market-wide whale stats

## MCP over plain curl (works from any shell, no MCP client needed)

The hosted MCP accepts raw JSON-RPC; useful where a tool exists but no REST twin does
(liquidations, market_snapshot):

```bash
curl -s -X POST https://coinlobster.com/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"liquidations","arguments":{"pair":"BTC/USD"}}}'
```

## Two liquidation lanes, never summed

`liquidations` (per pair), `market_liquidations` (market-wide, one call) and
`/api/public/liquidation-history` are PERP liquidations: a venue
force-closing a leveraged position. `defi_liquidations` (and
`/api/public/defi-liquidations`) are LENDING liquidations: a third party repaying a
debt and seizing collateral on Aave V3 or Morpho Blue. Different events, different
meaning, different denominators. Report them separately and never add them into one
total.

## Lifting the caps

A free API key (a one-off 1,000 credits: https://coinlobster.com/developers) unlocks the
keyed REST endpoints `/api/ai/v1/*` (history to 400 days, credit-metered). It
does NOT lift the live MCP caps. The full live feed on every pair, radar
magnitudes, non-BTC `market_snapshot` and 30-day flow windows need an active
developer plan (Builder $29/mo, Growth $99, Scale $249). One plan covers both
full-depth MCP and the REST credits, on one shared account balance. Send the key
as `X-API-Key` on the MCP or `Authorization: Bearer` on `/api/ai/v1/*`.

On an active developer plan each successful tool call spends 40 to 100 credits
(2x the mirrored REST cost) from the plan's balance. Keyless calls, discovery
and failed calls cost nothing.

CoinLobster Pro ($9/mo) is the coinlobster.com website subscription (live feed,
alerts, whale radar). It grants no MCP depth and no API access.

## Recorded-history endpoints

> Everything below reads the daily recorded archive (derivatives recorded since 2026-03-18, whale flow since 2026-06-18). Absent days mean no data was recorded, never interpolation; points carry their own coverage evidence (`n` snapshots or `hours` of candles).

### Keyless REST

| Endpoint | Params | Returns |
| --- | --- | --- |
| `/api/public/baseline` | `pair` (e.g. BTC/USD) | `available`, `headline` (string\|null), `funding` { phrase, band, value, percentile, at_record_high, at_record_low, asOf, days, outcome }, `oi` { same plus highDays }, and `ladder` { funding, oi } each { min, max, days, p5, p25, p50, p75, p95, fullDays, cov }. Bands: record high/low, top/bottom 5%, top/bottom 25%, typical. `value` + `ladder` are the raw number and the rungs it was ranked against, so a "top 5% of 128 days" claim is checkable rather than taken on trust. `asOf` = "now" or "recorded YYYY-MM-DD". Cached 60s. |
| `/api/public/extremes` | none | `available`, `computedAt`, `records[]` + `top5[]`, each { pair, metric (funding\|open_interest\|liquidations), band, day, days, phrase, outcome }. Daily scan of every recorded pair. Cached 300s. |
| `/api/public/liqmap` | `pair` | `liqmap` { pair, updatedAt, bucketPct, days, firstDay, lastDay, truncated, buckets[] } or null; each bucket { b, p, usd, longUsd, shortUsd, n }. Where liquidations actually happened, by price. Cached 300s. **Pair-gated**: keyless works on the free pairs (BTC/USD); other pairs return 403 without paid access (developer plan, from $29/mo). |

`headline` is null when nothing is at an extreme: the judgment layer only speaks at records / top-bottom 5%; typical is silence. `outcome` strings are next-day history for past occurrences ("on the N recorded days X: price next day up/down-or-flat Y of N, median Z%"), never forecasts. Liqmap is partial-venue by nature: an empty bucket never means "no liquidations there".

### Markdown mirrors

- `/extremes.md`: the daily extremes scan, plain markdown (records + top/bottom 5%, outcome history attached where it exists)
- `/currencies/{symbol}.md` (e.g. `/currencies/btc.md`): per-coin judgment lines vs its own recorded history, biggest recorded whale day, and a trailing 30-day funding/OI table. Free-shaped: 30 days only; the full archive lives on the API and MCP.

### MCP additions

`tools/list` currently returns 25 entries: 24 canonical tools (`whale_trades`, `whale_radar`, `flag_outcomes`, `whale_flow`, `liquidations`, `market_liquidations`, `market_snapshot`, `crypto_news`, `market_history`, `market_extremes`, `whale_context`, `market_overview`, `market_screener`, `funding_matrix`, `squeeze_score`, `liq_zones`, `trade_context`, `defi_summary`, `defi_liquidations`, `onchain_whales`, `hl_whales`, `hl_board`, `hl_wallet`, `dex_wallet`) plus `whale_tape`, a deprecated alias of `whale_trades` kept working for existing callers. The set grows: always call `tools/list` before relying on a tool.

**`dex_wallet`**: args `address`, optional `limit`. One Ethereum/Base/Arbitrum address: its recorded DEX swaps and net flow per token. Not the same subject as `hl_wallet` even when the 0x string matches, and the swap feed sees only part of a wallet's activity, so quiet here does not mean inactive.

**`market_history`**: args `pair` OR `coin`, plus `days`. Keyless = 30 days; a developer plan (from $29/mo) = full archive (up to 400 days). A free key changes nothing on MCP.

- Pair mode returns: `pair`, `days_requested`, `funding[]` ({ d, avg, min, max, n }), `open_interest[]` ({ d, usd, n }), `price[]` ({ d, o, h, l, c, v, hours }), `liquidations[]` ({ d, usd, n, longUsd, shortUsd }), `available`, `depth_note`.
- Coin mode returns: `coin`, `days_requested`, `whale_flow_daily[]` ({ d, buyUsd, sellUsd, cexUsd, dexUsd, count }), `hour_of_day_utc` ({ days, slots[] of { h, medUsd } }; null under 14 recorded days), `available`, `depth_note`. Hour-of-day medians (UTC) make "busy for this hour" checkable.

**`market_extremes`**: no args. Returns `computed_at`, `records[]`, `top5[]` (same entry shape as `/api/public/extremes`).

**`flag_outcomes`** additionally returns `all_time`: { fired, scored_h24, since, through, by_type }. Counts only; no win rates are published from the archive counters.

### Keyed REST (`/api/ai/v1`, `Authorization: Bearer`)

| Endpoint | Credits | Params | Returns |
| --- | --- | --- | --- |
| `GET /history/derivatives` | 30 | `pair` (default BTC/USD), `days` (default 120, max 400) | `funding[]`, `open_interest[]`, `price[]`, `liquidations[]` (point shapes as market_history pair mode), `updated_at`, `coverage_note`. 404 `no_history` for un-archived pairs. |
| `GET /history/whale-flow-daily` | 30 | `coin` (default BTC), `days` (default 120, max 400) | `days[]` ({ d, buyUsd, sellUsd, cexUsd, dexUsd, count }), `updated_at`, `coverage_note`. |

Integration rule: repeat the `coverage_note` / `depth_note` discipline. Present exactly the depth the response claims, quote the recorded day when ranking archived values (the archive settles about a week behind live), and never turn outcome history into a prediction.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall