openapi: 3.0.3
info:
  title: PATH - Path & Toolkit Harness API API
  description: PATH (Path API & Toolkit Harness) is an open source framework for enabling access to a decentralized supply network. It provides various tools and libraries to streamline the integration and interaction with decentralized protocols.
  version: 1.0.0
  contact:
    name: Grove Engineering
    email: engineering@grove.city
servers:
- url: https://{serviceId}.rpc.grove.city
  description: Production PATH URL with service-specific subdomain
  variables:
    serviceId:
      default: eth
      description: The service ID that determines the subdomain
      enum:
      - arb-one
      - arb-sepolia-testnet
      - avax
      - avax-dfk
      - base
      - base-sepolia-testnet
      - bera
      - bitcoin
      - blast
      - boba
      - bsc
      - celo
      - eth
      - eth-holesky-testnet
      - eth-sepolia-testnet
      - fantom
      - fraxtal
      - fuse
      - gnosis
      - harmony
      - ink
      - iotex
      - kaia
      - kava
      - linea
      - mantle
      - metis
      - moonbeam
      - moonriver
      - near
      - oasys
      - op
      - op-sepolia-testnet
      - opbnb
      - pocket
      - poly
      - poly-amoy-testnet
      - poly-zkevm
      - radix
      - scroll
      - sei
      - sonic
      - sui
      - taiko
      - taiko-hekla-testnet
      - tron
      - xrplevm
      - xrplevm-testnet
      - zklink-nova
      - zksync-era
- url: http://localhost:3069
  description: Local PATH instance
security:
- ApiKeyAuth: []
tags:
- name: API
  description: PATH API endpoints
