Traditional Twitter API - Complete Twitter Bot Management

The Traditional Twitter API provides comprehensive Twitter bot functionality for user verification, reward distribution, and social media engagement tracking. Built for enterprise-grade social media integration with blockchain reward systems and automated verification processes.

🎯 What Can You Manage?

Your complete Twitter bot ecosystem with these powerful tools:

User Verification: Twitter account verification with automated tweet checking
Reward Distribution: USDC rewards on supported EVM blockchain networks
Social Engagement: Mention tracking, retweet rewards, and daily limits
Webhook Integration: Real-time Twitter event processing
Admin Controls: Mention search, webhook monitoring, and service health
Compliance: Daily limits, verification expiry, and audit trails

🧩 Your Twitter Bot Building Blocks

✅ Verification Blocks

POST /twitter/verification/initiate - Start Twitter account verification
POST /twitter/verification/verify - Complete verification with tweet proof
GET /twitter/verification/status/:user_id - Check verification status

🎁 Reward System Blocks

POST /twitter/mint_reward - USDC minting via bridge contracts
POST /twitter/rewards/mention - Process mention/retweet rewards
GET /twitter/rewards/history/:user_id - Reward transaction history
GET /twitter/rewards/limits/:user_id - Daily reward limit checking

🔍 Twitter Integration Blocks

GET /twitter/mentions/search - Search bot mentions (admin)
GET /twitter/user/:username - Get Twitter user information
GET /twitter/health - Service health monitoring

🔗 Webhook Management Blocks

GET /twitter/webhook/status - Webhook service status
POST /twitter/webhook/test - Test webhook processing
GET /twitter/webhook/logs - Webhook processing logs

📄 Static Content Blocks

GET /twitter/callback - OAuth callback handling
GET /twitter/terms - Terms of Service
GET /twitter/privacy - Privacy Policy

🏗️ Common Twitter Bot Patterns

Pattern 1: "I want to verify my Twitter account"

User registration → initiateVerification → Tweet posting → verifyAccount → Reward

Use: /twitter/verification/initiate → /twitter/verification/verify

Pattern 2: "I want to earn rewards from mentions"

Mention bot → processMentionReward → Blockchain transfer → History tracking

Use: /twitter/rewards/mention → /twitter/rewards/history/:user_id

Pattern 3: "I want to monitor bot activity"

Admin access → searchMentions → getWebhookLogs → Service monitoring

Use: /twitter/mentions/search → /twitter/webhook/logs

Pattern 4: "I want to check reward eligibility"

User status → getVerificationStatus → checkDailyLimits → Reward processing

Use: /twitter/verification/status/:user_id → /twitter/rewards/limits/:user_id

🔗 Supported Networks

Twitter bot reward system operates on EVM networks with BRDZ bridge contracts for secure USDC distribution:

Network	Chain ID	Bridge Contract	USDC Contract
Sepolia	11155111	`0x432a3Ab53BEe8657cD5E26Bd9A7251Bbd19B3Fb1`	`0x9BF350fBaaA8c7200990B051809334c90778f435`
Polygon Amoy	80002	`0xb04EBd1cE956E5576c5A7A02f74E3DdCFeE564AF`	`0xC15239B6B9012F3225f9ebC091C7CE85FF31b983`
Neon EVM	245022926	`0xF0E6D21447281D3a858B6Bfee045D5c48D2E6065`	`0xB5234C0418402775bCA3f73c4B0B5bDd906FCA11`

Minting Process: All USDC rewards are minted through bridge contracts which interface with BRDZ custom USDC contracts on each supported EVM network.

✅ Verification Operations

Initiate Twitter Verification

POST/api/twitter/verification/initiate

Start Twitter Account Verification

Begin the Twitter account verification process by generating a unique verification code and tweet template. Users must post the generated tweet to prove account ownership.

Parameters

user_idnumber

User ID (can be provided via auth middleware)

twitter_usernamestringrequired

Twitter username to verify (without @ symbol)

Request Body

