Overview

The Nordcave API provides real-time on-chain risk intelligence across Ethereum, Arbitrum, Base, and Optimism. It is designed as a backend dependency for trading bots, MEV searchers, and on-chain quant systems — not a UI product.

All endpoints are under https://api.nordcave.com/v1 and require an API key. WebSocket streams are available for real-time event delivery.

https://api.nordcave.com/v1

Authentication

Pass your API key in the Authorization header as a Bearer token, or in the X-API-Key header.

curl https://api.nordcave.com/v1/risk/0xTOKEN_ADDRESS \
  -H "Authorization: Bearer nc_your_api_key"

curl https://api.nordcave.com/v1/risk/0xTOKEN_ADDRESS \
  -H "X-API-Key: nc_your_api_key"

API keys are prefixed with nc_. Keys are shown once at creation — store them immediately. Sign in with your wallet to get a key instantly — no approval required.

Supported Chains

Pass the chain as a chain_id query parameter. Defaults to Ethereum if omitted.

Risk API

Get token risk score

Returns the latest risk report for any EVM token address. The risk_score is a 0–100 integer — higher means more dangerous. Scores above 70 are considered high risk and will also appear in the /stream/alerts WebSocket channel. The confidence field (0–1) reflects how much on-chain data was available when scoring — a low confidence score means the token is too new or illiquid to assess reliably. Use flags to understand exactly which risk patterns were detected.

curl "https://api.nordcave.com/v1/risk/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48?chain_id=1" \
  -H "Authorization: Bearer nc_your_api_key"

{
  "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "chain_id": 1,
  "risk_score": 12,
  "flags": [],
  "confidence": 0.98,
  "scored_at": "2025-05-26T10:30:00Z"
}

Get risk history

Returns a time-ordered list of past risk reports for a token. Useful for detecting score drift — a token that was safe yesterday but scores 80 today is exhibiting suspicious on-chain behaviour. Pair with the /stream/alerts stream to catch changes in real time.

{
  "token": "0xA0b...",
  "chain": 1,
  "history": [
    {
      "token": "0xA0b...",
      "chain_id": 1,
      "risk_score": 12,
      "flags": [],
      "confidence": 0.98,
      "scored_at": "2025-05-26T10:30:00Z"
    }
  ]
}

Scan API

New token listings

Returns recently detected pool creation events — the earliest signal that a new token has launched with liquidity. Each event contains the token pair and pool address. Feed this into your pipeline to trigger risk scoring as soon as a token appears on-chain, before most traders see it.

{
  "chain": 1,
  "count": 2,
  "tokens": [
    {
      "id": "0xpool...",
      "chain_id": 1,
      "type": "new_pool",
      "data": { "token0": "0x...", "token1": "0xC02...WETH", "pool": "0x..." },
      "timestamp": "2025-05-26T10:29:00Z"
    }
  ]
}

Liquidity removal events

Returns recent liquidity burn events across tracked pools. A sudden large removal — especially shortly after launch — is one of the strongest rug pull signals available on-chain. Poll this endpoint or subscribe to /stream/liquidity to monitor pools your bot has open positions in.

Wallet API

Deployer risk profile

Aggregates the on-chain history of a deployer wallet into a single risk profile. Before trading any token, checking its deployer is one of the highest-signal pre-trade checks available — a wallet that has deployed ten tokens with an average risk score of 80 is almost certainly a serial scammer. The response includes token count, average risk, and high-risk deployment count so you can build your own thresholds.

{
  "address": "0xDeployer...",
  "chain_id": 1,
  "risk_score": 74,
  "flags": ["serial_deployer", "high_risk_deployer"],
  "tokens_deployed": 12,
  "avg_token_risk": 71.4,
  "high_risk_count": 9,
  "scored_at": "2025-05-26T10:30:00Z"
}

Use this to evaluate a token deployer before trading. A serial_deployer with high average token risk is a strong signal to avoid all tokens from that address.

WebSocket Streams

WebSocket streams deliver events to your bot in real time with no polling overhead. Connect once and receive a continuous feed for the duration of your session. Three independent channels are available — subscribe to only what your pipeline needs. Pass your API key in the Authorization header on the upgrade request.

const WebSocket = require('ws')

const ws = new WebSocket('wss://api.nordcave.com/v1/stream/alerts', {
  headers: { Authorization: 'Bearer nc_your_api_key' }
})

ws.on('open', () => console.log('connected'))
ws.on('message', (data) => {
  const event = JSON.parse(data)
  console.log(event)
  // { token: '0x...', chain_id: 1, risk_score: 87, flags: ['honeypot_possible'] }
})

import asyncio, websockets, json

async def stream():
    headers = {'Authorization': 'Bearer nc_your_api_key'}
    async with websockets.connect(
        'wss://api.nordcave.com/v1/stream/alerts',
        extra_headers=headers
    ) as ws:
        async for message in ws:
            print(json.loads(message))

asyncio.run(stream())

Webhooks

Webhook delivery is coming in Phase 2. You can register an endpoint now — it will be activated when the delivery system is live.

curl -X POST https://api.nordcave.com/v1/webhook/register \
  -H "Authorization: Bearer nc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-bot.com/hook", "events": ["risk_alert", "new_token"]}'

{
  "status": "registered",
  "url": "https://your-bot.com/hook",
  "events": ["risk_alert", "new_token"],
  "message": "webhook delivery coming in Phase 2"
}

Risk Flags

Flags are returned as a string array on every risk report. Multiple flags can be set simultaneously — for example a token can be both mintable and haveunlocked_liquidity. Critical and High flags directly drive the risk score above 70. Use individual flags to build custom trading rules beyond the aggregate score: you might accept a high_buy_tax token but hard-reject anything withhoneypot_possible or blacklist_function.

AI Insights

AI Insights do not affect the numeric risk_score, flags, or confidence — those are produced entirely by the deterministic scoring engine. The LLM reads the finished report and translates it into prose.

{
  "token": "0xAbCd...1234",
  "chain_id": 1,
  "risk_score": 87,
  "flags": ["honeypot_possible", "unlocked_liquidity"],
  "confidence": 0.94,
  "scored_at": "2025-05-28T10:30:00Z",
  "llm_explanation": "This token is high risk. A swap simulation showed that sells are effectively blocked, which is characteristic of a honeypot. Liquidity is also unlocked, meaning the deployer can drain the pool at any time.",
  "llm_bytecode_note": "The contract does not contain a mint or blacklist function, but the swap simulation captured 95% of sell value as tax — a strong indicator of hidden sell restrictions.",
  "llm_deployer_note": "This deployer has launched 4 tokens, 3 of which scored above 70. The pattern is consistent with serial honeypot deployment."
}

Errors & Rate Limits

HTTP error codes

{
  "message": "no risk data for token"
}

Rate limiting

Rate limits are enforced per API key on a sliding 60-second window. When you exceed your limit, the API returns 429 until the window resets. Limits vary by plan — see pricing for details.

If you need a higher limit, upgrade your plan or contact us for a custom arrangement.