paths:
  /v1:
    post:
      tags:
      - API
      summary: EVM Service Request
      description: "Handles EVM service requests. This endpoint processes API requests and forwards them to the appropriate endpoint in the Pocket Network.\n\n**Server Usage & Authentication:**\n- **Subdomain URLs** (`https://{serviceId}.rpc.grove.city`):\n  - Service ID determined from subdomain, no `Target-Service-Id` header needed\n  - **Requires** `Portal-Application-ID` header with your Grove Portal Application ID\n  - **Optional** `Authorization` header with Grove API Key (if your portal app requires it)\n- **Local PATH** (`http://localhost:3069`):\n  - **Requires** `Target-Service-Id` header to specify the service\n  - No authentication headers required\n"
      operationId: 1handleServiceRequest
      parameters:
      - $ref: '#/components/parameters/PortalApplicationIdParam'
      - $ref: '#/components/parameters/PortalAPIKey'
      - $ref: '#/components/parameters/TargetServiceIdParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                jsonrpc:
                  type: string
                  description: JSON-RPC version
                  example: '2.0'
                method:
                  type: string
                  description: Method to call
                  example: eth_blockNumber
                params:
                  type: array
                  description: Parameters for the method
                  items:
                    type: object
                  example: []
                id:
                  type: integer
                  description: Request identifier
                  example: 1
            examples:
              eth_blockNumber:
                summary: Ethereum Block Number Request
                value:
                  jsonrpc: '2.0'
                  method: eth_blockNumber
                  params: []
                  id: 1
              eth_call:
                summary: Call a Contract Method
                value:
                  jsonrpc: '2.0'
                  method: eth_call
                  params:
                  - to: '0x6b175474e89094c44da98b954eedeac495271d0f'
                    data: '0x70a08231000000000000000000000000b5d85cbf7cb3ee0d56b3bb207d5fc4b82f43f511'
                  - latest
                  id: 2
              eth_getTransactionReceipt:
                summary: Get Transaction Receipt
                value:
                  jsonrpc: '2.0'
                  method: eth_getTransactionReceipt
                  params:
                  - '0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238'
                  id: 3
              eth_getBlockByNumber:
                summary: Get Block By Number
                value:
                  jsonrpc: '2.0'
                  method: eth_getBlockByNumber
                  params:
                  - '0x1b4'
                  - true
                  id: 4
              eth_getBalance:
                summary: Get Account Balance
                value:
                  jsonrpc: '2.0'
                  method: eth_getBalance
                  params:
                  - '0xc94770007dda54cF92009BFF0dE90c06F603a09f'
                  - latest
                  id: 5
              eth_chainId:
                summary: Get Chain ID
                value:
                  jsonrpc: '2.0'
                  method: eth_chainId
                  params: []
                  id: 6
              eth_getTransactionCount:
                summary: Get Transaction Count for Address
                value:
                  jsonrpc: '2.0'
                  method: eth_getTransactionCount
                  params:
                  - '0xc94770007dda54cF92009BFF0dE90c06F603a09f'
                  - latest
                  id: 7
              eth_getTransactionByHash:
                summary: Get Transaction By Hash
                value:
                  jsonrpc: '2.0'
                  method: eth_getTransactionByHash
                  params:
                  - '0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238'
                  id: 8
              eth_gasPrice:
                summary: Get Current Gas Price
                value:
                  jsonrpc: '2.0'
                  method: eth_gasPrice
                  params: []
                  id: 9
      responses:
        '200':
          description: Successful JSON-RPC response
          content:
            application/json:
              schema:
                type: object
                properties:
                  jsonrpc:
                    type: string
                    description: JSON-RPC version
                    example: '2.0'
                  id:
                    type: integer
                    description: Request identifier that matches the request
                    example: 1
                  result:
                    type: string
                    description: Result of the request (format depends on the method called)
                    example: '0xc96eae'
              examples:
                eth_blockNumber:
                  summary: Ethereum Block Number Response
                  value:
                    jsonrpc: '2.0'
                    id: 1
                    result: '0xc96eae'
                eth_call:
                  summary: Contract Call Response
                  value:
                    jsonrpc: '2.0'
                    id: 2
                    result: '0x000000000000000000000000000000000000000000000000000000012a05f200'
                eth_getTransactionReceipt:
                  summary: Transaction Receipt Response
                  value:
                    jsonrpc: '2.0'
                    id: 3
                    result:
                      blockHash: '0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2'
                      blockNumber: '0x5daf3b'
                      contractAddress: null
                      cumulativeGasUsed: '0x7f110'
                      effectiveGasPrice: '0x7f110'
                      from: '0xa7d9ddbe1f17865597fbd27ec712455208b6b76d'
                      gasUsed: '0x5208'
                      logs: []
                      logsBloom: '0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000'
                      status: '0x1'
                      to: '0xf02c1c8e6114b1dbe8937a39260b5b0a374432bb'
                      transactionHash: '0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238'
                      transactionIndex: '0x1'
                eth_getBlockByNumber:
                  summary: Block By Number Response
                  value:
                    jsonrpc: '2.0'
                    id: 4
                    result:
                      number: '0x1b4'
                      hash: '0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331'
                      parentHash: '0x9646252be9520f6e71339a8df9c55e4d7619deeb018d2a3f2d21fc165dde5eb5'
                      nonce: '0xe04d296d2460cfb8472af2c5fd05b5a214109c25688d3704aed5484f9a7792f2'
                      sha3Uncles: '0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347'
                      logsBloom: '0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331'
                      transactionsRoot: '0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421'
                      stateRoot: '0xd5855eb08b3387c0af375e9cdb6acfc05eb8f519e419b874b6ff2ffda7ed1dff'
                      miner: '0x4e65fda2159562a496f9f3522f89122a3088497a'
                      difficulty: '0x027f07'
                      totalDifficulty: '0x027f07'
                      extraData: '0x0000000000000000000000000000000000000000000000000000000000000000'
                      size: '0x027f07'
                      gasLimit: '0x9f759'
                      gasUsed: '0x9f759'
                      timestamp: '0x54e34e8e'
                      transactions:
                      - hash: '0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b'
                        nonce: 0x
                        blockHash: '0xbeab0aa2411b7ab17f30a99d3cb9c6ef2fc5426d6ad6fd9e2a26a6aed1d1055b'
                        blockNumber: '0x15df'
                        transactionIndex: '0x1'
                        from: '0x407d73d8a49eeb85d32cf465507dd71d507100c1'
                        to: 0x85h43d8a49eeb85d32cf465507dd71d507100c1
                        value: '0x7f110'
                        gas: '0x7f110'
                        gasPrice: '0x09184e72a000'
                        input: '0x603880600c6000396000f300603880600c6000396000f3603880600c6000396000f360'
                      uncles: []
                eth_getBalance:
                  summary: Account Balance Response
                  value:
                    jsonrpc: '2.0'
                    id: 5
                    result: '0x0234c8a3397aab58'
                eth_chainId:
                  summary: Chain ID Response
                  value:
                    jsonrpc: '2.0'
                    id: 6
                    result: '0x1'
                eth_getTransactionCount:
                  summary: Transaction Count Response
                  value:
                    jsonrpc: '2.0'
                    id: 7
                    result: '0x1'
                eth_getTransactionByHash:
                  summary: Transaction By Hash Response
                  value:
                    jsonrpc: '2.0'
                    id: 8
                    result:
                      blockHash: '0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2'
                      blockNumber: '0x5daf3b'
                      from: '0xa7d9ddbe1f17865597fbd27ec712455208b6b76d'
                      gas: '0x24a22'
                      gasPrice: '0x2540be400'
                      hash: '0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238'
                      input: '0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675'
                      nonce: '0x9'
                      to: '0xf02c1c8e6114b1dbe8937a39260b5b0a374432bb'
                      transactionIndex: '0x1'
                      value: '0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675'
                      type: '0x0'
                      v: '0x1c'
                      r: '0x4e65fda2159562a496f9f3522f89122a3088497a'
                      s: '0x7a25abe9ee27691173cd5f82c7382755dd7d2bb7feea88a61b599ede1dd944'
                eth_gasPrice:
                  summary: Gas Price Response
                  value:
                    jsonrpc: '2.0'
                    id: 9
                    result: '0x4a817c800'
  /healthz:
    get:
      tags:
      - API
      summary: Health Check
      description: Returns a JSON health check response indicating the ready status of PATH
      operationId: 2healthCheck
      security: []
      responses:
        '200':
          description: Health check successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  message:
                    type: string
                    example: PATH is up and running
                  version:
                    type: string
                    example: 1.0.0
                  readyStates:
                    type: object
                    additionalProperties:
                      type: boolean
                    example:
                      endpoint-hydrator: true
                      pokt-shannon: true
                  configuredServiceIDs:
                    type: array
                    items:
                      type: string
                    example:
                    - eth
                    - poly
                    - avax
  /disqualified_endpoints:
    get:
      tags:
      - API
      summary: Disqualified Endpoints
      description: Returns a JSON list of disqualified endpoints for a given service ID.
      operationId: 3disqualifiedEndpoints
      parameters:
      - $ref: '#/components/parameters/TargetServiceIdParam'
      responses:
        '200':
          description: Successfully retrieved disqualified endpoints
          content:
            application/json:
              schema:
                type: object
                properties:
                  protocol_level_data_response:
                    type: object
                    properties:
                      permanently_sanctioned_endpoints:
                        type: object
                      session_sanctioned_endpoints:
                        type: object
                        additionalProperties:
                          type: object
                          properties:
                            endpoint_addr:
                              type: string
                            reason:
                              type: string
                            service_id:
                              type: string
                            sanction_type:
                              type: string
                            error_type:
                              type: string
                            session_height:
                              type: integer
                            created_at:
                              type: string
                              format: date-time
                      permanent_sanctioned_endpoints_count:
                        type: integer
                      session_sanctioned_endpoints_count:
                        type: integer
                      total_sanctioned_endpoints_count:
                        type: integer
                  qos_level_data_response:
                    type: object
                    properties:
                      disqualified_endpoints:
                        type: object
                      empty_response_count:
                        type: integer
                      chain_id_check_errors_count:
                        type: integer
                      archival_check_errors_count:
                        type: integer
                      block_number_check_errors_count:
                        type: integer
                  total_service_endpoints_count:
                    type: integer
                  valid_service_endpoints_count:
                    type: integer
                  invalid_service_endpoints_count:
                    type: integer
              examples:
                successResponse:
                  summary: Successful disqualified endpoints response
                  value:
                    protocol_level_data_response:
                      permanently_sanctioned_endpoints: {}
                      session_sanctioned_endpoints: {}
                      permanent_sanctioned_endpoints_count: 0
                      session_sanctioned_endpoints_count: 0
                      total_sanctioned_endpoints_count: 0
                    qos_level_data_response:
                      disqualified_endpoints: {}
                      empty_response_count: 0
                      chain_id_check_errors_count: 0
                      archival_check_errors_count: 0
                      block_number_check_errors_count: 0
                    total_service_endpoints_count: 5
                    valid_service_endpoints_count: 5
                    invalid_service_endpoints_count: 0
                disqualifiedEndpointsExample:
                  summary: Response with disqualified endpoints
                  value:
                    protocol_level_disqualified_endpoints:
                      permanently_sanctioned_endpoints: {}
                      session_sanctioned_endpoints:
                        pokt13771d0a403a599ee4a3812321e2fabc509e7f3-https://us-west-test-endpoint-1.demo:
                          supplier_address: pokt13771d0a403a599ee4a3812321e2fabc509e7f3
                          endpoint_url: https://us-west-test-endpoint-1.demo
                          app_addr: pokt1ccae0ce5ef5b1bcd74f3794f5b717b98a86412
                          session_id: 5a496c9faaabbaa1d184cf89ddfeb603ff515b990c6f714701b71572ab750ae8
                          service_id: base
                          reason: 'relay error: relay: error sending request to endpoint https://us-west-test-endpoint-1.demo: Post "https://us-west-test-endpoint-1.demo": dial tcp: lookup us-west-demo1-base-json.demo.do: no such host'
                          sanction_type: SHANNON_SANCTION_SESSION
                          error_type: SHANNON_ENDPOINT_ERROR_TIMEOUT
                          session_height: 23951
                          created_at: '2025-05-31T14:57:41.484372+01:00'
                      permanent_sanctioned_endpoints_count: 0
                      session_sanctioned_endpoints_count: 1
                      total_sanctioned_endpoints_count: 1
                    qos_level_disqualified_endpoints:
                      disqualified_endpoints:
                        pokt1ccae0ce5ef5b1bcd74f3794f5b717b98a86412-https://us-west-test-endpoint-1.demo:
                          endpoint_addr: pokt1ccae0ce5ef5b1bcd74f3794f5b717b98a86412-https://us-west-test-endpoint-1.demo
                          reason: endpoint has not returned an archival balance response to a "eth_getBalance" request
                          service_id: base
                      empty_response_count: 0
                      chain_id_check_errors_count: 0
                      archival_check_errors_count: 1
                      block_number_check_errors_count: 0
                    total_service_endpoints_count: 11
                    qualified_service_endpoints_count: 9
                    disqualified_service_endpoints_count: 2
        '400':
          description: Bad request - Target-Service-Id header is required or invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
              examples:
                missingHeader:
                  summary: Missing Target-Service-Id header
                  value:
                    error: 400 Bad Request
                    message: Target-Service-Id header is required
                invalidServiceId:
                  summary: Invalid service ID
                  value:
                    error: 400 Bad Request
                    message: 'invalid service ID: no apps matched the request for service: earth'
