aitbc/docs/partner-integration.md

Partner Integration Guide

This guide helps third-party services integrate with the AITBC platform for explorers, analytics, and other services.

Overview

AITBC provides multiple integration points for partners:

• REST APIs for real-time data
• WebSocket streams for live updates
• Export endpoints for bulk data
• Webhook notifications for events

Getting Started

1. Register Your Application

Register your service to get API credentials:

curl -X POST https://aitbc.bubuit.net/api/v1/partners/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your Service Name",
    "description": "Brief description of your service",
    "website": "https://yourservice.com",
    "contact": "contact@yourservice.com",
    "integration_type": "explorer"
  }'

Response:

{
  "partner_id": "partner-uuid",
  "api_key": "aitbc_xxxxxxxxxxxx",
  "api_secret": "secret_xxxxxxxxxxxx",
  "rate_limit": {
    "requests_per_minute": 1000,
    "requests_per_hour": 50000
  }
}

2. Authenticate Requests

Use your API credentials for authenticated requests:

curl -H "Authorization: Bearer aitbc_xxxxxxxxxxxx" \
  https://aitbc.bubuit.net/api/explorer/blocks

API Endpoints

Blockchain Data

Get Latest Blocks

GET /api/explorer/blocks?limit={limit}&offset={offset}

Response:

{
  "blocks": [
    {
      "hash": "0x123...",
      "height": 1000000,
      "timestamp": "2025-12-28T18:00:00Z",
      "proposer": "0xabc...",
      "transaction_count": 150,
      "gas_used": "15000000",
      "size": 1024000
    }
  ],
  "total": 1000000
}

Get Block Details

GET /api/explorer/blocks/{block_hash}

Get Transaction

GET /api/explorer/transactions/{tx_hash}

Get Address Details

GET /api/explorer/addresses/{address}?transactions={true|false}

Marketplace Data

Get Active Offers

GET /api/v1/marketplace/offers?status=active&limit={limit}

Get Bid History

GET /api/v1/marketplace/bids?offer_id={offer_id}

Get Service Categories

GET /api/v1/marketplace/services/categories

Analytics Data

Get Network Stats

GET /api/v1/analytics/network/stats

Response:

{
  "total_blocks": 1000000,
  "total_transactions": 50000000,
  "active_addresses": 10000,
  "network_hashrate": 1500000000000,
  "average_block_time": 5.2,
  "marketplace_volume": {
    "24h": "1500000",
    "7d": "10000000",
    "30d": "40000000"
  }
}

Get Historical Data

GET /api/v1/analytics/historical?metric={metric}&period={period}&start={timestamp}&end={timestamp}

Metrics:

• block_count
• transaction_count
• active_addresses
• marketplace_volume
• gas_price

Periods:

• 1h, 1d, 1w, 1m

WebSocket Streams

Connect to the WebSocket for real-time updates:

const ws = new WebSocket('wss://aitbc.bubuit.net/ws');

// Authenticate
ws.send(JSON.stringify({
  type: 'auth',
  api_key: 'aitbc_xxxxxxxxxxxx'
}));

// Subscribe to blocks
ws.send(JSON.stringify({
  type: 'subscribe',
  channel: 'blocks'
}));

// Subscribe to transactions
ws.send(JSON.stringify({
  type: 'subscribe',
  channel: 'transactions',
  filters: {
    to_address: '0xabc...'
  }
}));

// Handle messages
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data);
};

Available Channels

• blocks - New blocks
• transactions - New transactions
• marketplace_offers - New marketplace offers
• marketplace_bids - New bids
• governance - Governance proposals and votes

Bulk Data Export

Export Blocks

POST /api/v1/export/blocks

Request:

{
  "start_block": 900000,
  "end_block": 1000000,
  "format": "json",
  "compression": "gzip"
}

Response:

{
  "export_id": "export-uuid",
  "estimated_size": "500MB",
  "download_url": "https://aitbc.bubuit.net/api/v1/export/download/export-uuid"
}

Export Transactions

POST /api/v1/export/transactions

Webhooks

Configure webhooks to receive event notifications:

curl -X POST https://aitbc.bubuit.net/api/v1/webhooks \
  -H "Authorization: Bearer aitbc_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourservice.com/webhook",
    "events": ["block.created", "transaction.confirmed"],
    "secret": "your_webhook_secret"
  }'

Webhook Payload:

{
  "event": "block.created",
  "timestamp": "2025-12-28T18:00:00Z",
  "data": {
    "block": {
      "hash": "0x123...",
      "height": 1000000,
      "proposer": "0xabc..."
    }
  },
  "signature": "sha256_signature"
}

Verify webhook signatures:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Rate Limits

API requests are rate-limited based on your partner tier:

