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

Parameter	Type	Required	Description
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.heyhal.xyz/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.heyhal.xyz/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.heyhal.xyz/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;

}