Rest API

TLOCK API Documentation

Overview

TLOCK provides REST and gRPC APIs for interacting with the decentralized social media platform. All APIs are automatically generated from Protocol Buffer definitions and follow Cosmos SDK standards.

Base Configuration

Network Information

• Chain ID: localchain-1 (testnet) / tlock-1 (mainnet)

• Bech32 Prefix: tlock

• Native Token: TOK

• Cosmos SDK Version: v0.50

• Tendermint Version: v0.38

Endpoints

• REST API: http://localhost:1317 (local) / https://api.tlock.org (mainnet)

• RPC: http://localhost:26657 (local) / https://rpc.tlock.org (mainnet)

• gRPC: localhost:9090 (local) / grpc.tlock.org:443 (mainnet)

Authentication

TLOCK uses Cosmos SDK standard authentication with cryptographic signatures. No API keys required.

Transaction Signing

All write operations require proper transaction signing using your wallet's private key.

Periodic Allowance

Users with granted periodic allowances can perform transactions without holding TOK tokens.

Post Module APIs

Query Endpoints (GET)

Get Module Parameters

GET /post/v1/params

Response: Module configuration parameters

Resolve Name

GET /post/v1/name/{address}

Parameters:

• address: User's wallet address

Response:

{
  "name": "user_display_name"
}

Get Home Posts

GET /post/v1/homePosts/{page_size}

Parameters:

• page_size: Number of posts per page

Response:

{
  "page": 1,
  "posts": [PostResponse]
}

Get First Page Home Posts

GET /post/v1/firstPageHomePosts/{page}/{page_size}

Parameters:

• page: Page number

• page_size: Number of posts per page

Search Topics

GET /post/v1/topics/{matching}

Parameters:

• matching: Search term for topic matching

Response:

{
  "topics": [TopicResponse]
}

Get Topic Posts

GET /post/v1/topic/posts/{topic_id}/{page}

Parameters:

• topic_id: Topic identifier

• page: Page number

Get Specific Post

GET /post/v1/get/{post_id}

Parameters:

• post_id: Post identifier

Response:

{
  "post": PostResponse,
  "topics": [TopicResponse]
}

Get User Created Posts

GET /post/v1/user/created/{address}/{page}

Parameters:

• address: User's wallet address

• page: Page number

Get Likes I Made

GET /post/v1/likes/i/made/{address}/{page}

Get Saves I Made

GET /post/v1/saves/i/made/{address}/{page}

Get Likes Received

GET /post/v1/likes/received/{address}/{page}

Get Comments

GET /post/v1/comments/{id}/{page}

Parameters:

• id: Post or comment ID

• page: Page number

Get Comments Received

GET /post/v1/comments/received/{address}/{page}

Get Activities Received

GET /post/v1/activities/received/{address}/{page}

Get Categories

GET /post/v1/categories

Response:

{
  "categories": [CategoryResponse]
}

Get Topics by Category

GET /post/v1/category/topics/{category_id}/{page}

Get Category by Topic

GET /post/v1/topic/category/{topic_id}

Get Category Posts

GET /post/v1/category/posts/{category_id}/{page}

Get Following Posts

GET /post/v1/following/posts/{address}/{page}

Get Following Topics

GET /post/v1/following/topics/{address}/{page}

Check if Following Topic

GET /post/v1/isFollowing/topic/{address}/{topic_id}

Response:

{
  "is_following": true
}

Get Uncategorized Topics

GET /post/v1/uncategorized/topics/{address}/{page}/{limit}

Get Vote Option

GET /post/v1/vote/option/{address}/{post_id}

Get Topic Image

GET /post/v1/topic/image/{topic_id}

Get Topic Details

GET /post/v1/topic/{topic_id}

Get Trending Keywords

GET /post/v1/trending/keywords/{page}

Get Trending Topics

GET /post/v1/trending/topics/{page}

Get Paid Post Image

GET /post/v1/paid/image/{image_id}

Transaction Endpoints (POST)

All transaction endpoints require proper Cosmos SDK transaction formatting and signing.

Create Post

Endpoint: /cosmos/tx/v1beta1/txs Message Type: MsgCreatePost

Message Structure:

{
  "creator": "tlock1...",
  "post_detail": {
    "title": "Post Title",
    "content": "Post content",
    "imagesBase64": ["base64_encoded_image"],
    "imagesUrl": ["https://example.com/image.jpg"],
    "videosUrl": ["https://example.com/video.mp4"],
    "quote": "post_id_to_quote",
    "mention": ["tlock1address1", "tlock1address2"],
    "topic": ["topic1", "topic2"],
    "category": "category_name",
    "poll": {
      "totalVotes": 0,
      "votingStart": 1640995200,
      "votingEnd": 1641081600,
      "vote": [
        {"option": "Option 1", "count": 0, "id": 1},
        {"option": "Option 2", "count": 0, "id": 2}
      ]
    }
  }
}

