# 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](https://github.com/paragraph-xyz/paragraph-sdk-js/blob/main/openapi.json), in the repository on [GitHub](https://github.com/paragraph-xyz/paragraph-sdk-js), and in the documentation on [npm](https://www.npmjs.com/package/@paragraph-com/sdk).

**Prerequisites**: Node.js version 18 or higher.

## [Getting started](https://docs.paragraph.com/developers/sdk#getting-started)

### [Install the SDK](https://docs.paragraph.com/developers/sdk#install-the-sdk)

```
npm i @paragraph-com/sdk
```

### [Instantiate the class](https://docs.paragraph.com/developers/sdk#instantiate-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](https://app.paragraph.com/) under **Settings -> Publication -> Developer**.

### [Query data](https://docs.paragraph.com/developers/sdk#query-data)

```javascript
// 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](https://docs.paragraph.com/developers/sdk#examples)

Practical examples for common use cases. Each one assumes you've installed and initialized the SDK as shown above.

### [Fetching paginated posts](https://docs.paragraph.com/developers/sdk#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](https://docs.paragraph.com/developers/sdk#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](https://docs.paragraph.com/developers/sdk#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](https://docs.paragraph.com/developers/sdk#next-steps)

- Browse the [OpenAPI spec](https://github.com/paragraph-xyz/paragraph-sdk-js/blob/main/openapi.json) for the full API surface.
- View the [SDK repository](https://github.com/paragraph-xyz/paragraph-sdk-js) for more examples.
- Check out the [npm package](https://www.npmjs.com/package/@paragraph-com/sdk) for version information.