API Documentation

Complete API reference for integrating with the ReserveBTC protocol, including Oracle endpoints, balance verification, and signature validation.

API Overview

REST API

Standard HTTP endpoints for balance queries, verification, and Oracle data

Real-time Updates

WebSocket connections for live balance updates and synchronization events

Authentication

Signature-based authentication using EVM wallets and BIP-322 verification

Base URL

TESTNEThttps://app.reservebtc.io/api

Currently deployed on MegaETH Testnet. All API endpoints are prefixed with this base URL.

Oracle API

Note: Oracle API endpoints are used by the Oracle server for automated balance synchronization. Direct user access requires Oracle committee authorization.

GET/api/oracle/sync

Get Oracle system status and configuration

Response Example:

{
  "success": true,
  "data": {
    "committee": "0xea8fFEe94Da08f65765EC2A095e9931FD03e6c1b",
    "minConfirmations": "1",
    "maxFeePerSync": "10000000000000000",
    "chainId": 6342,
    "contractAddress": "0x611AFD3808e732Ba89A0D9991d2902b0Df9bd149"
  }
}

POST/api/oracle/sync

Synchronize user's Bitcoin balance with smart contracts. Requires Oracle committee authorization.

Request Body:

{
  "userAddress": "0x1234...5678",
  "btcBalance": "0.12345678",
  "blockHeight": 870000,
  "timestamp": 1698765432
}

Response Example:

{
  "success": true,
  "transactionHash": "0xabc123...",
  "gasUsed": "89432"
}

Wallet Verification API

Note: This endpoint is currently a mock implementation for testing purposes. Real BIP-322 verification will be implemented in production.

POST/api/verify-wallet

Verify Bitcoin address ownership using BIP-322 signature

Request Body:

{
  "bitcoinAddress": "[YOUR_BITCOIN_ADDRESS]",
  "ethereumAddress": "0x1234567890123456789012345678901234567890",
  "message": "ReserveBTC Verification Message",
  "signature": "base64_encoded_signature"
}

Response Example:

{
  "success": true,
  "data": {
    "bitcoinAddress": "[YOUR_BITCOIN_ADDRESS]",
    "ethereumAddress": "0x1234567890123456789012345678901234567890",
    "verified": true,
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

Token Minting API

Important: This endpoint is a mock implementation. In the actual Oracle-based architecture, tokens are minted automatically by the Oracle when Bitcoin balance changes are detected.

POST/api/mint-rbtc

Mock endpoint for rBTC token minting (actual minting is handled by Oracle)

Request Body:

{
  "amount": "0.12345678",
  "bitcoinAddress": "[YOUR_BITCOIN_ADDRESS]",
  "ethereumAddress": "0x1234567890123456789012345678901234567890",
  "amountSatoshis": 12345678
}

Response Example:

{
  "success": true,
  "txHash": "0xabc123def456...",
  "amount": "0.12345678",
  "rbtcAmount": "0.12345678"
}

Token Information API

GET/tokens/info

Get information about ReserveBTC tokens

Response Example:

{
  "success": true,
  "data": {
    "rbtcSynth": {
      "address": "0x37fE059490B70e2605cb3D6fD64F5292d3eB46dE",
      "name": "ReserveBTC Synthetic",
      "symbol": "rBTC-SYNTH",
      "decimals": 8,
      "totalSupply": "123.45678900",
      "soulbound": true
    },
    "wrbtc": {
      "address": "0xa10FC332f12d102Dddf431F8136E4E89279EFF87",
      "name": "Wrapped ReserveBTC",
      "symbol": "wrBTC",
      "decimals": 8,
      "totalSupply": "67.89012345",
      "transferable": true
    }
  }
}

Error Responses

Standard Error Format

{
  "success": false,
  "error": "Error message description",
  "code": "ERROR_CODE",
  "details": {}
}

Common HTTP Status Codes

200 - Success
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
429 - Rate Limited
500 - Internal Server Error

Common Error Codes

INVALID_ADDRESS - Invalid Bitcoin address
SIGNATURE_INVALID - BIP-322 signature failed
BALANCE_MISMATCH - Balance verification failed
RATE_LIMITED - Too many requests
ORACLE_ERROR - Oracle system error
CONTRACT_ERROR - Smart contract error

⚡ Important Notes

Current Implementation Status

• Only 4 API endpoints are currently implemented
• Oracle sync endpoint is fully functional for committee members
• Wallet verification and minting endpoints are mock implementations
• Real Bitcoin integration via Oracle server (oracle-server.js)

Oracle-Based Architecture

• Users don't directly mint tokens via API
• Oracle monitors Bitcoin addresses and automatically syncs balances
• Token minting/burning is handled by Oracle sync function
• See integration guide for proper usage patterns

Development Resources

SDK (Planned)

JavaScript/TypeScript SDK is in development

Documentation →

Smart Contracts

Complete ABI documentation and examples

View ABIs →

Integration Guide

Step-by-step integration examples

Get Started →

SDK Documentation Integration Guide