API v1 reference

Programmatic access to the same forensic engine behind the app: token scans, verdicts, and X account identity checks.

Overview

Base URL: https://www.scoped.fun. Every endpoint speaks JSON. Failed /api/v1/* requests use one envelope: { "success": false, "error": "..." }. The component-health endpoint, GET /api/status, is the exception: its 429 body is { "error": "Too many requests" } and its 500 fallback returns a snapshot-shaped body with overall set to unknown.

Scoped values are SAFE, CAUTION, or DANGER, displayed in the app and bots as LOW RISK, CAUTION, and AVOID. Risk scores run 0-100 where higher means riskier. Confidence is coverage-driven: it tells you how much of the holder population a scan saw, not how strong the signal is.

CORS: quick-scan and the X identity read are browser-callable. Authenticated endpoints have no CORS headers by design; call them server side so your key never ships to a browser.

Auth & API keys

Deep analysis and partner intelligence endpoints need a key. Send it server side as Authorization: Bearer. Analyze also accepts X-API-Key and the legacy JSON apiKey field. Keys look like rico_live_..., are shown once at issuance, and reissuing rotates the old key out. Connect a wallet holding $SCOPED to mint a Free-tier key right here; Pro and Enterprise keys come with a subscription.

What $SCOPED unlocks

Hold any amount of $SCOPED

Live X-FeedNew posts from a token's linked X account pop onto the chart in real time.

Wash RadarLive tape coloring every swap organic / suspected / wash: the real volume behind the chart.

Cabal RadarKnown-crew, bundle, and sniper supply surfaced on the map before you ape.

API keySelf-serve key for the public scan API. Wire Scoped forensics into your own tools and agents.

Advanced viewFull forensic breakdown: deployer history, holder PnL, and deeper wallet intel.

Verification is a free wallet signature. It proves you hold $SCOPED and authorizes no transaction.

Connect a wallet holding $SCOPED to mint your key.

Tiers & limits

Tier	Rate limit	Monthly quota
Free	10 requests/min	1,000 requests/month
Pro	60 requests/min	50,000 requests/month
Enterprise	300 requests/min	Unlimited

A tier changes access only. It never changes scan output or scores. Quota months are UTC calendar months.

Quick scan

POST/api/v1/quick-scan

Fast token forensics without a key. Returns a bounded 20-holder preview, then completes and caches the 50+ holder public scan after the response. Provenance labels partial versus final coverage.

AuthNone

Rate limit15 requests per minute per IP. 429 responses include a Retry-After header in seconds.

CORSOpen (browser calls allowed).

Parameter	Type	Required	Description
`address`	string	yes	Token mint address. Wallet addresses are rejected with 400.

Example request

curl -X POST https://www.scoped.fun/api/v1/quick-scan \
  -H "Content-Type: application/json" \
  -d '{"address": "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump"}'

Example response (stats and data trimmed for brevity)

{
  "success": true,
  "verdict": {
    "level": "CAUTION",
    "score": 46,
    "confidence": "medium",
    "topFlags": [
      {
        "evidenceId": "wash:volume-share",
        "label": "38% of volume looks washed",
        "severity": "high"
      },
      {
        "evidenceId": "deployer:serial",
        "label": "Serial deployer (4 launches)",
        "severity": "medium"
      }
    ],
    "coverageNote": "Analyzed the top 20 of 3120 holders"
  },
  "traderRead": {
    "action": "wait",
    "label": "Wait",
    "confidence": "medium",
    "score": 55,
    "summary": "Mixed signals. Wash volume is elevated and the deployer has prior launches.",
    "signals": [
      {
        "tone": "warn",
        "label": "Elevated wash volume",
        "weight": 2
      }
    ],
    "version": "v2-weighted",
    "shadow": false
  },
  "stats": {
    "totalHolders": 3120,
    "analyzedHolders": 20,
    "analysisIncomplete": false,
    "rugScore": {
      "score": 42,
      "level": "yellow",
      "confidence": "medium",
      "factors": []
    },
    "botActivityScore": {
      "score": 18,
      "level": "green",
      "confidence": "medium",
      "factors": [],
      "metrics": {}
    },
    "supplyConcentration": {
      "top10Pct": 31.2,
      "cabalSupplyPct": 6.4,
      "holderCoveragePct": 0.6
    },
    "holderQuality": {
      "winners": 9,
      "exitLiquidity": 3,
      "analyzed": 40
    }
  },
  "data": {
    "nodes": [],
    "links": []
  },
  "tokenSecurity": {
    "hasFreezeAuthority": false,
    "hasMintAuthority": false,
    "isMutable": false,
    "riskLevel": "low",
    "riskFactors": []
  },
  "tokenMetadata": {
    "name": "Example Token",
    "symbol": "EXMPL",
    "priceUsd": 0.0012,
    "marketCap": 118000
  },
  "deployerInfo": {
    "address": "DepLoyerExampLeVerdictDocs111111111111111111",
    "isSerialDeployer": true,
    "pastLaunchCount": 4,
    "isRugDev": false
  },
  "scanProvenance": {
    "cacheHit": false,
    "scannedAt": 1782926400,
    "schemaVersion": 4,
    "profile": "public-api",
    "analyzedHolders": 20,
    "stage": "partial",
    "nextProfile": "public-api",
    "coverageStatus": "complete",
    "indexedSlot": 352000000,
    "networkSlot": 352000012,
    "slotLag": 12
  }
}

Response notes

verdict.levelOne of SAFE, CAUTION, or DANGER. verdict.score is 0-100 where higher means riskier.

verdict.confidenceCoverage-driven, not signal strength: it reports how much of the holder population the scan saw. coverageNote appears whenever confidence is not high.

statsThe full scan stats object (rug score, bot activity, supply concentration, wash, bundles, and more). The example above is trimmed; see the response shapes section for the key fields.

dataThe full bubble-map graph: data.nodes and data.links, exactly what the web app renders.

traderReadA plain-language read (entry, wait, or avoid) with weighted signals. Treat it as a heuristic summary, not advice.

scanProvenance.stageCold calls return partial with nextProfile public-api while the 50+ holder scan completes. Cached complete scans return final; capped scans remain partial.

Status	Body	When
400	`{"success": false, "error": "Invalid address"}`	The address is not valid base58.
400	`{"success": false, "error": "Address is not a token mint"}`	A wallet address was passed instead of a token mint.
429	`{"success": false, "error": "Too many requests"}`	Per-IP rate limit hit. Retry after the Retry-After header (seconds).
503	`{"success": false, "error": "Couldn't classify this address right now. Please try again in a moment."}`	Upstream asset lookup is temporarily unavailable.
503	`{"success": false, "error": "Token data unavailable. Try again in a moment."}`	Upstream token data is temporarily unavailable.
500	`{"success": false, "error": "Scan failed"}`	Unexpected server error.

Recent scans may be served from cache. Use POST /api/v1/analyze for a fresh, deeper read.

Analyze

POST/api/v1/analyze

Deep cabal analysis with an API key: top 100 holders, 5 funders per holder, identity enrichment.

AuthBearer token or X-API-Key header. The legacy JSON apiKey field is also accepted. Keep the key server side.

Rate limitPer key by tier: Free 10/min and 1,000/month; Pro 60/min and 50,000/month; Enterprise 300/min with no monthly cap. 429 on the per-minute limit includes Retry-After. A tier changes access only, never scan output.

CORSNone. Call it server side and keep your key out of browser code.

Parameter	Type	Required	Description
`apiKey`	string	yes	Your API key via Authorization: Bearer, X-API-Key, or the legacy JSON field.
`mint`	string	yes	Token mint address. "address" is accepted as an alias.

Example request

curl -X POST https://www.scoped.fun/api/v1/analyze \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer rico_live_YOUR_KEY" \
  -d '{"mint": "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump"}'

Example response (nodes and links trimmed for brevity)

