{
  "openapi": "3.0.0",
  "info": {
    "title": "RouteMesh API",
    "version": "1.0.0",
    "description": "HTTP API for routing JSON-RPC requests across providers.",
    "license": {
      "name": "Proprietary",
      "url": "https://routeme.sh"
    }
  },
  "servers": [
    {
      "url": "https://lb.routeme.sh",
      "description": "Primary API endpoint"
    },
    {
      "url": "https://lb2.routeme.sh",
      "description": "AWS DNS load balancer (backup)"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "RPC",
      "description": "Forward JSON-RPC requests to the router."
    },
    {
      "name": "Chains",
      "description": "Discover supported chains."
    }
  ],
  "paths": {
    "/chains": {
      "get": {
        "operationId": "getChains",
        "tags": [
          "Chains"
        ],
        "summary": "List supported chains",
        "description": "Returns chains that have at least one available node and at least one paid provider plan.",
        "responses": {
          "200": {
            "description": "Supported chains",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ChainInfo"
                  }
                },
                "example": [
                  {
                    "chain_id": "1",
                    "name": "Ethereum Mainnet"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "Bad request"
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {
                  "error": "Unable to get supported chains. Please contact support."
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "getHealth",
        "tags": [
          "Chains"
        ],
        "summary": "Service health",
        "description": "Public health endpoint used by load balancers and uptime checks.",
        "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/{chainId}/{apiKey}": {
      "post": {
        "operationId": "postRpc",
        "tags": [
          "RPC"
        ],
        "summary": "JSON-RPC proxy",
        "description": "Send a single JSON-RPC request or a JSON-RPC batch (array).",
        "parameters": [
          {
            "name": "chainId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          },
          {
            "name": "apiKey",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "password"
            },
            "example": "your-api-key"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/JsonRpcRequest"
                  },
                  {
                    "$ref": "#/components/schemas/JsonRpcBatchRequest"
                  }
                ]
              },
              "examples": {
                "single": {
                  "summary": "Single request",
                  "value": {
                    "jsonrpc": "2.0",
                    "method": "eth_blockNumber",
                    "params": [],
                    "id": 1
                  }
                },
                "batch": {
                  "summary": "Batch request",
                  "value": [
                    {
                      "jsonrpc": "2.0",
                      "method": "eth_blockNumber",
                      "params": [],
                      "id": 1
                    },
                    {
                      "jsonrpc": "2.0",
                      "method": "net_version",
                      "params": [],
                      "id": 2
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response (single or batch)",
            "headers": {
              "X-Batch-Id": {
                "$ref": "#/components/headers/XBatchId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonRpcResponse"
                    },
                    {
                      "$ref": "#/components/schemas/JsonRpcBatchResponse"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request (e.g. invalid JSON or invalid JSON-RPC payload)",
            "headers": {
              "X-Batch-Id": {
                "$ref": "#/components/headers/XBatchId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized (invalid API key)",
            "headers": {
              "X-Batch-Id": {
                "$ref": "#/components/headers/XBatchId"
              }
            },
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "Invalid API key"
              }
            }
          },
          "403": {
            "description": "Forbidden (domain not allowed)",
            "headers": {
              "X-Batch-Id": {
                "$ref": "#/components/headers/XBatchId"
              }
            },
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable entity (e.g. chain not supported or method not supported)",
            "headers": {
              "X-Batch-Id": {
                "$ref": "#/components/headers/XBatchId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonRpcResponse"
                    },
                    {
                      "$ref": "#/components/schemas/JsonRpcBatchResponse"
                    }
                  ]
                }
              }
            }
          },
          "424": {
            "description": "Failed dependency (all upstream providers failed with non-2xx responses)",
            "headers": {
              "X-Batch-Id": {
                "$ref": "#/components/headers/XBatchId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonRpcResponse"
                    },
                    {
                      "$ref": "#/components/schemas/JsonRpcBatchResponse"
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (all upstream providers rate limited / on cooldown)",
            "headers": {
              "X-Batch-Id": {
                "$ref": "#/components/headers/XBatchId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonRpcResponse"
                    },
                    {
                      "$ref": "#/components/schemas/JsonRpcBatchResponse"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "headers": {
              "X-Batch-Id": {
                "$ref": "#/components/headers/XBatchId"
              }
            }
          },
          "504": {
            "description": "Gateway timeout (router timed out waiting for upstream providers)",
            "headers": {
              "X-Batch-Id": {
                "$ref": "#/components/headers/XBatchId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonRpcResponse"
                    },
                    {
                      "$ref": "#/components/schemas/JsonRpcBatchResponse"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ChainInfo": {
        "type": "object",
        "properties": {
          "chain_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "chain_id",
          "name"
        ],
        "additionalProperties": false
      },
      "JsonRpcRequest": {
        "type": "object",
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": [
              "2.0"
            ]
          },
          "method": {
            "type": "string"
          },
          "params": {
            "oneOf": [
              {
                "type": "array",
                "items": {}
              },
              {
                "type": "object",
                "additionalProperties": true
              }
            ]
          },
          "id": {}
        },
        "required": [
          "jsonrpc",
          "method",
          "id"
        ],
        "additionalProperties": false
      },
      "JsonRpcBatchRequest": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/JsonRpcRequest"
        }
      },
      "JsonRpcError": {
        "description": "JSON-RPC error object. See [RPC Error Codes](/rpc-error-codes) for full code → meaning and when each occurs.",
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "Router error codes: -32700 (parse error), -32600 (invalid request), -32602 (invalid params), -32603 (internal error), -32000 (server error), -32001 (chain not supported), -32002 (method not supported), -32003 (all nodes on cooldown)."
          },
          "message": {
            "type": "string",
            "description": "Human-readable error message."
          },
          "data": {
            "description": "Optional additional error data."
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": true
      },
      "JsonRpcResponse": {
        "type": "object",
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": [
              "2.0"
            ]
          },
          "id": {},
          "result": {
            "description": "Result value (varies by JSON-RPC method)."
          },
          "error": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/JsonRpcError"
              }
            ]
          }
        },
        "required": [
          "jsonrpc",
          "id"
        ],
        "additionalProperties": true
      },
      "JsonRpcBatchResponse": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/JsonRpcResponse"
        }
      }
    },
    "headers": {
      "XBatchId": {
        "description": "Correlation id for this HTTP request. Save it and share with RouteMesh support to help trace requests across logs and analytics.",
        "schema": {
          "type": "string"
        },
        "example": "1f4f3b23-1c2b-4c87-9c2f-7e2e0f0df4b5"
      }
    }
  }
}