Documentation
Documentation
https://docs.pocket.network/
RateLimits
https://github.com/api-evangelist/pokt/blob/main/rate-limits/rate-limits.yml
OpenAPI Specification
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