{
  "success": true,
  "mint": "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump",
  "data": {
    "nodes": [],
    "links": []
  },
  "stats": {
    "totalHolders": 3120,
    "analyzedHolders": 100,
    "analysisIncomplete": false,
    "rugScore": {
      "score": 34,
      "level": "yellow",
      "confidence": "medium",
      "factors": []
    },
    "supplyConcentration": {
      "holderCoveragePct": 3.2,
      "top10Pct": 28.4,
      "cabalSupplyPct": 4.8
    }
  },
  "verdict": {
    "level": "CAUTION",
    "score": 34,
    "confidence": "medium",
    "topFlags": []
  },
  "traderRead": {
    "action": "wait",
    "label": "Wait",
    "confidence": "medium",
    "score": 52,
    "summary": "Mixed holder signals.",
    "signals": [],
    "version": "v2-weighted"
  },
  "nodes": [
    {
      "id": "FunderExampLeVerdictDocs1111111111111111111",
      "type": "cabal-funder",
      "label": "Fund...1111",
      "tokenAmount": 0,
      "solBalance": 1.42,
      "identity": {
        "name": null,
        "category": null,
        "type": null,
        "tags": []
      },
      "metadata": {
        "fundedCount": 3,
        "threatScore": 85,
        "threatLevel": "high"
      }
    }
  ],
  "links": [
    {
      "source": "FunderExampLeVerdictDocs1111111111111111111",
      "target": "HoLderExampLeVerdictDocs1111111111111111111",
      "value": 0.5,
      "suspicious": true
    }
  ],
  "summary": {
    "totalHolders": 3120,
    "confidence": "medium",
    "analyzedHolders": 100,
    "holderCoveragePct": 3.2,
    "cabalCount": 3,
    "riskScore": 34,
    "verdict": {
      "level": "CAUTION",
      "score": 34,
      "confidence": "medium",
      "topFlags": []
    },
    "snipersDetected": 5,
    "bundleClustersDetected": 2,
    "holderQuality": {
      "winners": 22,
      "exitLiquidity": 6,
      "analyzed": 88
    },
    "coverageNote": "Analyzed the top 100 of 3120 holders"
  },
  "tokenSecurity": {
    "hasFreezeAuthority": false,
    "hasMintAuthority": false,
    "isMutable": false,
    "riskLevel": "low",
    "riskFactors": []
  },
  "tokenMetadata": {
    "name": "Example Token",
    "symbol": "EXMPL",
    "marketCap": 118000
  },
  "deployerInfo": {
    "address": "DepLoyerExampLeVerdictDocs111111111111111111",
    "isSerialDeployer": false,
    "pastLaunchCount": 1
  },
  "embed": {
    "type": "iframe",
    "url": "https://www.scoped.fun/embed?address=9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump&attribution=required",
    "customizationParams": [
      "background",
      "surface",
      "card",
      "border",
      "borderHi",
      "accent",
      "accentDeep",
      "text",
      "muted",
      "theme",
      "compact",
      "hideRail",
      "attribution"
    ],
    "attribution": {
      "label": "RicoMaps",
      "required": true
    }
  },
  "timestamp": "2026-07-01T12:00:00.000Z",
  "tier": "free",
  "processingMs": 8421,
  "scanProvenance": {
    "cacheHit": false,
    "scannedAt": 1782926400,
    "schemaVersion": 4,
    "profile": "deep-api",
    "analyzedHolders": 100,
    "stage": "final",
    "coverageStatus": "complete",
    "indexedSlot": 352000000,
    "networkSlot": 352000012,
    "slotLag": 12
  }
}

Response notes

summary.riskScore / summary.verdictThe canonical SAFE, CAUTION, or DANGER verdict and its 0-100 risk score. riskScore is the same value as verdict.score.

summary.confidenceCoverage measures: confidence and holderCoveragePct report analyzed holders over the true holder population. coverageNote appears whenever confidence is not high.

data / statsThe complete graph and forensic result, including node and link evidence, coverage, supply concentration, bot activity, bundles, wash analysis, and provider completeness.

nodes / links / summaryLegacy projections retained for existing integrations. New consumers should prefer data, stats, verdict, and traderRead.

embedA browser-ready bubble-map iframe URL plus supported color, density, and rail customization parameters. The API key never belongs in the iframe.

scanProvenanceCache status, scan time, engine schema, scan profile, and analyzed-holder depth for cross-surface comparisons.

Status	Body	When
401	`{"success": false, "error": "Missing apiKey"}`	No API key was supplied in a supported header or the JSON body.
403	`{"success": false, "error": "Invalid or revoked API key"}`	The key is unknown or has been rotated away.
429	`{"success": false, "error": "Rate limit exceeded"}`	Per-minute tier limit hit. Retry after the Retry-After header (seconds).
429	`{"success": false, "error": "Monthly quota exceeded for Free tier"}`	The tier's monthly quota (UTC calendar month) is used up.
400	`{"success": false, "error": "Invalid or missing token mint. Pass it as \"mint\" (or \"address\") in the JSON body."}`	The mint is missing or not valid base58.
503	`{"success": false, "error": "Token data unavailable. Try again in a moment."}`	Upstream token data is temporarily unavailable.
500	`{"success": false, "error": "Analysis failed"}`	Unexpected server error.

Partner token summary

GET/api/v1/intel/token/{mint}/summary

Stable partner contract for risk, holder concentration, launch coordination, clusters, and scan coverage.

AuthPartner API key as Authorization: Bearer. X-API-Key and JSON credentials are not accepted.

Rate limitPer key by tier. Enterprise allows 300 requests per minute with no monthly cap.

CORSNone. Call server to server.

Parameter	Type	Required	Description
`mint`	string (path)	yes	Solana token mint address.

Example request

curl -X GET https://www.scoped.fun/api/v1/intel/token/9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump/summary \
  -H "Authorization: Bearer $RICO_API_KEY"

Example response

{
  "success": true,
  "mint": "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump",
  "riskScore": {
    "score": 46,
    "level": "yellow",
    "confidence": "medium",
    "topFactors": []
  },
  "holders": {
    "totalHolders": 3120,
    "realHolderCount": 3108,
    "top10Pct": 31.2,
    "top20Pct": 39.4,
    "top25Pct": 43.1,
    "devWalletPct": 1.2,
    "devStillHolds": true,
    "giniCoefficient": 0.61,
    "freshWalletPct": 18.5
  },
  "snipers": {
    "launchWindowSeconds": 120,
    "coordinatedEntryLevel": "yellow",
    "coordinatedWalletCount": 5,
    "coordinatedSupplyPct": 3.4,
    "launchSnipedSupplyPct": 4.1,
    "launchStillHeldSupplyPct": 2.2,
    "bundleWalletCount": 2,
    "bundleSupplyPct": 1.4
  },
  "clusters": {
    "clusteredHolderCount": 7,
    "clusterCount": 2,
    "largestClusterPct": 6.4,
    "cabalSupplyPct": 6.4,
    "knownCabalMatch": false
  },
  "coverage": {
    "analyzedHolders": 50,
    "holderCoveragePct": 1.6,
    "analysisIncomplete": false
  },
  "scannedAt": 1782926400,
  "expiresAt": 1782926700,
  "stale": false,
  "providerVersion": "1.0.0",
  "analysisIncomplete": false,
  "analyzedHolders": 50
}

Response notes

riskScore.levelgreen, yellow, red, or unrated. Unrated means the engine could not support a score.

staleTrue means an expired prior result was served while a refresh was queued.

Status	Body	When
400	`{"success":false,"error":"Invalid Solana token mint address"}`	The mint path parameter is invalid.
401	`{"success":false,"error":"Missing apiKey"}`	The Bearer header is missing or malformed.
403	`{"success":false,"error":"API key is not authorized for the partner intel namespace"}`	The key is invalid, revoked, or lacks partner-intel capability.
429	`{"success":false,"error":"Rate limit exceeded"}`	The key exceeded its tier limit. Honor Retry-After.
503	`{"success":false,"error":"Intel temporarily unavailable"}`	Storage or an upstream provider failed without a usable cached result.

Partner holder table

GET/api/v1/intel/token/{mint}/holders

Largest analyzed holders with their circulating-supply share and sniper, bundle, and cabal classifications.

AuthPartner API key as Authorization: Bearer.

Rate limitPer key by tier.

CORSNone. Call server to server.

