> For the complete documentation index, see [llms.txt](https://docs.heyhal.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heyhal.xyz/api-documentation/king-of-the-hill.md).
# 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(
### ''
### );
###
### 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(
### \`
### );
###
### 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(
\`
);
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;
}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.heyhal.xyz/api-documentation/king-of-the-hill.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.