Get Token Details

Endpoint: GET /api/v1/coin/details

Description

This endpoint retrieves detailed information about a specific token, including its metadata, comments, creator information, AI agent configuration, and price history (OHLC data).

Authentication

Required: No

Type: None

Request

Headers

Content-Type: application/json

Query Parameters

Parameter	Type	Required	Description
token	string	Yes	The mint address of the token

Example Request:

GET /api/v1/coin/details?token=TokenMintAddress123...

Response

Success Response

Status Code: 200 OK

Content-Type: application/json

interface TokenDetailsResponse {

// Token Basic Info

mintAddress: string;

name: string;

symbol: string;

description: string;

metaDataUrl: string;

imageUrl: string;

creatorWalletAddress: string;

status: string;

// Token State

tx: string | null;

signature: string | null;

migrationStatus: string | null;

kingOfTheHillTimeStamp: string | null;

marketCap: string | null;

// Timestamps

createdAt: string;

updatedAt: string;

// Related Entities

comments: Array<{

id: number;

content: string;

createdAt: string;

updatedAt: string;

userId: string;

coinId: string;

}>;

creator: {

walletAddress: string;

username: string;

role: string;

lastLogin: string;

};

agent: {

id: number;

name: string;

description: string;

personality: string;

instruction: string;

knowledge: string;

points: number;

usedPoints: number;

telegramUrl: string;

twitterUrl: string;

websiteUrl: string;

createdAt: string;

updatedAt: string;

} | null;

ohlc: Array<{

timestamp: string;

open: string;

high: string;

low: string;

close: string;

volume: string;

}>;

}

Error Response

Status Code: 500 Internal Server Error

{

"error": "An internal error occurred. Please try again later."

}

Example Usage

// Basic token details fetcher

async function getTokenDetails(tokenMintAddress: string) {

try {

const response = await fetch(

`https://api.heyhal.xyz/api/v1/coin/details?token=${tokenMintAddress}`

);

if (!response.ok) {

throw new Error(`HTTP error! status: ${response.status}`);

}

const tokenDetails = await response.json();

return tokenDetails;

} catch (error) {

console.error('Error fetching token details:', error);

throw error;

}

}

// Token Details Manager with caching

class TokenDetailsManager {

private cache: Map<string, {

data: TokenDetailsResponse;

timestamp: number;

}> = new Map();

private readonly CACHE_DURATION = 30000; // 30 seconds

async getDetails(tokenMintAddress: string): Promise<TokenDetailsResponse> {

// Check cache

const cached = this.cache.get(tokenMintAddress);

if (cached && Date.now() - cached.timestamp < this.CACHE_DURATION) {

return cached.data;

}

// Fetch fresh data

const details = await getTokenDetails(tokenMintAddress);

// Update cache

this.cache.set(tokenMintAddress, {

data: details,

timestamp: Date.now()

});

return details;

}

clearCache(tokenMintAddress?: string) {

if (tokenMintAddress) {

this.cache.delete(tokenMintAddress);

} else {

this.cache.clear();

}

}

}

Implementation Notes

1. Data Processing Utilities

// Token status helper

function getTokenStatus(details: TokenDetailsResponse) {

if (details.migrationStatus === 'completed') {

return 'MIGRATED';

}

if (details.kingOfTheHillTimeStamp) {

return 'KING_OF_HILL';

}

if (details.status === 'success') {

return 'ACTIVE';

}

return 'PENDING';

}

// Price history formatter

function formatPriceHistory(details: TokenDetailsResponse) {

return details.ohlc.map(candle => ({

timestamp: new Date(candle.timestamp).getTime(),

open: parseFloat(candle.open),

high: parseFloat(candle.high),

low: parseFloat(candle.low),

close: parseFloat(candle.close),

volume: parseFloat(candle.volume)

}));

}

// Social links aggregator

function getSocialLinks(details: TokenDetailsResponse) {

return {

telegram: details.agent?.telegramUrl || null,

twitter: details.agent?.twitterUrl || null,

website: details.agent?.websiteUrl || null

};

}

Data Display Components

// React component example

interface TokenInfoProps {

tokenMintAddress: string;

}

function TokenInfo({ tokenMintAddress }: TokenInfoProps) {

const [details, setDetails] = useState<TokenDetailsResponse | null>(null);

const [loading, setLoading] = useState(true);

const [error, setError] = useState<string | null>(null);

useEffect(() => {

async function fetchDetails() {

try {

const data = await getTokenDetails(tokenMintAddress);

setDetails(data);

} catch (err) {

setError(err.message);

} finally {

setLoading(false);

}

}

fetchDetails();

}, [tokenMintAddress]);

if (loading) return <div>Loading...</div>;

if (error) return <div>Error: {error}</div>;

if (!details) return <div>No data found</div>;

return (

<div>

<h1>{details.name} ({details.symbol})</h1>

<img src={details.imageUrl} alt={details.name} />

<p>{details.description}</p>

<h2>Market Data</h2>

<p>Market Cap: {details.marketCap || 'N/A'}</p>

<h2>Comments ({details.comments.length})</h2>

{details.comments.map(comment => (

<div key={comment.id}>

<p>{comment.content}</p>

<small>

Posted on {new Date(comment.createdAt).toLocaleDateString()}

</small>

</div>

))}

{details.agent && (

<h2>AI Agent</h2>

<p>Name: {details.agent.name}</p>

<p>Description: {details.agent.description}</p>

<p>Points: {details.agent.points - details.agent.usedPoints}</p>

)}

</div>

);

}

Real-time Updates

class TokenDetailsWatcher {

private ws: WebSocket | null = null;

private listeners: Set<(details: TokenDetailsResponse) => void> = new Set();

constructor(private tokenMintAddress: string) {}

connect() {

this.ws = new WebSocket('wss://api.heyhal.xyz/ws');

this.ws.onopen = () => {

this.ws?.send(JSON.stringify({

type: 'subscribe',

token: this.tokenMintAddress

}));

};

this.ws.onmessage = (event) => {

const data = JSON.parse(event.data);

this.notifyListeners(data);

};

}

addListener(callback: (details: TokenDetailsResponse) => void) {

this.listeners.add(callback);

}

removeListener(callback: (details: TokenDetailsResponse) => void) {

this.listeners.delete(callback);

}

private notifyListeners(data: TokenDetailsResponse) {

this.listeners.forEach(listener => listener(data));

}

disconnect() {

this.ws?.close();

this.ws = null;

}

}