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

# API Reference

**Last Updated**: 2025-01-27  
**Status**: Active  
**Base URL**: `https://rpc.d-bis.org`

## Table of Contents

- [Overview](#overview)
- [Authentication](#authentication)
- [JSON-RPC Methods](#json-rpc-methods)
- [Request/Response Format](#requestresponse-format)
- [Error Handling](#error-handling)
- [Rate Limits](#rate-limits)
- [Examples](#examples)

## Overview

This API provides JSON-RPC 2.0 endpoints for interacting with the DeFi Oracle Meta Mainnet (ChainID 138).

## Authentication

Currently, the public RPC endpoint does not require authentication. Rate limiting is applied per IP address.

> **Note**: For production applications, consider using authenticated endpoints or API keys.

## JSON-RPC Methods

### Standard Ethereum Methods

All standard Ethereum JSON-RPC methods are supported. See [Ethereum JSON-RPC Specification](https://ethereum.org/en/developers/docs/apis/json-rpc/) for complete reference.

#### Common Methods

- `eth_blockNumber` - Get latest block number
- `eth_getBalance` - Get account balance
- `eth_getTransactionCount` - Get transaction count (nonce)
- `eth_sendTransaction` - Send transaction
- `eth_call` - Execute call without creating transaction
- `eth_getTransactionReceipt` - Get transaction receipt
- `eth_getLogs` - Get event logs

### Example Request

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

### Example Response

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

## Request/Response Format

### Request Format

```json
{
  "jsonrpc": "2.0",
  "method": "method_name",
  "params": [param1, param2],
  "id": 1
}
```

### Response Format

**Success**:
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "result_data"
}
```

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

## Error Handling

### Error Codes

| Code | Meaning | Description |
|------|---------|-------------|
| -32700 | Parse error | Invalid JSON |
| -32600 | Invalid Request | JSON is not a valid request |
| -32601 | Method not found | Method does not exist |
| -32602 | Invalid params | Invalid method parameters |
| -32603 | Internal error | Internal JSON-RPC error |
| -32000 | Server error | Generic server error |
| -32001 | Rate limit | Rate limit exceeded |

### Error Response Example

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Rate limit exceeded",
    "data": {
      "limit": 1200,
      "window": "1 minute"
    }
  }
}
```

## Rate Limits

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

Rate limit headers are included in responses:
- `X-RateLimit-Limit`: Maximum requests allowed
- `X-RateLimit-Remaining`: Remaining requests in window
- `X-RateLimit-Reset`: Time when limit resets

## Examples

### Get Latest 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 Account Balance

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

### Call Contract Method

```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 Transaction Receipt

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

## Related Documentation

- [API Overview](API.md)
- [Blockscout API](BLOCKSCOUT_API.md)
- [Tatum SDK](TATUM_SDK.md)
- [Integration Guide](../guides/INTEGRATION_GUIDE.md)

---

**Last Updated**: 2025-01-27