API Documentation

Complete guide for integrating Roocoin API into your social media platform

Quick Start

Base URL for all API requests:

https://roocoin-production.up.railway.app
Network
Sepolia Testnet
Chain ID
11155111
API Version
1.0.0

Authentication

Protected endpoints require an API key in the request header

x-api-key: SocialMediaTeam2026SecretKey

Contract Addresses

Deployed smart contracts on Sepolia testnet

ROO Token Contract
0xADa01bA7F3D8E8aD99aB74ddE5F900198c45Fe1A
Staking Contract
0xC677da73bAF20fEE2AB48F2bFEcf97212eaBa661

API Endpoints

Available endpoints for blockchain interactions

GET /health

Check if the API is running

curl https://roocoin-production.up.railway.app/health
Response:
{
  "status": "ok",
  "timestamp": "2026-02-02T12:22:12.455Z",
  "network": "sepolia"
}
GET /api/wallet/balance/:address

Get ROO token balance for a wallet address

curl https://roocoin-production.up.railway.app/api/wallet/balance/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1
Response:
{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
  "balance": "1000.0",
  "formattedBalance": "1,000.00 ROO"
}
POST /api/rewards/distribute Protected

Distribute ROO tokens to a user for a specific activity

curl -X POST https://roocoin-production.up.railway.app/api/rewards/distribute \
  -H "Content-Type: application/json" \
  -H "x-api-key: SocialMediaTeam2026SecretKey" \
  -d '{
    "userAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
    "activityType": "POST_CREATE",
    "metadata": {"postId": "12345"}
  }'
Response:
{
  "success": true,
  "transactionHash": "0x123abc...",
  "reward": "10",
  "activityType": "POST_CREATE",
  "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1"
}
POST /api/rewards/batch-distribute Protected

Distribute rewards to multiple users (more gas-efficient)

curl -X POST https://roocoin-production.up.railway.app/api/rewards/batch-distribute \
  -H "Content-Type: application/json" \
  -H "x-api-key: SocialMediaTeam2026SecretKey" \
  -d '{
    "distributions": [
      {"userAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1", "amount": "10"},
      {"userAddress": "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4", "amount": "5"}
    ]
  }'
POST /api/rewards/viral Protected NEW

Award viral bonus based on engagement count. 1 ROOBYTES per 1000 engagements (likes + comments + shares)

curl -X POST https://roocoin-production.up.railway.app/api/rewards/viral \
  -H "Content-Type: application/json" \
  -H "x-api-key: SocialMediaTeam2026SecretKey" \
  -d '{
    "userAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
    "postId": "viral-post-123",
    "engagementCount": 5000,
    "breakdown": {"likes": 2000, "comments": 1500, "shares": 1500}
  }'
Response:
{
  "success": true,
  "txHash": "0xviral123...",
  "amount": 5,
  "postId": "viral-post-123",
  "engagementCount": 5000,
  "breakdown": {"likes": 2000, "comments": 1500, "shares": 1500},
  "calculation": "5000 engagements ÷ 1000 = 5 ROOBYTES"
}

🔥 Viral Bonus: Content creators are rewarded dynamically based on their engagement performance. Minimum 1000 engagements required.

POST /api/rewards/referral/verify Protected NEW

Award referral bonus after user completes verification. 10 ROOBYTES to referrer when referee completes first post or verification

curl -X POST https://roocoin-production.up.railway.app/api/rewards/referral/verify \
  -H "Content-Type: application/json" \
  -H "x-api-key: SocialMediaTeam2026SecretKey" \
  -d '{
    "referrerAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
    "refereeAddress": "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4",
    "verificationAction": "FIRST_POST"
  }'
Response:
{
  "success": true,
  "txHash": "0xreferral456...",
  "amount": 10,
  "referrerAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
  "refereeAddress": "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4",
  "verificationAction": "FIRST_POST",
  "message": "Referral bonus awarded: 10 ROOBYTES"
}
Valid verification actions:
FIRST_POST PROFILE_COMPLETE EMAIL_VERIFIED

👥 Smart Referrals: Prevents abuse by only rewarding referrers after their referees demonstrate genuine engagement.

POST /api/wallet/create

Create a new custodial wallet for a user (platform stores private key securely)

curl -X POST https://roocoin-production.up.railway.app/api/wallet/create \
  -H "Content-Type: application/json" \
  -d '{}'
Response:
{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
  "privateKey": "0xabc123...",
  "mnemonic": "word1 word2 word3..."
}

