### Example error response for -32005 (query too dense)

Source: https://routeme.sh/docs/intro/rpc-error-codes

Example JSON-RPC error response for code -32005, indicating the query exceeds max results and suggesting a maximum of 1025 blocks.

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32005,
    "message": "query exceeds max results; try a block range of at most 1025 blocks"
  }
}
```

--------------------------------

### Service Health Response Example

Source: https://routeme.sh/docs/api-reference

The expected JSON response when the service is healthy.

```json
{
  "success": true,
  "message": "The service is ready to serve requests"
}
```

--------------------------------

### GET /chains/ws

Source: https://routeme.sh/docs/intro/websockets

Retrieves the list of chains currently supported over WebSocket subscriptions.

```APIDOC
## GET /chains/ws

### Description
Returns the set of chains currently supported over WebSocket connections. Use this to discover available chains.

### Method
GET

### Endpoint
GET /chains/ws

### Response
- **Response** - Contains a list of supported chains (not specified in source).
```

--------------------------------

### Check Service Health with Go

Source: https://routeme.sh/docs/api-reference

Use the net/http package to perform a GET request to the health endpoint.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.routeme.sh/health"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### GET /provider/plans

Source: https://routeme.sh/docs/api-reference/provider/list-my-plans

Retrieves a list of pricing plans for the authenticated provider. Returns an empty array if no plans are associated with the provider.

```APIDOC
## GET /provider/plans

### Description
Returns the authenticated provider's pricing plans, or an empty array when the provider has none. Plan creation and pricing edits remain admin-managed.

### Method
GET

### Endpoint
https://api.routeme.sh/provider/plans

### Response
#### Success Response (200)
- **Array** (ProviderPlan) - List of plans or empty array

#### Error Responses
- **401** - Unauthorized
- **403** - Provider not resolved - token's customer is not linked to a provider
- **500** - Internal server error
```

--------------------------------

### GET /provider/plans/{planId}/methods

Source: https://routeme.sh/docs/api-reference/provider/list-a-plans-rpc-methods

Lists the RPC method rows configured for a plan owned by the authenticated provider. Returns an empty array when the plan has no methods. Plans not owned by the caller's provider are reported as 404.

```APIDOC
## GET /provider/plans/{planId}/methods

### Description
Returns the RPC method rows configured for one of the authenticated provider's plans. Returns an empty array when the plan has no methods. Plans not owned by the caller's provider are reported as 404.

### Method
GET

### Endpoint
https://api.routeme.sh/provider/plans/{planId}/methods

### Parameters
#### Path Parameters
- **planId** (integer) - Required - Numeric plan ID.

### Authentication
- **X-Api-Key** (header) - Required - Management token from the RouteMesh dashboard (Settings → Management Tokens). Tokens are prefixed rmtm_ and scoped to your account.

### Response
#### Success Response (200)
- **array of ProviderPlanMethod** - List of method rows or empty array

Each ProviderPlanMethod object has the following properties:
- **method** (string) - RPC method name, e.g. eth_blockNumber.
- **vm** (string) - Virtual machine type, e.g. evm.
- **node_target_type** (string) - Node target type the method routes to.
- **cost** (integer) - Credit cost per call (0 = free).
- **rate_limit** (integer, nullable) - Optional per-call rate limit.
- **rate_limit_interval_sec** (integer, nullable) - Rate limit window in seconds.
- **chain_id** (string, nullable) - Chain this cost applies to; null/omitted for all chains.

#### Response Example
```json
[
  {
    "method": "eth_blockNumber",
    "vm": "evm",
    "node_target_type": "full",
    "cost": 1,
    "rate_limit": 100,
    "rate_limit_interval_sec": 60,
    "chain_id": "1"
  }
]
```