Tier	Requests/Minute	Requests/Hour	Features
Basic	100	5,000	Public data
Pro	1,000	50,000	+ WebSocket
Enterprise	10,000	500,000	+ Bulk export

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640692800

SDKs and Libraries

Python SDK

from aitbc_sdk import AITBCClient

client = AITBCClient(
    api_key="aitbc_xxxxxxxxxxxx",
    base_url="https://aitbc.bubuit.net/api/v1"
)

# Get latest block
block = client.blocks.get_latest()
print(f"Latest block: {block.height}")

# Stream transactions
for tx in client.stream.transactions():
    print(f"New tx: {tx.hash}")

JavaScript SDK

import { AITBCClient } from 'aitbc-sdk-js';

const client = new AITBCClient({
  apiKey: 'aitbc_xxxxxxxxxxxx',
  baseUrl: 'https://aitbc.bubuit.net/api/v1'
});

// Get network stats
const stats = await client.analytics.getNetworkStats();
console.log('Network stats:', stats);

// Subscribe to blocks
client.subscribe('blocks', (block) => {
  console.log('New block:', block);
});

Explorer Integration Guide

Display Blocks

<div class="block-list">
  {% for block in blocks %}
  <div class="block-item">
    <a href="/block/{{ block.hash }}">
      Block #{{ block.height }}
    </a>
    <span class="timestamp">{{ block.timestamp }}</span>
    <span class="proposer">{{ block.proposer }}</span>
  </div>
  {% endfor %}
</div>

Transaction Details

async function showTransaction(txHash) {
  const tx = await client.transactions.get(txHash);
  
  document.getElementById('tx-hash').textContent = tx.hash;
  document.getElementById('tx-status').textContent = tx.status;
  document.getElementById('tx-from').textContent = tx.from_address;
  document.getElementById('tx-to').textContent = tx.to_address;
  document.getElementById('tx-amount').textContent = tx.amount;
  document.getElementById('tx-gas').textContent = tx.gas_used;
  
  // Show events
  const events = await client.transactions.getEvents(txHash);
  renderEvents(events);
}

Address Activity

async function loadAddress(address) {
  const [balance, transactions, tokens] = await Promise.all([
    client.addresses.getBalance(address),
    client.addresses.getTransactions(address),
    client.addresses.getTokens(address)
  ]);
  
  updateBalance(balance);
  renderTransactions(transactions);
  renderTokens(tokens);
}

Analytics Integration

Custom Dashboards

import plotly.graph_objects as go
from aitbc_sdk import AITBCClient

client = AITBCClient(api_key="your_key")

# Get historical data
data = client.analytics.get_historical(
  metric='transaction_count',
  period='1d',
  start='2025-01-01',
  end='2025-12-28'
)

# Create chart
fig = go.Figure()
fig.add_trace(go.Scatter(
  x=data.timestamps,
  y=data.values,
  mode='lines',
  name='Transactions per Day'
))

fig.show()

Real-time Monitoring

const client = new AITBCClient({ apiKey: 'your_key' });

// Monitor network health
client.subscribe('blocks', (block) => {
  const blockTime = calculateBlockTime(block);
  updateBlockTimeMetric(blockTime);
  
  if (blockTime > 10) {
    alert('Block time is high!');
  }
});

// Monitor marketplace activity
client.subscribe('marketplace_bids', (bid) => {
  updateBidChart(bid);
  checkForAnomalies(bid);
});

Best Practices

1. Caching: Cache frequently accessed data
2. Pagination: Use pagination for large datasets
3. Error Handling: Implement proper error handling
4. Rate Limiting: Respect rate limits and implement backoff
5. Security: Keep API keys secure and use HTTPS
6. Webhooks: Verify webhook signatures
7. Monitoring: Monitor your API usage and performance

Support

For integration support:

• Documentation: https://aitbc.bubuit.net/docs/
• API Reference: https://aitbc.bubuit.net/api/v1/docs
• Email: partners@aitbc.io
• Discord: https://discord.gg/aitbc

Example Implementations

Block Explorer

• GitHub: https://github.com/aitbc/explorer-example
• Demo: https://explorer.aitbc-example.com

Analytics Platform

• GitHub: https://github.com/aitbc/analytics-example
• Demo: https://analytics.aitbc-example.com

Mobile App

• GitHub: https://github.com/aitbc/mobile-example
• iOS: https://apps.apple.com/aitbc-wallet
• Android: https://play.google.com/aitbc-wallet

Changelog

v1.2.0 (2025-12-28)

• Added governance endpoints
• Improved WebSocket reliability
• New analytics metrics

v1.1.0 (2025-12-15)

• Added bulk export API
• Webhook support
• Python SDK improvements

v1.0.0 (2025-12-01)

• Initial release
• REST API v1
• WebSocket streams
• JavaScript SDK