Like Post

Message Type: MsgLikeRequest

{
  "sender": "tlock1...",
  "id": "post_id"
}

Unlike Post

Message Type: MsgUnlikeRequest

{
  "sender": "tlock1...",
  "id": "post_id"
}

Comment on Post

Message Type: MsgCommentRequest

{
  "creator": "tlock1...",
  "parentId": "post_id",
  "comment": "Comment content",
  "mention": ["tlock1address1"]
}

Quote Post

Message Type: MsgQuotePostRequest

{
  "creator": "tlock1...",
  "quote": "post_id_to_quote",
  "comment": "Quote comment",
  "mention": ["tlock1address1"],
  "topic": ["topic1"],
  "category": "category_name"
}

Repost

Message Type: MsgRepostRequest

{
  "creator": "tlock1...",
  "quote": "post_id_to_repost",
  "mention": ["tlock1address1"],
  "topic": ["topic1"],
  "category": "category_name"
}

Save Post

Message Type: MsgSaveRequest

{
  "sender": "tlock1...",
  "id": "post_id"
}

Cast Vote on Poll

Message Type: CastVoteOnPollRequest

{
  "creator": "tlock1...",
  "id": "post_id",
  "optionId": 1
}

Follow Topic

Message Type: MsgFollowTopicRequest

{
  "creator": "tlock1...",
  "topic_id": "topic_id"
}

Grant Allowance from Module

Message Type: MsgGrantAllowanceFromModuleRequest

{
  "sender": "tlock1admin...",
  "userAddress": "tlock1user..."
}

Profile Module APIs

Query Endpoints (GET)

Get Module Parameters

GET /profile/v1/params

Get Profile

GET /profile/v1/get/{address}

Response:

{
  "profile": {
    "wallet_address": "tlock1...",
    "user_handle": "username",
    "nickname": "Display Name",
    "avatar": "base64_or_url",
    "has_avatar": true,
    "bio": "User bio",
    "level": 5,
    "admin_level": 0,
    "following": 150,
    "followers": 300,
    "creation_time": 1640995200,
    "location": "Location",
    "website": "https://example.com",
    "idVerification_status": "ID_VERIFICATION_PERSONAL",
    "score": 15625,
    "line_manager": ""
  }
}

Get Profile Avatar

GET /profile/v1/avatar/{address}

Get Following List

GET /profile/v1/following/{address}/{page}/{limit}

Get Followers List

GET /profile/v1/followers/{address}

Get Follow Relationship

GET /profile/v1/follow/relationship/{addressA}/{addressB}

Response:

{
  "relationship": 1
}

Relationship codes: 0-No relationship; 1-A follows B; 2-B follows A; 3-Mutual follows

Get Mention Suggestions

GET /profile/v1/getMentionSuggestions/{address}/{matching}

Get Activities Received Count

GET /profile/v1/activities/received/count/{address}

Search Users

GET /profile/v1/users/search/{matching}

Check if Admin

GET /profile/v1/isAdmin/{address}

Transaction Endpoints (POST)

Add/Update Profile

Message Type: MsgAddProfileRequest

{
  "creator": "tlock1...",
  "profile_json": {
    "nickname": "Display Name",
    "user_handle": "username",
    "avatar": "base64_encoded_image",
    "bio": "User biography",
    "location": "City, Country",
    "website": "https://example.com"
  }
}

Follow User

Message Type: MsgFollowRequest

{
  "creator": "tlock1...",
  "targetAddr": "tlock1target..."
}

Unfollow User

Message Type: MsgUnfollowRequest

{
  "creator": "tlock1...",
  "targetAddr": "tlock1target..."
}

Add Admin

Message Type: MsgAddAdminRequest

{
  "creator": "tlock1...",
  "address": "tlock1newadmin..."
}

Manage Admin

Message Type: MsgManageAdminRequest

{
  "creator": "tlock1...",
  "manage_json": {
    "line_manager": "tlock1manager...",
    "admin_address": "tlock1admin...",
    "admin_level": 2,
    "editable": true
  },
  "action": "update"
}

Standard Cosmos SDK APIs

TLOCK includes all standard Cosmos SDK modules with their respective APIs:

Bank Module

• Base Path: /cosmos/bank/v1beta1/

• Endpoints: balances, supply, metadata, etc.

Auth Module

• Base Path: /cosmos/auth/v1beta1/

• Endpoints: accounts, params

