Paragraph Skill

intent

this skill gives you full programmatic access to Paragraph.com's Web3-native blogging API. use it to automate content publishing workflows, manage subscribers at scale, track tokenized engagement, and integrate onchain posts into larger systems. build automated research publishing pipelines, token-gated newsletters, cross-platform syndication, or personal content archives without touching the Paragraph UI.

inputs

environment variables

all required unless noted:

name	description	required	example
PARAGRAPH_API_KEY	API authentication key from Paragraph account settings → integrations	yes	pk_live_xxxxxxxx
PARAGRAPH_PUBLICATION_SLUG	publication slug (URL-friendly name) for your blog	yes	myblog or jonathancolton.eth
PARAGRAPH_PUBLICATION_ID	publication ID as fallback (not recommended; slug is preferred)	no	pub_123abc
PARAGRAPH_API_BASE_URL	custom API endpoint for testing or self-hosted instances	no	https://api.paragraph.local

external connections

• Paragraph API (https://api.paragraph.com): requires valid PARAGRAPH_API_KEY with scope to read/write posts, subscribers, publications, and coins. keys expire or can be revoked; always validate with paragraph_testConnection before production workflows.

edge cases to handle

• api key invalid, expired, or revoked: tool returns 401 error
• publication slug not found: verify via dashboard or call paragraph_getMyPublication to auto-discover
• rate limits: paragraph applies per-key limits; implement exponential backoff (1s, 2s, 4s, 8s) on 429 responses
• network timeout: retry with jitter for transient failures
• onchain delays: when waitForProcessing: false, post slug may be undefined for seconds to minutes while transaction confirms; poll or set waitForProcessing: true to block
• csv import: file must be utf-8 text, headers must be exactly email,wallet,tags; duplicates are silently skipped by Paragraph
• empty result sets: list tools return empty arrays, not null; check .length before iterating
• subscriber count: returns aggregate only; individual subscriber details require separate calls

procedure

1. validate connection

input: none (uses PARAGRAPH_API_KEY from environment)

call paragraph_testConnection(). this makes a lightweight authenticated request to verify the api key is valid and the Paragraph service is reachable.

output: { success: true } or { success: false, error: "reason" }

decision: if success is false, stop and fix PARAGRAPH_API_KEY or network connectivity before proceeding.

2. discover or verify publication

input: none (uses PARAGRAPH_PUBLICATION_SLUG or PARAGRAPH_PUBLICATION_ID from environment)

call paragraph_getMyPublication() to fetch the authenticated user's primary publication. this auto-discovers publication ID, name, domain, subscriber count, and other metadata. no parameters needed.

output: publication object with fields: id, name, slug, domain, subscriberCount, description, avatar, settings

decision: if you don't have PARAGRAPH_PUBLICATION_SLUG set, this call returns the default. if you need a specific publication (multi-publication account), pass publicationId explicitly to subsequent calls.

3. create a post

input:

• title (string, required): post title
• markdown (string, required): post body in markdown (supports images, embeds, code blocks)
• categories (array of strings, optional): tags for discoverability (e.g., ["web3", "blockchain"])
• sendNewsletter (boolean, optional, default false): notify subscribers immediately
• waitForProcessing (boolean, optional, default false): block until onchain confirmation and slug is assigned

call paragraph_createPost({ title, markdown, categories, sendNewsletter, waitForProcessing }). Paragraph publishes the post onchain immediately.

output: post object with id, title, slug (may be undefined if waitForProcessing: false), url, content, createdAt, coinId (if post has a coin)

decision: if waitForProcessing: false and you need the slug immediately, poll paragraph_getPost with the returned id every 2-3 seconds until slug appears (usually within 10-30 seconds). if waitForProcessing: true, the call blocks but guarantees slug is present on return.

4. retrieve a post by id

input: postId (string): internal post identifier

call paragraph_getPost({ postId }). returns full post data including metadata and onchain transaction details.

output: post object as above

edge case: if post does not exist, Paragraph returns a 404 error.

5. retrieve a post by slug

input: slug (string): human-readable post identifier from URL

call paragraph_getPostBySlug({ slug }). useful for fetching a post when you only have the public-facing slug.

output: post object as above

edge case: if slug does not exist or is still pending onchain confirmation, returns 404. use this to poll when waiting for onchain processing to complete.

6. list posts in publication

input:

• limit (number, optional, default 10): max posts to return
• offset (number, optional, default 0): pagination offset
• includeContent (boolean, optional, default false): fetch full markdown or just metadata

call paragraph_listPosts({ limit, offset, includeContent }). auto-discovers publication ID from environment.

output: array of post objects (abbreviated if includeContent: false)

edge case: if publication has zero posts, returns empty array. if limit exceeds API max, Paragraph caps silently.

7. get publication metadata

input: publicationSlug (string) or publicationId (string)

call paragraph_getPublication({ publicationSlug }) or paragraph_getPublicationByDomain({ domain }) to fetch a publication by its domain (e.g., myblog.paragraph.eth).

output: publication object with id, name, slug, description, avatar, subscriberCount, settings

edge case: if slug or domain does not exist, returns 404.

8. add a subscriber

input:

• email (string, optional): subscriber email
• walletAddress (string, optional): eth wallet address
• tags (array of strings, optional): labels for segmentation (e.g., ["premium", "nft-holder"])

call paragraph_addSubscriber({ email, walletAddress, tags }). at least one of email or wallet must be provided.

output: subscriber object with id, email, wallet, tags, subscribedAt

edge case: if email or wallet already subscribed, returns the existing subscriber (idempotent). if neither email nor wallet provided, returns validation error.

9. list subscribers

input:

• limit (number, optional, default 100): max subscribers to return
• offset (number, optional, default 0): pagination offset
• tag (string, optional): filter to subscribers with a specific tag

call paragraph_listSubscribers({ limit, offset, tag }). auto-discovers publication ID from environment.

output: array of subscriber objects

edge case: if publication has zero subscribers, returns empty array. if tag does not exist, returns empty array. pagination is required for large lists.

10. import subscribers from csv

input:

• csvData (string or buffer): utf-8 encoded csv file with headers email,wallet,tags
• tags (array of strings, optional): additional tags to apply to all imported subscribers

call paragraph_importSubscribers({ csvData, tags }). bulk-loads subscribers from csv, ideal for migrations from substack, ghost, or internal lists.

output: import result object with imported (count), skipped (count), errors (array of row numbers with issues)

csv format:

email,wallet,tags
alice@example.com,,newsletter
bob@example.com,0x123...,nft-holder,premium

edge case: if csv is invalid (bad encoding, missing headers, binary), returns 400 error. if row is missing both email and wallet, that row is skipped. if email/wallet is duplicate, Paragraph silently merges with existing subscriber.

11. get subscriber count

input: none (uses publication from environment)

call paragraph_getSubscriberCount(). lightweight call to fetch aggregate subscriber count.

output: object with count (number)

12. fetch the global feed

input:

• limit (number, optional, default 10): posts to return
• offset (number, optional, default 0): pagination offset

call paragraph_getFeed({ limit, offset }). returns trending/recent posts across the Paragraph platform.

output: array of post objects

edge case: empty if no posts exist on platform (unlikely).

13. fetch posts by tag

input:

• tag (string): tag name
• limit (number, optional, default 10): posts to return
• offset (number, optional, default 0): pagination offset

call paragraph_getPostsByTag({ tag, limit, offset }). filters platform posts by a single tag.

output: array of post objects

edge case: if tag does not exist, returns empty array.

14. get coin (token) details

input: coinId (string): internal coin identifier

call paragraph_getCoin({ coinId }). returns supply, price, holder count, and metadata for a post's social token.

output: coin object with id, name, symbol, supply, price, holderCount, contractAddress, postId

edge case: if coin does not exist or post has no coin, returns 404.

15. get coin by contract address

input: contractAddress (string): ethereum contract address

call paragraph_getCoinByContract({ contractAddress }). resolves a coin from its on-chain contract.

output: coin object as above

edge case: if contract not found on Paragraph, returns 404.

16. list popular coins

input:

• limit (number, optional, default 10): coins to return
• offset (number, optional, default 0): pagination offset

call paragraph_getPopularCoins({ limit, offset }). returns trending coins by volume or holder growth.

output: array of coin objects

17. list coin holders

input:

• coinId (string): coin identifier
• limit (number, optional, default 100): holders to return
• offset (number, optional, default 0): pagination offset

call paragraph_listCoinHolders({ coinId, limit, offset }). useful for airdrops, community analysis, or reward distribution.

output: array of holder objects with wallet, balance, percentage (of supply)

edge case: if coin has no holders, returns empty array. large holder lists require pagination.

18. get user profile

input: userId (string): internal user identifier

call paragraph_getUser({ userId }). returns user profile, wallet, publications, and follower count.

output: user object with id, name, wallet, avatar, bio, followingCount, followerCount, publications

edge case: if user does not exist, returns 404.

19. get user by wallet address

input: walletAddress (string): eth address

call paragraph_getUserByWallet({ walletAddress }). reverse-lookup a user by their connected wallet.

output: user object as above

edge case: if wallet not connected to any Paragraph account, returns 404.

decision points

if api key is invalid or missing: paragraph_testConnection() returns success: false. stop all subsequent calls, correct PARAGRAPH_API_KEY environment variable, and validate again before proceeding.

if publication slug is not set: you have two options: (a) set PARAGRAPH_PUBLICATION_SLUG in environment and restart agent, or (b) call paragraph_getMyPublication() without parameters to auto-discover the primary publication ID, then use that ID in subsequent calls.

if you need to create a post and want the slug immediately: set waitForProcessing: true to block until onchain confirmation. if you want fast response and don't need slug right away, use default waitForProcessing: false and poll paragraph_getPostBySlug every 2-3 seconds (max wait time 30-60 seconds typically).

if you hit a 429 rate limit error: implement exponential backoff (wait 1s, retry; if still 429, wait 2s, retry; if still 429, wait 4s, retry; if still 429, wait 8s and give up). alternatively, batch operations (e.g., import csv subscribers instead of individual adds) or cache frequently accessed data.

if csv import returns errors: check the errors array in the response; it contains row numbers that failed. common reasons: missing both email and wallet in a row, malformed tags, or non-utf-8 encoding. fix the file and retry.

if a post returns slug undefined and you used waitForProcessing: false: don't assume it failed. the post exists (you have the id) but the onchain transaction hasn't confirmed yet. poll paragraph_getPostBySlug with the id every 2-3 seconds until slug appears, or call with waitForProcessing: true next time for blocking confirmation.

if you need to "edit" a post: Paragraph API does not support PUT/PATCH operations. workaround: delete the post (if you have that tool) and recreate it, or create a new post and reference the old one. slug preservation during recreation depends on Paragraph's internal rules (usually possible if you use the same title).

if subscriber list returns empty but you expect subscribers: verify the publication ID is correct (call paragraph_getMyPublication() to confirm) and check the tag filter if you provided one. also check paragraph_getSubscriberCount() to see if count is nonzero (list might be paginated).

if you're importing subscribers and some rows are skipped: Paragraph silently skips rows with both email and wallet missing, or rows with duplicate email/wallet. this is not an error; check the skipped count in the import result.

output contract

all tools return a standardized response object:

{
  "success": true|false,
  "data": { /* tool-specific data */ },
  "error": "human-readable error message (only if success: false)"
}

post object

{
  "id": "post_123abc",
  "title": "My Web3 Blog Post",
  "slug": "my-web3-blog-post",
  "url": "https://myblog.paragraph.eth/my-web3-blog-post",
  "content": "# Hello\n\nThis is my first post...",
  "createdAt": "2024-03-10T12:00:00Z",
  "publishedAt": "2024-03-10T12:00:00Z",
  "categories": ["web3", "blockchain"],
  "coinId": "coin_456def",
  "transactionHash": "0x789..."
}

subscriber object

{
  "id": "sub_123abc",
  "email": "alice@example.com",
  "wallet": "0x123...",
  "tags": ["newsletter", "premium"],
  "subscribedAt": "2024-03-10T12:00:00Z",
  "unsubscribedAt": null
}

coin object

{
  "id": "coin_123abc",
  "name": "Alice's Insights",
  "symbol": "ALICE",
  "supply": "1000000",
  "price": "0.05",
  "holderCount": 245,
  "contractAddress": "0x789...",
  "postId": "post_456def"
}

publication object

{
  "id": "pub_123abc",
  "name": "My Blog",
  "slug": "myblog",
  "domain": "myblog.paragraph.eth",
  "description": "thoughts on web3",
  "avatar": "https://...",
  "subscriberCount": 1250,
  "settings": { /* nested config */ }
}

user object

{
  "id": "user_123abc",
  "name": "Alice",
  "wallet": "0x123...",
  "avatar": "https://...",
  "bio": "Web3 researcher",
  "followingCount": 50,
  "followerCount": 120,
  "publications": [ /* array of publication objects */ ]
}

import result object

{
  "imported": 45,
  "skipped": 2,
  "errors": [
    { "row": 12, "reason": "missing email and wallet" },
    { "row": 23, "reason": "duplicate email" }
  ]
}

all numeric fields (supply, price, counts) are returned as strings or numbers depending on precision; always coerce to number if arithmetic is needed.

outcome signal

success criteria:

1. connection validated: paragraph_testConnection() returns { success: true }
2. publication discovered: paragraph_getMyPublication() returns publication object with non-empty id and slug
3. post created: paragraph_createPost(...) returns post object with non-empty id; slug may be undefined if using waitForProcessing: false, but will appear within 30 seconds
4. post retrievable: after creation, paragraph_getPostBySlug() or paragraph_getPost() returns the same post with full metadata
5. subscriber added: paragraph_addSubscriber(...) returns subscriber object with the provided email/wallet and tags
6. list operations return results: paragraph_listPosts(), paragraph_listSubscribers(), etc. return arrays (may be empty if no data, but not null or error)
7. coin data accessible: paragraph_getCoin() or paragraph_getCoinByContract() returns coin object with supply and holder count
8. csv import completes: paragraph_importSubscribers() returns result object with nonzero imported count and errors array present (even if empty)
9. no rate limit blocking: if you hit 429, implementing exponential backoff allows the call to eventually succeed (or you decide to abort gracefully)
10. feed and user discovery work: paragraph_getFeed(), paragraph_getPostsByTag(), paragraph_getUser(), etc. all return expected data structures

if any tool returns success: false, check the error message for diagnostic info. common errors:

• Not logged in → invalid or expired PARAGRAPH_API_KEY
• Publication not found → wrong PARAGRAPH_PUBLICATION_SLUG or missing env var
• Rate limit exceeded → back off exponentially
• Onchain processing pending → slug not yet available; poll or wait and retry
• Not found (404) → post/user/coin does not exist; verify id/slug/address