> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomaestro.org/llms.txt
> Use this file to discover all available pages before exploring further.

> A drop-in replacement for Ethereum JSON-RPC interface supporting all standard methods.

# JSON-RPC

MIDL provides a single JSON-RPC endpoint that supports all standard Ethereum 2.0 JSON-RPC methods, making it a drop-in replacement for EVM-compatible blockchain interactions.

## JSON-RPC Methods:

* [Block](#block-methods)
* [Transaction](#transaction-methods)
* [Account](#account-methods)
* [Network](#network-methods)

### Block Methods

#### `eth_getBlockByNumber`

Get block information by block number.

**Parameters:**

1. `blockNumber` (string): Block number in hex or "latest", "earliest", "pending"
2. `includeTransactions` (boolean): If true, returns full transaction objects

**Example Request:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "eth_getBlockByNumber",
  "params": ["latest", true],
  "id": 1
}
```

**Example Response:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "number": "0x1b4",
    "hash": "0x1234567890abcdef...",
    "parentHash": "0x...",
    "gasLimit": "0x1c9c380",
    "gasUsed": "0x...",
    "timestamp": "0x...",
    "transactions": [...]
  }
}
```

#### `eth_getBlockByHash`

Get block information by block hash.

**Parameters:**

1. `blockHash` (string): Block hash in hexadecimal format
2. `includeTransactions` (boolean): If true, returns full transaction objects

**Example Request:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "eth_getBlockByHash",
  "params": ["0x1234567890abcdef...", true],
  "id": 1
}
```

#### `eth_blockNumber`

Get the current block number.

**Parameters:** None

**Example Request:**

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

**Example Response:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x4b7"
}
```

### Transaction Methods

#### `eth_getTransactionByHash`

Get transaction information by transaction hash.

**Parameters:**

1. `transactionHash` (string): Transaction hash in hexadecimal format

**Example Request:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "eth_getTransactionByHash",
  "params": ["0x1234567890abcdef..."],
  "id": 1
}
```

**Example Response:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "hash": "0x1234567890abcdef...",
    "blockNumber": "0x1b4",
    "blockHash": "0x...",
    "transactionIndex": "0x0",
    "from": "0x...",
    "to": "0x...",
    "value": "0x...",
    "gas": "0x5208",
    "gasPrice": "0x...",
    "input": "0x"
  }
}
```

#### `eth_getTransactionReceipt`

Get transaction receipt by transaction hash.

**Parameters:**

1. `transactionHash` (string): Transaction hash in hexadecimal format

**Example Request:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "eth_getTransactionReceipt",
  "params": ["0x1234567890abcdef..."],
  "id": 1
}
```

**Example Response:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "transactionHash": "0x1234567890abcdef...",
    "blockNumber": "0x1b4",
    "blockHash": "0x...",
    "transactionIndex": "0x0",
    "from": "0x...",
    "to": "0x...",
    "gasUsed": "0x5208",
    "cumulativeGasUsed": "0x5208",
    "status": "0x1",
    "logs": []
  }
}
```

### Account Methods

#### `eth_getBalance`

Get account balance for a specific address.

**Parameters:**

1. `address` (string): Account address in hexadecimal format
2. `blockParameter` (string): Block number in hex, or "latest", "earliest", "pending"

**Example Request:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "eth_getBalance",
  "params": ["0x1234567890abcdef...", "latest"],
  "id": 1
}
```

**Example Response:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x0234c8a3397aab58"
}
```

#### `eth_getTransactionCount`

Get the transaction count (nonce) for an account.

**Parameters:**

1. `address` (string): Account address in hexadecimal format
2. `blockParameter` (string): Block number in hex, or "latest", "earliest", "pending"

**Example Request:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "eth_getTransactionCount",
  "params": ["0x1234567890abcdef...", "latest"],
  "id": 1
}
```

**Example Response:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x1"
}
```

### Network Methods

#### `eth_gasPrice`

Get the current gas price.

**Parameters:** None

**Example Request:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "eth_gasPrice",
  "params": [],
  "id": 1
}
```

**Example Response:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x09184e72a000"
}
```

#### `eth_chainId`

Get the network chain ID.

**Parameters:** None

**Example Request:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "eth_chainId",
  "params": [],
  "id": 1
}
```

**Example Response:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x1"
}
```

## Error Handling

Standard JSON-RPC 2.0 error responses:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}
```

## Integration Examples

### Web3.js

```javascript theme={null}
const Web3 = require('web3');
const web3 = new Web3('https://midl-mainnet.gomaestro-api.org/v0');

// Set default headers for API key
web3.currentProvider.headers = {
  'api-key': 'YOUR_API_KEY'
};

// Get latest block
const block = await web3.eth.getBlock('latest');
```

### Ethers.js

```javascript theme={null}
const { JsonRpcProvider } = require('ethers');

const provider = new JsonRpcProvider('https://midl-mainnet.gomaestro-api.org/v0', {
  headers: {
    'api-key': 'YOUR_API_KEY'
  }
});