Parameter	Type	Required	Description
`mint`	string (path)	yes	Solana token mint address.
`limit`	integer (query)	no	Default 20; clamped from 1 through 50.

Example request

curl -X GET https://www.scoped.fun/api/v1/intel/token/9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump/holders?limit=20 \
  -H "Authorization: Bearer $RICO_API_KEY"

Example response

{
  "success": true,
  "mint": "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump",
  "holders": [
    {
      "address": "HoLderExampLeVerdictDocs1111111111111111111",
      "pct": 2.4,
      "isSniper": true,
      "isBundled": false,
      "isCabal": true
    }
  ],
  "scannedAt": 1782926400,
  "expiresAt": 1782926700,
  "stale": false,
  "providerVersion": "1.0.0",
  "analysisIncomplete": false,
  "analyzedHolders": 50
}

Response notes

holders[].pctShare of the same circulating-supply denominator used by the summary concentration fields.

Status	Body	When
400	`{"success":false,"error":"Invalid Solana token mint address"}`	The mint path parameter is invalid.
401	`{"success":false,"error":"Missing apiKey"}`	The Bearer header is missing or malformed.
403	`{"success":false,"error":"API key is not authorized for the partner intel namespace"}`	The key is invalid, revoked, or lacks partner-intel capability.
429	`{"success":false,"error":"Rate limit exceeded"}`	The key exceeded its tier limit. Honor Retry-After.
503	`{"success":false,"error":"Intel temporarily unavailable"}`	Storage or an upstream provider failed without a usable cached result.

Partner launch coordination

GET/api/v1/intel/token/{mint}/snipers

Launch-window coordination and bundle evidence, including current and exited supply.

AuthPartner API key as Authorization: Bearer.

Rate limitPer key by tier.

CORSNone. Call server to server.

Parameter	Type	Required	Description
`mint`	string (path)	yes	Solana token mint address.

Example request

curl -X GET https://www.scoped.fun/api/v1/intel/token/9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump/snipers \
  -H "Authorization: Bearer $RICO_API_KEY"

Example response

{
  "success": true,
  "mint": "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump",
  "coordinatedEntry": {
    "level": "yellow",
    "maxWalletsInWindow": 5,
    "windowSeconds": 120,
    "coordinatedSupplyPct": 3.4,
    "wallets": [
      "HoLderExampLeVerdictDocs1111111111111111111"
    ],
    "crewUsd": [
      1840
    ]
  },
  "bundle": {
    "walletCount": 2,
    "exitedCount": 1,
    "supplyPct": 1.4,
    "soldSupplyPct": 0.8
  },
  "scannedAt": 1782926400,
  "expiresAt": 1782926700,
  "stale": false,
  "providerVersion": "1.0.0",
  "analysisIncomplete": false,
  "analyzedHolders": 50
}

Response notes

coordinatedEntry.wallets / crewUsdIndependent sorted arrays. Do not pair entries by array index.

Status	Body	When
400	`{"success":false,"error":"Invalid Solana token mint address"}`	The mint path parameter is invalid.
401	`{"success":false,"error":"Missing apiKey"}`	The Bearer header is missing or malformed.
403	`{"success":false,"error":"API key is not authorized for the partner intel namespace"}`	The key is invalid, revoked, or lacks partner-intel capability.
429	`{"success":false,"error":"Rate limit exceeded"}`	The key exceeded its tier limit. Honor Retry-After.
503	`{"success":false,"error":"Intel temporarily unavailable"}`	Storage or an upstream provider failed without a usable cached result.

Partner graph

GET/api/v1/intel/token/{mint}/graph

Size-capped public bubble graph with generic role labels and no private provider attribution.

AuthPartner API key as Authorization: Bearer.

Rate limitPer key by tier.

CORSNone. Call server to server.

Parameter	Type	Required	Description
`mint`	string (path)	yes	Solana token mint address.
`maxNodes`	integer (query)	no	Default 60; clamped from 1 through 150.

Example request

curl -X GET https://www.scoped.fun/api/v1/intel/token/9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump/graph?maxNodes=60 \
  -H "Authorization: Bearer $RICO_API_KEY"

Example response

{
  "success": true,
  "mint": "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump",
  "nodes": [
    {
      "id": "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump",
      "label": "Token",
      "val": 20,
      "color": "#5cd47f",
      "type": "target"
    }
  ],
  "links": [],
  "truncated": false,
  "scannedAt": 1782926400,
  "expiresAt": 1782926700,
  "stale": false,
  "providerVersion": "1.0.0",
  "analysisIncomplete": false,
  "analyzedHolders": 50
}

Response notes

truncatedTrue when nodes outside maxNodes were removed. Links to removed nodes are omitted.

Status	Body	When
400	`{"success":false,"error":"Invalid Solana token mint address"}`	The mint path parameter is invalid.
401	`{"success":false,"error":"Missing apiKey"}`	The Bearer header is missing or malformed.
403	`{"success":false,"error":"API key is not authorized for the partner intel namespace"}`	The key is invalid, revoked, or lacks partner-intel capability.
429	`{"success":false,"error":"Rate limit exceeded"}`	The key exceeded its tier limit. Honor Retry-After.
503	`{"success":false,"error":"Intel temporarily unavailable"}`	Storage or an upstream provider failed without a usable cached result.

Partner prescan

POST/api/v1/intel/token/{mint}/prescan

Queue an idempotent forensic warm-up immediately after launch detection.

AuthPartner API key as Authorization: Bearer.

Rate limitPer key by tier.

CORSNone. Call server to server.

Parameter	Type	Required	Description
`mint`	string (path)	yes	Solana token mint address.

Example request

curl -X POST https://www.scoped.fun/api/v1/intel/token/9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump/prescan \
  -H "Authorization: Bearer $RICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Example response

{
  "success": true,
  "mint": "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump",
  "queued": true
}

Example response (fresh result already cached)

{
  "success": true,
  "mint": "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump",
  "queued": false,
  "reason": "already-cached"
}

Response notes

queuedFalse is a successful no-op when a compatible fresh result already exists.

Status	Body	When
400	`{"success":false,"error":"Invalid Solana token mint address"}`	The mint path parameter is invalid.
401	`{"success":false,"error":"Missing apiKey"}`	The Bearer header is missing or malformed.
403	`{"success":false,"error":"API key is not authorized for the partner intel namespace"}`	The key is invalid, revoked, or lacks partner-intel capability.
429	`{"success":false,"error":"Rate limit exceeded"}`	The key exceeded its tier limit. Honor Retry-After.
503	`{"success":false,"error":"Intel temporarily unavailable"}`	Storage or an upstream provider failed without a usable cached result.

Pre-launch deployer screen

POST/api/v1/intel/screen-deployer

Check one through 25 funding or deployer wallets against vetted historical launch crews before a mint exists.

AuthPartner API key as Authorization: Bearer.

Rate limitPer key by tier.

CORSNone. Call server to server.

Parameter	Type	Required	Description
`wallet`	string (JSON)	no	One Solana wallet. Use either wallet or wallets.
`wallets`	string[] (JSON)	no	One through 25 Solana wallets.

Example request

curl -X POST https://www.scoped.fun/api/v1/intel/screen-deployer \
  -H "Authorization: Bearer $RICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallets":["DepLoyerExampLeVerdictDocs111111111111111111"]}'

Example response

{
  "success": true,
  "results": [
    {
      "wallet": "DepLoyerExampLeVerdictDocs111111111111111111",
      "found": true,
      "attribution": "single-group",
      "crews": [
        {
          "id": "crew-example",
          "code": "CREW-EXAMPLE",
          "tokensLaunched": 12,
          "ruggedCount": 3,
          "firstSeen": 1767225600,
          "lastSeen": 1785542400,
          "url": "https://www.scoped.fun/crew/crew-example"
        }
      ]
    }
  ],
  "methodology": {
    "basis": "Wallets matched against vetted historical launch groups.",
    "notFound": "No record is not a safety statement.",
    "noVerdict": "This endpoint reports launch history only."
  },
  "generatedAt": "2026-08-21T12:00:00.000Z"
}

Response notes

found: falseMeans no matching record was found. It is not a safety statement.

crewsHistorical launch counts and outcomes only. This endpoint deliberately emits no score or recommendation.

