Building Apps with ChainSocial
ChainSocial provides three integration paths. Choose based on your use case.
Decision Guide
| I want to… | Use |
|---|---|
| Build a client-side app that writes to the chain | SDK |
| Build a server that reads social data | API |
| Build a bot that posts automatically | SDK |
| Build another smart contract that interacts with ChainSocial | Direct contracts |
| Quickly prototype without a wallet connection | API (read-only) |
Integration Options
TypeScript SDK
Best for: Client apps, bots, scripts, anything that needs to write on-chain
The SDK wraps viem to provide typed methods for all ChainSocial operations.
import { createChainSocialClient } from '@chainsocial/client'
const client = createChainSocialClient({
worldAddress: '0x7405fCbEc24C00278b7e821Ace222f5CFfa6c6eA',
publicClient,
walletClient
})
// Create a post
await client.post.createInlinePost('Hello world!')
// Follow a user
await client.follow.follow('0x...')
// Send a DM
await client.directMessage.sendInlineMessage('0x...', 'Hey!')Pros:
- Full type safety
- Direct contract interaction (no middleman)
- Supports all write operations
- Works client-side and server-side
Cons:
- Requires wallet connection for writes
- Each write costs gas
Complete guide to all SDK systems with examples.
REST API
Best for: Server-side reads, aggregated feeds, search, when you don’t need wallet signing
The API provides indexed data from the chain, optimized for fast reads.
# Get the global feed
curl https://api.chainsocial.cc/api/feed?limit=20
# Get a user's profile
curl https://api.chainsocial.cc/api/profiles/0x...
# Search posts
curl https://api.chainsocial.cc/api/search?q=ethereumPros:
- Fast reads (indexed data)
- No wallet needed
- Pagination, filtering, search
- Lower latency than RPC calls
Cons:
- Read-only (cannot write to chain)
- Depends on indexer being in sync
- Slight delay (indexer lag)
Full documentation for all REST endpoints.
Direct Contract Calls
Best for: Smart contracts, advanced customization, when you need raw control
Call the World contract directly using any Ethereum library.
import { IWorld } from "@chainsocial/contracts/src/codegen/world/IWorld.sol";
contract MyApp {
IWorld public world;
function createPost(bytes32 contentId) external {
world.chainsocial__createPost(contentId, 0); // PUBLIC visibility
}
}Pros:
- Maximum control
- Can compose with other contracts
- No SDK dependencies
Cons:
- No type safety (unless using generated interfaces)
- Must handle content storage yourself
- More complex error handling
Understand the MUD architecture and system interfaces.
Common Patterns
Read from API, Write with SDK
The most common pattern combines both:
// Use API for fast reads
const feed = await fetch('https://api.chainsocial.cc/api/feed').then(r => r.json())
// Use SDK for writes
await client.post.createInlinePost('My response!')This gives you:
- Fast, indexed reads from the API
- Direct on-chain writes via SDK
- No unnecessary RPC calls
Optimistic Updates
For snappy UX, update the UI before the transaction confirms:
function PostButton({ onPost }) {
const client = useChainSocialClient()
const handlePost = async (text: string) => {
// Optimistically add to UI
onPost({ text, pending: true })
try {
const result = await client.post.createInlinePost(text)
// Update with real post ID
onPost({ text, postId: result.postId, pending: false })
} catch (error) {
// Remove on failure
onPost(null)
}
}
}Polling vs Events
The API doesn’t support WebSockets yet. For real-time updates:
// Poll for new posts
useEffect(() => {
const interval = setInterval(async () => {
const feed = await fetch('/api/feed?limit=10').then(r => r.json())
setItems(feed.items)
}, 10000) // Every 10 seconds
return () => clearInterval(interval)
}, [])