Mini API

The TOS Mini API is a lightweight, efficient interface designed for mobile applications, IoT devices, and resource-constrained environments. It provides essential blockchain functionality with minimal overhead.

Overview

Design Principles

Minimal Resource Usage: Optimized for low-memory devices
Fast Response Times: Sub-100ms API responses
Battery Efficient: Reduced CPU and network usage
Offline Capability: Local caching and sync mechanisms
Security First: End-to-end encryption by default

Use Cases

Mobile Wallets: Smartphone and tablet applications
IoT Devices: Sensors and smart contracts
Embedded Systems: Hardware wallets and mining devices
Microservices: Lightweight blockchain integration
Edge Computing: Distributed processing nodes

API Endpoints

Base URL


Production:  https://mini-api.tos.network/v1
Testnet:     https://mini-api-testnet.tos.network/v1

Authentication


Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Wallet Operations

Get Balance


GET /wallet/balance/{address}

Parameters:

address (string): TOS wallet address

Response:


{
  "address": "tos1abc123...",
  "balance": {
    "available": "1000.500000",
    "locked": "50.000000",
    "total": "1050.500000"
  },
  "nonce": 42,
  "last_activity": "2024-03-20T10:30:00Z"
}

Create Transaction


POST /wallet/transaction

Request:


{
  "from": "tos1abc123...",
  "to": "tos1def456...",
  "amount": "10.500000",
  "fee": "0.001000",
  "nonce": 43,
  "private_key": "encrypted_private_key"
}

Response:


{
  "transaction_id": "tx_789xyz...",
  "status": "pending",
  "estimated_confirmation": "2024-03-20T10:32:15Z",
  "network_fee": "0.001000"
}

Transaction History


GET /wallet/history/{address}?limit=10&offset=0

Response:


{
  "transactions": [
    {
      "id": "tx_789xyz...",
      "type": "transfer",
      "amount": "10.500000",
      "fee": "0.001000",
      "from": "tos1abc123...",
      "to": "tos1def456...",
      "timestamp": "2024-03-20T10:30:00Z",
      "confirmations": 6,
      "status": "confirmed"
    }
  ],
  "total_count": 156,
  "has_more": true
}

Network Information

Network Status


GET /network/status

Response:


{
  "network": "mainnet",
  "block_height": 2891540,
  "block_time": 15.2,
  "hashrate": "125.5 PH/s",
  "difficulty": 18796541234567,
  "active_addresses": 89234,
  "total_supply": "8945123.000000",
  "ai_mining_percentage": 42.0
}

Block Information


GET /network/block/{height_or_hash}

Response:


{
  "height": 2891540,
  "hash": "block_hash_abc123...",
  "previous_hash": "prev_hash_def456...",
  "timestamp": "2024-03-20T10:30:00Z",
  "transactions_count": 45,
  "size": 2048,
  "miner": "tos1miner123...",
  "difficulty": 18796541234567,
  "reward": "50.000000"
}

Mining Operations

Mining Stats


GET /mining/stats/{address}

Response:


{
  "miner_address": "tos1miner123...",
  "hashrate": "2.5 TH/s",
  "blocks_found": 15,
  "last_block": "2024-03-20T09:45:00Z",
  "estimated_earnings": {
    "daily": "5.234000",
    "weekly": "36.638000",
    "monthly": "157.454000"
  },
  "efficiency": {
    "power_consumption": "1200W",
    "hash_per_watt": "2.08 GH/W"
  }
}

Submit Work


POST /mining/submit

Request:


{
  "miner_address": "tos1miner123...",
  "block_template": "template_hash_abc...",
  "nonce": 1234567890,
  "timestamp": "2024-03-20T10:30:00Z",
  "extra_nonce": "extra_123"
}

Response:


{
  "accepted": true,
  "block_hash": "new_block_hash_def...",
  "reward": "50.000000",
  "difficulty": 18796541234567
}

AI-Mining Integration

AI Task Information