Status	Body	When
401	`{"success":false,"error":"Missing apiKey"}`	The Bearer header is missing or malformed.
403	`{"success":false,"error":"API key is not authorized for the partner intel namespace"}`	The key is invalid, revoked, or lacks partner-intel capability.
429	`{"success":false,"error":"Rate limit exceeded"}`	The key exceeded its tier limit. Honor Retry-After.
503	`{"success":false,"error":"Intel temporarily unavailable"}`	Storage or an upstream provider failed without a usable cached result.
400	{"success":false,"error":"Provide `wallet` or `wallets`: one or more Solana addresses"}	No valid wallet was supplied, or more than 25 wallets were requested.

X account identity

GET/api/v1/x-account

Resolve an X handle to its cross-time identity: current handle, prior handles seen on the same immutable user id, and linked token contract addresses.

AuthNone

Rate limit30 requests per minute per IP.

CORSOpen (browser calls allowed).

Parameter	Type	Required	Description
`handle`	string (query)	yes	X username, with or without the @.

Example request

curl "https://www.scoped.fun/api/v1/x-account?handle=example_handle"

Example response (tracked handle)

{
  "success": true,
  "tracked": true,
  "identity": {
    "userId": "1234567890123456789",
    "currentUsername": "example_handle",
    "priorUsernames": [
      "old_handle"
    ],
    "isRecycled": true,
    "followers": 5120,
    "firstSeen": 1735689600,
    "lastSeen": 1751328000,
    "linkedMints": [
      "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump"
    ]
  },
  "timestamp": "2026-07-01T12:00:00.000Z"
}

Example response (handle not tracked yet)

{
  "success": true,
  "tracked": false,
  "handle": "example_handle",
  "message": "Not in the tracker."
}

Response notes

identity.isRecycledMeans more than one distinct handle has been observed on the same X user id. That is evidence of a renamed or reused account, not proof of bad intent.

tracked: falseNo identity is currently stored. Reads never enroll an unknown handle into paid tracking.

identity.linkedMintsToken contract addresses this identity has been associated with in scans.

Status	Body	When
400	`{"success": false, "error": "Provide a valid X handle: ?handle=username"}`	The handle query parameter is missing or invalid.

Enroll X account tracking

POST/api/v1/x-account

Enroll up to 25 X handles for recurring identity-history tracking. This changes durable tracking state.

AuthPartner API key as Authorization: Bearer.

Rate limitAPI-key tier limit plus a 10 enrollment requests per minute safety ceiling. Up to 25 handles per request.

CORSNone. Call server to server.

Parameter	Type	Required	Description
`handle`	string (JSON)	no	One X username. Use either handle or handles.
`handles`	string[] (JSON)	no	One through 25 X usernames.

Example request

curl -X POST https://www.scoped.fun/api/v1/x-account \
  -H "Authorization: Bearer $RICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"handles":["example_handle"]}'

Example response

{
  "success": true,
  "queued": [
    "example_handle"
  ],
  "count": 1
}

Response notes

queuedNormalized, deduplicated handles accepted for recurring tracking.

Status	Body	When
400	{"success":false,"error":"Provide `handle` or `handles`: one or more valid X handles"}	No valid handle was supplied, or more than 25 handles were requested.
401	`{"success":false,"error":"Missing apiKey"}`	The Bearer header is missing or malformed.
403	`{"success":false,"error":"API key is not authorized for the partner intel namespace"}`	The key is invalid, revoked, or lacks partner capability.
429	`{"success":false,"error":"Rate limit exceeded"}`	The key exceeded its tier limit. Honor Retry-After.

API status

GET/api/v1/status

Liveness stub for uptime checks: confirms the API is serving and reports the API version.

AuthNone

Rate limitNone

Example request

curl https://www.scoped.fun/api/v1/status

Example response

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

Response notes

versionThe v1 API version string.

responseAdditional health fields may be added over time; treat unknown fields as informational. For per-component health, use GET /api/status below.

Component health

GET/api/status

Per-component health for the platform: app, database, Solana RPC, the always-on worker, live streams, and the bots. No key required.

AuthNone (no key required)

Rate limit30 requests per minute per IP. The snapshot behind it is cached for about 30 seconds, so faster polling returns the same data.

Example request

curl https://www.scoped.fun/api/status

Example response

{
  "overall": "degraded",
  "components": [
    {
      "component": "app",
      "label": "Web app and API",
      "status": "operational",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    },
    {
      "component": "database",
      "label": "Database",
      "status": "operational",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    },
    {
      "component": "solana-rpc",
      "label": "Solana data",
      "status": "operational",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    },
    {
      "component": "worker",
      "label": "Streaming worker",
      "status": "operational",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    },
    {
      "component": "live-streams",
      "label": "Live streams (bubble map, wash radar)",
      "status": "operational",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    },
    {
      "component": "x-bot",
      "label": "X reply bot",
      "status": "operational",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    },
    {
      "component": "x-stream",
      "label": "X account tracking",
      "status": "down",
      "detail": "Stream disconnected",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    },
    {
      "component": "x-feed",
      "label": "Extension X feed",
      "status": "unknown",
      "detail": "Coming soon",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    },
    {
      "component": "discord",
      "label": "Discord bot",
      "status": "unknown",
      "detail": "Coming soon",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    },
    {
      "component": "telegram",
      "label": "Telegram and Discord alert delivery",
      "status": "unknown",
      "detail": "Coming soon",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    },
    {
      "component": "market-data",
      "label": "Market data (Solana Tracker)",
      "status": "operational",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    }
  ],
  "generatedAt": "2026-07-01T12:00:00.000Z",
  "cacheTtlSeconds": 30
}

Response notes

overallRoll-up banner. Only a core component (app, database, solana-rpc, worker) going down reads as a full outage; a non-core outage, like the x-stream row in the example, rolls up as degraded.

components[].componentOne of: app, database, solana-rpc, worker, live-streams, x-bot, x-stream, x-feed, discord, telegram, market-data, robinhood-chain. label is the display name.

components[].statusOne of: operational, degraded, down, unknown. "unknown" means the check could not reach the component, not that it is down.

components[].detailOptional short context for a non-operational status.

components[].checkedAtISO timestamp of the underlying check. cacheTtlSeconds states the snapshot cache window.

responseThe response may gain additional fields over time; treat unknown fields as informational.

Status	Body	When
429	`{"error": "Too many requests"}`	Per-IP rate limit hit. Retry after the Retry-After header (seconds).

Errors

Status	Meaning
400	Invalid input: malformed address, missing mint, or a wallet passed where a token mint is required.
401	Missing API key on an authenticated endpoint.
403	Invalid or revoked API key, or a key that lacks the endpoint capability.
429	Rate limit or monthly quota hit. Per-minute 429s include a Retry-After header in seconds.
500	Unexpected server error. Safe to retry after a short wait.
503	Upstream token data temporarily unavailable. Retry in a moment.

Response shapes

Verdict

levelSAFE, CAUTION, or DANGER. The app and bots display these as LOW RISK, CAUTION, and AVOID.

score0-100, higher means riskier.

confidencehigh, medium, or low. Driven by holder coverage, not by the score.

topFlagsUp to 5 ranked flags, each with a label and a severity of critical, high, medium, or low.

coverageNotePresent when confidence is not high; states how many holders the scan actually saw.

RugScore

score0-100, higher means riskier.

levelgreen, yellow, or red traffic light.

confidencehigh, medium, or low, driven by holder coverage.

factorsContributing factors, sorted by points, each with a label and severity.

SupplyConcentration (coverage fields)

holderCoveragePctAnalyzed holders as a percent of the true holder population. Absent when the true total is unknown.

analyzedSupplyPctPercent of supply the analyzed holders represent.

top10Pct / top25PctSupply share held by the top 10 and top 25 real holders.

cabalSupplyPctSupply share held by shared-funder cluster members.

TraderRead

actionentry, wait, or avoid, with a matching label.

confidence / score / summaryHeuristic confidence, a 0-100 score, and a plain-language summary.

signalsWeighted signals, each with a tone of good, warn, or bad.

version / shadowModel version identifier and whether the read came from a shadow model.