#### Error Responses
- **400** - Invalid plan id
- **401** - Unauthorized
- **403** - Provider not resolved
- **404** - Plan not found (or not owned by the caller's provider)
- **500** - Internal server error
```

--------------------------------

### OpenAPI definition for /usage

Source: https://routeme.sh/docs/api-reference/usage/get-usage-data

The OpenAPI specification for the GET /usage endpoint, detailing parameters like time range, grouping, and granularity.

```yaml
openapi: 3.0.0
info:
  title: RouteMesh API
  version: 1.0.0
  description: >-
    HTTP API for routing JSON-RPC requests across providers, managing API keys,
    and viewing usage.
  license:
    name: Proprietary
    url: https://routeme.sh
servers:
  - url: https://api.routeme.sh
    description: API server — health, chains, API keys, usage, and public submissions
  - url: https://lb.routeme.sh
    description: RPC router (primary load balancer)
  - url: https://lb2.routeme.sh
    description: RPC router (AWS backup load balancer)
security: []
tags:
  - name: RPC
    description: Forward JSON-RPC requests to the router.
  - name: Chains
    description: Discover supported chains.
  - name: Submissions
    description: Public chain and node listing requests (rate-limited per IP).
  - name: API Keys
    description: Manage your API keys for self-service access.
  - name: Usage
    description: View your usage and billing data.
  - name: Pricing
    description: >-
      Current RPC route and websocket notification prices (public,
      rate-limited).
  - name: Health
    description: Service health checks.
  - name: Provider
    description: >-
      Provider-scoped management endpoints for managing node plans, methods, and
      nodes. Authenticated with a management token whose customer is linked to a
      provider.
paths:
  /usage:
    servers:
      - url: https://api.routeme.sh
    get:
      tags:
        - Usage
      summary: Get usage data
      description: >-
        Returns customer-scoped usage aggregates. Supports filtering by time
        range, chain, API key, grouping, and granularity. By default returns
        summary and balance.
      operationId: getUsage
      parameters:
        - name: from
          in: query
          description: Start time (RFC3339). Defaults to 30 days ago.
          schema:
            type: string
            format: date-time
          example: '2025-01-01T00:00:00Z'
        - name: to
          in: query
          description: End time (RFC3339). Defaults to now.
          schema:
            type: string
            format: date-time
          example: '2025-07-01T00:00:00Z'
        - name: include
          in: query
          description: >-
            Comma-separated list of sections to include. Options: summary,
            balance, by_chain, by_api_key, by_api_key_chain, top_methods,
            time_series, by_scenario. Default: summary,balance.
          schema:
            type: string
            example: summary,balance,by_chain,by_api_key
        - name: group_by
          in: query
          description: >-
            Group usage by a dimension. Options: chain, api_key, api_key,chain,
            method, day.
          schema:
            type: string
            example: chain
        - name: granularity
          in: query
          description: 'Time bucket size. Options: day, hour. Default: day.'
          schema:
            type: string
            enum:
              - day
              - hour
          example: day
        - name: chain_id
          in: query
          description: Filter by chain ID (e.g. 1, 137, 8453).
          schema:
            type: string
          example: '1'
        - name: api_key_id
          in: query
          description: Filter by API key numeric ID (found in list response).
          schema:
            type: integer
          example: 1
        - name: limit
          in: query
          description: Maximum number of rows returned (default and max depend on config).
          schema:
            type: integer
            minimum: 1
          example: 100
      responses:
        '200':
          description: Usage data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '400':
          description: >-
            Bad request (invalid time range, include value, group_by, or
            granularity)
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
        '503':
          description: Usage data temporarily unavailable (ClickHouse)
      security:
        - MgmtKeyAuth: []
components:
  schemas:
    UsageResponse:
      type: object
      properties:
        customer_id:
          type: integer
        period:
          $ref: '#/components/schemas/UsagePeriod'
        summary:
          $ref: '#/components/schemas/UsageSummary'
          description: Aggregate credits and request count.
        balance:
```

--------------------------------

### Example error response for -32602 (block range too large)

Source: https://routeme.sh/docs/intro/rpc-error-codes

Example JSON-RPC error response for code -32602, indicating the block range is too large and suggesting a maximum of 10000 blocks.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "block range too large; try a block range of at most 10000 blocks"
  }
}
```

--------------------------------

### rpc_get_balance

Source: https://routeme.sh/docs/intro/mcp-server

Gets the native token balance for an address. Use this to check account balances.

```APIDOC
## rpc_get_balance

### Description
Gets the native token balance for an address. Use this to check account balances.

### Parameters
- **chainId** (number) - Required - Numeric EVM chain ID.
- **address** (string) - Required - Address to query.
- **blockTag** (string) - Optional - Block number or tag (default 'latest').

```

--------------------------------

### OpenAPI specification for GET /api-keys

Source: https://routeme.sh/docs/api-reference/api-keys/list-my-api-keys

Defines the GET /api-keys endpoint, its response schema ApiKeyResponse, and the MgmtKeyAuth security scheme. The response excludes the secret key, and authentication is via the X-Api-Key header with a management token prefixed rmtm_. This is the base OpenAPI document used by the endpoint.

```yaml
openapi: 3.0.0
info:
  title: RouteMesh API
  version: 1.0.0
  description: >-
    HTTP API for routing JSON-RPC requests across providers, managing API keys,
    and viewing usage.
  license:
    name: Proprietary
    url: https://routeme.sh
servers:
  - url: https://api.routeme.sh
    description: API server — health, chains, API keys, usage, and public submissions
  - url: https://lb.routeme.sh
    description: RPC router (primary load balancer)
  - url: https://lb2.routeme.sh
    description: RPC router (AWS backup load balancer)
security: []
tags:
  - name: RPC
    description: Forward JSON-RPC requests to the router.
  - name: Chains
    description: Discover supported chains.
  - name: Submissions
    description: Public chain and node listing requests (rate-limited per IP).
  - name: API Keys
    description: Manage your API keys for self-service access.
  - name: Usage
    description: View your usage and billing data.
  - name: Pricing
    description: >-
      Current RPC route and websocket notification prices (public,
      rate-limited).
  - name: Health
    description: Service health checks.
  - name: Provider
    description: >-
      Provider-scoped management endpoints for managing node plans, methods, and
      nodes. Authenticated with a management token whose customer is linked to a
      provider.
paths:
  /api-keys:
    servers:
      - url: https://api.routeme.sh
    get:
      tags:
        - API Keys
      summary: List my API keys
      description: >-
        Returns the authenticated customer's API keys. Excludes the secret key
        value; use X-Hint for identification.
      operationId: listMyApiKeys
      responses:
        '200':
          description: List of API keys
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiKeyResponse'
        '401':
          description: Unauthorized
      security:
        - MgmtKeyAuth: []
components:
  schemas:
    ApiKeyResponse:
      type: object
      properties:
        id:
          type: integer
          description: Internal key ID (for filtering /usage).
        name:
          type: string
          nullable: true
          description: Friendly name.
        active:
          type: boolean
          description: Whether the key is active.
        allowed_domains:
          type: array
          items:
            type: string
          description: Allowed domains.
        routing_strategy:
          type: string
          enum:
            - economy
            - performance
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - name
        - active
        - allowed_domains
        - routing_strategy
        - created_at
        - updated_at
      additionalProperties: false
  securitySchemes:
    MgmtKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        Management token from the RouteMesh dashboard (Settings → Management
        Tokens). Required for customer API endpoints (/api-keys, /usage). Tokens
        are prefixed rmtm_ and scoped to your account. Authenticate by passing
        the token in the X-Api-Key header. Separate from RPC service keys (rm_),
        which authenticate dApp traffic to the routing layer.
```

--------------------------------

### Check Service Health with Java

Source: https://routeme.sh/docs/api-reference

Use the Unirest library to perform a GET request to the health endpoint.

```java
HttpResponse<String> response = Unirest.get("https://api.routeme.sh/health")
  .asString();
```

--------------------------------

### GET /v1/usage

Source: https://routeme.sh/docs/api-reference/usage/get-usage-data

Retrieves usage data for a given customer within a period, with optional grouping and breakdown.

```APIDOC
## GET /v1/usage

### Description
Retrieves usage data for a customer within a specified period, providing totals and various breakdowns.

### Method
GET

### Endpoint
/v1/usage

### Parameters
#### Query Parameters
- **customer_id** (string) - Required - The customer identifier.
- **period[from]** (string, date-time) - Required - Start of the period.
- **period[to]** (string, date-time) - Required - End of the period.
- **group_by** (string, comma-separated) - Optional - Group the usage data by fields such as chain_id, api_key_id, method, scenario, day.
- **chain_id** (string) - Optional - Filter by chain ID.
- **api_key_id** (string) - Optional - Filter by API key ID.
- **method** (string) - Optional - Filter by RPC method.
- **scenario** (string) - Optional - Filter by routing scenario.
- **page** (integer) - Optional - Pagination page number.
- **per_page** (integer) - Optional - Items per page.

### Response
#### Success Response (200)
- **customer_id** (string) - The customer identifier.
- **period** (object) - The requested period with `from` and `to` date-time fields.
- **summary** (object) - Summary of usage with `credits_consumed` (number), `request_count` (integer), `credits_per_request` (number).
- **balance** (object) - Current credit balance with `credits` (number) and `as_of` (date-time).
- **by_chain** (array) - Per-chain breakdown. Each item contains `chain_id` (string), `credits_consumed` (number), `request_count` (integer).
- **by_api_key** (array) - Per-API-key breakdown. Each item contains `api_key_id` (integer), `name` (string, nullable), `key_hint` (string), `credits_consumed` (number), `request_count` (integer).
- **by_api_key_chain** (array) - Per-API-key, per-chain breakdown. Each item contains `api_key_id` (integer), `name` (string, nullable), `key_hint` (string), `chain_id` (string), `credits_consumed` (number), `request_count` (integer).
- **top_methods** (array) - Top RPC methods by spend. Each item contains `method` (string), `credits_consumed` (number), `request_count` (integer).
- **time_series** (array) - Time-bucketed usage data. Each item contains `bucket` (date-time), `credits_consumed` (number), `request_count` (integer).
- **by_scenario** (array) - Usage by routing scenario. Each item contains `scenario` (string), `credits_consumed` (number), `request_count` (integer).
- **groups** (array) - Grouped results when `group_by` specified. Each item contains `api_key_id`, `name`, `key_hint`, `chain_id`, `method`, `scenario`, `day` (all nullable), `credits_consumed` (number), `request_count` (integer).

#### Response Example
{
  "customer_id": "customer123",
  "period": {
    "from": "2025-01-01T00:00:00Z",
    "to": "2025-01-31T23:59:59Z"
  },
  "summary": {
    "credits_consumed": 123.45,
    "request_count": 1234,
    "credits_per_request": 0.1
  },
  "balance": {
    "credits": 500.0,
    "as_of": "2025-01-31T23:59:59Z"
  },
  "by_chain": [
    {
      "chain_id": "1",
      "credits_consumed": 10.0,
      "request_count": 100
    }
  ],
  "by_api_key": [
    {
      "api_key_id": 1,
      "name": "my key",
      "key_hint": "rm_a…456",
      "credits_consumed": 10.0,
      "request_count": 100
    }
  ],
  "by_api_key_chain": [
    {
      "api_key_id": 1,
      "name": "my key",
      "key_hint": "rm_a…456",
      "chain_id": "1",
      "credits_consumed": 10.0,
      "request_count": 100
    }
  ],
  "top_methods": [
    {
      "method": "eth_call",
      "credits_consumed": 5.0,
      "request_count": 50
    }
  ],
  "time_series": [
    {
      "bucket": "2025-01-01T00:00:00Z",
      "credits_consumed": 1.0,
      "request_count": 10
    }
  ],
  "by_scenario": [
    {
      "scenario": "direct",
      "credits_consumed": 5.0,
      "request_count": 50
    }
  ],
  "groups": [
    {
      "api_key_id": 1,
      "name": "my key",
      "key_hint": "rm_a…456",
      "chain_id": "1",
      "method": "eth_call",
      "scenario": "direct",
      "day": "2025-01-01",
      "credits_consumed": 5.0,
      "request_count": 50
    }
  ]
}
```

### Error Handling
- **400 Bad Request** - Invalid parameters or missing required fields.
- **401 Unauthorized** - Missing or invalid authentication.
- **404 Not Found** - Customer not found.
- **429 Too Many Requests** - Rate limit exceeded.
- **500 Internal Server Error** - Unexpected server error.
```

--------------------------------

### GET /usage

Source: https://routeme.sh/docs/api-reference/usage/get-usage-data

Returns customer-scoped usage aggregates. Supports filtering by time range, chain, API key, grouping, and granularity. By default returns summary and balance.

```APIDOC
## GET /usage

### Description
Returns customer-scoped usage aggregates. Supports filtering by time range, chain, API key, grouping, and granularity. By default returns summary and balance.

### Method
GET

### Endpoint
https://api.routeme.sh/usage

### Parameters
#### Query Parameters
- **from** (string, date-time) - Optional - Start time (RFC3339). Defaults to 30 days ago.
- **to** (string, date-time) - Optional - End time (RFC3339). Defaults to now.
- **include** (string) - Optional - Comma-separated list of sections to include. Options: summary, balance, by_chain, by_api_key, by_api_key_chain, top_methods, time_series, by_scenario. Default: summary,balance.
- **group_by** (string) - Optional - Group usage by a dimension. Options: chain, api_key, api_key,chain, method, day.
- **granularity** (string) - Optional - Time bucket size. Options: day, hour. Default: day.
- **chain_id** (string) - Optional - Filter by chain ID (e.g. 1, 137, 8453).
- **api_key_id** (integer) - Optional - Filter by API key numeric ID (found in list response).
- **limit** (integer) - Optional - Maximum number of rows returned (default and max depend on config).

### Request Example
GET https://api.routeme.sh/usage?from=2025-01-01T00:00:00Z&to=2025-07-01T00:00:00Z&include=summary,balance,by_chain,by_api_key&group_by=chain&granularity=day&chain_id=1&api_key_id=1&limit=100

### Response
#### Success Response (200)
Returns a UsageResponse object with customer_id, period, and summary.

#### Response Example
{
  "customer_id": 0,
  "period": {},
  "summary": {}
}

### Error Handling
- **400** - Bad request (invalid time range, include value, group_by, or granularity)
- **401** - Unauthorized
- **500** - Internal server error
- **503** - Usage data temporarily unavailable (ClickHouse)
```

--------------------------------

### GET /api-keys

Source: https://routeme.sh/docs/api-reference/api-keys/list-my-api-keys

Retrieves the authenticated customer's API keys. The response excludes the secret key value; use the X-Hint header for identification. Requires a management token in the X-Api-Key header.

```APIDOC
## GET /api-keys

### Description
Returns the authenticated customer's API keys. Excludes the secret key value; use X-Hint for identification.

### Method
GET

### Endpoint
https://api.routeme.sh/api-keys

### Parameters
#### Headers
- **X-Api-Key** (string) - Required - Management token from the RouteMesh dashboard (Settings → Management Tokens). Required for customer API endpoints (/api-keys, /usage). Tokens are prefixed rmtm_ and scoped to your account.

### Response
#### Success Response (200)
Returns an array of API key objects. Each object contains:
- **id** (integer) - Internal key ID (for filtering /usage).
- **name** (string, nullable) - Friendly name.
- **active** (boolean) - Whether the key is active.
- **allowed_domains** (array of strings) - Allowed domains.
- **routing_strategy** (string) - Routing strategy. Possible values: `economy`, `performance`.
- **created_at** (string, date-time) - Creation timestamp.
- **updated_at** (string, date-time) - Last update timestamp.

#### Response Example
```json
[
  {
    "id": 1,
    "name": "My Key",
    "active": true,
    "allowed_domains": ["example.com"],
    "routing_strategy": "performance",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
]
```

#### Error Response (401)
Unauthorized - Invalid or missing API key.
```

--------------------------------

### GET /pricing/ws

Source: https://routeme.sh/docs/api-reference/pricing/list-websocket-notification-prices

Public endpoint returning current websocket notification prices per chain ID and subscription type. No authentication required. Rate-limited per IP (default 30 requests per 60 seconds). Empty results return an empty JSON array.

```APIDOC
## GET /pricing/ws

### Description
Public endpoint returning current websocket notification prices per chain ID and subscription type. No authentication required. Rate-limited per IP (default 30 requests per 60 seconds). Empty results return an empty JSON array.

### Method
GET

### Endpoint
https://api.routeme.sh/pricing/ws

### Parameters
#### Query Parameters
- **chain_id** (string) - Optional - Filter by chain ID (e.g. 1, 137, 8453).
- **subscription_type** (string) - Optional - Filter by websocket subscription type (e.g. newHeads).

### Request Example
GET /pricing/ws?chain_id=1&subscription_type=newHeads

### Response
#### Success Response (200)
- **vm** (string) - Virtual machine type (currently always "evm").
- **chain_id** (string) - Numeric chain ID (e.g. "1", "137", "8453").
- **subscription_type** (string) - Websocket subscription type (e.g. "newHeads").
- **price_per_million** (number) - Price per one million notifications.

#### Response Example
[
  {
    "vm": "evm",
    "chain_id": "1",
    "subscription_type": "newHeads",
    "price_per_million": 6
  }
]

#### Error Responses
- **429** - Rate limit exceeded (per-IP limit; default 30 requests per 60 seconds)
- **503** - Pricing data temporarily unavailable
```

--------------------------------

### Check Service Health with Ruby

Source: https://routeme.sh/docs/api-reference

Use the Net::HTTP library to perform a GET request to the health endpoint.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.routeme.sh/health")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

--------------------------------

### GET /chains/rpc

Source: https://routeme.sh/docs/api-reference/chains/list-supported-rpc-chains

Returns the EVM chains supported over HTTP RPC, sorted by chain ID. Public endpoint, no authentication required. Returns an empty array when no chains are supported.

```APIDOC
## GET /chains/rpc

### Description
Returns the EVM chains supported over HTTP RPC, sorted by chain ID. Public endpoint, no authentication required. Returns an empty array when no chains are supported.

### Method
GET

### Endpoint
https://api.routeme.sh/chains/rpc

### Parameters
None

### Request Example
No request body required.

### Response
#### Success Response (200)
- **chain_id** (string) - Numeric chain ID (e.g. "1", "137", "8453").
- **name** (string) - Human-readable chain name.

#### Response Example
[
  {
    "chain_id": "1",
    "name": "Ethereum Mainnet"
  },
  {
    "chain_id": "8453",
    "name": "Base"
  }
]

#### Error Response (500)
Internal server error.
```

--------------------------------

### OpenAPI definition for /pricing/rpc

Source: https://routeme.sh/docs/api-reference/pricing/list-rpc-route-prices

The OpenAPI specification for the RouteMesh API, detailing the GET /pricing/rpc endpoint, its query parameters, and the expected JSON response structure.

```yaml
openapi: 3.0.0
info:
  title: RouteMesh API
  version: 1.0.0
  description: >-
    HTTP API for routing JSON-RPC requests across providers, managing API keys,
    and viewing usage.
  license:
    name: Proprietary
    url: https://routeme.sh
servers:
  - url: https://api.routeme.sh
    description: API server — health, chains, API keys, usage, and public submissions
  - url: https://lb.routeme.sh
    description: RPC router (primary load balancer)
  - url: https://lb2.routeme.sh
    description: RPC router (AWS backup load balancer)
security: []
tags:
  - name: RPC
    description: Forward JSON-RPC requests to the router.
  - name: Chains
    description: Discover supported chains.
  - name: Submissions
    description: Public chain and node listing requests (rate-limited per IP).
  - name: API Keys
    description: Manage your API keys for self-service access.
  - name: Usage
    description: View your usage and billing data.
  - name: Pricing
    description: >-
      Current RPC route and websocket notification prices (public,
      rate-limited).
  - name: Health
    description: Service health checks.
  - name: Provider
    description: >-
      Provider-scoped management endpoints for managing node plans, methods, and
      nodes. Authenticated with a management token whose customer is linked to a
      provider.
paths:
  /pricing/rpc:
    servers:
      - url: https://api.routeme.sh
    get:
      tags:
        - Pricing
      summary: List RPC route prices
      description: >-
        Public endpoint returning current RPC route prices for each vm, chain
        ID, method, and routing strategy combination. No authentication
        required. Rate-limited per IP (default 30 requests per 60 seconds).
        Empty results return an empty JSON array.
      operationId: getRoutePrices
      parameters:
        - name: vm
          in: query
          description: Filter by virtual machine type (e.g. evm).
          schema:
            type: string
          example: evm
        - name: chain_id
          in: query
          description: Filter by chain ID (e.g. 1, 137, 8453).
          schema:
            type: string
          example: '1'
        - name: method
          in: query
          description: Filter by JSON-RPC method (e.g. eth_blockNumber).
          schema:
            type: string
          example: eth_blockNumber
        - name: routing_strategy
          in: query
          description: Filter by routing strategy.
          schema:
            type: string
            enum:
              - economy
              - performance
          example: economy
      responses:
        '200':
          description: Current route prices
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RoutePrice'
              example:
                - vm: evm
                  chain_id: '1'
                  method: eth_blockNumber
                  routing_strategy: economy
                  price_per_million: 3
        '429':
          description: >-
            Rate limit exceeded (per-IP limit; default 30 requests per 60
            seconds)
        '503':
          description: Pricing data temporarily unavailable
components:
  schemas:
    RoutePrice:
      type: object
      properties:
        vm:
          type: string
          description: Virtual machine type (e.g. "evm").
        chain_id:
          type: string
          description: Numeric chain ID (e.g. "1", "137", "8453").
        method:
          type: string
          description: JSON-RPC method name (e.g. eth_blockNumber).
        routing_strategy:
          type: string
          enum:
            - economy
            - performance
          description: Routing strategy the price applies to.
        price_per_million:
          type: number
          description: Price per one million requests.
      required:
        - vm
        - chain_id
        - method
        - routing_strategy
        - price_per_million
      additionalProperties: false
```

--------------------------------

### GET /chains/ws

Source: https://routeme.sh/docs/api-reference/chains/list-supported-websocket-chains

Returns the EVM chains supported over WebSocket, sorted by chain ID. Public endpoint, no authentication required. Returns an empty array when no chains are supported.

```APIDOC
## GET /chains/ws

### Description
Returns the EVM chains supported over WebSocket, sorted by chain ID. Public endpoint, no authentication required. Returns an empty array when no chains are supported.

### Method
GET

### Endpoint
https://api.routeme.sh/chains/ws

### Parameters
None

### Request Example
No request body required.

### Response
#### Success Response (200)
- **chain_id** (string) - Numeric chain ID (e.g. "1", "137", "8453").
- **name** (string) - Human-readable chain name.

#### Response Example
```json
[
  {
    "chain_id": "1",
    "name": "Ethereum Mainnet"
  }
]
```

#### Error Response (500)
Internal server error.
```

--------------------------------

### Make your first RPC request with curl

Source: https://routeme.sh/docs/intro/quick-start

Replace your existing RPC endpoint with RouteMesh. Use a supported chain_id (e.g., 1 for Ethereum) and your API key. The URL scheme is POST /rpc/{chain_id}/{api_key}.

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

--------------------------------

### OpenAPI spec for GET /chains/rpc

Source: https://routeme.sh/docs/api-reference/chains/list-supported-rpc-chains

OpenAPI specification for the GET /chains/rpc endpoint. It defines the response schema (array of ChainInfo objects) and example response with chain_id and name fields. The endpoint is public, requires no authentication, and returns an empty array when no chains are supported.

```yaml
openapi: 3.0.0
info:
  title: RouteMesh API
  version: 1.0.0
  description: >-
    HTTP API for routing JSON-RPC requests across providers, managing API keys,
    and viewing usage.
  license:
    name: Proprietary
    url: https://routeme.sh
servers:
  - url: https://api.routeme.sh
    description: API server — health, chains, API keys, usage, and public submissions
  - url: https://lb.routeme.sh
    description: RPC router (primary load balancer)
  - url: https://lb2.routeme.sh
    description: RPC router (AWS backup load balancer)
security: []
tags:
  - name: RPC
    description: Forward JSON-RPC requests to the router.
  - name: Chains
    description: Discover supported chains.
  - name: Submissions
    description: Public chain and node listing requests (rate-limited per IP).
  - name: API Keys
    description: Manage your API keys for self-service access.
  - name: Usage
    description: View your usage and billing data.
  - name: Pricing
    description: >-
      Current RPC route and websocket notification prices (public,
      rate-limited).
  - name: Health
    description: Service health checks.
  - name: Provider
    description: >-
      Provider-scoped management endpoints for managing node plans, methods, and
      nodes. Authenticated with a management token whose customer is linked to a
      provider.
paths:
  /chains/rpc:
    servers:
      - url: https://api.routeme.sh
    get:
      tags:
        - Chains
      summary: List supported RPC chains
      description: >-
        Returns the EVM chains supported over HTTP RPC, sorted by chain ID.
        Public endpoint, no authentication required. Returns an empty array when
        no chains are supported.
      operationId: getChainsRpc
      responses:
        '200':
          description: Supported RPC chains
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChainInfo'
              example:
                - chain_id: '1'
                  name: Ethereum Mainnet
                - chain_id: '8453'
                  name: Base
        '500':
          description: Internal server error
components:
  schemas:
    ChainInfo:
      type: object
      properties:
        chain_id:
          type: string
          description: Numeric chain ID (e.g. "1", "137", "8453").
        name:
          type: string
          description: Human-readable chain name.
      required:
        - chain_id
        - name
      additionalProperties: false
```

--------------------------------

### OpenAPI specification for /health endpoint

Source: https://routeme.sh/docs/api-reference/health/service-health

OpenAPI 3.0.0 specification for the GET /health endpoint. It defines the server as https://api.routeme.sh and the response schema with success and message properties. The example response shows success: true and message: The service is ready to serve requests.

```yaml
openapi: 3.0.0
info:
  title: RouteMesh API
  version: 1.0.0
  description: >-
    HTTP API for routing JSON-RPC requests across providers, managing API keys,
    and viewing usage.
  license:
    name: Proprietary
    url: https://routeme.sh
servers:
  - url: https://api.routeme.sh
    description: API server — health, chains, API keys, usage, and public submissions
  - url: https://lb.routeme.sh
    description: RPC router (primary load balancer)
  - url: https://lb2.routeme.sh
    description: RPC router (AWS backup load balancer)
security: []
tags:
  - name: RPC
    description: Forward JSON-RPC requests to the router.
  - name: Chains
    description: Discover supported chains.
  - name: Submissions
    description: Public chain and node listing requests (rate-limited per IP).
  - name: API Keys
    description: Manage your API keys for self-service access.
  - name: Usage
    description: View your usage and billing data.
  - name: Pricing
    description: >-
      Current RPC route and websocket notification prices (public,
      rate-limited).
  - name: Health
    description: Service health checks.
  - name: Provider
    description: >-
      Provider-scoped management endpoints for managing node plans, methods, and
      nodes. Authenticated with a management token whose customer is linked to a
      provider.
paths:
  /health:
    servers:
      - url: https://api.routeme.sh
    get:
      tags:
        - Health
      summary: Service health
      description: Public health endpoint used by load balancers and uptime checks.
      operationId: getHealth
      responses:
        '200':
          description: Service is healthy and serving requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                required:
                  - success
                  - message
                additionalProperties: false
              example:
                success: true
                message: The service is ready to serve requests

```

--------------------------------

### rpc_get_fee_data

Source: https://routeme.sh/docs/intro/mcp-server

Gets current gas price, max priority fee, and a one-block fee history. Use this to get fee information for the chain.

```APIDOC
## rpc_get_fee_data

### Description
Gets current gas price, max priority fee, and a one-block fee history. Use this to get fee information for the chain.

### Parameters
- **chainId** (number) - Required - Numeric EVM chain ID.

```

--------------------------------

### GET /pricing/rpc

Source: https://routeme.sh/docs/api-reference/pricing/list-rpc-route-prices

Public endpoint returning current RPC route prices for each vm, chain ID, method, and routing strategy combination. No authentication required. Rate-limited per IP (default 30 requests per 60 seconds). Empty results return an empty JSON array.

```APIDOC
## GET /pricing/rpc

### Description
Public endpoint returning current RPC route prices for each vm, chain ID, method, and routing strategy combination. No authentication required. Rate-limited per IP (default 30 requests per 60 seconds). Empty results return an empty JSON array.

### Method
GET

### Endpoint
https://api.routeme.sh/pricing/rpc

### Parameters
#### Query Parameters
- **vm** (string) - Optional - Filter by virtual machine type (e.g. evm). Example: evm
- **chain_id** (string) - Optional - Filter by chain ID (e.g. 1, 137, 8453). Example: '1'
- **method** (string) - Optional - Filter by JSON-RPC method (e.g. eth_blockNumber). Example: eth_blockNumber
- **routing_strategy** (string) - Optional - Filter by routing strategy. Enum: economy, performance. Example: economy

### Response
#### Success Response (200)
- **vm** (string) - Virtual machine type (e.g. "evm").
- **chain_id** (string) - Numeric chain ID (e.g. "1", "137", "8453").
- **method** (string) - JSON-RPC method name (e.g. eth_blockNumber).
- **routing_strategy** (string) - Routing strategy the price applies to. Enum: economy, performance.
- **price_per_million** (number) - Price per one million requests.

#### Response Example
[
  {
    "vm": "evm",
    "chain_id": "1",
    "method": "eth_blockNumber",
    "routing_strategy": "economy",
    "price_per_million": 3
  }
]

#### Error Responses
- **429** - Rate limit exceeded (per-IP limit; default 30 requests per 60 seconds)
- **503** - Pricing data temporarily unavailable
```

--------------------------------

### Configure Cursor MCP server

Source: https://routeme.sh/docs/intro/mcp-server

Add this configuration to your ~/.cursor/mcp.json file to enable the RouteMesh MCP server in Cursor.

```json
{
  "mcpServers": {
    "routemesh": {
      "command": "npx",
      "args": ["-y", "@routemesh/mcp"],
      "env": {
        "ROUTEMESH_API_KEY": "your_routemesh_api_key"
      }
    }
  }
}
```

--------------------------------

### POST /provider/plans/{planId}/methods

Source: https://routeme.sh/docs/api-reference/provider/add-methods-to-a-plan

Appends RPC method rows (1-500) to one of the authenticated provider's plans. The plan must be owned by the caller's provider (otherwise 404).

```APIDOC
## POST /provider/plans/{planId}/methods

### Description
Appends RPC method rows (1-500) to one of the authenticated provider's plans. The plan must be owned by the caller's provider (otherwise 404).

### Method
POST

### Endpoint
https://api.routeme.sh/provider/plans/{planId}/methods

### Parameters
#### Path Parameters
- **planId** (integer) - Required - Numeric plan ID.

#### Request Body
- **methods** (array) - Required - Array of method definitions (1-500 items).
  - **method** (string) - Required - The RPC method name.
  - **vm** (string) - Required - The virtual machine type.
  - **node_target_type** (string) - Required - The node target type.
  - **cost** (integer) - Required - The cost of the method (minimum 0).
  - **rate_limit** (integer) - Optional - Rate limit (minimum 0).
  - **rate_limit_interval_sec** (integer) - Optional - Rate limit interval in seconds (minimum 0).
  - **chain_id** (string) - Optional - Chain ID (nullable).

### Request Example
{
  "methods": [
    {
      "method": "eth_blockNumber",
      "vm": "evm",
      "node_target_type": "public",
      "cost": 1,
      "rate_limit": 100,
      "rate_limit_interval_sec": 60,
      "chain_id": "1"
    }
  ]
}

### Response
#### Success Response (201)
- Returns a plain-text success message.

#### Response Example
Plan methods inserted.

### Error Responses
- **400** - Invalid plan id, request body, or validation failure
- **401** - Unauthorized
- **403** - Provider not resolved
- **404** - Plan not found (or not owned by the caller's provider)
- **500** - Internal server error

### Authentication
- **MgmtKeyAuth** - API key in header `X-Api-Key`. Management token from the RouteMesh dashboard (Settings → Management Tokens). Tokens are prefixed `rmtm_` and scoped to your account.
```

--------------------------------

### rpc_get_transaction

Source: https://routeme.sh/docs/intro/mcp-server

Fetches a transaction by hash. Use this to get transaction details.

```APIDOC
## rpc_get_transaction

### Description
Fetches a transaction by hash. Use this to get transaction details.

### Parameters
- **chainId** (number) - Required - Numeric EVM chain ID.
- **txHash** (string) - Required - Transaction hash.

```

--------------------------------

### rpc_get_transaction_receipt

Source: https://routeme.sh/docs/intro/mcp-server

Fetches a transaction receipt by hash. Use this to get receipt details.

```APIDOC
## rpc_get_transaction_receipt

### Description
Fetches a transaction receipt by hash. Use this to get receipt details.

### Parameters
- **chainId** (number) - Required - Numeric EVM chain ID.
- **txHash** (string) - Required - Transaction hash.

```

--------------------------------

### Check Service Health with cURL

Source: https://routeme.sh/docs/api-reference

Use this command to perform a GET request to the health endpoint.

```bash
curl --request GET \
  --url https://api.routeme.sh/health
```