{
  "user_id": 123,
  "twitter_username": "johndoe"
}

Response

200Verification initiated successfully

{
  "success": true,
  "message": "Twitter verification initiated successfully",
  "data": {
    "verification_id": "verify_456789",
    "verification_code": "BRDZ-A1B2C",
    "twitter_username": "johndoe",
    "expires_at": "2024-01-15T11:00:00Z",
    "user_info": {
      "id": "1234567890",
      "username": "johndoe",
      "name": "John Doe",
      "verified": false,
      "followers_count": 150
    },
    "tweet_template": "Verifying my Twitter account for @BRDZBot with code: BRDZ-A1B2C",
    "instructions": "Copy this tweet exactly and post it as a public tweet on your Twitter account"
  },
  "next_steps": [
    "Copy the tweet template exactly",
    "Post it on Twitter as a public tweet",
    "Call the verify endpoint with your verification code"
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

400Invalid request parameters

{
  "success": false,
  "error": {
    "code": "INVALID_TWITTER_USERNAME",
    "message": "Twitter username must be between 1 and 15 characters"
  }
}

404Twitter account not found

{
  "success": false,
  "error": {
    "code": "TWITTER_ACCOUNT_NOT_FOUND",
    "message": "Twitter account not found or private"
  }
}

409Verification conflict

{
  "success": false,
  "error": {
    "code": "ALREADY_VERIFIED",
    "message": "User already has verified Twitter account"
  }
}

Complete Twitter Verification

POST/api/twitter/verification/verify

Complete Twitter Account Verification

Complete the verification process by providing the verification code. System will check for the verification tweet and distribute welcome rewards upon successful verification.

Parameters

user_idnumber

User ID (can be provided via auth middleware)

verification_codestringrequired

Verification code from initiate step (format: BRDZ-XXXXX)

Request Body

{
  "user_id": 123,
  "verification_code": "BRDZ-A1B2C"
}

Response

200Verification completed successfully

{
  "success": true,
  "message": "Twitter account verified successfully! Welcome reward has been sent.",
  "data": {
    "verification": {
      "verification_id": "verify_456789",
      "twitter_username": "johndoe",
      "verified_at": "2024-01-15T10:35:00Z",
      "status": "verified"
    },
    "reward": {
      "amount": 5,
      "currency": "USDC",
      "chain": "sepolia",
      "wallet_address": "0x742d35Cc6634C0532925a3b8D389E2B74e8E8329",
      "tx_hash": "0xabc123...",
      "status": "completed",
      "reward_id": "reward_789012"
    },
    "wallet_info": {
      "chain": "sepolia",
      "address": "0x742d35Cc6634C0532925a3b8D389E2B74e8E8329",
      "balance_before": 0,
      "balance_after": 5
    },
    "user": {
      "user_id": 123,
      "username": "johndoe",
      "twitter_username": "johndoe",
      "twitter_verified": true
    }
  },
  "congratulations": "Your Twitter account is now verified! You can now earn USDC rewards by mentioning our bot.",
  "timestamp": "2024-01-15T10:35:00Z"
}

400Invalid verification code

{
  "success": false,
  "error": {
    "code": "INVALID_VERIFICATION_CODE",
    "message": "Invalid verification code format"
  }
}

404Verification not found

{
  "success": false,
  "error": {
    "code": "VERIFICATION_NOT_FOUND",
    "message": "Verification not found or already processed"
  }
}

410Verification expired

{
  "success": false,
  "error": {
    "code": "VERIFICATION_EXPIRED",
    "message": "Verification code has expired"
  }
}

Check Verification Status

GET/api/twitter/verification/status/:user_id

Get Twitter Verification Status

Check the current Twitter verification status for a user, including any pending verifications and eligibility for starting new verification.

Parameters

user_idstringrequired

User ID to check verification status for

Response

200Verification status retrieved successfully

{
  "success": true,
  "message": "Verification status retrieved successfully",
  "data": {
    "user_id": 123,
    "username": "johndoe",
    "twitter_verified": true,
    "twitter_username": "johndoe",
    "pending_verification": {
      "has_pending": false,
      "verification_code": null,
      "expires_at": null
    },
    "can_start_verification": false
  },
  "status_summary": "Twitter account @johndoe is verified",
  "timestamp": "2024-01-15T10:40:00Z"
}

404User not found

{
  "success": false,
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "User not found"
  }
}

🎁 Reward System Operations

USDC Reward Minting

POST/api/twitter/mint_reward

Execute USDC Reward Minting via Bridge Contract

Mint USDC rewards to user wallets using BRDZ bridge contracts on supported EVM networks. Bridge contracts interface with BRDZ custom USDC contracts for secure reward distribution.

Parameters

chainstringrequired

EVM blockchain network (sepolia, amoy, neon)

addressstringrequired

Recipient wallet address

amountnumber

USDC amount to mint (default: 10)

user_idnumber

User ID for tracking (optional)

Request Body

{
  "chain": "sepolia",
  "address": "0x742d35Cc6634C0532925a3b8D389E2B74e8E8329",
  "amount": 25,
  "user_id": 123
}

Response

200Reward minted successfully

{
  "success": true,
  "data": {
    "transaction_hash": "0xdef456789abcdef...",
    "chain": "sepolia",
    "amount": 25,
    "recipient": "0x742d35Cc6634C0532925a3b8D389E2B74e8E8329",
    "user_id": 123,
    "timestamp": "2024-01-15T10:45:00Z"
  },
  "message": "Successfully minted 25 USDC"
}

400Invalid parameters

{
  "success": false,
  "message": "Invalid chain. Supported EVM networks: sepolia, amoy, neon"
}

500Minting failed

{
  "success": false,
  "message": "Bridge contract minting failed",
  "error": "Insufficient gas or bridge contract error"
}

Process Mention Rewards

POST/api/twitter/rewards/mention

Process Mention/Retweet Rewards

Process and distribute rewards for Twitter mentions or retweets. Includes daily limit checking and automatic USDC distribution to user wallets.

Parameters

user_idnumber

User ID (can be provided via auth middleware)

tweet_idstringrequired

Twitter tweet ID that mentions the bot

tweet_textstringrequired

Full text content of the tweet

action_typestring

Type of action (mention, retweet) - default: mention

Request Body

{
  "user_id": 123,
  "tweet_id": "1234567890123456789",
  "tweet_text": "Hey @BRDZBot, loving the new features! #crypto #rewards",
  "action_type": "mention"
}

Response

200Reward processed successfully

{
  "success": true,
  "message": "Reward processed successfully! 10 USDC sent to your sepolia wallet.",
  "data": {
    "reward": {
      "reward_id": "reward_345678",
      "amount": 10,
      "currency": "USDC",
      "chain": "sepolia",
      "wallet_address": "0x742d35Cc6634C0532925a3b8D389E2B74e8E8329",
      "tx_hash": "0x123abc456def...",
      "status": "completed",
      "action_type": "mention",
      "tweet_id": "1234567890123456789",
      "created_at": "2024-01-15T10:50:00Z",
      "user_id": 123,
      "twitter_username": "johndoe"
    },
    "daily_status": {
      "daily_count": 2,
      "daily_limit": 3,
      "remaining": 1,
      "can_receive_reward": true
    },
    "user": {
      "user_id": 123,
      "twitter_username": "johndoe"
    }
  },
  "daily_limit_info": "You have 1 rewards remaining today.",
  "timestamp": "2024-01-15T10:50:00Z"
}

403User not verified

{
  "success": false,
  "error": {
    "code": "USER_NOT_VERIFIED",
    "message": "User not found or Twitter not verified"
  }
}

409Tweet already rewarded

{
  "success": false,
  "error": {
    "code": "TWEET_ALREADY_REWARDED",
    "message": "This tweet has already been rewarded"
  }
}

429Daily limit reached

{
  "success": false,
  "error": {
    "code": "DAILY_LIMIT_REACHED",
    "message": "Daily reward limit reached"
  }
}

Get Rewards History

GET/api/twitter/rewards/history/:user_id

Get User's Twitter Rewards History

Retrieve comprehensive reward history for a user with filtering options and statistics. Includes pagination and daily status information.

Parameters

user_idstringrequired

User ID to get reward history for

limitnumber

Maximum records to return (1-100, default: 10)

offsetnumber

Records to skip for pagination (default: 0)

statusstring

Filter by status (pending, completed, failed)

action_typestring

Filter by action type (verification, mention, retweet)

chainstring

Filter by blockchain (sepolia, amoy, neon)

Response

200Rewards history retrieved successfully

{
  "success": true,
  "message": "Rewards history retrieved successfully",
  "data": {
    "user_id": 123,
    "rewards": [
      {
        "reward_id": "reward_345678",
        "amount": 10,
        "currency": "USDC",
        "chain": "sepolia",
        "wallet_address": "0x742d35Cc6634C0532925a3b8D389E2B74e8E8329",
        "tx_hash": "0x123abc456def...",
        "status": "completed",
        "action_type": "mention",
        "tweet_id": "1234567890123456789",
        "created_at": "2024-01-15T10:50:00Z"
      },
      {
        "reward_id": "reward_123456",
        "amount": 5,
        "currency": "USDC",
        "chain": "sepolia",
        "wallet_address": "0x742d35Cc6634C0532925a3b8D389E2B74e8E8329",
        "tx_hash": "0xabc123def456...",
        "status": "completed",
        "action_type": "verification",
        "tweet_id": null,
        "created_at": "2024-01-15T10:35:00Z"
      }
    ],
    "pagination": {
      "total": 2,
      "limit": 10,
      "offset": 0,
      "has_more": false
    },
    "statistics": {
      "total_earned": 15,
      "total_rewards": 2,
      "completed_rewards": 2,
      "pending_rewards": 0,
      "failed_rewards": 0
    },
    "daily_status": {
      "daily_count": 2,
      "daily_limit": 3,
      "remaining_today": 1,
      "can_receive_reward": true
    }
  },
  "summary": {
    "total_earned": "15 USDC",
    "total_rewards": 2,
    "success_rate": "100%"
  },
  "timestamp": "2024-01-15T11:00:00Z"
}

400Invalid parameters

{
  "success": false,
  "error": {
    "code": "INVALID_LIMIT",
    "message": "limit must be a number between 1 and 100"
  }
}

Check Daily Limits

GET/api/twitter/rewards/limits/:user_id

Check Daily Reward Limits

Check the current daily reward usage and remaining limits for a user. Includes progress tracking and eligibility status.

Parameters

user_idstringrequired

User ID to check daily limits for

Response

200Daily limits retrieved successfully

{
  "success": true,
  "message": "Daily limits retrieved successfully",
  "data": {
    "user_id": 123,
    "daily_count": 2,
    "daily_limit": 3,
    "remaining_today": 1,
    "can_receive_reward": true,
    "progress_percentage": 67
  },
  "status_message": "You can earn 1 more rewards today",
  "timestamp": "2024-01-15T11:05:00Z"
}

500Failed to check limits

{
  "success": false,
  "error": {
    "code": "SERVER_ERROR",
    "message": "Failed to check daily limits"
  }
}

🔍 Twitter Integration Operations

Search Bot Mentions

GET/api/twitter/mentions/search

Search Twitter Bot Mentions (Admin Only)

Search for mentions of the Twitter bot across Twitter. Used for monitoring engagement and discovering potential reward opportunities. Admin access required.

Parameters

bot_usernamestringrequired

Bot's Twitter username to search for (without @)

max_resultsnumber

Maximum results to return (1-50, default: 10)

Response

200Mentions found successfully

{
  "success": true,
  "message": "Found 3 mentions for @BRDZBot",
  "data": {
    "bot_username": "BRDZBot",
    "mentions": [
      {
        "tweet_id": "1234567890123456789",
        "text": "Just discovered @BRDZBot and loving the reward system! #crypto",
        "author_id": "9876543210",
        "created_at": "2024-01-15T10:55:00Z",
        "engagement": {
          "retweets": 5,
          "likes": 23,
          "replies": 3
        }
      },
      {
        "tweet_id": "9876543210987654321",
        "text": "Thanks @BRDZBot for the quick USDC reward! Amazing service.",
        "author_id": "1122334455",
        "created_at": "2024-01-15T09:30:00Z",
        "engagement": {
          "retweets": 2,
          "likes": 15,
          "replies": 1
        }
      }
    ],
    "total_found": 3,
    "search_timestamp": "2024-01-15T11:10:00Z"
  },
  "timestamp": "2024-01-15T11:10:00Z"
}

400Invalid parameters

{
  "success": false,
  "error": {
    "code": "INVALID_MAX_RESULTS",
    "message": "max_results must be a number between 1 and 50"
  }
}

503Twitter API error

{
  "success": false,
  "error": {
    "code": "TWITTER_API_ERROR",
    "message": "Failed to search mentions"
  }
}

Get Twitter User Info

GET/api/twitter/user/:username

Get Twitter User Information

Retrieve detailed information about a Twitter user including profile data, follower counts, and account status. Used for verification and user analysis.

Parameters

usernamestringrequired

Twitter username to get information for (without @)

Response

200User information retrieved successfully

{
  "success": true,
  "message": "Twitter user information retrieved for @johndoe",
  "data": {
    "user_id": "1234567890",
    "username": "johndoe",
    "display_name": "John Doe",
    "verified": false,
    "description": "Crypto enthusiast and blockchain developer. Building the future of DeFi.",
    "metrics": {
      "followers": 1520,
      "following": 342,
      "tweets": 987
    },
    "account_created": "2019-03-15T08:22:00Z"
  },
  "timestamp": "2024-01-15T11:15:00Z"
}

400Invalid username

{
  "success": false,
  "error": {
    "code": "INVALID_USERNAME",
    "message": "Username must be between 1 and 15 characters"
  }
}

404User not found

{
  "success": false,
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "Twitter account not found or account is private"
  }
}