DeployerInfo

address / sourceDeployer wallet and how it was attributed (mint-tx-signer, creator, or update-authority).

pastLaunchCount / isSerialDeployerPrior token launches by this address; null means the lookup was skipped or failed.

priorRugCount / priorRugEvidence / isRugDevCross-token reputation context. Aggregate legacy counts are unverified and do not affect the verdict unless an itemized attribution receipt exists.

stillHolds / heldSupplyPctWhether the deployer still holds within analyzed coverage; null means unknown, not sold.

API v1 reference

Programmatic access to the same forensic engine behind the app: token scans, verdicts, and X account identity checks.

Overview

CORS: quick-scan and the X identity read are browser-callable. Authenticated endpoints have no CORS headers by design; call them server side so your key never ships to a browser.

Auth & API keys

What $SCOPED unlocks

Hold any amount of $SCOPED

Live X-FeedNew posts from a token's linked X account pop onto the chart in real time.

Wash RadarLive tape coloring every swap organic / suspected / wash: the real volume behind the chart.

Cabal RadarKnown-crew, bundle, and sniper supply surfaced on the map before you ape.

API keySelf-serve key for the public scan API. Wire Scoped forensics into your own tools and agents.

Advanced viewFull forensic breakdown: deployer history, holder PnL, and deeper wallet intel.

Verification is a free wallet signature. It proves you hold $SCOPED and authorizes no transaction.

Connect a wallet holding $SCOPED to mint your key.

Tiers & limits

Tier	Rate limit	Monthly quota
Free	10 requests/min	1,000 requests/month
Pro	60 requests/min	50,000 requests/month
Enterprise	300 requests/min	Unlimited

A tier changes access only. It never changes scan output or scores. Quota months are UTC calendar months.

Quick scan

POST/api/v1/quick-scan

Fast token forensics without a key. Returns a bounded 20-holder preview, then completes and caches the 50+ holder public scan after the response. Provenance labels partial versus final coverage.

AuthNone

Rate limit15 requests per minute per IP. 429 responses include a Retry-After header in seconds.

CORSOpen (browser calls allowed).

Parameter	Type	Required	Description
`address`	string	yes	Token mint address. Wallet addresses are rejected with 400.

Example request

curl -X POST https://www.scoped.fun/api/v1/quick-scan \
  -H "Content-Type: application/json" \
  -d '{"address": "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump"}'

Example response (stats and data trimmed for brevity)

{
  "success": true,
  "verdict": {
    "level": "CAUTION",
    "score": 46,
    "confidence": "medium",
    "topFlags": [
      {
        "evidenceId": "wash:volume-share",
        "label": "38% of volume looks washed",
        "severity": "high"
      },
      {
        "evidenceId": "deployer:serial",
        "label": "Serial deployer (4 launches)",
        "severity": "medium"
      }
    ],
    "coverageNote": "Analyzed the top 20 of 3120 holders"
  },
  "traderRead": {
    "action": "wait",
    "label": "Wait",
    "confidence": "medium",
    "score": 55,
    "summary": "Mixed signals. Wash volume is elevated and the deployer has prior launches.",
    "signals": [
      {
        "tone": "warn",
        "label": "Elevated wash volume",
        "weight": 2
      }
    ],
    "version": "v2-weighted",
    "shadow": false
  },
  "stats": {
    "totalHolders": 3120,
    "analyzedHolders": 20,
    "analysisIncomplete": false,
    "rugScore": {
      "score": 42,
      "level": "yellow",
      "confidence": "medium",
      "factors": []
    },
    "botActivityScore": {
      "score": 18,
      "level": "green",
      "confidence": "medium",
      "factors": [],
      "metrics": {}
    },
    "supplyConcentration": {
      "top10Pct": 31.2,
      "cabalSupplyPct": 6.4,
      "holderCoveragePct": 0.6
    },
    "holderQuality": {
      "winners": 9,
      "exitLiquidity": 3,
      "analyzed": 40
    }
  },
  "data": {
    "nodes": [],
    "links": []
  },
  "tokenSecurity": {
    "hasFreezeAuthority": false,
    "hasMintAuthority": false,
    "isMutable": false,
    "riskLevel": "low",
    "riskFactors": []
  },
  "tokenMetadata": {
    "name": "Example Token",
    "symbol": "EXMPL",
    "priceUsd": 0.0012,
    "marketCap": 118000
  },
  "deployerInfo": {
    "address": "DepLoyerExampLeVerdictDocs111111111111111111",
    "isSerialDeployer": true,
    "pastLaunchCount": 4,
    "isRugDev": false
  },
  "scanProvenance": {
    "cacheHit": false,
    "scannedAt": 1782926400,
    "schemaVersion": 4,
    "profile": "public-api",
    "analyzedHolders": 20,
    "stage": "partial",
    "nextProfile": "public-api",
    "coverageStatus": "complete",
    "indexedSlot": 352000000,
    "networkSlot": 352000012,
    "slotLag": 12
  }
}

Response notes

verdict.levelOne of SAFE, CAUTION, or DANGER. verdict.score is 0-100 where higher means riskier.

verdict.confidenceCoverage-driven, not signal strength: it reports how much of the holder population the scan saw. coverageNote appears whenever confidence is not high.

statsThe full scan stats object (rug score, bot activity, supply concentration, wash, bundles, and more). The example above is trimmed; see the response shapes section for the key fields.

dataThe full bubble-map graph: data.nodes and data.links, exactly what the web app renders.

traderReadA plain-language read (entry, wait, or avoid) with weighted signals. Treat it as a heuristic summary, not advice.

scanProvenance.stageCold calls return partial with nextProfile public-api while the 50+ holder scan completes. Cached complete scans return final; capped scans remain partial.

Status	Body	When
400	`{"success": false, "error": "Invalid address"}`	The address is not valid base58.
400	`{"success": false, "error": "Address is not a token mint"}`	A wallet address was passed instead of a token mint.
429	`{"success": false, "error": "Too many requests"}`	Per-IP rate limit hit. Retry after the Retry-After header (seconds).
503	`{"success": false, "error": "Couldn't classify this address right now. Please try again in a moment."}`	Upstream asset lookup is temporarily unavailable.
503	`{"success": false, "error": "Token data unavailable. Try again in a moment."}`	Upstream token data is temporarily unavailable.
500	`{"success": false, "error": "Scan failed"}`	Unexpected server error.

Recent scans may be served from cache. Use POST /api/v1/analyze for a fresh, deeper read.

Analyze

POST/api/v1/analyze

Deep cabal analysis with an API key: top 100 holders, 5 funders per holder, identity enrichment.

AuthBearer token or X-API-Key header. The legacy JSON apiKey field is also accepted. Keep the key server side.

CORSNone. Call it server side and keep your key out of browser code.

Parameter	Type	Required	Description
`apiKey`	string	yes	Your API key via Authorization: Bearer, X-API-Key, or the legacy JSON field.
`mint`	string	yes	Token mint address. "address" is accepted as an alias.

Example request

curl -X POST https://www.scoped.fun/api/v1/analyze \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer rico_live_YOUR_KEY" \
  -d '{"mint": "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump"}'

Example response (nodes and links trimmed for brevity)

