King of the Hill
Endpoint: GET /api/v1/coin/king-of-the-hill
Description
This endpoint serves two purposes:
When called without a token parameter, it retrieves the current "King of the Hill" token (the most recent token to reach the threshold)
When called with a token parameter, it checks and updates the King of the Hill status for that specific token
Authentication
Required: No
Type: None
Request
Headers
Content-Type: application/json
Query Parameters
token
string
No
The mint address of the token to check/update
Example Requests:
GET /api/v1/coin/king-of-the-hill // Get current King of the Hill
GET /api/v1/coin/king-of-the-hill?token=ABC // Check/update specific token
Response
Success Response - Get Current King
Status Code: 200 OK
Content-Type: application/json
interface KingOfTheHillResponse {
mintAddress: string;
name: string;
symbol: string;
description: string;
metaDataUrl: string;
imageUrl: string;
creatorWalletAddress: string;
status: string;
kingOfTheHillTimeStamp: string;
comments: Array<{
id: number;
content: string;
user: {
walletAddress: string;
username: string;
}
}>;
creator: {
walletAddress: string;
username: string;
role: string;
};
agent: {
name: string;
description: string;
telegramUrl: string;
twitterUrl: string;
websiteUrl: string;
// ... other agent properties
} | null;
}
Success Response - Update Token Status
Status Code: 200 OK
{
"success": true
}
Error Response
Status Code: 500 Internal Server Error
{
"error": "An internal error occurred. Please try again later."
}
Example Usage
// Function to get current King of the Hill
async function getCurrentKing() {
try {
const response = await fetch(
'https://api.cybers.app/api/v1/coin/king-of-the-hill'
);
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const kingToken = await response.json();
return kingToken;
} catch (error) {
console.error('Error fetching King of the Hill:', error);
throw error;
}
}
// Function to check/update token status
async function checkKingStatus(tokenMintAddress: string) {
try {
const response = await fetch(
`https://api.cybers.app/api/v1/coin/king-of-the-hill?token=${tokenMintAddress}`
);
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const result = await response.json();
return result.success;
} catch (error) {
console.error('Error checking King status:', error);
throw error;
}
}
// Example usage with UI updates
async function displayKingOfTheHill() {
try {
const king = await getCurrentKing();
if (king) {
console.log(`
Current King of the Hill:
Token: ${king.name} (${king.symbol})
Achieved at: ${new Date(Number(king.kingOfTheHillTimeStamp) * 1000).toLocaleString()}
Creator: ${king.creator.username || king.creator.walletAddress}
Comments: ${king.comments.length}
`);
} else {
console.log('No token has achieved King of the Hill status yet');
}
} catch (error) {
console.error('Error displaying King of the Hill:', error);
}
}
Implementation Notes
King of the Hill Threshold
A token becomes King of the Hill when its reserve reaches below config.constants.kingOfTheHill
The timestamp is recorded in Unix seconds (Date.now() / 1000)
Only the first time reaching the threshold is recorded
2. Status Checking
The endpoint checks current reserves using the reserves() function
Tokens can only achieve King of the Hill status once
The status is permanent once achieved
Data Relationships
The response includes related comments, creator info, and agent details
All timestamps are in Unix seconds format
Comments are ordered by creation time
Best Practices
Polling
// Example of responsible polling for King status
async function pollForKingStatus(tokenMintAddress: string) {
const POLL_INTERVAL = 30000; // 30 seconds
const MAX_ATTEMPTS = 20; // Stop after ~10 minutes
let attempts = 0;
const poll = async () => {
try {
const result = await checkKingStatus(tokenMintAddress);
if (result.success) {
return true;
}
attempts++;
if (attempts >= MAX_ATTEMPTS) {
throw new Error('Polling timeout');
}
await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL));
return poll();
} catch (error) {
console.error('Polling error:', error);
throw error;
}
};
return poll();
}
Event Handling
// Example of handling King of the Hill achievement
async function handleKingAchievement(token: string) {
try {
// Check current status
const response = await fetch(
`https://api.cybers.app/api/v1/coin/king-of-the-hill?token=${token}`
);
const result = await response.json();
if (result.success) {
// Trigger any necessary UI updates
// Update local state
// Show achievement notification
}
} catch (error) {
console.error('Error handling achievement:', error);
}
}
Cache Management
// Example of caching King of the Hill data
const CACHE_DURATION = 60000; // 1 minute
let kingCache = {
data: null,
timestamp: 0
};
async function getCachedKing() {
const now = Date.now();
if (now - kingCache.timestamp < CACHE_DURATION) {
return kingCache.data;
}
const king = await getCurrentKing();
kingCache = {
data: king,
timestamp: now
};
return king;
}
Last updated