503Twitter API error

{
  "success": false,
  "error": {
    "code": "TWITTER_API_ERROR",
    "message": "Failed to get Twitter user info"
  }
}

Get Service Health Status

GET/api/twitter/health

Twitter Bot Service Health Check

Check the health status of the Twitter bot service including API configuration, supported features, and service availability.

Response

200Service health retrieved successfully

{
  "success": true,
  "message": "Twitter bot service is running",
  "data": {
    "service": "Twitter Bot API",
    "status": "healthy",
    "timestamp": "2024-01-15T11:20:00Z",
    "environment": {
      "twitter_api_configured": true,
      "supported_chains": [
        "sepolia",
        "amoy",
        "neon"
      ],
      "reward_config": {
        "verification_reward": "5 USDC",
        "mention_reward": "10 USDC",
        "daily_limit": 3,
        "verification_expires": "30 minutes"
      }
    },
    "endpoints": {
      "verification": "/twitter/verification/*",
      "rewards": "/twitter/rewards/*",
      "mentions": "/twitter/mentions/*",
      "user_info": "/twitter/user/*"
    }
  },
  "timestamp": "2024-01-15T11:20:00Z"
}

500Health check failed

{
  "success": false,
  "error": {
    "code": "HEALTH_CHECK_FAILED",
    "message": "Twitter bot service health check failed"
  }
}