{
  "success": true,
  "mint": "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump",
  "data": {
    "nodes": [],
    "links": []
  },
  "stats": {
    "totalHolders": 3120,
    "analyzedHolders": 100,
    "analysisIncomplete": false,
    "rugScore": {
      "score": 34,
      "level": "yellow",
      "confidence": "medium",
      "factors": []
    },
    "supplyConcentration": {
      "holderCoveragePct": 3.2,
      "top10Pct": 28.4,
      "cabalSupplyPct": 4.8
    }
  },
  "verdict": {
    "level": "CAUTION",
    "score": 34,
    "confidence": "medium",
    "topFlags": []
  },
  "traderRead": {
    "action": "wait",
    "label": "Wait",
    "confidence": "medium",
    "score": 52,
    "summary": "Mixed holder signals.",
    "signals": [],
    "version": "v2-weighted"
  },
  "nodes": [
    {
      "id": "FunderExampLeVerdictDocs1111111111111111111",
      "type": "cabal-funder",
      "label": "Fund...1111",
      "tokenAmount": 0,
      "solBalance": 1.42,
      "identity": {
        "name": null,
        "category": null,
        "type": null,
        "tags": []
      },
      "metadata": {
        "fundedCount": 3,
        "threatScore": 85,
        "threatLevel": "high"
      }
    }
  ],
  "links": [
    {
      "source": "FunderExampLeVerdictDocs1111111111111111111",
      "target": "HoLderExampLeVerdictDocs1111111111111111111",
      "value": 0.5,
      "suspicious": true
    }
  ],
  "summary": {
    "totalHolders": 3120,
    "confidence": "medium",
    "analyzedHolders": 100,
    "holderCoveragePct": 3.2,
    "cabalCount": 3,
    "riskScore": 34,
    "verdict": {
      "level": "CAUTION",
      "score": 34,
      "confidence": "medium",
      "topFlags": []
    },
    "snipersDetected": 5,
    "bundleClustersDetected": 2,
    "holderQuality": {
      "winners": 22,
      "exitLiquidity": 6,
      "analyzed": 88
    },
    "coverageNote": "Analyzed the top 100 of 3120 holders"
  },
  "tokenSecurity": {
    "hasFreezeAuthority": false,
    "hasMintAuthority": false,
    "isMutable": false,
    "riskLevel": "low",
    "riskFactors": []
  },
  "tokenMetadata": {
    "name": "Example Token",
    "symbol": "EXMPL",
    "marketCap": 118000
  },
  "deployerInfo": {
    "address": "DepLoyerExampLeVerdictDocs111111111111111111",
    "isSerialDeployer": false,
    "pastLaunchCount": 1
  },
  "embed": {
    "type": "iframe",
    "url": "https://www.scoped.fun/embed?address=9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump&attribution=required",
    "customizationParams": [
      "background",
      "surface",
      "card",
      "border",
      "borderHi",
      "accent",
      "accentDeep",
      "text",
      "muted",
      "theme",
      "compact",
      "hideRail",
      "attribution"
    ],
    "attribution": {
      "label": "RicoMaps",
      "required": true
    }
  },
  "timestamp": "2026-07-01T12:00:00.000Z",
  "tier": "free",
  "processingMs": 8421,
  "scanProvenance": {
    "cacheHit": false,
    "scannedAt": 1782926400,
    "schemaVersion": 4,
    "profile": "deep-api",
    "analyzedHolders": 100,
    "stage": "final",
    "coverageStatus": "complete",
    "indexedSlot": 352000000,
    "networkSlot": 352000012,
    "slotLag": 12
  }
}

Response notes

summary.riskScore / summary.verdictThe canonical SAFE, CAUTION, or DANGER verdict and its 0-100 risk score. riskScore is the same value as verdict.score.

summary.confidenceCoverage measures: confidence and holderCoveragePct report analyzed holders over the true holder population. coverageNote appears whenever confidence is not high.

data / statsThe complete graph and forensic result, including node and link evidence, coverage, supply concentration, bot activity, bundles, wash analysis, and provider completeness.

nodes / links / summaryLegacy projections retained for existing integrations. New consumers should prefer data, stats, verdict, and traderRead.

embedA browser-ready bubble-map iframe URL plus supported color, density, and rail customization parameters. The API key never belongs in the iframe.

scanProvenanceCache status, scan time, engine schema, scan profile, and analyzed-holder depth for cross-surface comparisons.

Status	Body	When
401	`{"success": false, "error": "Missing apiKey"}`	No API key was supplied in a supported header or the JSON body.
403	`{"success": false, "error": "Invalid or revoked API key"}`	The key is unknown or has been rotated away.
429	`{"success": false, "error": "Rate limit exceeded"}`	Per-minute tier limit hit. Retry after the Retry-After header (seconds).
429	`{"success": false, "error": "Monthly quota exceeded for Free tier"}`	The tier's monthly quota (UTC calendar month) is used up.
400	`{"success": false, "error": "Invalid or missing token mint. Pass it as \"mint\" (or \"address\") in the JSON body."}`	The mint is missing or not valid base58.
503	`{"success": false, "error": "Token data unavailable. Try again in a moment."}`	Upstream token data is temporarily unavailable.
500	`{"success": false, "error": "Analysis failed"}`	Unexpected server error.

Partner token summary

GET/api/v1/intel/token/{mint}/summary

Stable partner contract for risk, holder concentration, launch coordination, clusters, and scan coverage.

AuthPartner API key as Authorization: Bearer. X-API-Key and JSON credentials are not accepted.

Rate limitPer key by tier. Enterprise allows 300 requests per minute with no monthly cap.

CORSNone. Call server to server.

Parameter	Type	Required	Description
`mint`	string (path)	yes	Solana token mint address.

Example request

curl -X GET https://www.scoped.fun/api/v1/intel/token/9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump/summary \
  -H "Authorization: Bearer $RICO_API_KEY"

Example response

{
  "success": true,
  "mint": "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump",
  "riskScore": {
    "score": 46,
    "level": "yellow",
    "confidence": "medium",
    "topFactors": []
  },
  "holders": {
    "totalHolders": 3120,
    "realHolderCount": 3108,
    "top10Pct": 31.2,
    "top20Pct": 39.4,
    "top25Pct": 43.1,
    "devWalletPct": 1.2,
    "devStillHolds": true,
    "giniCoefficient": 0.61,
    "freshWalletPct": 18.5
  },
  "snipers": {
    "launchWindowSeconds": 120,
    "coordinatedEntryLevel": "yellow",
    "coordinatedWalletCount": 5,
    "coordinatedSupplyPct": 3.4,
    "launchSnipedSupplyPct": 4.1,
    "launchStillHeldSupplyPct": 2.2,
    "bundleWalletCount": 2,
    "bundleSupplyPct": 1.4
  },
  "clusters": {
    "clusteredHolderCount": 7,
    "clusterCount": 2,
    "largestClusterPct": 6.4,
    "cabalSupplyPct": 6.4,
    "knownCabalMatch": false
  },
  "coverage": {
    "analyzedHolders": 50,
    "holderCoveragePct": 1.6,
    "analysisIncomplete": false
  },
  "scannedAt": 1782926400,
  "expiresAt": 1782926700,
  "stale": false,
  "providerVersion": "1.0.0",
  "analysisIncomplete": false,
  "analyzedHolders": 50
}

Response notes

riskScore.levelgreen, yellow, red, or unrated. Unrated means the engine could not support a score.

staleTrue means an expired prior result was served while a refresh was queued.

Status	Body	When
400	`{"success":false,"error":"Invalid Solana token mint address"}`	The mint path parameter is invalid.
401	`{"success":false,"error":"Missing apiKey"}`	The Bearer header is missing or malformed.
403	`{"success":false,"error":"API key is not authorized for the partner intel namespace"}`	The key is invalid, revoked, or lacks partner-intel capability.
429	`{"success":false,"error":"Rate limit exceeded"}`	The key exceeded its tier limit. Honor Retry-After.
503	`{"success":false,"error":"Intel temporarily unavailable"}`	Storage or an upstream provider failed without a usable cached result.

Partner holder table

GET/api/v1/intel/token/{mint}/holders

Largest analyzed holders with their circulating-supply share and sniper, bundle, and cabal classifications.

AuthPartner API key as Authorization: Bearer.

Rate limitPer key by tier.

CORSNone. Call server to server.

Parameter	Type	Required	Description
`mint`	string (path)	yes	Solana token mint address.
`limit`	integer (query)	no	Default 20; clamped from 1 through 50.

Example request

curl -X GET https://www.scoped.fun/api/v1/intel/token/9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump/holders?limit=20 \
  -H "Authorization: Bearer $RICO_API_KEY"

Example response

{
  "success": true,
  "mint": "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump",
  "holders": [
    {
      "address": "HoLderExampLeVerdictDocs1111111111111111111",
      "pct": 2.4,
      "isSniper": true,
      "isBundled": false,
      "isCabal": true
    }
  ],
  "scannedAt": 1782926400,
  "expiresAt": 1782926700,
  "stale": false,
  "providerVersion": "1.0.0",
  "analysisIncomplete": false,
  "analyzedHolders": 50
}

