Sacred Scrolls

API REFERENCE

Invoke the oracle programmatically. Integrate Kvlt Score into your bots, dashboards, and trading terminals.

Base URL: https://api.kvlt.fun

Authentication

Public endpoints require no authentication. Rate limits apply per IP. Hold $KVLT to unlock higher rate limits.

Tier	$KVLT Required	Rate Limit
Free	0	5 req/day
Acolyte	10,000	50 req/day
Priest	50,000	500 req/day
High Priest	250,000	1,000 req/day
Oracle	1,000,000	Unlimited

POST/scan

Submit a Solana token contract address for community analysis. Returns the Kvlt Score, grade, and all five indicator breakdowns.

Request Body

{
  "ca": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"
}

Field	Type	Required	Description
ca	string	Yes	Solana token mint address (base58)

Response (200)

{
  "success": true,
  "data": {
    "ca": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
    "projectName": "BONK",
    "score": 78.25,
    "grade": "Congregation",
    "indicators": {
      "telegramActivity": 82,
      "twitterOrganic": 78,
      "holderStickiness": 85,
      "whaleIndependence": 70,
      "contentGeneration": 75
    },
    "socialLinks": {
      "twitter": "https://x.com/bonaboratiooo",
      "telegram": "https://t.me/bonkbot"
    },
    "updatedAt": "2026-03-30T12:00:00.000Z"
  }
}

Errors

400 — Missing or invalid ca field

404 — Token not found

429 — Rate limit exceeded

500 — Internal server error

GET/rankings

Retrieve the ranked leaderboard of all scanned tokens, sorted by Kvlt Score.

Query Parameters

Param	Type	Default	Description
limit	number	50	Max results (1-100)
sort	string	score	Sort by: score, name
minScore	number	0	Minimum score filter

Response (200)

{
  "success": true,
  "rankings": [
    {
      "ca": "...",
      "projectName": "BONK",
      "score": 85.50,
      "grade": "True Cult",
      "indicators": { ... },
      "socialLinks": { ... },
      "updatedAt": "..."
    }
  ],
  "total": 42
}

GET/health

Service health check. No authentication required.

{
  "status": "ok",
  "timestamp": "2026-03-30T12:00:00.000Z"
}

Quick Start

cURL

curl -X POST https://api.kvlt.fun/scan \
  -H "Content-Type: application/json" \
  -d '{"ca": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"}'

JavaScript / TypeScript

const res = await fetch('https://api.kvlt.fun/scan', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ ca: 'YOUR_TOKEN_CA' }),
});
const { data } = await res.json();
console.log(data.score, data.grade);

Python

import requests

r = requests.post('https://api.kvlt.fun/scan',
    json={'ca': 'YOUR_TOKEN_CA'})
data = r.json()['data']
print(f"{data['projectName']}: {data['score']} ({data['grade']})")

Error Format

All errors follow a consistent JSON format with an HTTP status code.

{
  "success": false,
  "error": "Rate limit exceeded. Retry after 60 seconds."
}

Rate-limited responses include a Retry-After header.