🔗 Webhook Management Operations

Get Webhook Status

GET/api/twitter/webhook/status

Get Webhook Service Status (Admin Only)

Retrieve the current status of the Twitter webhook service including configuration, health status, and endpoint information. Admin access required.

Response

200Webhook status retrieved successfully

{
  "success": true,
  "message": "Webhook service status retrieved successfully",
  "data": {
    "service": "Twitter Webhook Service",
    "status": "healthy",
    "webhook_configured": true,
    "last_event_received": "2024-01-15T10:45:00Z",
    "events_processed_today": 127,
    "environment_checks": {
      "consumer_secret_configured": true,
      "webhook_url_registered": true,
      "crc_validation_enabled": true
    },
    "supported_events": [
      "tweet_create_events",
      "follow_events",
      "favorite_events",
      "direct_message_events"
    ]
  },
  "endpoints": {
    "verification": "GET /api/twitter/webhook?crc_token=xxx",
    "events": "POST /api/twitter/webhook",
    "status": "GET /api/twitter/webhook/status"
  },
  "timestamp": "2024-01-15T11:25:00Z"
}

500Status check failed

{
  "success": false,
  "error": {
    "code": "STATUS_CHECK_FAILED",
    "message": "Failed to get webhook status"
  }
}

Test Webhook Event