// Get account balance
const balance = await provider.getBalance('0x...');
```

## Rate Limits

API calls are subject to your plan's rate limits. See [billing documentation](/account/manage-billing) for details on threshold billing and plan limits.


## OpenAPI

````yaml midl/node-rpc-api/openapi.json post /rpc
openapi: 3.1.0
info:
  description: >-
    Drop-in replacement for Ethereum JSON-RPC interface supporting all standard
    methods: eth_getBlockByNumber, eth_getBlockByHash, eth_blockNumber,
    eth_getTransactionByHash, eth_getTransactionReceipt, eth_getBalance,
    eth_getTransactionCount, eth_gasPrice, eth_chainId
  title: MIDL - Node RPC API
  version: 1.0.0
servers:
  - description: Midl Regtest
    url: https://midl-regtest.gomaestro-api.org/v0
security: []
externalDocs:
  description: ''
  url: ''
paths:
  /rpc:
    post:
      tags:
        - JSON-RPC
      summary: JSON-RPC
      description: Drop-in replacement for MIDL EVM JSON-RPC interface.
      operationId: json-rpc
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcRequest'
            examples:
              eth_blockNumber:
                summary: Get current block number
                value:
                  jsonrpc: '2.0'
                  method: eth_blockNumber
                  params: []
                  id: 1
              eth_getBlockByNumber:
                summary: Get block by number
                value:
                  jsonrpc: '2.0'
                  method: eth_getBlockByNumber
                  params:
                    - latest
                    - true
                  id: 1
              eth_getBlockByHash:
                summary: Get block by hash
                value:
                  jsonrpc: '2.0'
                  method: eth_getBlockByHash
                  params:
                    - >-
                      0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
                    - true
                  id: 1
              eth_getTransactionByHash:
                summary: Get transaction by hash
                value:
                  jsonrpc: '2.0'
                  method: eth_getTransactionByHash
                  params:
                    - >-
                      0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
                  id: 1
              eth_getTransactionReceipt:
                summary: Get transaction receipt
                value:
                  jsonrpc: '2.0'
                  method: eth_getTransactionReceipt
                  params:
                    - >-
                      0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
                  id: 1
              eth_getBalance:
                summary: Get account balance
                value:
                  jsonrpc: '2.0'
                  method: eth_getBalance
                  params:
                    - '0x1234567890abcdef1234567890abcdef12345678'
                    - latest
                  id: 1
              eth_getTransactionCount:
                summary: Get transaction count (nonce)
                value:
                  jsonrpc: '2.0'
                  method: eth_getTransactionCount
                  params:
                    - '0x1234567890abcdef1234567890abcdef12345678'
                    - latest
                  id: 1
              eth_gasPrice:
                summary: Get gas price
                value:
                  jsonrpc: '2.0'
                  method: eth_gasPrice
                  params: []
                  id: 1
              eth_chainId:
                summary: Get chain ID
                value:
                  jsonrpc: '2.0'
                  method: eth_chainId
                  params: []
                  id: 1
        description: JSON-RPC request payload
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    jsonrpc: '2.0'
                    id: 1
                    result: '0x1b4'
                block_response:
                  summary: Block response
                  value:
                    jsonrpc: '2.0'
                    id: 1
                    result:
                      number: '0x1b4'
                      hash: >-
                        0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
                      parentHash: >-
                        0x0987654321fedcba0987654321fedcba0987654321fedcba0987654321fedcba
                      gasLimit: '0x1c9c380'
                      gasUsed: '0x5208'
                      timestamp: '0x61bc3f3c'
                      transactions: []
          description: JSON-RPC response payload
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
              example:
                jsonrpc: '2.0'
                id: 1
                error:
                  code: -32600
                  message: Invalid Request
          description: Bad request - Invalid JSON-RPC
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
              example:
                jsonrpc: '2.0'
                id: 1
                error:
                  code: -32601
                  message: Method not found
          description: Server error - Method not found or internal error
      security:
        - ApiKeyAuth: []
components:
  schemas:
    JsonRpcRequest:
      type: object
      required:
        - jsonrpc
        - method
        - id
      properties:
        jsonrpc:
          type: string
          enum:
            - '2.0'
          description: JSON-RPC version
        method:
          type: string
          description: The RPC method to call
          enum:
            - eth_getBlockByNumber
            - eth_getBlockByHash
            - eth_blockNumber
            - eth_getTransactionByHash
            - eth_getTransactionReceipt
            - eth_getBalance
            - eth_getTransactionCount
            - eth_gasPrice
            - eth_chainId
        params:
          type: array
          description: Method parameters
          items: {}
        id:
          oneOf:
            - type: string
            - type: number
          description: Request identifier
    JsonRpcResponse:
      type: object
      required:
        - jsonrpc
        - id
      properties:
        jsonrpc:
          type: string
          enum:
            - '2.0'
        id:
          oneOf:
            - type: string
            - type: number
        result:
          description: Result data (present on success)
        error:
          type: object
          description: Error object (present on error)
          properties:
            code:
              type: integer
            message:
              type: string
  securitySchemes:
    ApiKeyAuth:
      description: Project API Key
      in: header
      name: api-key
      type: apiKey

````