CU
ChainUnified
API Access Overview

ChainUnified API Reference

Programmatic access to the same gas metrics and token intelligence that power the product experience. Bring ChainUnified data into automated pipelines, dashboards, and risk workflows.

Authentication

  • Issue API keys from your dashboard (/dashboard → API keys).
  • Send requests with the header x-api-key: <token>.
  • Keys are scoped; starter plans grant summary data, professional and above unlock advanced scopes.

Rate limiting

  • Sliding windows enforced per API key: per-second, 60-second burst, and calendar-month quotas.
  • Quota accounting persists in PostgreSQL (`ApiUsage`, `RateLimit` tables) for auditability.
  • HTTP 429 responses include a retry-after header when applicable.

Plan limits

The table below reflects the live configuration powering authentication middleware. Quotas update instantly when you change plans.

PlanMonthly quotaPer-second60s burstScopes
free
API disabled at this tier
Disabled——None
starter
Summary token intel + gas metrics
1,0003 req/s30gas.read, token.intel.summary
professional
Full token intel including liquidity insights
10,00010 req/s120gas.read, token.intel.summary, token.intel.full, liquidity.read, portfolio.read
enterprise
Unlimited usage with custom add-ons
Unlimited25 req/s250gas.read, token.intel.summary, token.intel.full, liquidity.read, portfolio.read, webhook.manage

CORS & client access

Browser clients are supported. We send preflight responses and set CORS headers for external apps.

  • Access-Control-Allow-Origin: defaults to *. Override with NEXT_PUBLIC_API_CORS_ORIGIN (comma-separated allowlist).
  • Access-Control-Expose-Headers: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, retry-after.
  • Auth header: x-api-key

cURL

curl -i \
+  -H 'x-api-key: YOUR_API_KEY' \
+  'https://chainunified.com/api/external/v1/gas?chain=ethereum'

fetch() with 429 handling

const res = await fetch('/api/external/v1/token-intel?symbol=usdt', {
  headers: { 'x-api-key': YOUR_API_KEY },
});
if (res.status === 429) {
  const retry = res.headers.get('retry-after');
  // wait Number(retry) seconds then retry
}
const data = await res.json();

Versioning

Use the /api/external/v1 base path for stable contracts. Legacy non-versioned routes remain temporarily for compatibility.

OpenAPI schema: /api/openapi.json (import into Postman or other clients).

Available endpoints

GET

Gas Metrics

Returns live base fee, priority fee, and speed buckets for supported EVM networks.

/api/external/v1/gas
Required scope: gas.read

Parameters

  • chain (optional) — ethereum | bsc | polygon | arbitrum | optimism | base | avalanche | zksync

Response example

{
  "data": {
    "chain": "Ethereum",
    "chainId": 1,
    "icon": "🔷",
    "currency": "Gwei",
    "baseFee": 18.245,
    "priorityFee": 0.96,
    "current": {
      "slow": 16.41,
      "standard": 19.21,
      "fast": 24.08
    },
    "lastBlock": 19123456
  },
  "meta": {
    "chain": "ethereum",
    "timestamp": "2024-09-30T09:01:12.000Z"
  }
}
GET

Token Intelligence

Delivers the structured content used on /token/[symbol] pages. Paid plans unlock the "dex" liquidity object.

/api/external/v1/token-intel
Required scope: token.intel.summary

Parameters

  • symbol (required) — Token symbol slug (e.g. usdt, shib)

Response example

{
  "data": {
    "id": "tether",
    "symbol": "usdt",
    "name": "Tether",
    "chainId": "ethereum",
    "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
    "profile": {
      "path": "/token/usdt",
      "hero": {
        "eyebrow": "Ethereum • Contract 0xdac17f958d2ee523a2206206994597c13d831ec7",
        "headline": "Tether (USDT) intelligence dashboard",
        "subheading": "ChainUnified keeps USDT risk, liquidity, and holder analytics in one place."
      },
      "stats": [
        { "label": "Market cap rank", "value": "#3" },
        { "label": "Ethereum contract", "value": "0xdac17f958d2ee523a2206206994597c13d831ec7" }
      ],
      "resources": [
        {
          "title": "Run ChainUnified token scanner",
          "href": "/token-scanner?address=0xdac17f958d2ee523a2206206994597c13d831ec7&chain=ethereum"
        }
      ],
      "updatedAt": "2024-09-30T09:00:00.000Z"
    },
    "dex": {
      "chainId": "ethereum",
      "dexId": "uniswap-v3",
      "pairAddress": "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
      "liquidityUsd": 83540215.42,
      "liquidityBase": 41751904.11,
      "liquidityQuote": 41788311.31,
      "priceUsd": 1.0006,
      "url": "https://dexscreener.com/ethereum/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
    }
  },
  "meta": {
    "symbol": "usdt",
    "timestamp": "2024-09-30T09:01:12.000Z"
  }
}

Usage & monitoring

  • Every request increments monthly counters in `ApiUsage`. Dashboard widgets surface usage in real time.
  • 429 responses indicate either rate limit (per-second/burst) or monthly quota exhaustion.
  • Enterprise plans can request custom alerting (webhooks or email) for quota thresholds.

Roadmap

  • Liquidity endpoint with pool liquidity, volume, and smart money indicators (in validation).
  • Portfolio read APIs for treasury monitoring with explicit wallet opt-in.
  • OpenAPI schema + Postman collection published alongside sandbox credentials.
ChainUnified API Reference