POST/api/twitter/webhook/test

Test Webhook Event Processing (Admin Only)

Test webhook event processing with custom payloads. Used for development and debugging webhook functionality. Admin access required.

Parameters

test_event_typestringrequired

Type of test event (tweet_create_events, follow_events, etc.)

test_payloadobjectrequired

Test event payload data

Request Body

{
  "test_event_type": "tweet_create_events",
  "test_payload": {
    "id": "1234567890123456789",
    "text": "Test tweet mentioning @BRDZBot for webhook testing",
    "user": {
      "id": "9876543210",
      "screen_name": "testuser"
    },
    "created_at": "2024-01-15T11:30:00Z"
  }
}

Response

200Test event processed successfully

{
  "success": true,
  "message": "Webhook test event processed successfully",
  "data": {
    "test_event_type": "tweet_create_events",
    "processed_count": 1,
    "results": [
      {
        "event_type": "tweet_create",
        "tweet_id": "1234567890123456789",
        "processing_result": "success",
        "actions_taken": [
          "mention_detected",
          "reward_eligibility_checked"
        ],
        "processing_time_ms": 150
      }
    ],
    "timestamp": "2024-01-15T11:30:00Z"
  },
  "test_info": {
    "signature_validation_skipped": true,
    "admin_user": "admin_user",
    "test_timestamp": "2024-01-15T11:30:00Z"
  },
  "timestamp": "2024-01-15T11:30:00Z"
}