⚠️ IMPORTANT: Store privateKey encrypted in your database. Never expose it to users.

POST /api/wallet/faucet ADMIN ONLY

Manual wallet crediting by admin. Requires authentication with x-api-key header. Not for public use

curl -X POST https://roocoin-production.up.railway.app/api/wallet/faucet \\
  -H "Content-Type: application/json" \\
  -H "x-api-key: YOUR_PLATFORM_API_KEY" \\
  -d '{
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "amount": "100"
  }'
Response:
{
  "success": true,
  "message": "Admin credit successful",
  "amount": "100",
  "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "transactionHash": "0xabc123...",
  "newBalance": "150.5",
  "creditedBy": "admin"
}

🔐 Admin Authentication Required: Public faucet disabled. Only authorized admins can credit user wallets.

⛽ Percentage-Based Fee System

All transactions use a percentage-based fee model. Posting is FREE!

  • Transaction fee: 1% of the amount
  • Gas fee: 0.5% of the amount (covers ETH costs)
  • Total fee: 1.5% of transaction amount
  • Example: Send 100 ROOBYTES = 101.5 total (100 + 1% + 0.5%)
  • Free posting (amount: 0) requires no fees or transaction
POST /api/wallet/spend FREE Posting

Deduct ROOBYTES when user spends on platform. Creating posts is now FREE (amount: 0). + 0.1 ROOBYTES gas fee (only if amount > 0)

curl -X POST https://roocoin-production.up.railway.app/api/wallet/spend \
  -H "Content-Type: application/json" \
  -d '{
    "userPrivateKey": "0xabc123...",
    "amount": "0",
    "activityType": "POST_CREATE",
    "metadata": {"postId": "12345"}
  }'
Response (Free Activity):
{
  "success": true,
  "transactionHash": null,
  "userAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
  "amount": "0",
  "gasFee": "0",
  "totalCharged": "0",
  "activityType": "POST_CREATE",
  "remainingBalance": "100.00",
  "metadata": {"postId": "12345"},
  "message": "Free activity - no transaction required"
}
POST /api/wallet/transfer 1% Fee

Transfer ROOBYTES from custodial wallet to user's external MetaMask wallet. + 1% withdrawal fee + 0.1 ROOBYTES gas fee

curl -X POST https://roocoin-production.up.railway.app/api/wallet/transfer \
  -H "Content-Type: application/json" \
  -d '{
    "fromPrivateKey": "0xabc123...",
    "toAddress": "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4",
    "amount": "100"
  }'
Response:
{
  "success": true,
  "transactionHash": "0xghi789...",
  "collectionHash": "0xabc123...",
  "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
  "to": "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4",
  "amount": "100",
  "withdrawalFee": "1.0000 (1%)",
  "gasFee": "0.1",
  "totalCharged": "101.1000",
  "breakdown": {
    "transferAmount": "100",
    "withdrawalFee": "1.0000",
    "gasFee": "0.1",
    "total": "101.1000"
  }
}

💰 Withdrawal Fee: 1% of transfer amount is charged to prevent abuse and support platform sustainability.

POST /api/wallet/send 1.5% Fees

Peer-to-peer transfer - User sends ROOBYTES to another user on the platform. + 1% transaction fee + 0.5% gas fee

curl -X POST https://roocoin-production.up.railway.app/api/wallet/send \
  -H "Content-Type: application/json" \
  -d '{
    "fromPrivateKey": "0xabc123...",
    "toAddress": "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4",
    "amount": "10",
    "metadata": {"note": "Thanks for the help!"}
  }'
Response:
{
  "success": true,
  "transactionHash": "0xjkl012...",
  "collectionHash": "0xdef456...",
  "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
  "to": "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4",
  "amount": "10",
  "transactionFee": "0.1000 (1%)",
  "gasFee": "0.0500 (0.5%)",
  "totalCharged": "10.1500",
  "remainingBalance": "89.8500",
  "breakdown": {
    "sendAmount": "10",
    "transactionFee": "0.1000",
    "gasFee": "0.0500",
    "totalFees": "0.1500",
    "total": "10.1500"
  },
  "metadata": {"note": "Thanks for the help!"}
}

💡 Use case: Tipping creators, sending gifts, splitting rewards. Percentage fees ensure fair costs at any amount.

Wallet Integration Flow

Complete user journey for custodial wallet management

