Posts

🚧

Coming Soon — The ChainSocial SDK is not yet published. This documentation describes the planned API. Use the REST API for current integrations.

Posts are the core content unit in ChainSocial. This guide covers creating, reading, and interacting with posts.

Creating Posts

Inline Posts (Simplest)

For text content up to 4KB, use inline posts. The text is stored directly on-chain in a single transaction.


const result = await client.post.createInlinePost('Hello, ChainSocial!')
 
console.log('Transaction:', result.hash)
console.log('Post ID:', result.postId)

With Visibility

Control who can see your post:


import { PostVisibility } from '@chainsocial/client'
 
// Public (default) - visible to everyone
await client.post.createInlinePost('Public post', PostVisibility.PUBLIC)
 
// Followers only
await client.post.createInlinePost('For followers', PostVisibility.FOLLOWERS)
 
// Private (only you)
await client.post.createInlinePost('Private note', PostVisibility.PRIVATE)

With Content IDs (For Large/IPFS Content)

For larger content or media, first create the content, then reference it:


// Create content first
const contentId = await client.content.createIpfsContent(
  'bafkrei...',  // IPFS CID
  'text/plain',
  1024  // size in bytes
)
 
// Then create post referencing the content
const result = await client.post.createPost(contentId, PostVisibility.PUBLIC)

Replies

Create a threaded reply to an existing post:


// Inline reply (text stored on-chain)
const result = await client.post.createInlineReply(
  'Great point!',
  parentPostId  // bytes32 post ID
)
 
// Or with content ID
const result = await client.post.createReply(contentId, parentPostId)

Quote Posts

Quote another post with your commentary:


// Inline quote
const result = await client.post.createInlineQuote(
  'This is so true',
  quotedPostId
)
 
// Or with content ID
const result = await client.post.createQuote(contentId, quotedPostId)

Attachments

Add media or additional content to posts:


// Create post with attachments in one transaction
const attachmentIds = [imageContentId, videoContentId]
const result = await client.post.createPostWithAttachments(
  contentId,
  PostVisibility.PUBLIC,
  attachmentIds
)
 
// Or add attachment to existing post
await client.post.addAttachment(postId, imageContentId)

Batch Operations

Create multiple posts efficiently:


// Create up to 50 posts in one transaction
const contentIds = ['0x...', '0x...', '0x...']
const result = await client.post.createPostBatch(contentIds, PostVisibility.PUBLIC)
 
console.log('Created posts:', result.postIds)

Editing Posts

Update a post’s content:


const newContentId = await client.content.createInlineContent('Updated text')
await client.post.editPost(postId, newContentId)

Edited posts retain their original ID and timestamp, but the content changes. The isEdited flag will be true.

Deleting Posts


await client.post.deletePost(postId)

Deleted posts:

Are marked with isDeleted: true
Still exist on-chain (blockchain is immutable)
Won’t appear in feeds/search

Hashtags

Add hashtags to posts for discovery:


// Add hashtag (without the # symbol)
await client.post.addHashtagToPost(postId, 'web3')
await client.post.addHashtagToPost(postId, 'onchain')
 
// Remove hashtag
await client.post.removeHashtagFromPost(postId, 'web3')
 
// Get hashtag stats
const info = await client.post.getHashtagInfo('web3')
console.log('Post count:', info.postCount)
console.log('First used:', info.firstUsedAt)

Fees

Some networks may require fees to create posts. Check the fee configuration:


const config = await client.post.getFeeConfig()
 
console.log('Post fee:', config.postFee)      // in wei
console.log('Reply fee:', config.replyFee)
console.log('Quote fee:', config.quoteFee)
console.log('Fee token:', config.feeToken)    // address(0) = ETH
console.log('Fees enabled:', config.isEnabled)
 
// Calculate batch fee
const batchFee = await client.post.calculateBatchPostFee(10)

Paying Fees

If fees are enabled, pass the value:


const feeConfig = await client.post.getFeeConfig()
 
if (feeConfig.isEnabled) {
  await client.post.createInlinePost('Hello!', PostVisibility.PUBLIC, feeConfig.postFee)
}

Reading Posts

From the API (Recommended)


// Get a single post
const post = await fetch(`https://api.chainsocial.cc/api/posts/${postId}`).then(r => r.json())
 
// Get user's posts
const posts = await fetch(`https://api.chainsocial.cc/api/users/${address}/posts`).then(r => r.json())
 
// Get global feed
const feed = await fetch('https://api.chainsocial.cc/api/feed?limit=20').then(r => r.json())
 
// Get post replies
const replies = await fetch(`https://api.chainsocial.cc/api/posts/${postId}/replies`).then(r => r.json())

API Response Structure


{
  "post": {
    "postId": "0x...",
    "author": "0x...",
    "contentId": "0x...",
    "content": "Hello, ChainSocial!",
    "visibility": "PUBLIC",
    "createdAt": 1704067200,
    "editedAt": null,
    "replyTo": null,
    "quoteOf": null,
    "isDeleted": false,
    "isEdited": false
  },
  "author": {
    "address": "0x...",
    "username": "alice",
    "metadata": {
      "displayName": "Alice",
      "avatar": { "uri": "ipfs://..." }
    }
  }
}

Reactions

Users can react to posts (e.g., likes):


import { ReactionType } from '@chainsocial/client'
 
// Add a like
await client.reaction.addReaction(postId, ReactionType.LIKE)
 
// Remove reaction
await client.reaction.removeReaction(postId, ReactionType.LIKE)

Reading Reactions (API)


const reactions = await fetch(`https://api.chainsocial.cc/api/posts/${postId}/reactions`)
  .then(r => r.json())
 
console.log('Like count:', reactions.likeCount)

Delegation: On-Behalf-Of

Create posts as a delegate for another user:


// Requires delegation permission
await client.post.createInlinePostOnBehalfOf(
  authorAddress,  // Who the post appears from
  'Posted by my assistant',
  PostVisibility.PUBLIC
)

Complete Example


import { createChainSocialClient, PostVisibility, ReactionType } from '@chainsocial/client'
 
async function socialInteraction(client) {
  // Create a post
  const post = await client.post.createInlinePost(
    'Just shipped a new feature! #buildinpublic',
    PostVisibility.PUBLIC
  )
  console.log('Posted:', post.postId)
 
  // Add hashtag
  await client.post.addHashtagToPost(post.postId, 'buildinpublic')
 
  // Someone replies (different user)
  // const reply = await otherClient.post.createInlineReply('Nice work!', post.postId)
 
  // React to our own post (for demo)
  await client.reaction.addReaction(post.postId, ReactionType.LIKE)
 
  // Read back from API
  const feedResponse = await fetch('https://api.chainsocial.cc/api/feed?limit=1')
  const feed = await feedResponse.json()
  console.log('Latest post:', feed.items[0]?.post.content)
}

Next Steps

Social Graph — Follow users, build relationships
Messaging — Send direct messages