400Invalid test data

{
  "success": false,
  "error": {
    "code": "MISSING_TEST_DATA",
    "message": "test_event_type and test_payload are required"
  }
}

403Insufficient permissions

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Admin access required for webhook testing"
  }
}

Get Webhook Logs

GET/api/twitter/webhook/logs

Get Webhook Processing Logs (Admin Only)

Retrieve recent webhook processing logs with filtering options. Used for monitoring webhook activity and debugging issues. Admin access required.

Parameters

limitnumber

Maximum logs to return (1-100, default: 50)

event_typestring

Filter by event type

statusstring

Filter by processing status

Response

200Webhook logs retrieved successfully

{
  "success": true,
  "message": "Webhook logs retrieved successfully",
  "data": {
    "total_events": 127,
    "recent_events": [],
    "event_summary": {
      "tweet_create_events": 85,
      "verification_events": 12,
      "mention_events": 25,
      "error_events": 5
    },
    "time_range": {
      "from": "2024-01-14T11:30:00Z",
      "to": "2024-01-15T11:30:00Z"
    }
  },
  "filters": {
    "limit": 50,
    "event_type": "all",
    "status": "all"
  },
  "timestamp": "2024-01-15T11:35:00Z"
}

403Insufficient permissions

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Admin access required for webhook logs"
  }
}

📄 Static Content Operations

OAuth Callback

GET/api/twitter/callback

Twitter OAuth Callback Handler

Handle Twitter OAuth callback for authentication flows. Used for Twitter API integration setup and development.

Response

200Callback received successfully

{
  "success": true,
  "message": "Twitter OAuth callback received",
  "data": {
    "service": "BRDZ Twitter Bot",
    "callback_received": true,
    "query_params": {
      "oauth_token": "sample_token",
      "oauth_verifier": "sample_verifier"
    }
  },
  "timestamp": "2024-01-15T11:40:00Z"
}

