Pocket Network Relays API

openapi: 3.2.0
info:
  title: Pocket Network PATH Gateway Relays API
  description: 'PATH (Path API and Toolkit Harness) is the open-source Go gateway maintained by Grove (github.com/buildwithgrove/path mirrored at github.com/pokt-network/path) that exposes Pocket Network Shannon as a single HTTP surface. PATH proxies JSON-RPC, REST, and WebSocket calls for every service (blockchain) staked on Shannon, selects suppliers via Quality-of-Service scoring, signs relay requests with the operator''s Gateway and Application keys, and returns upstream responses verbatim. The same protocol drives Grove''s hosted endpoints on rpc.grove.city — each chain is exposed as a subdomain such as `eth.rpc.grove.city/v1/{appId}` or `solana.rpc.grove.city/v1/{appId}`. The payload for every operation is the JSON-RPC envelope of the target chain (e.g. Ethereum eth_*, Solana getBalance) so PATH itself is service-agnostic.

    '
  version: 0.1.0
  contact:
    name: Grove Support
    url: https://grove.city
  license:
    name: MIT
    url: https://github.com/buildwithgrove/path/blob/main/LICENSE
servers:
- url: https://rpc.grove.city
  description: Grove hosted PATH gateway (authenticated, paid)
- url: https://eth.rpc.grove.city
  description: Grove public Ethereum endpoint (no key required)
- url: https://solana.rpc.grove.city
  description: Grove public Solana endpoint (no key required)
security:
- PortalApplicationId: []
- {}
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: {}
  securitySchemes:
    PortalApplicationId:
      type: apiKey
      in: path
      name: appId
      description: Grove portal Application ID embedded in the relay URL.