> 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/get-reserves.md).
# Get Reserves
**Endpoint:** `GET /api/v1/coin/reserves`
**Description**
This endpoint retrieves the current reserves (token and SOL amounts) for a specific token's bonding curve pool. This information is crucial for calculating prices and understanding the liquidity depth of a token.
**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/reserves?token=TokenMintAddress123…
### Response
**Success Response**
Status Code: 200 OK
Content-Type: application/json
interface ReservesResponse {
reserveOne: string; // Token reserve amount (in base units)
reserveTwo: string; // SOL reserve amount (in lamports)
reserveOneBN: string; // Token reserve as BigNumber string
reserveTwoBN: string; // SOL reserve as BigNumber string
reserveOneDecimal: string; // Token reserve in decimal format
reserveTwoDecimal: string; // SOL reserve in decimal format
}
**Example Response:**
{
"reserveOne": "1000000000000",
"reserveTwo": "5000000000",
"reserveOneBN": "1000000000000",
"reserveTwoBN": "5000000000",
"reserveOneDecimal": "1000.0",
"reserveTwoDecimal": "5.0"
}
**Error Response**
Status Code: 500 Internal Server Error
{
"error": "An internal error occurred. Please try again later."
}
### Example Usage
async function getTokenReserves(tokenMintAddress: string) {
try {
const response = await fetch(
\`
);
if (!response.ok) {
throw new Error(\`HTTP error! status: ${response.status}\`);
}
const reserves = await response.json();
return reserves;
} catch (error) {
console.error('Error fetching reserves:', error);
throw error;
}
}
**// Example usage with price calculation**
async function calculateTokenPrice(tokenMintAddress: string) {
try {
const reserves = await getTokenReserves(tokenMintAddress);
**// Calculate price (SOL per token)**
const price = Number(reserves.reserveTwoDecimal) /
Number(reserves.reserveOneDecimal);
console.log(\`
Current Pool Status:
Token Reserve: ${reserves.reserveOneDecimal}
SOL Reserve: ${reserves.reserveTwoDecimal} SOL
Current Price: ${price.toFixed(6)} SOL/token
\`);
return price;
} catch (error) {
console.error('Error calculating price:', error);
throw error;
}
}
**// Example usage with liquidity analysis**
async function analyzeLiquidity(tokenMintAddress: string) {
try {
const reserves = await getTokenReserves(tokenMintAddress);
return {
totalLiquiditySOL: Number(reserves.reserveTwoDecimal),
totalLiquidityTokens: Number(reserves.reserveOneDecimal),
liquidityDepth: {
sol: Number(reserves.reserveTwoDecimal),
tokens: Number(reserves.reserveOneDecimal)
}
};
} catch (error) {
console.error('Error analyzing liquidity:', error);
throw error;
}
}
### Implementation Notes
**Number Formats**
reserveOne and reserveTwo are provided in base units (smallest denomination)
reserveOneBN and reserveTwoBN are provided as BigNumber strings for precise calculations
reserveOneDecimal and reserveTwoDecimal are provided in human-readable decimal format
**Precision Handling**
Use the BigNumber (BN) versions for calculations to avoid floating-point precision issues
The decimal versions are provided for display purposes
SOL amounts are in lamports (1 SOL = 1,000,000,000 lamports)
**Common Calculations**
// Price calculation
const price = Number(reserves.reserveTwoDecimal) / Number(reserves.reserveOneDecimal);
// Impact of buying tokens
function calculateBuyImpact(buyAmount: number, reserves: ReservesResponse) {
const k = Number(reserves.reserveOneDecimal) \* Number(reserves.reserveTwoDecimal);
const newTokenReserve = Number(reserves.reserveOneDecimal) - buyAmount;
const newSolReserve = k / newTokenReserve;
const solNeeded = newSolReserve - Number(reserves.reserveTwoDecimal);
return solNeeded;
}
**Error Handling**
Always check if the token exists before attempting to get reserves
Handle network errors appropriately
Consider implementing retry logic for temporary failures
## **Best Practices**
**Caching**
Consider caching the reserves data for short periods (e.g., 5-10 seconds)
Implement cache invalidation on relevant transactions
**Rate Limiting**
Implement reasonable rate limiting when polling for reserve updates
Consider using WebSocket connections for real-time updates instead of polling
**Price Impact**
Use reserves data to calculate price impact before executing trades
Consider slippage tolerance in calculations