> 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
---
# 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/get-reserves.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.