Data Specifications & API
Chainity provides a decentralized social data layer with on-chain events, IPFS content storage, and open APIs (REST & GraphQL).
1. Post Metadata
Posts are stored with references to IPFS CIDs. Metadata follows a standardized JSON schema.
{
"version": "1.0",
"author": "0xAuthor",
"cid": "ipfs://.../content",
"title": "string",
"tags": ["string"],
"createdAt": 1690000000,
"license": "CC-BY-NC-4.0",
"nsfw": false,
"media": [
{
"type": "image/png",
"cid": "ipfs://.../file"
}
],
"encrypted": false
}Fields:
version→ Schema version.author→ Wallet/DID of creator.cid→ IPFS link to main content.title,tags→ Content metadata.createdAt→ Unix timestamp.license→ License type (CC, custom, etc.).nsfw→ Boolean flag for sensitive content.media→ Array of attached files.encrypted→truefor gated/premium content.
2. Smart Contract Events
PostCreated(postId, author, cid) → When a post is published.
EngagementAdded(postId, user, kind, weight) → Engagement (like, comment, share).
RewardClaimed(user, amount, epoch) → When rewards are claimed.
NFTMinted(postId, tokenId, to) → Post is minted as NFT.
RoyaltyPaid(tokenId, to, amount) → Royalties sent to creator.
3. API Endpoints
3.1 Posts
REST: Get Post by ID
GET /api/v1/posts/{postId}
Response:
{
"postId": "12345",
"author": "0xAuthor",
"cid": "ipfs://bafy...content",
"title": "Hello Chainity",
"tags": ["socialfi", "dao"],
"createdAt": 1690000000,
"license": "CC-BY-NC-4.0",
"nsfw": false,
"media": [
{
"type": "image/png",
"cid": "ipfs://bafy...image"
}
],
"engagementStats": {
"likes": 120,
"comments": 45,
"shares": 30
},
"rewards": {
"pending": "50.00 CHN",
"claimed": "200.50 CHN"
}
}GraphQL: Get Posts by Author
query GetPostsByAuthor($author: String!) {
posts(author: $author, limit: 5, orderBy: createdAt_desc) {
postId
cid
title
tags
createdAt
license
nsfw
media { type cid }
engagementStats { likes comments shares }
rewards { totalEarned }
}
}3.2 Engagement
REST: Submit Engagement
POST /api/v1/engagements
Request Body:
{
"postId": "12345",
"user": "0xUser",
"kind": "like",
"weight": 1
}Response:
{
"status": "success",
"txHash": "0xabc123...",
"engagement": {
"postId": "12345",
"user": "0xUser",
"kind": "like",
"weight": 1,
"timestamp": 1690005000
}
}3.3 Rewards
REST: Check Reward Balance
GET /api/v1/rewards/{user}
Response:
{
"user": "0xUser",
"pending": "75.00 CHN",
"claimed": "320.50 CHN",
"lastClaimEpoch": "2025-Q4",
"nextClaimableEpoch": "2026-Q1"
}REST: Claim Rewards
POST /api/v1/rewards/claim
Request Body:
{
"user": "0xUser",
"epoch": "2026-Q1",
"signature": "0xsignedMessage"
}Response:
{
"status": "success",
"txHash": "0xdef456...",
"claimedAmount": "120.75 CHN",
"epoch": "2026-Q1",
"timestamp": 1690010000
}GraphQL: Claim Rewards
mutation ClaimRewards($user: String!, $epoch: String!, $signature: String!) {
claimRewards(user: $user, epoch: $epoch, signature: $signature) {
txHash
claimedAmount
epoch
timestamp
}
}4. NFT API (Posts as NFTs)
Chainity lets creators tokenize posts as NFTs for provenance and monetization. NFTs reference the post CID and inherit license data from post metadata.
4.1 Data Model
NFT Metadata (JSON stored on IPFS):
{
"name": "Post #12345 — Hello Chainity",
"description": "Original post by 0xAuthor on Chainity",
"image": "ipfs://.../cover.png",
"external_url": "https://app.chainity.xyz/post/12345",
"attributes": [
{"trait_type": "PostID", "value": "12345"},
{"trait_type": "License", "value": "CC-BY-NC-4.0"},
{"trait_type": "NSFW", "value": false}
],
"chainity": {
"postCid": "ipfs://.../content",
"author": "0xAuthor",
"createdAt": 1690000000
}
}4.2 Smart Contract Events (NFT)
NFTMinted(postId, tokenId, to) — Emitted when a post is minted.
RoyaltyPaid(tokenId, to, amount) — Emitted on secondary sales royalty payout.
LicenseUpdated(tokenId, license) — Emitted if license metadata is updated (if allowed by policy).
NFTRedeemed(tokenId, by, right) — Optional: for gated-access redemption/auditing.
Royalty calculation can follow common royalty interfaces (e.g., an ERC-2981-style
royaltyInfo(tokenId, salePrice)method).
4.3 REST Endpoints
Mint an NFT from a Post
POST /api/v1/nfts/mint
Request:
{
"postId": "12345",
"to": "0xCreatorWallet",
"supply": 1,
"royaltyBps": 500,
"license": "CC-BY-NC-4.0",
"signature": "0xsignedMessage"
}Response:
{
"status": "queued",
"txHash": "0xmint123...",
"tokenId": "10001",
"contract": "0xNFTContract"
}Get NFT by Token ID
GET /api/v1/nfts/{tokenId}
Response:
{
"tokenId": "10001",
"contract": "0xNFTContract",
"owner": "0xCreatorWallet",
"postId": "12345",
"postCid": "ipfs://.../content",
"metadataCid": "ipfs://.../metadata.json",
"license": "CC-BY-NC-4.0",
"royaltyBps": 500,
"mintTx": "0xmint123...",
"createdAt": 1690001000
}List NFTs by Creator
GET /api/v1/nfts?creator=0xAuthor&limit=20&cursor=...
Response:
{
"items": [
{"tokenId": "10001", "postId": "12345", "owner": "0xAuthor", "royaltyBps": 500},
{"tokenId": "10022", "postId": "12410", "owner": "0xAuthor", "royaltyBps": 700}
],
"nextCursor": "eyJwYWdlIjoyfQ=="
}Transfer NFT
POST /api/v1/nfts/transfer
Request:
{
"tokenId": "10001",
"from": "0xSender",
"to": "0xReceiver",
"signature": "0xsignedMessage"
}Response:
{
"status": "success",
"txHash": "0xtransferabc...",
"tokenId": "10001",
"from": "0xSender",
"to": "0xReceiver",
"timestamp": 1690007000
}Record a Secondary Sale (for indexing/royalty reporting)
POST /api/v1/nfts/sales
Request:
{
"tokenId": "10001",
"market": "0xMarketplace",
"buyer": "0xBuyer",
"seller": "0xSeller",
"price": "250.00 CHN",
"txHash": "0xsale777..."
}Response:
{
"status": "success",
"txHash": "0xsale777...",
"royalty": {
"to": "0xAuthor",
"amount": "12.50 CHN",
"bps": 500
}
}Get Royalty & Sales History
GET /api/v1/nfts/{tokenId}/royalties
Response:
{
"tokenId": "10001",
"royaltyBps": 500,
"totalRoyaltiesPaid": "230.00 CHN",
"payments": [
{"txHash": "0xsale001", "to": "0xAuthor", "amount": "10.00 CHN", "timestamp": 1690100000},
{"txHash": "0xsale777", "to": "0xAuthor", "amount": "12.50 CHN", "timestamp": 1690200000}
]
}4.4 GraphQL
Mint NFT (Mutation)
mutation MintPostNFT(
$postId: String!,
$to: String!,
$supply: Int!,
$royaltyBps: Int!,
$license: String!,
$signature: String!
) {
mintNFT(
postId: $postId,
to: $to,
supply: $supply,
royaltyBps: $royaltyBps,
license: $license,
signature: $signature
) {
txHash
tokenId
contract
}
}Fetch NFT by Token ID
query GetNFT($tokenId: String!) {
nft(tokenId: $tokenId) {
tokenId
contract
owner
postId
postCid
metadataCid
license
royaltyBps
mintTx
createdAt
}
}List Creator NFTs
query ListCreatorNFTs($creator: String!, $limit: Int, $cursor: String) {
nfts(creator: $creator, limit: $limit, cursor: $cursor) {
items { tokenId postId owner royaltyBps }
nextCursor
}
}Sales & Royalties
query GetRoyaltyHistory($tokenId: String!) {
royaltyHistory(tokenId: $tokenId) {
tokenId
royaltyBps
totalRoyaltiesPaid
payments { txHash to amount timestamp }
}
}4.5 Policy & Security Notes
Mint Permissions: Only the post author (or delegated operator) can mint the post NFT.
Immutable Linkage: NFT metadata references the original post CID to guarantee provenance.
Royalties: Royalty basis points are stored on-chain; payouts occur on secondary sales.
License Integrity: License string from post metadata is mirrored in NFT metadata; updates (if ever allowed) must emit
LicenseUpdated.Signatures: All mutating API calls include a wallet signature to prevent spoofing.
Pagination: List endpoints use cursor-based pagination for scalability.
Indexing: Off-chain indexers consume on-chain events for quick reads and analytics.
Last updated