openapi: 3.1.0
info:
  title: Pocket Network CometBFT RPC Application Relays API
  description: 'Shannon full nodes expose the standard CometBFT (Tendermint) RPC on port 26657. It is a JSON-RPC 2.0 surface covering consensus, mempool, and network-level queries — node status, network info, peer set, block by height, block results, and unconfirmed transactions. Grove operates a public Shannon mainnet RPC at `shannon-grove-rpc.mainnet.poktroll.com`. Most operations are exposed both as JSON-RPC methods and as HTTP GET shortcuts at the same root URL.

    '
  version: v1
  contact:
    name: Pocket Network Foundation
    url: https://pocket.network
  license:
    name: MIT
    url: https://github.com/pokt-network/poktroll/blob/main/LICENSE
servers:
- url: https://shannon-grove-rpc.mainnet.poktroll.com
  description: Grove-operated Shannon mainnet CometBFT RPC
- url: https://shannon-testnet-grove-rpc.beta.poktroll.com
  description: Grove-operated Shannon beta testnet CometBFT RPC
tags:
- name: Relays
  description: JSON-RPC, REST, and WebSocket relays proxied to Shannon suppliers
paths:
  /v1/{appId}:
    post:
      summary: Send Authenticated JSON-RPC Relay
      description: 'Send a JSON-RPC payload for the configured service through a Grove portal application. The path segment `appId` is the Grove portal Application ID returned by the dashboard; the subdomain selects the chain (e.g. `eth.rpc.grove.city`). The request body is the standard JSON-RPC 2.0 envelope of the target chain — PATH does not rewrite it.

        '
      operationId: sendAuthenticatedRelay
      tags:
      - Relays
      parameters:
      - name: appId
        in: path
        required: true
        description: Grove portal Application ID (alphanumeric).
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        description: Optional bearer token for portal-secured applications.
        schema:
          type: string
      - name: Target-Service-Id
        in: header
        required: false
        description: 'Override the service-id derived from the subdomain. Used when self-hosting PATH behind a single hostname.

          '
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcRequest'
            examples:
              EthBlockNumber:
                summary: Ethereum eth_blockNumber
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: eth_blockNumber
                  params: []
              EthGetBalance:
                summary: Ethereum eth_getBalance
                value:
                  jsonrpc: '2.0'
                  id: 2
                  method: eth_getBalance
                  params:
                  - '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
                  - latest
      responses:
        '200':
          description: Successful relay response from a Shannon supplier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '401':
          description: Missing or invalid portal authentication.
        '402':
          description: Application out of compute units / over plan.
        '429':
          description: Rate limit exceeded for the application or organization.
        '503':
          description: No healthy supplier returned a usable response.
  /v1:
    post:
      summary: Send Public JSON-RPC Relay
      description: 'Send a JSON-RPC payload to a Grove public endpoint. No portal Application ID is required — the chain is identified by the subdomain. Public endpoints are throttled per-IP and intended for development.

        '
      operationId: sendPublicRelay
      tags:
      - Relays
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcRequest'
      responses:
        '200':
          description: Successful relay response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '429':
          description: Public-endpoint rate limit exceeded.
components:
  schemas:
    JsonRpcRequest:
      type: object
      description: JSON-RPC 2.0 request envelope of the target service.
      required:
      - jsonrpc
      - method
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          oneOf:
          - type: integer
          - type: string
          - type: 'null'
        method:
          type: string
          description: JSON-RPC method of the target chain (e.g. eth_blockNumber).
        params:
          description: Method parameters, varies per chain and method.
          oneOf:
          - type: array
          - type: object
    JsonRpcResponse:
      type: object
      description: JSON-RPC 2.0 response envelope returned by the supplier.
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          oneOf:
          - type: integer
          - type: string
          - type: 'null'
        result: {}
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
            data: {}