1
User Signs Up
Platform calls /api/wallet/create → User gets custodial wallet
Store encrypted privateKey in database
2
Initial Balance (Admin Credit)
Admin calls /api/wallet/faucet (with API key) → User gets credited
Admin-only manual crediting
3
User Creates Post
Check balance → Call /api/wallet/spend (1 ROO) → Post created
Balance: 100 ROO → 99 ROO
4
User Earns Rewards
Other users like/comment → Call /api/rewards/distribute → User earns ROO
Balance: 99 ROO → 101.1 ROO
5
User Withdraws (Optional)
User connects MetaMask → Call /api/wallet/transfer → ROO sent to their wallet
User now controls tokens in their own wallet

Statistics & Analytics

Real-time blockchain metrics for admin dashboard

GET /api/stats/dashboard ⚡ Recommended

Get all statistics in a single call (optimized for admin dashboard)

curl https://roocoin-production.up.railway.app/api/stats/dashboard
Response:
{
  "success": true,
  "data": {
    "circulation": {
      "total": "1000000.0",
      "symbol": "ROO",
      "label": "Total Circulation"
    },
    "treasury": {
      "balance": "500000.0",
      "address": "0x0cB2Fdc39Cf998BaA86E80099aC4E9cB998adD54",
      "symbol": "ROO",
      "label": "Reserve Balance"
    },
    "staking": {
      "totalLocked": "250000.0",
      "contract": "0xC677da73bAF20fEE2AB48F2bFEcf97212eaBa661",
      "symbol": "ROO",
      "label": "Total Staked"
    },
    "lifetime": {
      "minted": "1000000.0",
      "burned": "0.0",
      "symbol": "ROO"
    },
    "network": "sepolia",
    "timestamp": "2026-02-11T00:00:00.000Z"
  }
}
/api/stats/total-supply

Total circulation of ROO tokens

Returns: totalSupply
/api/stats/treasury

Platform reserve balance

Returns: treasuryBalance, address
/api/stats/total-staked

Total ROO locked in staking

Returns: totalStaked
/api/stats/total-minted

Lifetime minting (all rewards)

Returns: totalMinted
/api/stats/total-burned

Lifetime burning (removed from circulation)

Returns: totalBurned
/api/stats/contract-info

Smart contract addresses and network

Returns: contracts, network, rpcUrl

💡 Performance Tip: Use /api/stats/dashboard for admin dashboards to get all metrics in one call instead of making multiple requests.

Activity Types & Rewards

Reward amounts for different social media activities

Activity Type Reward (ROO) Description
POST_CREATE 0 (FREE) User creates a post - now free!
POST_LIKE 0.01 User likes a post
POST_COMMENT 0 Disabled
POST_SHARE 0.01 User shares a post
REFERRAL 10 User refers another user (after verification)
PROFILE_FOLLOW 0.1 User follows a profile
DAILY_LOGIN 0.1 User logs in daily
CONTENT_VIRAL 1 per 1000 engagements Dynamic viral bonus (use /api/rewards/viral)

Integration Examples

Sample code for popular programming languages

JavaScript / Node.js

const axios = require('axios');

const API_BASE = 'https://roocoin-production.up.railway.app';
const API_KEY = 'SocialMediaTeam2026SecretKey';

async function rewardPostCreation(userAddress, postId) {
  const response = await axios.post(
    `${API_BASE}/api/rewards/distribute`,
    {
      userAddress: userAddress,
      activityType: 'POST_CREATE',
      metadata: { postId: postId }
    },
    {
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': API_KEY
      }
    }
  );
  return response.data;
}

// Usage
rewardPostCreation('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1', 'post_12345');

Python

import requests

API_BASE = 'https://roocoin-production.up.railway.app'
API_KEY = 'SocialMediaTeam2026SecretKey'

def reward_post_creation(user_address, post_id):
    url = f'{API_BASE}/api/rewards/distribute'
    headers = {
        'Content-Type': 'application/json',
        'x-api-key': API_KEY
    }
    data = {
        'userAddress': user_address,
        'activityType': 'POST_CREATE',
        'metadata': {'postId': post_id}
    }
    
    response = requests.post(url, json=data, headers=headers)
    return response.json()

# Usage
reward_post_creation('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1', 'post_12345')

Error Handling

Common HTTP status codes and error responses

200 Success
400 Bad Request (invalid parameters)
401 Unauthorized (missing/invalid API key)
500 Internal Server Error
Error Response Format:
{
  "error": "Error message",
  "details": "Additional details if available"
}

Important Notes

Roocoin API • Version 1.0.0 • Sepolia Testnet

Home • Etherscan • GitHub