Response notes

holders[].pctShare of the same circulating-supply denominator used by the summary concentration fields.

Status	Body	When
400	`{"success":false,"error":"Invalid Solana token mint address"}`	The mint path parameter is invalid.
401	`{"success":false,"error":"Missing apiKey"}`	The Bearer header is missing or malformed.
403	`{"success":false,"error":"API key is not authorized for the partner intel namespace"}`	The key is invalid, revoked, or lacks partner-intel capability.
429	`{"success":false,"error":"Rate limit exceeded"}`	The key exceeded its tier limit. Honor Retry-After.
503	`{"success":false,"error":"Intel temporarily unavailable"}`	Storage or an upstream provider failed without a usable cached result.

Partner launch coordination

GET/api/v1/intel/token/{mint}/snipers

Launch-window coordination and bundle evidence, including current and exited supply.

AuthPartner API key as Authorization: Bearer.

Rate limitPer key by tier.

CORSNone. Call server to server.

Parameter	Type	Required	Description
`mint`	string (path)	yes	Solana token mint address.

Example request

curl -X GET https://www.scoped.fun/api/v1/intel/token/9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump/snipers \
  -H "Authorization: Bearer $RICO_API_KEY"

Example response

{
  "success": true,
  "mint": "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump",
  "coordinatedEntry": {
    "level": "yellow",
    "maxWalletsInWindow": 5,
    "windowSeconds": 120,
    "coordinatedSupplyPct": 3.4,
    "wallets": [
      "HoLderExampLeVerdictDocs1111111111111111111"
    ],
    "crewUsd": [
      1840
    ]
  },
  "bundle": {
    "walletCount": 2,
    "exitedCount": 1,
    "supplyPct": 1.4,
    "soldSupplyPct": 0.8
  },
  "scannedAt": 1782926400,
  "expiresAt": 1782926700,
  "stale": false,
  "providerVersion": "1.0.0",
  "analysisIncomplete": false,
  "analyzedHolders": 50
}

Response notes

coordinatedEntry.wallets / crewUsdIndependent sorted arrays. Do not pair entries by array index.

Status	Body	When
400	`{"success":false,"error":"Invalid Solana token mint address"}`	The mint path parameter is invalid.
401	`{"success":false,"error":"Missing apiKey"}`	The Bearer header is missing or malformed.
403	`{"success":false,"error":"API key is not authorized for the partner intel namespace"}`	The key is invalid, revoked, or lacks partner-intel capability.
429	`{"success":false,"error":"Rate limit exceeded"}`	The key exceeded its tier limit. Honor Retry-After.
503	`{"success":false,"error":"Intel temporarily unavailable"}`	Storage or an upstream provider failed without a usable cached result.

Partner graph

GET/api/v1/intel/token/{mint}/graph

Size-capped public bubble graph with generic role labels and no private provider attribution.

AuthPartner API key as Authorization: Bearer.

Rate limitPer key by tier.

CORSNone. Call server to server.

Parameter	Type	Required	Description
`mint`	string (path)	yes	Solana token mint address.
`maxNodes`	integer (query)	no	Default 60; clamped from 1 through 150.

Example request

curl -X GET https://www.scoped.fun/api/v1/intel/token/9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump/graph?maxNodes=60 \
  -H "Authorization: Bearer $RICO_API_KEY"

Example response

{
  "success": true,
  "mint": "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump",
  "nodes": [
    {
      "id": "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump",
      "label": "Token",
      "val": 20,
      "color": "#5cd47f",
      "type": "target"
    }
  ],
  "links": [],
  "truncated": false,
  "scannedAt": 1782926400,
  "expiresAt": 1782926700,
  "stale": false,
  "providerVersion": "1.0.0",
  "analysisIncomplete": false,
  "analyzedHolders": 50
}

Response notes

truncatedTrue when nodes outside maxNodes were removed. Links to removed nodes are omitted.

Status	Body	When
400	`{"success":false,"error":"Invalid Solana token mint address"}`	The mint path parameter is invalid.
401	`{"success":false,"error":"Missing apiKey"}`	The Bearer header is missing or malformed.
403	`{"success":false,"error":"API key is not authorized for the partner intel namespace"}`	The key is invalid, revoked, or lacks partner-intel capability.
429	`{"success":false,"error":"Rate limit exceeded"}`	The key exceeded its tier limit. Honor Retry-After.
503	`{"success":false,"error":"Intel temporarily unavailable"}`	Storage or an upstream provider failed without a usable cached result.

Partner prescan

POST/api/v1/intel/token/{mint}/prescan

Queue an idempotent forensic warm-up immediately after launch detection.

AuthPartner API key as Authorization: Bearer.

Rate limitPer key by tier.

CORSNone. Call server to server.

Parameter	Type	Required	Description
`mint`	string (path)	yes	Solana token mint address.

Example request

curl -X POST https://www.scoped.fun/api/v1/intel/token/9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump/prescan \
  -H "Authorization: Bearer $RICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Example response

{
  "success": true,
  "mint": "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump",
  "queued": true
}

Example response (fresh result already cached)

{
  "success": true,
  "mint": "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump",
  "queued": false,
  "reason": "already-cached"
}

Response notes

queuedFalse is a successful no-op when a compatible fresh result already exists.

Status	Body	When
400	`{"success":false,"error":"Invalid Solana token mint address"}`	The mint path parameter is invalid.
401	`{"success":false,"error":"Missing apiKey"}`	The Bearer header is missing or malformed.
403	`{"success":false,"error":"API key is not authorized for the partner intel namespace"}`	The key is invalid, revoked, or lacks partner-intel capability.
429	`{"success":false,"error":"Rate limit exceeded"}`	The key exceeded its tier limit. Honor Retry-After.
503	`{"success":false,"error":"Intel temporarily unavailable"}`	Storage or an upstream provider failed without a usable cached result.

Pre-launch deployer screen

POST/api/v1/intel/screen-deployer

Check one through 25 funding or deployer wallets against vetted historical launch crews before a mint exists.

AuthPartner API key as Authorization: Bearer.

Rate limitPer key by tier.

CORSNone. Call server to server.

Parameter	Type	Required	Description
`wallet`	string (JSON)	no	One Solana wallet. Use either wallet or wallets.
`wallets`	string[] (JSON)	no	One through 25 Solana wallets.

Example request

curl -X POST https://www.scoped.fun/api/v1/intel/screen-deployer \
  -H "Authorization: Bearer $RICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallets":["DepLoyerExampLeVerdictDocs111111111111111111"]}'

Example response

{
  "success": true,
  "results": [
    {
      "wallet": "DepLoyerExampLeVerdictDocs111111111111111111",
      "found": true,
      "attribution": "single-group",
      "crews": [
        {
          "id": "crew-example",
          "code": "CREW-EXAMPLE",
          "tokensLaunched": 12,
          "ruggedCount": 3,
          "firstSeen": 1767225600,
          "lastSeen": 1785542400,
          "url": "https://www.scoped.fun/crew/crew-example"
        }
      ]
    }
  ],
  "methodology": {
    "basis": "Wallets matched against vetted historical launch groups.",
    "notFound": "No record is not a safety statement.",
    "noVerdict": "This endpoint reports launch history only."
  },
  "generatedAt": "2026-08-21T12:00:00.000Z"
}

Response notes

found: falseMeans no matching record was found. It is not a safety statement.

crewsHistorical launch counts and outcomes only. This endpoint deliberately emits no score or recommendation.

Status	Body	When
401	`{"success":false,"error":"Missing apiKey"}`	The Bearer header is missing or malformed.
403	`{"success":false,"error":"API key is not authorized for the partner intel namespace"}`	The key is invalid, revoked, or lacks partner-intel capability.
429	`{"success":false,"error":"Rate limit exceeded"}`	The key exceeded its tier limit. Honor Retry-After.
503	`{"success":false,"error":"Intel temporarily unavailable"}`	Storage or an upstream provider failed without a usable cached result.
400	{"success":false,"error":"Provide `wallet` or `wallets`: one or more Solana addresses"}	No valid wallet was supplied, or more than 25 wallets were requested.