GET /ai-mining/tasks/available

Response:


{
  "tasks": [
    {
      "task_id": "ai_task_123",
      "type": "machine_learning",
      "difficulty": "medium",
      "estimated_time": "2 hours",
      "reward": "12.500000",
      "requirements": {
        "min_ram": "8GB",
        "min_gpu": "GTX 1060",
        "frameworks": ["tensorflow", "pytorch"]
      },
      "deadline": "2024-03-21T10:30:00Z"
    }
  ],
  "total_available": 42
}

Submit AI Work


POST /ai-mining/submit

Request:


{
  "task_id": "ai_task_123",
  "worker_address": "tos1worker456...",
  "solution": "base64_encoded_solution",
  "metadata": {
    "processing_time": 7200,
    "algorithm_used": "neural_network_v2",
    "accuracy": 0.95
  }
}

Response:


{
  "submission_id": "sub_789xyz",
  "status": "evaluating",
  "estimated_evaluation_time": "30 minutes",
  "quality_score": 8.5,
  "potential_reward": "12.500000"
}

Smart Contract Integration

Contract Call


POST /contract/call

Request:


{
  "contract_address": "tos1contract123...",
  "method": "transfer",
  "parameters": ["tos1recipient456...", "100.000000"],
  "caller": "tos1caller789...",
  "gas_limit": 100000
}

Response:


{
  "transaction_id": "tx_contract_abc...",
  "gas_used": 85000,
  "result": {
    "success": true,
    "return_value": "true",
    "events": [
      {
        "event": "Transfer",
        "data": {
          "from": "tos1caller789...",
          "to": "tos1recipient456...",
          "amount": "100.000000"
        }
      }
    ]
  }
}

Contract State


GET /contract/state/{contract_address}

Response:


{
  "contract_address": "tos1contract123...",
  "balance": "1000.000000",
  "storage_size": 2048,
  "last_updated": "2024-03-20T10:30:00Z",
  "state_variables": {
    "total_supply": "1000000.000000",
    "owner": "tos1owner123...",
    "paused": false
  }
}

Caching and Offline Support

Sync Status


GET /sync/status

Response:


{
  "last_sync": "2024-03-20T10:30:00Z",
  "blocks_behind": 0,
  "sync_percentage": 100.0,
  "estimated_catch_up": "0 seconds",
  "cache_size": "15.2 MB",
  "offline_transactions": 3
}

Offline Transaction Queue


GET /offline/transactions

Response:


{
  "queued_transactions": [
    {
      "local_id": "offline_tx_1",
      "to": "tos1recipient456...",
      "amount": "5.000000",
      "created_at": "2024-03-20T09:45:00Z",
      "status": "pending_sync"
    }
  ],
  "queue_size": 3,
  "estimated_sync_time": "30 seconds"
}

Error Handling

Error Response Format


{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Wallet balance is insufficient for this transaction",
    "details": {
      "required": "10.500000",
      "available": "8.250000",
      "deficit": "2.250000"
    },
    "timestamp": "2024-03-20T10:30:00Z"
  }
}

Common Error Codes

Code	Description	HTTP Status
`INVALID_ADDRESS`	Wallet address format is invalid	400
`INSUFFICIENT_BALANCE`	Not enough funds for transaction	400
`NONCE_TOO_LOW`	Transaction nonce is outdated	400
`GAS_LIMIT_EXCEEDED`	Transaction requires more gas	400
`NETWORK_CONGESTION`	Network is temporarily busy	503
`RATE_LIMIT_EXCEEDED`	Too many requests	429
`UNAUTHORIZED`	Invalid API key or signature	401
`CONTRACT_NOT_FOUND`	Smart contract doesn’t exist	404

Rate Limiting

Limits by Plan

Plan	Requests/Minute	Burst Limit	Monthly Quota
Free	60	120	10,000
Developer	300	600	100,000
Business	1,200	2,400	1,000,000
Enterprise	Custom	Custom	Unlimited