components:
  parameters:
    PortalApplicationIdParam:
      name: Portal-Application-ID
      in: header
      required: false
      description: 'Grove Portal Application ID for authentication.


        **Required when using:**

        - `https://{serviceId}.rpc.grove.city` (production subdomain URLs)


        **Not required when using:**

        - `http://localhost:3069` (local PATH instance)


        Get yours at https://portal.grove.city/

        '
      schema:
        type: string
      example: your-grove-portal-app-id
    PortalAPIKey:
      name: Authorization
      in: header
      required: false
      description: 'Grove API Key for authorization (optional).


        **When to use:**

        - Required if your Grove Portal application requires API key authorization

        - Not required for applications without API key restrictions

        - Only applicable when using production URLs (`https://{serviceId}.rpc.grove.city`)

        - Not used with local PATH instances (`http://localhost:3069`)


        Get yours at https://portal.grove.city/

        '
      schema:
        type: string
      example: your-api-key
    TargetServiceIdParam:
      name: Target-Service-Id
      in: header
      required: false
      description: 'The service ID to route the request to (required for local PATH instance)


        **Required when using:**

        - `http://localhost:3069` (local PATH instance)


        **Not required when using:**

        - `https://{serviceId}.rpc.grove.city` (service-specific subdomain URLs)


        When using subdomain-based URLs, the service ID is automatically determined from the subdomain.

        '
      schema:
        type: string