aitbc/docs/api/blockchain/README.md

Blockchain Node API

The Blockchain Node API provides access to blockchain operations including block queries, transaction submission, and network status.

Base URL

• Production: https://aitbc.bubuit.net/api
• Staging: https://staging-api.aitbc.io
• Development: http://localhost:8080

Endpoints

Block Operations

Get Block by Height

GET /v1/blocks/{height}

Retrieve a block by its height.

Parameters:

• height (path parameter): Block height as integer

Response: 200 OK

{
  "height": 12345,
  "hash": "0x...",
  "parent_hash": "0x...",
  "timestamp": "2026-05-11T10:00:00Z",
  "transactions": [],
  "state_root": "0x...",
  "difficulty": 1000
}

Get Head Block

GET /v1/blocks/head

Retrieve the latest (head) block in the blockchain.

Response: 200 OK

{
  "height": 12345,
  "hash": "0x...",
  "parent_hash": "0x...",
  "timestamp": "2026-05-11T10:00:00Z",
  "transactions": [],
  "state_root": "0x...",
  "difficulty": 1000
}

Get Block Range

GET /v1/blocks?from={start}&to={end}

Retrieve a range of blocks.

Parameters:

• from (query): Starting block height
• to (query): Ending block height

Response: 200 OK

[
  {
    "height": 12345,
    "hash": "0x...",
    "timestamp": "2026-05-11T10:00:00Z"
  }
]

Transaction Operations

Get Transaction

GET /v1/transactions/{tx_hash}

Retrieve a transaction by its hash.

Parameters:

• tx_hash (path parameter): Transaction hash

Response: 200 OK

{
  "hash": "0x...",
  "block_height": 12345,
  "from": "0x...",
  "to": "0x...",
  "value": 1000,
  "gas_used": 21000,
  "timestamp": "2026-05-11T10:00:00Z"
}

Submit Transaction

POST /v1/transactions

Submit a new transaction to the blockchain.

Request Body:

{
  "from": "0x...",
  "to": "0x...",
  "value": 1000,
  "gas": 21000,
  "data": "0x...",
  "signature": "0x..."
}

Response: 201 Created

{
  "hash": "0x...",
  "status": "pending"
}

Network Status

Get Network Info

GET /v1/network

Retrieve network status and information.

Response: 200 OK

{
  "chain_id": 1,
  "block_height": 12345,
  "peer_count": 42,
  "sync_status": "synced",
  "version": "1.0.0"
}

Get Peers

GET /v1/network/peers

Retrieve list of connected peers.

Response: 200 OK

[
  {
    "peer_id": "Qm...",
    "address": "192.168.1.100:8080",
    "latency_ms": 50,
    "is_outbound": true
  }
]

Smart Contract Operations

Call Contract

POST /v1/contracts/{address}/call

Call a smart contract method (read-only).

Request Body:

{
  "method": "balanceOf",
  "args": ["0x..."]
}

Response: 200 OK

{
  "result": "0x...",
  "gas_used": 1000
}

Send Transaction to Contract

POST /v1/contracts/{address}/transact

Send a transaction to a smart contract (state-changing).

Request Body:

{
  "method": "transfer",
  "args": ["0x...", 1000],
  "gas": 100000,
  "value": 0
}

Response: 201 Created

{
  "hash": "0x...",
  "status": "pending"
}

Examples

cURL

# Get head block
curl http://localhost:8080/v1/blocks/head

# Get block by height
curl http://localhost:8080/v1/blocks/12345

# Get network info
curl http://localhost:8080/v1/network

# Submit transaction
curl -X POST http://localhost:8080/v1/transactions \
  -H "Content-Type: application/json" \
  -d '{
    "from": "0x...",
    "to": "0x...",
    "value": 1000,
    "gas": 21000,
    "signature": "0x..."
  }'

Python SDK

import aitbc_sdk

client = aitbc_sdk.BlockchainClient(base_url="http://localhost:8080")

# Get head block
head_block = client.get_head_block()
print(f"Current height: {head_block['height']}")

# Get block by height
block = client.get_block(height=12345)

# Get network info
network = client.get_network_info()
print(f"Peer count: {network['peer_count']}")

WebSocket

Real-time blockchain events are available via WebSocket connection:

ws://localhost:8080/v1/events

The WebSocket sends events as JSON messages:

{
  "type": "new_block",
  "block": {
    "height": 12346,
    "hash": "0x...",
    "timestamp": "2026-05-11T10:05:00Z"
  }
}

Rate Limits

• Block queries: 1000 requests per minute
• Transaction submission: 100 requests per minute
• Contract calls: 500 requests per minute

OpenAPI Specification

The complete OpenAPI 3.1.0 specification is available in openapi.json.