API Reference

Complete API documentation for BitMshauri bot integrations

Table of Contents

API Overview

Introduction

BitMshauri bot provides several API integrations for external services and applications. This documentation covers all available APIs and their usage.

Base URL

https://api.bitmshauri.com

All API endpoints are relative to this base URL

Authentication

Authorization: Bearer YOUR_API_KEY

Include your API key in the Authorization header

Response Format

Content-Type: application/json

All responses are returned in JSON format

Common Response Structure

Success Response

{
  "success": true,
  "data": {
    // Response data here
  },
  "message": "Operation completed successfully",
  "timestamp": "2024-01-15T10:30:00Z"
}

Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid parameters provided",
    "details": "Missing required field: user_id"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Telegram Bot API

Bot Commands

The bot responds to various commands and natural language inputs:

POST /bot/command

Send Bot Command

Send a command to the bot programmatically

Request Body
{
  "user_id": 123456789,
  "command": "/price",
  "parameters": {}
}
Response
{
  "success": true,
  "data": {
    "message_id": 987654321,
    "response": "Bitcoin price: $43,250.00 USD"
  }
}
GET /bot/status

Bot Status

Check the current status of the bot

Response
{
  "success": true,
  "data": {
    "status": "online",
    "uptime": "24h 15m 30s",
    "active_users": 1250,
    "total_commands": 15420
  }
}

Price API Integration

Cryptocurrency Price Data

Access real-time cryptocurrency price information:

GET /price/bitcoin

Get Bitcoin Price

Retrieve current Bitcoin price in multiple currencies

Query Parameters
  • currency - Target currency (USD, TZS, EUR, etc.)
  • format - Response format (json, simple)
Response
{
  "success": true,
  "data": {
    "price_usd": 43250.00,
    "price_tzs": 108125000.00,
    "change_24h": 2.45,
    "market_cap": 847500000000,
    "volume_24h": 28500000000,
    "last_updated": "2024-01-15T10:30:00Z"
  }
}
GET /price/convert

Currency Conversion

Convert between different currencies and Bitcoin

Query Parameters
  • amount - Amount to convert
  • from - Source currency
  • to - Target currency
Example Request
GET /price/convert?amount=100&from=USD&to=BTC
Response
{
  "success": true,
  "data": {
    "amount": 100,
    "from": "USD",
    "to": "BTC",
    "result": 0.00231,
    "rate": 43250.00,
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

AI Integration

AI-Powered Q&A

Access the AI-powered question answering system:

POST /ai/ask

Ask AI Question

Send a question to the AI system for Bitcoin-related answers

Request Body
{
  "question": "What is Bitcoin?",
  "language": "en",
  "context": "beginner"
}
Response
{
  "success": true,
  "data": {
    "answer": "Bitcoin is a decentralized digital currency...",
    "confidence": 0.95,
    "sources": ["bitcoin.org", "wikipedia.org"],
    "related_topics": ["blockchain", "cryptography", "mining"]
  }
}
GET /ai/topics

Get AI Topics

Retrieve available topics for AI questions

Response
{
  "success": true,
  "data": {
    "topics": [
      "bitcoin_basics",
      "blockchain_technology",
      "mining",
      "wallet_security",
      "trading",
      "regulation"
    ]
  }
}

Webhooks

Real-time Notifications

Receive real-time notifications about bot events:

Webhook Configuration

Configure webhooks to receive notifications about:

  • New user registrations
  • Lesson completions
  • Price alerts
  • Group activities
Webhook URL Format
POST https://your-domain.com/webhook/bitmshauri
Webhook Payload Example
{
  "event": "user_registered",
  "user_id": 123456789,
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "username": "john_doe",
    "language": "en"
  }
}

Rate Limits

API Rate Limiting

To ensure fair usage, the API implements rate limiting:

Free Tier

  • 100 requests per hour
  • Basic price data
  • Limited AI queries

Pro Tier

  • 1000 requests per hour
  • Full price data
  • Unlimited AI queries
  • Webhook support

Rate Limit Headers

The API includes rate limit information in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642233600

Usage Examples

Code Examples

Here are some practical examples of how to use the API:

Python Example

import requests

# Get Bitcoin price
response = requests.get(
    'https://api.bitmshauri.com/price/bitcoin',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

if response.status_code == 200:
    data = response.json()
    price = data['data']['price_usd']
    print(f"Bitcoin price: ${price:,.2f}")

JavaScript Example

// Ask AI question
const response = await fetch('https://api.bitmshauri.com/ai/ask', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify({
        question: 'What is blockchain?',
        language: 'en'
    })
});

const data = await response.json();
console.log(data.data.answer);

cURL Example

# Convert currency
curl -X GET \
  "https://api.bitmshauri.com/price/convert?amount=100&from=USD&to=BTC" \
  -H "Authorization: Bearer YOUR_API_KEY"