{
  "openapi": "3.1.0",
  "info": {
    "title": "SolidRPC EVM JSON-RPC API",
    "version": "1.0.0",
    "description": "Send JSON-RPC 2.0 calls to supported EVM networks through one SolidRPC endpoint. SolidRPC operates upstream selection, capability-aware routing, failover, monitoring, and recovery behind the endpoint. This contract describes the agent-friendly header-authenticated route and the keyless public route; API-key-in-URL clients can use the equivalent endpoint documented in the getting-started guide.",
    "termsOfService": "https://solidrpc.io/terms",
    "contact": {
      "name": "SolidRPC developer support",
      "url": "https://solidrpc.io/contact",
      "email": "hello@solidrpc.io"
    },
    "license": {
      "name": "SolidRPC Terms of Service",
      "url": "https://solidrpc.io/terms"
    }
  },
  "externalDocs": {
    "description": "SolidRPC developer documentation, authentication, supported networks, rate limits, and error guidance",
    "url": "https://solidrpc.io/docs"
  },
  "servers": [
    {
      "url": "https://rpc.solidrpc.io",
      "description": "SolidRPC production JSON-RPC gateway"
    }
  ],
  "tags": [
    {
      "name": "Authenticated RPC",
      "description": "Production JSON-RPC calls authenticated with one API-key header."
    },
    {
      "name": "Public RPC",
      "description": "Keyless JSON-RPC calls for wallets, development, testing, and lightweight traffic."
    }
  ],
  "paths": {
    "/evm/{chainId}": {
      "post": {
        "operationId": "callSolidRpcEvmJsonRpc",
        "summary": "Call an EVM network through an authenticated SolidRPC endpoint",
        "description": "Sends one JSON-RPC 2.0 request or batch to the selected EVM chain. Authenticate with either `Authorization: Bearer YOUR_API_KEY` or `X-API-Key: YOUR_API_KEY`, not both. Each method call in a batch consumes one response unit and one rate-limit token. Use the live network catalog before calling to confirm the chain ID and method capabilities. This generic operation can invoke state-changing methods such as `eth_sendRawTransaction`; an agent must not sign, construct, or broadcast a transaction without the user's explicit authorization.",
        "tags": [
          "Authenticated RPC"
        ],
        "externalDocs": {
          "description": "Authentication, batching, method policy, and client examples",
          "url": "https://solidrpc.io/docs/getting-started"
        },
        "security": [
          {
            "BearerApiKey": []
          },
          {
            "HeaderApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ChainId"
          }
        ],
        "requestBody": {
          "required": true,
          "description": "One JSON-RPC 2.0 request or a non-empty batch of requests.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequestOrBatch"
              },
              "examples": {
                "latestBlock": {
                  "summary": "Read the latest block number",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "eth_blockNumber",
                    "params": []
                  }
                },
                "batch": {
                  "summary": "Read the chain ID and latest block in one batch",
                  "value": [
                    {
                      "jsonrpc": "2.0",
                      "id": 1,
                      "method": "eth_chainId",
                      "params": []
                    },
                    {
                      "jsonrpc": "2.0",
                      "id": 2,
                      "method": "eth_blockNumber",
                      "params": []
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonRpcResponse"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/QuotaExceeded"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "413": {
            "$ref": "#/components/responses/RequestTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "504": {
            "$ref": "#/components/responses/GatewayTimeout"
          }
        }
      }
    },
    "/public/evm/{chainId}": {
      "post": {
        "operationId": "callSolidRpcPublicEvmJsonRpc",
        "summary": "Call a supported EVM network without an API key",
        "description": "Sends one JSON-RPC 2.0 request or batch through the keyless public route. Use this operation for wallets, development, testing, and lightweight traffic. Public traffic is limited to documented networks and standard `eth_*`, `net_*`, and `web3_*` methods; `eth_getLogs` is limited to 2,000 blocks. The public method set includes state-changing methods such as `eth_sendRawTransaction`; an agent must not sign, construct, or broadcast a transaction without the user's explicit authorization. Use the authenticated operation for production throughput, archive access, trace methods, or debug methods.",
        "tags": [
          "Public RPC"
        ],
        "externalDocs": {
          "description": "Public endpoint networks, method policy, quotas, and limits",
          "url": "https://solidrpc.io/docs/public-rpc"
        },
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/PublicChainId"
          }
        ],
        "requestBody": {
          "required": true,
          "description": "One JSON-RPC 2.0 request or a non-empty batch of requests.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequestOrBatch"
              },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "eth_blockNumber",
                "params": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonRpcResponse"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/PublicChainNotFound"
          },
          "413": {
            "$ref": "#/components/responses/RequestTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/PublicRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "504": {
            "$ref": "#/components/responses/GatewayTimeout"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerApiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "A SolidRPC API key sent as `Authorization: Bearer YOUR_API_KEY`. Do not combine this API-key form with `X-API-Key`."
      },
      "HeaderApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "A SolidRPC API key sent in `X-API-Key`. This form leaves the Authorization header available for an optional customer-signed JWT."
      }
    },
    "parameters": {
      "ChainId": {
        "name": "chainId",
        "in": "path",
        "required": true,
        "description": "Positive EVM chain ID from the authoritative live catalog at https://api.solidrpc.io/networks.",
        "schema": {
          "type": "integer",
          "format": "int32",
          "minimum": 1,
          "maximum": 2147483647
        },
        "example": 1
      },
      "PublicChainId": {
        "name": "chainId",
        "in": "path",
        "required": true,
        "description": "EVM chain ID available through the keyless public endpoint.",
        "schema": {
          "type": "integer",
          "format": "int32",
          "minimum": 1,
          "maximum": 2147483647,
          "enum": [
            1,
            10,
            56,
            137,
            4663,
            8453,
            42161,
            43114,
            5042002
          ]
        },
        "example": 1
      }
    },
    "headers": {
      "RetryAfter": {
        "description": "Seconds to wait before retrying.",
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      },
      "RateLimitLimit": {
        "description": "Sustained RPC method calls allowed per second.",
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      },
      "RateLimitBurst": {
        "description": "Maximum token-bucket burst capacity in RPC method calls.",
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      },
      "RateLimitRemaining": {
        "description": "RPC method-call tokens remaining in the active bucket.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "RateLimitReset": {
        "description": "Estimated seconds until the token bucket is full.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "QuotaLimit": {
        "description": "Response-unit allowance for the current quota window.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "QuotaUsed": {
        "description": "Response units consumed in the current quota window.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "QuotaRemaining": {
        "description": "Response units remaining in the current quota window.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "QuotaReset": {
        "description": "Seconds until the quota window resets.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "QuotaWindow": {
        "description": "Current quota window type.",
        "schema": {
          "type": "string",
          "enum": [
            "day",
            "month"
          ]
        }
      }
    },
    "schemas": {
      "JsonRpcId": {
        "description": "Client-selected request identifier. Notifications without an ID are accepted but are not represented in this tool-oriented contract.",
        "oneOf": [
          {
            "type": "integer"
          },
          {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          }
        ]
      },
      "JsonRpcParams": {
        "description": "Method parameters, represented positionally as an array or by name as an object.",
        "oneOf": [
          {
            "type": "array",
            "items": {}
          },
          {
            "type": "object",
            "additionalProperties": true
          }
        ]
      },
      "JsonRpcRequest": {
        "type": "object",
        "description": "One JSON-RPC 2.0 method call.",
        "required": [
          "jsonrpc",
          "id",
          "method",
          "params"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0",
            "description": "JSON-RPC protocol version."
          },
          "id": {
            "$ref": "#/components/schemas/JsonRpcId"
          },
          "method": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "EVM JSON-RPC method name, such as `eth_blockNumber`."
          },
          "params": {
            "$ref": "#/components/schemas/JsonRpcParams"
          }
        },
        "additionalProperties": true
      },
      "JsonRpcBatchRequest": {
        "type": "array",
        "description": "A non-empty JSON-RPC batch. Each entry consumes its own response unit and rate-limit token.",
        "minItems": 1,
        "items": {
          "$ref": "#/components/schemas/JsonRpcRequest"
        }
      },
      "JsonRpcRequestOrBatch": {
        "description": "One JSON-RPC request or a non-empty batch.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/JsonRpcRequest"
          },
          {
            "$ref": "#/components/schemas/JsonRpcBatchRequest"
          }
        ]
      },
      "JsonRpcSuccess": {
        "type": "object",
        "description": "Successful JSON-RPC response.",
        "required": [
          "jsonrpc",
          "id",
          "result"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/JsonRpcId"
              },
              {
                "type": "null"
              }
            ]
          },
          "result": {
            "description": "Method-specific result returned by the selected EVM network."
          }
        },
        "additionalProperties": true
      },
      "JsonRpcErrorDetail": {
        "type": "object",
        "description": "JSON-RPC protocol, gateway-policy, or node error.",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "description": "Standard or implementation-defined JSON-RPC error code."
          },
          "message": {
            "type": "string",
            "minLength": 1,
            "description": "Human-readable error summary."
          },
          "data": {
            "type": "object",
            "description": "Optional structured context, retry guidance, and resolution hint.",
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "JsonRpcError": {
        "type": "object",
        "description": "JSON-RPC error response.",
        "required": [
          "jsonrpc",
          "id",
          "error"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/JsonRpcId"
              },
              {
                "type": "null"
              }
            ]
          },
          "error": {
            "$ref": "#/components/schemas/JsonRpcErrorDetail"
          }
        },
        "additionalProperties": true
      },
      "JsonRpcBatchResponse": {
        "type": "array",
        "description": "Responses for a JSON-RPC batch.",
        "minItems": 1,
        "items": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/JsonRpcSuccess"
            },
            {
              "$ref": "#/components/schemas/JsonRpcError"
            }
          ]
        }
      },
      "GatewayError": {
        "type": "object",
        "description": "Structured HTTP-layer error generated by the SolidRPC gateway before a node response is available.",
        "required": [
          "error",
          "code",
          "message",
          "resolution"
        ],
        "properties": {
          "error": {
            "type": "string",
            "minLength": 1,
            "description": "Backward-compatible short error label."
          },
          "code": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]*$",
            "description": "Stable machine-readable error code."
          },
          "message": {
            "type": "string",
            "minLength": 1,
            "description": "Human-readable explanation of the failure."
          },
          "resolution": {
            "type": "string",
            "minLength": 1,
            "description": "Concrete next step an agent or developer can take."
          },
          "documentation_url": {
            "type": "string",
            "format": "uri",
            "description": "Canonical SolidRPC documentation for this error class."
          }
        },
        "additionalProperties": true
      }
    },
    "responses": {
      "JsonRpcResponse": {
        "description": "A JSON-RPC result, JSON-RPC error, or batch response. Node-returned JSON-RPC errors use HTTP 200.",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitLimit"
          },
          "X-RateLimit-Burst": {
            "$ref": "#/components/headers/RateLimitBurst"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitReset"
          },
          "X-Quota-Limit": {
            "$ref": "#/components/headers/QuotaLimit"
          },
          "X-Quota-Used": {
            "$ref": "#/components/headers/QuotaUsed"
          },
          "X-Quota-Remaining": {
            "$ref": "#/components/headers/QuotaRemaining"
          },
          "X-Quota-Reset": {
            "$ref": "#/components/headers/QuotaReset"
          },
          "X-Quota-Window": {
            "$ref": "#/components/headers/QuotaWindow"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/JsonRpcSuccess"
                },
                {
                  "$ref": "#/components/schemas/JsonRpcError"
                },
                {
                  "$ref": "#/components/schemas/JsonRpcBatchResponse"
                }
              ]
            }
          }
        }
      },
      "BadRequest": {
        "description": "Malformed JSON, invalid JSON-RPC, or conflicting API-key sources.",
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/GatewayError"
                },
                {
                  "$ref": "#/components/schemas/JsonRpcError"
                }
              ]
            }
          }
        }
      },
      "Unauthorized": {
        "description": "The API key is missing or malformed, or a required customer JWT is missing or invalid.",
        "headers": {
          "WWW-Authenticate": {
            "description": "Bearer challenge when Bearer authentication is required.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GatewayError"
            }
          }
        }
      },
      "QuotaExceeded": {
        "description": "The account used its response-unit allowance and overage billing is not enabled.",
        "headers": {
          "X-Quota-Limit": {
            "$ref": "#/components/headers/QuotaLimit"
          },
          "X-Quota-Used": {
            "$ref": "#/components/headers/QuotaUsed"
          },
          "X-Quota-Remaining": {
            "$ref": "#/components/headers/QuotaRemaining"
          },
          "X-Quota-Reset": {
            "$ref": "#/components/headers/QuotaReset"
          },
          "X-Quota-Window": {
            "$ref": "#/components/headers/QuotaWindow"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GatewayError"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The API key is unknown or revoked, the subscription is inactive, or an API-key policy denied the request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GatewayError"
            }
          }
        }
      },
      "NotFound": {
        "description": "The requested gateway route or chain path does not exist.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GatewayError"
            }
          }
        }
      },
      "MethodNotAllowed": {
        "description": "The authenticated RPC route only accepts HTTPS POST requests.",
        "headers": {
          "Allow": {
            "description": "The method accepted by this route.",
            "schema": {
              "type": "string",
              "const": "POST"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GatewayError"
            }
          }
        }
      },
      "PublicChainNotFound": {
        "description": "The chain is not available through the keyless public endpoint.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/JsonRpcError"
            }
          }
        }
      },
      "RequestTooLarge": {
        "description": "The JSON request body exceeds 5 MB.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GatewayError"
            }
          }
        }
      },
      "RateLimited": {
        "description": "The authenticated account, key, or delegated token exceeded its rate limit. Retry-After is omitted when the submitted batch can never fit within the applicable burst limit.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitLimit"
          },
          "X-RateLimit-Burst": {
            "$ref": "#/components/headers/RateLimitBurst"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GatewayError"
            }
          }
        }
      },
      "PublicRateLimited": {
        "description": "The keyless public route exceeded its rate or daily quota. Retry-After is omitted when the submitted batch can never fit within the applicable burst limit.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitLimit"
          },
          "X-RateLimit-Burst": {
            "$ref": "#/components/headers/RateLimitBurst"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/JsonRpcError"
            }
          }
        }
      },
      "InternalError": {
        "description": "The gateway could not complete the request because of an unexpected internal failure. Proxy-generated variants include Retry-After; a generic unhandled failure or upstream pass-through may omit it.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/GatewayError"
                },
                {
                  "$ref": "#/components/schemas/JsonRpcError"
                }
              ]
            }
          }
        }
      },
      "BadGateway": {
        "description": "The gateway received an invalid upstream response. Gateway-generated proxy failures include Retry-After; an upstream pass-through may omit it.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/GatewayError"
                },
                {
                  "$ref": "#/components/schemas/JsonRpcError"
                }
              ]
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "A security, rate-limit, public block-resolution, or upstream dependency is temporarily unavailable. Gateway-generated auth and rate-limit failures include Retry-After; a public block-resolution error or upstream pass-through may omit it.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/GatewayError"
                },
                {
                  "$ref": "#/components/schemas/JsonRpcError"
                }
              ]
            }
          }
        }
      },
      "GatewayTimeout": {
        "description": "The upstream request exceeded the gateway timeout or lost its transport connection. Gateway-generated proxy failures include Retry-After; an upstream pass-through may omit it.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/GatewayError"
                },
                {
                  "$ref": "#/components/schemas/JsonRpcError"
                }
              ]
            }
          }
        }
      }
    }
  }
}