smom-dbis-138/docs/api/API.md

# API Documentation

## JSON-RPC API

The DeFi Oracle Meta Mainnet provides a public JSON-RPC API for reading blockchain data.

### Endpoint

- **HTTPS**: `https://rpc.d-bis.org`
- **WebSocket**: `wss://rpc.d-bis.org`
- **Secondary HTTPS**: `https://rpc2.d-bis.org`
- **Domain**: `d-bis.org` (Cloudflare DNS/SSL)

### Authentication

Currently, authentication is not required for public endpoints. API keys may be required in the future.

### Rate Limits

- **Default**: 1200 requests/minute per IP
- **eth_call**: 600 requests/minute
- **eth_getLogs**: 300 requests/minute
- **eth_getBlockByNumber**: 600 requests/minute
- **eth_getTransactionReceipt**: 600 requests/minute
- **eth_estimateGas**: 300 requests/minute

### Allowed Methods

#### Read Operations

- `eth_blockNumber` - Get current block number
- `eth_call` - Execute a message call
- `eth_estimateGas` - Estimate gas for a transaction
- `eth_gasPrice` - Get current gas price
- `eth_getBalance` - Get account balance
- `eth_getBlockByHash` - Get block by hash
- `eth_getBlockByNumber` - Get block by number
- `eth_getBlockTransactionCountByHash` - Get transaction count in block
- `eth_getBlockTransactionCountByNumber` - Get transaction count in block
- `eth_getCode` - Get contract code
- `eth_getLogs` - Get logs (limited to 10,000 blocks)
- `eth_getStorageAt` - Get storage at address
- `eth_getTransactionByHash` - Get transaction by hash
- `eth_getTransactionByBlockHashAndIndex` - Get transaction by block and index
- `eth_getTransactionByBlockNumberAndIndex` - Get transaction by block and index
- `eth_getTransactionCount` - Get transaction count (nonce)
- `eth_getTransactionReceipt` - Get transaction receipt
- `eth_getUncleByBlockHashAndIndex` - Get uncle by block and index
- `eth_getUncleByBlockNumberAndIndex` - Get uncle by block and index
- `eth_getUncleCountByBlockHash` - Get uncle count by block hash
- `eth_getUncleCountByBlockNumber` - Get uncle count by block number
- `eth_protocolVersion` - Get protocol version
- `eth_syncing` - Get sync status
- `net_listening` - Check if node is listening
- `net_peerCount` - Get peer count
- `net_version` - Get network version
- `web3_clientVersion` - Get client version
- `web3_sha3` - Hash data with keccak256

#### Blocked Methods

The following methods are blocked for public users:

- `eth_sendTransaction` - Send transaction (write operation)
- `eth_sendRawTransaction` - Send raw transaction (write operation)
- `miner_*` - Mining operations
- `admin_*` - Admin operations
- `debug_*` - Debug operations (except limited trace operations)

### Request Format

```json
{
  "jsonrpc": "2.0",
  "method": "eth_blockNumber",
  "params": [],
  "id": 1
}
```

### Response Format

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x1234"
}
```

### Error Format

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "execution reverted"
  }
}
```

## Examples

### Get Block Number

```bash
curl -X POST https://rpc.d-bis.org \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_blockNumber",
    "params": [],
    "id": 1
  }'
```

### Get Block by Number

```bash
curl -X POST https://rpc.d-bis.org \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBlockByNumber",
    "params": ["latest", false],
    "id": 1
  }'
```

### Call Contract

```bash
curl -X POST https://rpc.d-bis.org \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_call",
    "params": [{
      "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "data": "0x70a08231000000000000000000000000742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
    }, "latest"],
    "id": 1
  }'
```

### Get Logs

```bash
curl -X POST https://rpc.d-bis.org \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getLogs",
    "params": [{
      "fromBlock": "0x0",
      "toBlock": "latest",
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
    }],
    "id": 1
  }'
```

## WebSocket API

### Connection

```javascript
const ws = new WebSocket('wss://rpc.d-bis.org');

ws.onopen = () => {
  ws.send(JSON.stringify({
    jsonrpc: "2.0",
    method: "eth_subscribe",
    params: ["newHeads"],
    id: 1
  }));
};

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

## Chain Metadata

- **ChainID**: 138
- **Network Name**: DeFi Oracle Meta Mainnet
- **Native Currency**: ETH
- **Block Time**: ~2 seconds
- **Explorer**: https://explorer.d-bis.org

## Rate Limit Headers

When rate limits are approached, the following headers are included in responses:

- `X-RateLimit-Limit`: Maximum requests per minute
- `X-RateLimit-Remaining`: Remaining requests in current window
- `X-RateLimit-Reset`: Time when the rate limit resets

## Error Codes

- `-32700`: Parse error
- `-32600`: Invalid request
- `-32601`: Method not found
- `-32602`: Invalid params
- `-32603`: Internal error
- `-32000`: Execution error
- `-32001`: Resource not found
- `-32002`: Resource unavailable
- `-32003`: Transaction rejected
- `-32004`: Method not supported
- `-32005`: Limit exceeded

## Support

For API support, please contact the network operators or open an issue on the project repository.