TypeScript SDK
Install the Paragraph SDK and query publications, posts, coins, and user profiles with full type safety.
The Paragraph SDK is a TypeScript wrapper around our REST API. All functionality in the SDK is described in the OpenAPI spec, in the repository on GitHub, and in the documentation on npm.
Prerequisites: Node.js version 18 or higher.
Getting started
Install the SDK
npm i @paragraph-com/sdkInstantiate the class
Instantiate the ParagraphAPI class.
import { ParagraphAPI } from "@paragraph-com/sdk"
// For public endpoints (no API key required)
const api = new ParagraphAPI()
// For protected endpoints (API key required)
const apiWithAuth = new ParagraphAPI({ apiKey: "your-api-key" })You can generate an API key in the app at app.paragraph.com under Settings -> Publication -> Developer.
Query data
// Fetch a publication by slug (use .single() for single object)
const publication = await api.publications.get({ slug: "@blog" }).single()
console.log(`Fetched publication: ${publication}`)
// Fetch posts (paginated list)
const { items: posts, pagination } = await api.posts.get({ publicationId: publication.id })
console.log(`Fetched ${posts.length} posts from @blog, out of ${pagination.total} posts: ${JSON.stringify(posts)}`)Examples
Practical examples for common use cases. Each one assumes you've installed and initialized the SDK as shown above.
Fetching paginated posts
Retrieve posts from a publication with pagination support. This example demonstrates how to fetch multiple pages of posts using cursor-based pagination.
/**
* Given a Paragraph publication slug, fetch the first two
* pages of posts.
*/
async function fetchParagraphPosts(slug: string) {
const publication = await api.publications.get({ slug }).single()
console.log("Publication:", publication)
const posts = []
const firstBatch = await api.posts.get({ publicationId: publication.id })
posts.push(...firstBatch.items)
console.log("Posts:", firstBatch.items)
if (firstBatch.pagination.hasMore && firstBatch.pagination.cursor) {
const secondBatch = await api.posts.get({
publicationId: publication.id,
cursor: firstBatch.pagination.cursor
})
posts.push(...secondBatch.items)
}
console.log(`Last ${posts.length} posts from ${slug}, out of ${firstBatch.pagination.total} posts: ${JSON.stringify(firstBatch.items)}`)
}Working with coins and holders
Fetch coin information and holder data associated with a specific post. This example shows how to retrieve monetization details for content.
/**
* Given a publication & post slug, fetch coin & holders.
*/
async function fetchCoinFromPost(publicationSlug: string, postSlug: string) {
const publication = await api.publications.get({ slug: publicationSlug }).single()
const publicationId = publication.id
const post = await api.posts.get({
publicationId: publicationId,
slug: postSlug
}).single()
if (post.coinId) {
const [coin, holders] = await Promise.all([
api.coins.get({ id: post.coinId }).single(),
api.coins.getHolders({ id: post.coinId })
])
console.log("Fetched coin & holders from post:", coin, holders)
}
}User profile lookup
Retrieve user profile information by wallet address, including any associated Farcaster profiles.
/**
* Given a wallet address, fetch the user profile including
* any associated Farcaster profile.
*/
async function getUserProfileByWallet(walletAddress: string) {
const user = await api.users.get({ wallet: walletAddress }).single()
console.log("User profile:", user)
}Next steps
- Browse the OpenAPI spec for the full API surface.
- View the SDK repository for more examples.
- Check out the npm package for version information.