Terms of Service

GET/api/twitter/terms

Get Terms of Service

Retrieve the Terms of Service for the BRDZ Twitter Bot service. Used for compliance and user agreement display.

Response

200Terms of Service retrieved successfully

{
  "success": true,
  "message": "BRDZ Twitter Bot Terms of Service",
  "data": {
    "service_name": "BRDZ Twitter Bot",
    "version": "1.0.0",
    "terms": {
      "title": "Terms of Service for BRDZ Twitter Bot",
      "description": "By using BRDZ Twitter Bot, you agree to these terms and conditions.",
      "key_points": [
        "Users must have verified Twitter accounts",
        "Maximum 3 rewards per day per user",
        "Rewards are distributed on supported blockchain networks",
        "Users are responsible for their wallet security",
        "Service may be modified or discontinued at any time"
      ],
      "contact": "support@brdz.link",
      "last_updated": "2024-01-01"
    }
  },
  "timestamp": "2024-01-15T11:45:00Z"
}

Privacy Policy

GET/api/twitter/privacy

Get Privacy Policy

Retrieve the Privacy Policy for the BRDZ Twitter Bot service. Used for compliance and privacy information display.

Response

200Privacy Policy retrieved successfully

{
  "success": true,
  "message": "BRDZ Twitter Bot Privacy Policy",
  "data": {
    "service_name": "BRDZ Twitter Bot",
    "version": "1.0.0",
    "privacy": {
      "title": "Privacy Policy for BRDZ Twitter Bot",
      "description": "This policy describes how BRDZ Twitter Bot collects and uses your information.",
      "data_collected": [
        "Twitter username and public profile information",
        "Tweet content for verification purposes",
        "Blockchain wallet addresses for reward distribution",
        "Transaction history for reward tracking"
      ],
      "data_usage": [
        "Verify Twitter account ownership",
        "Process and distribute rewards",
        "Maintain service security and functionality",
        "Comply with legal requirements"
      ],
      "data_sharing": "We do not share personal data with third parties except as required by law.",
      "data_retention": "Data is retained as long as necessary to provide services.",
      "contact": "privacy@brdz.link",
      "last_updated": "2024-01-01"
    }
  },
  "timestamp": "2024-01-15T11:50:00Z"
}

🔒 Authentication Requirements

All endpoints require API key authentication. User-level endpoints require JWT token. Admin endpoints require admin role authorization.

Headers Required

Content-Type: application/json
x-api-key: YOUR_API_KEY
Authorization: Bearer YOUR_JWT_TOKEN

Rate Limits

User endpoints: 100 requests/hour per user
Admin endpoints: 1000 requests/hour
Webhook endpoints: No rate limit (secured by signature validation)

🎯 Response Codes

Success Codes

200 - Operation successful
201 - Resource created successfully
202 - Request accepted for processing

Error Codes

400 - Bad request or invalid parameters
401 - Authentication required or invalid
403 - Insufficient permissions
404 - Resource not found
409 - Conflict (already exists)
410 - Resource expired
429 - Rate limit exceeded
500 - Internal server error
503 - Service unavailable

🔧 Environment Configuration

Required Environment Variables

# Twitter API Credentials
API_KEY_TWITTER=your_api_key
API_KEY_TWITTER_SECRET=your_api_secret  
BEARER_TOKEN_DEV_TWITTER=your_bearer_token
ACCESS_TOKEN_TWITTER=your_access_token
ACCESS_TOKEN_TWITTER_SECRET=your_access_secret

# Webhook Security
TWITTER_WEBHOOK_SECRET=your_webhook_secret

# Blockchain Configuration
ETHEREUM_RPC_URL=your_ethereum_rpc
POLYGON_RPC_URL=your_polygon_rpc
NEON_RPC_URL=your_neon_rpc

Service Dependencies

Twitter API v2 access
Blockchain RPC endpoints for USDC minting
Database for user verification and reward tracking
Webhook endpoint with HTTPS and signature validation

