API Reference

Pocket Network exposes APIs at two levels: the Shannon chain (CometBFT/Cosmos SDK endpoints for on-chain operations) and the PATH gateway (relay forwarding and gateway management). Most developers only need the relay endpoints — the chain API is for operators and protocol integrators.

Relay API (Gateway/PATH)

This is what application developers interact with. Relay endpoints accept standard JSON-RPC requests and forward them through the Pocket Network to backend chains.

Endpoint Format

POST https://{chain-slug}.api.pocket.network
Content-Type: application/json

Request Body

Standard JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "method": "eth_blockNumber",
  "params": [],
  "id": 1
}

Response

Standard JSON-RPC 2.0 response from the backend chain:

{
  "jsonrpc": "2.0",
  "result": "0x134a5b8",
  "id": 1
}

Error Codes

Shannon Chain API

The Shannon chain (poktroll) exposes standard Cosmos SDK API endpoints. These are used for on-chain operations: staking, querying state, submitting governance proposals, etc.

CometBFT RPC

Default port: 26657

Used for transaction broadcasting, block queries, and consensus state. Standard CometBFT JSON-RPC interface.

# Get latest block
curl http://localhost:26657/block

# Broadcast transaction
curl -X POST http://localhost:26657/broadcast_tx_commit \
  -d '{"tx": "<encoded_tx>"}'

Cosmos REST (LCD)

Default port: 1317

RESTful API for querying chain state. Auto-generated from proto definitions.

# Query application
curl http://localhost:1317/poktroll/application/application/{address}

# Query all suppliers
curl http://localhost:1317/poktroll/supplier/supplier

# Query session
curl http://localhost:1317/poktroll/session/get_session?application_address={addr}&service_id={id}&block_height={height}

# Query shared params
curl http://localhost:1317/poktroll/shared/params

gRPC

Default port: 9090

Protocol Buffers-based API for programmatic access. Fastest option for service integrations.

# Using grpcurl
grpcurl -plaintext localhost:9090 poktroll.application.Query/Application
grpcurl -plaintext localhost:9090 poktroll.supplier.Query/AllSuppliers
grpcurl -plaintext localhost:9090 poktroll.session.Query/GetSession

Key Query Endpoints

Key Transaction Endpoints

PATH Gateway API

PATH exposes operational endpoints for monitoring and management:

OpenAPI Specifications

Full machine-readable API specs are available in the source repositories:

• Shannon chain: poktroll/docusaurus/open_api.md (~10K words, auto-generated from protos)
• PATH gateway: path/api/path_openapi.yaml

Related Pages

• Integration Examples — code samples for using relay endpoints
• Supported Chains — chain list with endpoint slugs
• Ports & Endpoints — full port reference for all services
• Shannon Architecture — module overview for chain API context