Coin Queries
The Coins SDK provides several query functions to fetch information about specific coins. This page details the available coin query functions, their parameters, and includes usage examples.
Available Queries
getCoin
The getCoin
function retrieves detailed information about a specific coin, including its metadata, market data, and creator information.
Parameters
type GetCoinParams = {
address: string; // The coin contract address
chain?: number; // Optional: The chain ID (defaults to Base: 8453)
};
Usage Example
import { getCoin } from "@zoralabs/coins-sdk";
async function fetchSingleCoin() {
const response = await getCoin({
address: "0xCoinContractAddress",
chain: 8453, // Optional: Base chain
});
const coin = response.data?.zora20Token;
if (coin) {
console.log("Coin Details:");
console.log("- Name:", coin.name);
console.log("- Symbol:", coin.symbol);
console.log("- Description:", coin.description);
console.log("- Total Supply:", coin.totalSupply);
console.log("- Market Cap:", coin.marketCap);
console.log("- 24h Volume:", coin.volume24h);
console.log("- Creator:", coin.creatorAddress);
console.log("- Created At:", coin.createdAt);
console.log("- Unique Holders:", coin.uniqueHolders);
// Access media if available
if (coin.media?.previewImage) {
console.log("- Preview Image:", coin.media.previewImage);
}
}
return response;
}
Response Structure
The response includes a data
object containing a zora20Token
object with the following properties:
type Zora20Token = {
zora20Token?: {
id?: string; // Unique identifier
name?: string; // Coin name
description?: string; // Coin description
address?: string; // Contract address
symbol?: string; // Trading symbol
totalSupply?: string; // Total supply (as string)
totalVolume?: string; // All-time volume
volume24h?: string; // 24-hour volume
createdAt?: string; // Creation timestamp
creatorAddress?: string; // Creator's address
creatorEarnings?: Array<{ // Creator earnings data
amount?: {
currency?: { address?: string };
amountRaw?: string;
amountDecimal?: number;
};
amountUsd?: string;
}>;
marketCap?: string; // Current market cap
marketCapDelta24h?: string; // 24-hour market cap change
chainId?: number; // The chain ID
creatorProfile?: string; // Creator's profile handle
handle?: string; // Coin handle (if available)
avatar?: { // Avatar image data
previewImage?: string;
blurhash?: string;
small?: string;
};
media?: { // Media associated with the coin
mimeType?: string;
originalUri?: string;
format?: string;
previewImage?: string;
medium?: string;
blurhash?: string;
};
transfers?: { count?: number }; // Transfer count
uniqueHolders?: number; // Number of unique holders
}
}
getCoins
The getCoins
function retrieves information about multiple coins at once, useful for batch processing or displaying multiple coins.
Parameters
type GetCoinsParams = {
coinAddresses: string[]; // Array of coin contract addresses
chainId?: number; // Optional: The chain ID (defaults to Base: 8453)
};
Usage Example
import { getCoins } from "@zoralabs/coins-sdk";
import { base } from "viem/chains";
async function fetchMultipleCoins() {
const response = await getCoins({
coinAddresses: [
"0xFirstCoinAddress",
"0xSecondCoinAddress",
"0xThirdCoinAddress"
],
chainId: base.id, // Optional: Base chain
});
// Process each coin in the response
response.data?.zora20Tokens?.forEach((coin: any, index: number) => {
console.log(`Coin ${index + 1}: ${coin.name} (${coin.symbol})`);
console.log(`- Market Cap: ${coin.marketCap}`);
console.log(`- 24h Volume: ${coin.volume24h}`);
console.log(`- Holders: ${coin.uniqueHolders}`);
console.log('-----------------------------------');
});
return response;
}
Response Structure
The response includes a zora20Tokens
array containing objects with the same structure as the zora20Token
object in the getCoin
response.
getCoinComments
The getCoinComments
function retrieves comments associated with a specific coin, useful for displaying community engagement.
Parameters
type GetCoinCommentsParams = {
address: string; // The coin contract address
chain?: number; // Optional: The chain ID (defaults to Base: 8453)
after?: string; // Optional: Pagination cursor for fetching next page
count?: number; // Optional: Number of comments to return per page
};
Usage Example
import { getCoinComments } from "@zoralabs/coins-sdk";
import { Address } from "viem";
async function fetchCoinComments() {
const response = await getCoinComments({
address: "0xCoinContractAddress" as Address,
chain: 8453, // Optional: Base chain
after: undefined, // Optional: for pagination
count: 20, // Optional: number of comments per page
});
// ^?
// Process comments
console.log(`Found ${response.data?.zora20Token?.zoraComments?.edges?.length || 0} comments`);
response.data?.zora20Token?.zoraComments?.edges?.forEach((edge: any, index: number) => {
console.log(`Comment ${index + 1}:`);
console.log(`- Author: ${edge.node.author?.handle || edge.node.author?.address}`);
console.log(`- Text: ${edge.node.text}`);
console.log(`- Created At: ${edge.node.createdAt}`);
// Check for reactions if available
if (edge.node.reactions && edge.node.reactions.length > 0) {
console.log(`- Reactions: ${edge.node.reactions.length}`);
edge.node.reactions.forEach(reaction => {
console.log(` - ${reaction.type}: ${reaction.count}`);
});
}
console.log('-----------------------------------');
});
// For pagination
if (response.data?.zora20Token?.zoraComments?.pageInfo?.endCursor) {
console.log("Next page cursor:", response.data?.zora20Token?.zoraComments?.pageInfo?.endCursor);
}
return response;
}
Paginating Through All Comments
To fetch all comments for a coin, you can use pagination:
import { getCoinComments } from "@zoralabs/coins-sdk";
async function fetchAllCoinComments(coinAddress: string) {
let allComments: any[] = [];
let cursor = undefined;
const pageSize = 20;
// Continue fetching until no more pages
do {
const response = await getCoinComments({
address: coinAddress,
count: pageSize,
after: cursor,
});
// Add comments to our collection
if (response.data?.zora20Token?.zoraComments?.edges && response.data?.zora20Token?.zoraComments?.edges.length > 0) {
allComments = [...allComments, ...response.data?.zora20Token?.zoraComments?.edges];
}
// Update cursor for next page
cursor = response.data?.zora20Token?.zoraComments?.pageInfo?.endCursor;
// Break if no more results
if (!cursor || response.data?.zora20Token?.zoraComments?.edges?.length === 0) {
break;
}
} while (true);
console.log(`Fetched ${allComments.length} total comments`);
return allComments;
}
Response Structure
The response includes a comments
array and pagination information:
type CommentsResponse = {
comments?: Array<{
id?: string; // Comment ID
text?: string; // Comment text
createdAt?: string; // Creation timestamp
updatedAt?: string; // Last update timestamp
author?: { // Author information
address?: string; // Author's wallet address
handle?: string; // Author's handle/username
displayName?: string; // Author's display name
profileImage?: { // Author's profile image
previewImage?: string;
small?: string;
blurhash?: string;
};
};
reactions?: Array<{ // Reactions to the comment
type?: string; // Reaction type
count?: number; // Reaction count
}>;
}>;
pagination?: {
cursor?: string; // Cursor for the next page
};
}
Error Handling
All query functions follow the same error handling pattern. When an error occurs, the promise is rejected with an error object that includes details about what went wrong.
import { Address } from "viem";
import { getCoin } from "@zoralabs/coins-sdk";
try {
const response = await getCoin({ address: "0xCoinAddress" as Address });
// Process response...
} catch (error: any) {
if (error.status === 404) {
console.error("Coin not found");
} else if (error.status === 401) {
console.error("API key invalid or missing");
} else {
console.error("Unexpected error:", error.message);
}
}
Best Practices
- Cache Results: Consider caching query results to reduce API calls and improve performance.
- Use Batch Queries: When fetching data for multiple coins, use
getCoins
instead of multiplegetCoin
calls. - Implement Pagination: For
getCoinComments
, always implement pagination to handle potentially large datasets. - Handle Missing Data: Always check for the existence of fields before accessing them, as some fields may be undefined.
- Error Handling: Implement robust error handling for all API queries to provide a good user experience.