Staking Module

• Base Path: /cosmos/staking/v1beta1/

• Endpoints: validators, delegations, unbonding

Governance Module

• Base Path: /cosmos/gov/v1beta1/

• Endpoints: proposals, votes, params

Distribution Module

• Base Path: /cosmos/distribution/v1beta1/

• Endpoints: rewards, commission

Fee Grant Module

• Base Path: /cosmos/feegrant/v1beta1/

• Endpoints: allowances

IBC Module

• Base Path: /ibc/

• Endpoints: channels, connections, clients

Transaction Broadcasting

POST /cosmos/tx/v1beta1/txs

Transaction Query

GET /cosmos/tx/v1beta1/txs/{hash}

Node Info

GET /cosmos/base/tendermint/v1beta1/node_info

Block Info

GET /cosmos/base/tendermint/v1beta1/blocks/{height}

Data Structures

PostResponse

{
  "post": {
    "id": "post_123",
    "post_type": "ORIGINAL",
    "parent_id": "",
    "title": "Post Title",
    "content": "Post content",
    "creator": "tlock1...",
    "timestamp": 1640995200,
    "image_ids": ["img_1", "img_2"],
    "images_url": ["https://example.com/img.jpg"],
    "videos_url": ["https://example.com/vid.mp4"],
    "quote": "quoted_post_id",
    "like_count": 42,
    "comment_count": 15,
    "repost_count": 8,
    "save_count": 23,
    "score": 1250,
    "homePostsUpdate": 1640995200,
    "poll": {
      "totalVotes": 100,
      "votingStart": 1640995200,
      "votingEnd": 1641081600,
      "vote": [
        {"option": "Yes", "count": 60, "id": 1},
        {"option": "No", "count": 40, "id": 2}
      ]
    }
  },
  "profile": Profile,
  "quote_post": Post,
  "quote_profile": Profile
}

Profile

{
  "wallet_address": "tlock1...",
  "user_handle": "username",
  "nickname": "Display Name",
  "avatar": "base64_or_url",
  "has_avatar": true,
  "bio": "User biography",
  "level": 5,
  "admin_level": 0,
  "following": 150,
  "followers": 300,
  "creation_time": 1640995200,
  "location": "City, Country",
  "website": "https://example.com",
  "idVerification_status": "ID_VERIFICATION_PERSONAL",
  "score": 15625,
  "line_manager": ""
}

TopicResponse

{
  "id": "topic_123",
  "name": "blockchain",
  "image": "base64_or_url",
  "title": "Blockchain Technology",
  "summary": "Discussion about blockchain",
  "score": 5000,
  "trending_keywords_score": 1200,
  "category_id": "tech",
  "creator": "tlock1..."
}

CategoryResponse

{
  "id": "tech",
  "name": "Technology",
  "avatar": "base64_or_url",
  "index": 1
}

CommentResponse

{
  "post": Post,
  "profile": Profile,
  "targetProfile": Profile
}

Error Handling

Standard HTTP Status Codes

• 200: Success

• 400: Bad Request - Invalid parameters

• 404: Not Found - Resource doesn't exist

• 500: Internal Server Error

Cosmos SDK Error Format

{
  "code": 2,
  "message": "account sequence mismatch",
  "details": []
}

Common Errors

Transaction Errors

{
  "code": 4,
  "message": "insufficient funds",
  "details": []
}

Validation Errors

{
  "code": 400,
  "message": "post content exceeds maximum length",
  "details": []
}

Authentication Errors

{
  "code": 401,
  "message": "signature verification failed",
  "details": []
}

Rate Limiting

Default Limits

• Query Endpoints: 1000 requests per hour per IP

• Transaction Endpoints: 100 transactions per hour per address

• Search Endpoints: 500 requests per hour per IP

Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1640998800

Development Tools

CLI Commands

# Query examples
tlockd query post get post_123
tlockd query profile get tlock1...

# Transaction examples
tlockd tx post create-post --from mykey
tlockd tx profile add-profile --from mykey

gRPC Clients

# Using grpcurl
grpcurl -plaintext localhost:9090 list
grpcurl -plaintext localhost:9090 post.v1.Query/QueryPost

Swagger/OpenAPI

• Local: http://localhost:1317/swagger/

• Mainnet: https://api.tlock.org/swagger/

Support and Resources

Documentation

• Cosmos SDK Docs: https://docs.cosmos.network

• Protocol Buffers: https://developers.google.com/protocol-buffers

Community

• Telegram: https://t.me/TlockChat

• GitHub: https://github.com/Tlock-org/tlock

---

This API documentation is automatically generated from Protocol Buffer definitions and reflects the actual implementation in the codebase.