📊 Error Response Format

All error responses follow this consistent format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Common Error Codes

INVALID_TWITTER_USERNAME - Username format validation failed
ALREADY_VERIFIED - User already has verified Twitter account
VERIFICATION_EXPIRED - Verification code has expired
DAILY_LIMIT_REACHED - User has reached daily reward limit
USER_NOT_VERIFIED - User must verify Twitter account first
TWEET_ALREADY_REWARDED - Tweet has already received reward
INSUFFICIENT_PERMISSIONS - Admin access required

This completes the Twitter Bot API Reference documentation covering all 16 endpoints with detailed parameters, response examples, error handling, and integration guidelines.

🎯 What Can You Manage?​

🧩 Your Twitter Bot Building Blocks​

✅ Verification Blocks​

🎁 Reward System Blocks​

🔍 Twitter Integration Blocks​

🔗 Webhook Management Blocks​

📄 Static Content Blocks​

🏗️ Common Twitter Bot Patterns​

Pattern 1: "I want to verify my Twitter account"​

Pattern 2: "I want to earn rewards from mentions"​

Pattern 3: "I want to monitor bot activity"​

Pattern 4: "I want to check reward eligibility"​

🔗 Supported Networks​

✅ Verification Operations​

Initiate Twitter Verification​

Start Twitter Account Verification

Parameters

Request Body

Response

Complete Twitter Verification​

Complete Twitter Account Verification

Parameters

Request Body

Response

Check Verification Status​

Get Twitter Verification Status

Parameters

Response

🎁 Reward System Operations​

USDC Reward Minting​

Execute USDC Reward Minting via Bridge Contract

Parameters

Request Body

Response

Process Mention Rewards​

Process Mention/Retweet Rewards

Parameters

Request Body

Response

Get Rewards History​

Get User's Twitter Rewards History

Parameters

Response

Check Daily Limits​

Check Daily Reward Limits

Parameters

Response

🔍 Twitter Integration Operations​

Search Bot Mentions​

Search Twitter Bot Mentions (Admin Only)

Parameters

Response

Get Twitter User Info​

Get Twitter User Information

Parameters

Response

Get Service Health Status​

Twitter Bot Service Health Check

Response

🔗 Webhook Management Operations​

Get Webhook Status​

Get Webhook Service Status (Admin Only)

Response

Test Webhook Event​

Test Webhook Event Processing (Admin Only)

Parameters

Request Body

Response

Get Webhook Logs​

Get Webhook Processing Logs (Admin Only)

Parameters

Response

📄 Static Content Operations​

OAuth Callback​

Twitter OAuth Callback Handler

Response

Terms of Service​

Get Terms of Service

Response

Privacy Policy​

🎯 What Can You Manage?

🧩 Your Twitter Bot Building Blocks

✅ Verification Blocks

🎁 Reward System Blocks

🔍 Twitter Integration Blocks

🔗 Webhook Management Blocks

📄 Static Content Blocks

🏗️ Common Twitter Bot Patterns

Pattern 1: "I want to verify my Twitter account"

Pattern 2: "I want to earn rewards from mentions"

Pattern 3: "I want to monitor bot activity"

Pattern 4: "I want to check reward eligibility"

🔗 Supported Networks

✅ Verification Operations

Initiate Twitter Verification

Complete Twitter Verification

Check Verification Status

🎁 Reward System Operations

USDC Reward Minting

Process Mention Rewards

Get Rewards History

Check Daily Limits

🔍 Twitter Integration Operations

Search Bot Mentions

Get Twitter User Info

Get Service Health Status

🔗 Webhook Management Operations

Get Webhook Status

Test Webhook Event

Get Webhook Logs

📄 Static Content Operations

OAuth Callback

Terms of Service

Privacy Policy

🔒 Authentication Requirements

Headers Required

Rate Limits

🎯 Response Codes

Success Codes

Error Codes

🔧 Environment Configuration

Required Environment Variables

Service Dependencies

📊 Error Response Format

Common Error Codes