X account identity

GET/api/v1/x-account

Resolve an X handle to its cross-time identity: current handle, prior handles seen on the same immutable user id, and linked token contract addresses.

AuthNone

Rate limit30 requests per minute per IP.

CORSOpen (browser calls allowed).

Parameter	Type	Required	Description
`handle`	string (query)	yes	X username, with or without the @.

Example request

curl "https://www.scoped.fun/api/v1/x-account?handle=example_handle"

Example response (tracked handle)

{
  "success": true,
  "tracked": true,
  "identity": {
    "userId": "1234567890123456789",
    "currentUsername": "example_handle",
    "priorUsernames": [
      "old_handle"
    ],
    "isRecycled": true,
    "followers": 5120,
    "firstSeen": 1735689600,
    "lastSeen": 1751328000,
    "linkedMints": [
      "9wKrtBEsToKenExampLeMintVerdictDocs1Abcdpump"
    ]
  },
  "timestamp": "2026-07-01T12:00:00.000Z"
}

Example response (handle not tracked yet)

{
  "success": true,
  "tracked": false,
  "handle": "example_handle",
  "message": "Not in the tracker."
}

Response notes

identity.isRecycledMeans more than one distinct handle has been observed on the same X user id. That is evidence of a renamed or reused account, not proof of bad intent.

tracked: falseNo identity is currently stored. Reads never enroll an unknown handle into paid tracking.

identity.linkedMintsToken contract addresses this identity has been associated with in scans.

Status	Body	When
400	`{"success": false, "error": "Provide a valid X handle: ?handle=username"}`	The handle query parameter is missing or invalid.

Enroll X account tracking

POST/api/v1/x-account

Enroll up to 25 X handles for recurring identity-history tracking. This changes durable tracking state.

AuthPartner API key as Authorization: Bearer.

Rate limitAPI-key tier limit plus a 10 enrollment requests per minute safety ceiling. Up to 25 handles per request.

CORSNone. Call server to server.

Parameter	Type	Required	Description
`handle`	string (JSON)	no	One X username. Use either handle or handles.
`handles`	string[] (JSON)	no	One through 25 X usernames.

Example request

curl -X POST https://www.scoped.fun/api/v1/x-account \
  -H "Authorization: Bearer $RICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"handles":["example_handle"]}'

Example response

{
  "success": true,
  "queued": [
    "example_handle"
  ],
  "count": 1
}

Response notes

queuedNormalized, deduplicated handles accepted for recurring tracking.

Status	Body	When
400	{"success":false,"error":"Provide `handle` or `handles`: one or more valid X handles"}	No valid handle was supplied, or more than 25 handles were requested.
401	`{"success":false,"error":"Missing apiKey"}`	The Bearer header is missing or malformed.
403	`{"success":false,"error":"API key is not authorized for the partner intel namespace"}`	The key is invalid, revoked, or lacks partner capability.
429	`{"success":false,"error":"Rate limit exceeded"}`	The key exceeded its tier limit. Honor Retry-After.

API status

GET/api/v1/status

Liveness stub for uptime checks: confirms the API is serving and reports the API version.

AuthNone

Rate limitNone

Example request

curl https://www.scoped.fun/api/v1/status

Example response

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

Response notes

versionThe v1 API version string.

responseAdditional health fields may be added over time; treat unknown fields as informational. For per-component health, use GET /api/status below.

Component health

GET/api/status

Per-component health for the platform: app, database, Solana RPC, the always-on worker, live streams, and the bots. No key required.

AuthNone (no key required)

Rate limit30 requests per minute per IP. The snapshot behind it is cached for about 30 seconds, so faster polling returns the same data.

Example request

curl https://www.scoped.fun/api/status

Example response

{
  "overall": "degraded",
  "components": [
    {
      "component": "app",
      "label": "Web app and API",
      "status": "operational",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    },
    {
      "component": "database",
      "label": "Database",
      "status": "operational",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    },
    {
      "component": "solana-rpc",
      "label": "Solana data",
      "status": "operational",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    },
    {
      "component": "worker",
      "label": "Streaming worker",
      "status": "operational",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    },
    {
      "component": "live-streams",
      "label": "Live streams (bubble map, wash radar)",
      "status": "operational",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    },
    {
      "component": "x-bot",
      "label": "X reply bot",
      "status": "operational",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    },
    {
      "component": "x-stream",
      "label": "X account tracking",
      "status": "down",
      "detail": "Stream disconnected",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    },
    {
      "component": "x-feed",
      "label": "Extension X feed",
      "status": "unknown",
      "detail": "Coming soon",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    },
    {
      "component": "discord",
      "label": "Discord bot",
      "status": "unknown",
      "detail": "Coming soon",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    },
    {
      "component": "telegram",
      "label": "Telegram and Discord alert delivery",
      "status": "unknown",
      "detail": "Coming soon",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    },
    {
      "component": "market-data",
      "label": "Market data (Solana Tracker)",
      "status": "operational",
      "checkedAt": "2026-07-01T12:00:00.000Z"
    }
  ],
  "generatedAt": "2026-07-01T12:00:00.000Z",
  "cacheTtlSeconds": 30
}

Response notes

overallRoll-up banner. Only a core component (app, database, solana-rpc, worker) going down reads as a full outage; a non-core outage, like the x-stream row in the example, rolls up as degraded.

components[].componentOne of: app, database, solana-rpc, worker, live-streams, x-bot, x-stream, x-feed, discord, telegram, market-data, robinhood-chain. label is the display name.

components[].statusOne of: operational, degraded, down, unknown. "unknown" means the check could not reach the component, not that it is down.

components[].detailOptional short context for a non-operational status.

components[].checkedAtISO timestamp of the underlying check. cacheTtlSeconds states the snapshot cache window.

responseThe response may gain additional fields over time; treat unknown fields as informational.

Status	Body	When
429	`{"error": "Too many requests"}`	Per-IP rate limit hit. Retry after the Retry-After header (seconds).

Errors

Status	Meaning
400	Invalid input: malformed address, missing mint, or a wallet passed where a token mint is required.
401	Missing API key on an authenticated endpoint.
403	Invalid or revoked API key, or a key that lacks the endpoint capability.
429	Rate limit or monthly quota hit. Per-minute 429s include a Retry-After header in seconds.
500	Unexpected server error. Safe to retry after a short wait.
503	Upstream token data temporarily unavailable. Retry in a moment.

Response shapes

Verdict

levelSAFE, CAUTION, or DANGER. The app and bots display these as LOW RISK, CAUTION, and AVOID.

score0-100, higher means riskier.

confidencehigh, medium, or low. Driven by holder coverage, not by the score.

topFlagsUp to 5 ranked flags, each with a label and a severity of critical, high, medium, or low.

coverageNotePresent when confidence is not high; states how many holders the scan actually saw.

RugScore

score0-100, higher means riskier.

levelgreen, yellow, or red traffic light.

confidencehigh, medium, or low, driven by holder coverage.

factorsContributing factors, sorted by points, each with a label and severity.

SupplyConcentration (coverage fields)

holderCoveragePctAnalyzed holders as a percent of the true holder population. Absent when the true total is unknown.

analyzedSupplyPctPercent of supply the analyzed holders represent.

top10Pct / top25PctSupply share held by the top 10 and top 25 real holders.

cabalSupplyPctSupply share held by shared-funder cluster members.

TraderRead

actionentry, wait, or avoid, with a matching label.

confidence / score / summaryHeuristic confidence, a 0-100 score, and a plain-language summary.

signalsWeighted signals, each with a tone of good, warn, or bad.

version / shadowModel version identifier and whether the read came from a shadow model.

DeployerInfo

address / sourceDeployer wallet and how it was attributed (mint-tx-signer, creator, or update-authority).

pastLaunchCount / isSerialDeployerPrior token launches by this address; null means the lookup was skipped or failed.

priorRugCount / priorRugEvidence / isRugDevCross-token reputation context. Aggregate legacy counts are unverified and do not affect the verdict unless an itemized attribution receipt exists.

stillHolds / heldSupplyPctWhether the deployer still holds within analyzed coverage; null means unknown, not sold.