Rate Limit Headers


X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1647781800
X-RateLimit-Retry-After: 60

SDK Examples

JavaScript/Node.js


const TOSMiniAPI = require('@tos-network/mini-api');
 
const client = new TOSMiniAPI({
  apiKey: 'your_api_key',
  network: 'mainnet' // or 'testnet'
});
 
// Get wallet balance
const balance = await client.wallet.getBalance('tos1abc123...');
console.log(`Balance: ${balance.total} TOS`);
 
// Send transaction
const tx = await client.wallet.sendTransaction({
  to: 'tos1def456...',
  amount: '10.5',
  privateKey: 'your_private_key'
});
console.log(`Transaction ID: ${tx.transaction_id}`);

Python


from tos_mini_api import TOSMiniClient
 
client = TOSMiniClient(
    api_key='your_api_key',
    network='mainnet'
)
 
# Get network status
status = client.network.get_status()
print(f"Block height: {status['block_height']}")
 
# Get mining stats
stats = client.mining.get_stats('tos1miner123...')
print(f"Hashrate: {stats['hashrate']}")

Swift (iOS)


import TOSMiniAPI
 
let client = TOSMiniClient(
    apiKey: "your_api_key",
    network: .mainnet
)
 
// Get balance
client.wallet.getBalance(address: "tos1abc123...") { result in
    switch result {
    case .success(let balance):
        print("Balance: \(balance.total) TOS")
    case .failure(let error):
        print("Error: \(error)")
    }
}

Kotlin (Android)


import network.tos.miniapi.TOSMiniClient
 
val client = TOSMiniClient(
    apiKey = "your_api_key",
    network = Network.MAINNET
)
 
// Coroutine example
lifecycleScope.launch {
    try {
        val balance = client.wallet.getBalance("tos1abc123...")
        println("Balance: ${balance.total} TOS")
    } catch (e: Exception) {
        println("Error: ${e.message}")
    }
}

Webhooks

Setup Webhook


POST /webhooks/create

Request:


{
  "url": "https://your-app.com/webhook",
  "events": ["transaction", "block", "ai_task_complete"],
  "secret": "webhook_secret_key"
}

Webhook Payload


{
  "event": "transaction",
  "timestamp": "2024-03-20T10:30:00Z",
  "data": {
    "transaction_id": "tx_789xyz...",
    "from": "tos1abc123...",
    "to": "tos1def456...",
    "amount": "10.500000",
    "confirmations": 6
  },
  "signature": "webhook_signature"
}

Performance Optimization

Caching Strategy

Balance Cache: 30 seconds
Block Data: 5 minutes
Network Stats: 1 minute
Transaction History: 10 minutes

Compression

All responses support gzip compression:


Accept-Encoding: gzip, deflate

Pagination


GET /wallet/history/tos1abc123...?page=2&per_page=25

Response Headers:


X-Total-Count: 156
X-Page-Count: 7
X-Current-Page: 2
X-Per-Page: 25

Security Features

API Key Management


POST /auth/api-key/rotate

Response:


{
  "new_api_key": "new_key_abc123...",
  "expires_at": "2024-06-20T10:30:00Z",
  "old_key_valid_until": "2024-03-21T10:30:00Z"
}

Request Signing


const crypto = require('crypto');
 
function signRequest(method, path, body, timestamp, secret) {
  const message = `${method}${path}${body}${timestamp}`;
  return crypto.createHmac('sha256', secret).update(message).digest('hex');
}

Testing and Development

Testnet Configuration


const client = new TOSMiniAPI({
  apiKey: 'test_key_123',
  network: 'testnet',
  baseURL: 'https://mini-api-testnet.tos.network/v1'
});

Mock Data

For development, use mock responses:


const client = new TOSMiniAPI({
  apiKey: 'mock_key',
  network: 'mock',
  useMockData: true
});

“Don’t Trust, Verify it” - The Mini API provides cryptographic proofs for all responses, allowing clients to verify data integrity independently!