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
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(
`https://api.cybers.app/api/v1/coin/reserves?token=${tokenMintAddress}`
);
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
Last updated