Querying the Chain
Overview
Pocket Network is a public blockchain, which means all of its data is open for anyone to inspect. Querying the chain is simply reading information from the network — looking up account balances, checking which suppliers are active, reviewing governance settings, or examining session details.
Think of the blockchain as a public bulletin board. Everything posted there — every staked application, every registered supplier, every governance parameter — is visible to anyone who knows where to look. Querying is how you read that bulletin board.
Importantly, queries are read-only. They do not change anything on the network. You are simply asking the network a question and getting an answer back. There are no fees for querying, and you do not need to have an account or stake to look up information.
Why Query the Chain?
Different participants query the chain for different reasons:
- Token holders might check their account balance or look up the current tokenomics settings to understand how rewards are distributed.
- Application operators might look up their staking status, see which gateways they are delegated to, or check which suppliers were assigned to their latest session.
- Suppliers might verify their registration, check their staking amount, review relay mining difficulty for the services they provide, or examine their claims and proofs.
- Gateway operators might confirm their staking status and review the current minimum stake requirement.
- Community members and governance participants might review the current parameters for any module to understand the network’s current configuration before proposing changes.
- Analysts and researchers might browse the full list of services, suppliers, or applications to understand network health and growth.
- Migration participants might check whether their Morse account is available for claiming on Shannon.
What You Can Look Up
Application Information
You can look up details about any staked application on the network:
- All applications — Browse the complete list of staked applications.
- A specific application — Look up a single application by its address to see its stake amount, which gateways it delegates to, which services it uses, and any pending changes.
- Application parameters — Check the current governance settings for applications, such as the maximum number of gateways and the minimum stake requirement.
Gateway Information
You can look up details about gateways operating on the network:
- All gateways — Browse the complete list of staked gateways.
- A specific gateway — Look up a single gateway by its address to see its stake amount and status.
- Gateway parameters — Check the current minimum stake and other gateway settings.
Supplier Information
Supplier queries are especially rich, with several ways to filter and narrow results:
- All suppliers — Browse the full list of registered suppliers.
- Filtered by service — See only the suppliers that serve a particular service (for example, all suppliers serving Ethereum Mainnet).
- Filtered by owner or operator — Find suppliers associated with a particular address.
- A specific supplier — Look up a single supplier to see its full details: stake amount, services offered, service configuration history, and revenue sharing setup.
- Supplier parameters — Check the current minimum stake and staking fee.
Supplier queries also support a compact mode that omits detailed history and revenue share information, which is useful when you just need a quick overview rather than full details.
Service Information
Services are the APIs and blockchains available through Pocket Network. You can explore:
- All services — Browse every registered service on the network.
- A specific service — Look up a service by its identifier to see its name, compute units per relay, owner, and full metadata (API specifications).
- Relay mining difficulty — Check the current difficulty level for any service. Difficulty adjusts automatically based on traffic to keep the network balanced. You can also look up the difficulty at a specific point in time or browse the full history of difficulty changes for a service.
- Service parameters — Check the fee to register a new service and the target relay volume.
Session Information
Sessions are the time windows during which specific suppliers are matched with applications:
- A specific session — Look up which suppliers were assigned to serve a particular application for a particular service at a given point in time. This is useful for debugging or auditing relay delivery.
- Session parameters — Check how many suppliers are assigned per session and other timing settings.
Proof and Claim Information
The proof system is how the network verifies that work was done. You can examine:
- All claims — Browse claims that suppliers have submitted for their work during sessions. You can filter by session, by block height, or by supplier address.
- A specific claim — Look up the details of a particular claim.
- All proofs — Browse the cryptographic proofs that suppliers have submitted. The same filtering options are available as for claims.
- A specific proof — Look up the details of a particular proof.
Claims and proofs are temporary — they are removed from the chain after they have been fully processed and the dispute window has closed.
Tokenomics Information
- Tokenomics parameters — Review the complete set of economic settings: inflation rate, mint allocations, the DAO reward address, the burn distribution, and the deflationary mint ratio introduced by PIP-41.
Shared Module Information
- Shared parameters — Review the cross-module settings that affect session timing, unbonding periods, and compute unit pricing. These are the fundamental coordination parameters of the network.
Migration Information
- Migration parameters — Check whether gas fees are waived for migration claims and whether claiming is currently enabled.
- All Morse claimable accounts — Browse the list of Morse accounts that have been imported and are available for claiming.
- A specific Morse claimable account — Look up a particular Morse address to see its balance, stake, and whether it has already been claimed.
General Blockchain Information
Beyond Pocket-specific data, you can also look up standard blockchain information:
- Account balances — Check the POKT balance of any address.
- Transaction details — Look up a specific transaction by its unique hash to see whether it succeeded, what it did, and when it was processed.
- Block information — Examine the contents of a specific block at a given height.
- Governance proposals — Review any active or past governance proposals.
- Authorization grants — See what governance permissions have been granted and to whom.
Browsing Results Page by Page
When you query a list — such as all suppliers or all services — the results may be too numerous to return all at once. The network handles this through pagination, which works just like pages in a book or search results on a website.
You can:
- Set a page size — Choose how many results to show per page (for example, 50 or 100 at a time).
- Navigate pages — Move forward and backward through the results.
- Get a total count — Ask the network how many total items exist so you know how many pages there are.
- Reverse the order — View results in reverse order if needed.
This makes it practical to browse even very large datasets without overwhelming your connection or waiting for massive responses.
Historical Queries
One powerful feature of blockchain queries is the ability to look back in time. You can query the state of the network at any past block height. This means you can answer questions like:
- “What was this application’s stake 1,000 blocks ago?”
- “Which suppliers were active last week?”
- “What was the relay mining difficulty for Ethereum at block 5,000?”
Historical queries are invaluable for auditing, analysis, and dispute resolution.
Summary of Available Queries
| Area | What You Can Look Up |
|---|---|
| Applications | Parameters, list all, show one by address |
| Gateways | Parameters, list all, show one by address |
| Suppliers | Parameters, list all (with filters by service/owner/operator), show one by address |
| Services | Parameters, list all, show one by ID, relay mining difficulty (current, historical, at a given height) |
| Sessions | Parameters, look up a session by application + service + block height |
| Proofs and Claims | Parameters, list claims (with filters), show one claim, list proofs (with filters), show one proof |
| Tokenomics | Parameters (inflation, mint allocation, burn distribution, mint ratio) |
| Shared | Parameters (session timing, unbonding periods, compute unit pricing) |
| Migration | Parameters, list claimable Morse accounts, show one claimable account |
| General | Account balances, transactions, blocks, governance proposals, authorization grants |
For the exact technical commands and syntax, see the developer documentation.
This document covers every available query command across all Pocket Network Shannon modules. Each command is shown with its full pocketd CLI syntax, available flags, filtering options, and pagination support.
Common Query Flags
All query commands support the following standard Cosmos SDK flags:
| Flag | Description |
|---|---|
--network | Target network (local, beta, main) |
--node | RPC endpoint URL (overrides --network) |
--output | Output format: text (default) or json |
--height | Query state at a specific block height |
--home | Path to pocketd home directory |
Pagination
List queries that return multiple items support pagination via the following flags:
| Flag | Description |
|---|---|
--page | Page number (1-indexed) |
--limit | Number of results per page |
--count-total | Include total count in response |
--offset | Number of results to skip (alternative to --page) |
--reverse | Reverse the order of results |
--page-key | Key for cursor-based pagination (from a previous response) |
Example using pagination:
pocketd query supplier list-suppliers --page 2 --limit 50 --network=mainApplication Module Queries
Query Application Parameters
Displays all governance parameters for the application module.
pocketd query application params --network=mainList All Applications
Returns a paginated list of all staked applications on the network.
pocketd query application list-application --network=mainWith pagination:
pocketd query application list-application --limit 50 --page 1 --network=mainShow a Specific Application
Retrieves detailed information about a single staked application by its address.
pocketd query application show-application pokt1mrqt5f7qh8uxs27cjm9t7v9e74a9vvdnq5jva4 --network=mainThe response includes the application’s staked amount, delegated gateways, service configurations, and pending undelegations.
Gateway Module Queries
Query Gateway Parameters
Displays all governance parameters for the gateway module.
pocketd query gateway params --network=mainList All Gateways
Returns a paginated list of all staked gateways.
pocketd query gateway list-gateway --network=mainWith pagination:
pocketd query gateway list-gateway --limit 100 --page 1 --network=mainShow a Specific Gateway
Retrieves detailed information about a single gateway by its address.
pocketd query gateway show-gateway pokt1abc123...xyz --network=mainSupplier Module Queries
Query Supplier Parameters
Displays all governance parameters for the supplier module.
pocketd query supplier params --network=mainList All Suppliers
New in v0.1.31: The
--owner-address,--operator-address, and--dehydratedflags were added to support filtering and compact responses.
Returns a paginated list of all suppliers registered on the network. Supports optional filtering by service ID, operator address, or owner address. Multiple filters can be combined (AND logic).
pocketd query supplier list-suppliers --network=mainAliases: suppliers, ls
Filtering by Service ID
Return only suppliers that serve a specific service:
pocketd query supplier list-suppliers --service-id anvil --network=mainThe --service-id flag (shorthand: -s) accepts a service ID string.
Filtering by Operator Address
Return only suppliers operated by a specific address:
pocketd query supplier list-suppliers --operator-address pokt1operator...xyz --network=mainFiltering by Owner Address
Return only suppliers owned by a specific address:
pocketd query supplier list-suppliers --owner-address pokt1owner...xyz --network=mainCombining Filters
Filters can be combined. For example, suppliers serving “anvil” owned by a specific address:
pocketd query supplier list-suppliers \
--service-id anvil \
--owner-address pokt1owner...xyz \
--network=mainDehydrated Output
Use the --dehydrated flag (shorthand: -d) to exclude service_config_history and rev_share details for a smaller response payload:
pocketd query supplier list-suppliers --dehydrated --network=mainCombining filters with dehydrated output and pagination:
pocketd query supplier list-suppliers \
--service-id anvil \
--dehydrated \
--page 1 \
--limit 100 \
--network=mainShow a Specific Supplier
Retrieves comprehensive information about a supplier identified by their operator address.
pocketd query supplier show-supplier pokt1operator...xyz --network=mainAliases: supplier, s
Returned details include:
- Supplier staked amount and status
- List of services provided
- Service configuration history
- Revenue share configuration
With JSON output:
pocketd query supplier show-supplier pokt1operator...xyz --output json --network=mainAt a specific block height:
pocketd query supplier show-supplier pokt1operator...xyz --height 100 --network=mainWith dehydrated output (compact, excluding history and rev share):
pocketd query supplier show-supplier pokt1operator...xyz --dehydrated --network=mainService Module Queries
Query Service Parameters
Displays all governance parameters for the service module.
pocketd query service params --network=mainList All Services
Returns a paginated list of all services registered on the network. By default, service metadata (API specifications) is excluded to reduce payload size.
pocketd query service all-services --network=mainWith pagination:
pocketd query service all-services --limit 50 --page 2 --network=mainTo include full metadata (up to 256 KiB per service):
pocketd query service all-services --dehydrated=false --network=mainShow a Specific Service
Retrieves full details for a service by its unique on-chain ID. By default, metadata is included in the response.
pocketd query service show-service anvil --network=mainReturned details include:
- Service ID and name
- Compute units per relay
- Owner address
- Full metadata (API specifications)
With JSON output:
pocketd query service show-service anvil --output json --network=mainWith dehydrated output (no metadata):
pocketd query service show-service anvil --dehydrated --network=mainRelay Mining Difficulty — All Services
Lists the current relay mining difficulty for every service on the network.
pocketd query service relay-mining-difficulty-all --network=mainRelay Mining Difficulty — Single Service
Shows the current relay mining difficulty for a specific service.
pocketd query service relay-mining-difficulty anvil --network=mainRelay Mining Difficulty at a Specific Height
New in v0.1.31: Historical relay mining difficulty queries are now supported via the on-chain difficulty history store.
Shows the relay mining difficulty that was effective for a specific service at a given block height. This is useful for historical analysis and verifying the difficulty used during past sessions.
pocketd query service relay-mining-difficulty-at-height anvil 1000 --network=mainArguments:
service-id— The service to queryblock-height— The block height to look up
Relay Mining Difficulty History
Lists all historical relay mining difficulty changes for a specific service. Each entry shows when a difficulty became effective and its parameters.
pocketd query service relay-mining-difficulty-history anvil --network=mainSupports pagination:
pocketd query service relay-mining-difficulty-history anvil --limit 50 --page 1 --network=mainSession Module Queries
Query Session Parameters
Displays all governance parameters for the session module.
pocketd query session params --network=mainGet a Session
Queries session data for a specific (application, service, block height) tuple. This is a read-only query that does not modify chain state.
pocketd query session get-session <application_address> <service_id> [block_height] --network=mainArguments:
application_address— The staked application’s bech32 addressservice_id— The service ID for the sessionblock_height(optional) — The block height for the session. If omitted, defaults to the latest height.
Examples:
# Get the current session for an app and service
pocketd query session get-session pokt1mrqt5f7qh8uxs27cjm9t7v9e74a9vvdnq5jva4 anvil --network=main
# Get the session at a specific block height
pocketd query session get-session pokt1mrqt5f7qh8uxs27cjm9t7v9e74a9vvdnq5jva4 anvil 42 --network=mainThe response includes:
- Session header (application address, service, session start/end heights, session ID)
- List of suppliers assigned to the session
- Session number
Proof Module Queries
Query Proof Parameters
Displays all governance parameters for the proof module.
pocketd query proof params --network=mainList All Claims
Returns a paginated list of all claims in the node’s state. Claims can be filtered by exactly one of the following flags (only one filter at a time):
| Flag | Description |
|---|---|
--session-id | Filter by session ID |
--session-end-height | Filter by session end block height |
--supplier-operator-address | Filter by supplier operator address |
# List all claims
pocketd query proof list-claims --network=main
# Filter by session ID
pocketd query proof list-claims --session-id abc123...def --network=main
# Filter by session end height
pocketd query proof list-claims --session-end-height 1000 --network=main
# Filter by supplier operator address
pocketd query proof list-claims --supplier-operator-address pokt1supplier...xyz --network=mainWith pagination:
pocketd query proof list-claims --limit 100 --page 1 --network=mainShow a Specific Claim
Retrieves a specific claim identified by its session ID and supplier operator address. Claims are pruned from state after their proof has been submitted and the dispute window has closed.
pocketd query proof show-claim <session_id> <supplier_operator_address> --network=mainExample:
pocketd query proof show-claim abc123...def pokt1supplier...xyz --network=mainList All Proofs
Returns a paginated list of all proofs in the node’s state. Supports the same filter flags as claims (only one at a time):
| Flag | Description |
|---|---|
--session-id | Filter by session ID |
--session-end-height | Filter by session end block height |
--supplier-operator-address | Filter by supplier operator address |
# List all proofs
pocketd query proof list-proofs --network=main
# Filter by session ID
pocketd query proof list-proofs --session-id abc123...def --network=main
# Filter by session end height
pocketd query proof list-proofs --session-end-height 1000 --network=main
# Filter by supplier operator address
pocketd query proof list-proofs --supplier-operator-address pokt1supplier...xyz --network=mainWith pagination:
pocketd query proof list-proofs --limit 100 --page 1 --network=mainShow a Specific Proof
Retrieves a specific proof identified by its session ID and supplier operator address.
pocketd query proof show-proof <session_id> <supplier_operator_address> --network=mainExample:
pocketd query proof show-proof abc123...def pokt1supplier...xyz --network=mainTokenomics Module Queries
Query Tokenomics Parameters
Displays all governance parameters for the tokenomics module, including mint allocations, inflation rates, and the deflationary mint ratio.
pocketd query tokenomics params --network=mainNew in v0.1.31: The
mint_ratioparameter (PIP-41) is now included in the tokenomics params response.
Shared Module Queries
Query Shared Parameters
Displays all governance parameters for the shared module, including session timing, unbonding periods, and compute unit pricing.
pocketd query shared params --network=mainMigration Module Queries
Query Migration Parameters
Displays the migration module parameters that control the Morse-to-Shannon migration process.
pocketd query migration params --network=mainList Morse Claimable Accounts
Returns a paginated list of all Morse claimable accounts that have been imported on-chain and are available for claiming.
pocketd query migration list-morse-claimable-account --network=mainWith pagination:
pocketd query migration list-morse-claimable-account --limit 100 --page 1 --network=mainShow a Specific Morse Claimable Account
Retrieves details for a specific Morse claimable account by its Morse address.
pocketd query migration show-morse-claimable-account <morse_address_hex> --network=mainExample:
pocketd query migration show-morse-claimable-account A1B2C3D4E5F6... --network=mainStandard Cosmos SDK Queries
In addition to the Pocket-specific module queries above, pocketd supports all standard Cosmos SDK query commands. Below are some commonly used ones.
Account Balance
pocketd query bank balances pokt1youraddress... --network=mainTransaction by Hash
pocketd query tx --type=hash <TRANSACTION_HASH> --network=mainBlock at Height
pocketd query block --type=height 1000 --network=mainAuthorization Grants
# Grants issued by a specific granter
pocketd query authz grants-by-granter pokt10d07y265gmmuvt4z0w9aw880jnsr700j8yv32t --network=main
# Grants received by a specific grantee
pocketd query authz grants-by-grantee pokt1hv3xrylxvwd7hfv03j50ql0ttp3s5hqqelegmv --network=mainConsensus Parameters
pocketd query consensus params --network=mainStaking Parameters
pocketd query staking params --network=mainGovernance Proposals
pocketd query gov proposals --network=mainQuery Command Summary Table
The following table provides a complete reference of all Pocket-specific query commands:
| Module | Command | Description |
|---|---|---|
application | params | Show application module parameters |
application | list-application | List all staked applications |
application | show-application <address> | Show a specific application |
gateway | params | Show gateway module parameters |
gateway | list-gateway | List all staked gateways |
gateway | show-gateway <address> | Show a specific gateway |
supplier | params | Show supplier module parameters |
supplier | list-suppliers | List all suppliers (filterable) |
supplier | show-supplier <operator_address> | Show a specific supplier |
service | params | Show service module parameters |
service | all-services | List all registered services |
service | show-service <service_id> | Show a specific service |
service | relay-mining-difficulty-all | List relay mining difficulty for all services |
service | relay-mining-difficulty <service_id> | Show relay mining difficulty for one service |
service | relay-mining-difficulty-at-height <service_id> <height> | Difficulty at a specific block height |
service | relay-mining-difficulty-history <service_id> | Historical difficulty changes for a service |
session | params | Show session module parameters |
session | get-session <app_addr> <svc_id> [height] | Get session for an app/service/height tuple |
proof | params | Show proof module parameters |
proof | list-claims | List all claims (filterable) |
proof | show-claim <session_id> <supplier_addr> | Show a specific claim |
proof | list-proofs | List all proofs (filterable) |
proof | show-proof <session_id> <supplier_addr> | Show a specific proof |
tokenomics | params | Show tokenomics module parameters |
shared | params | Show shared module parameters |
migration | params | Show migration module parameters |
migration | list-morse-claimable-account | List Morse claimable accounts |
migration | show-morse-claimable-account <address> | Show a Morse claimable account |
Tips for Effective Querying
JSON Output for Scripting
Use --output json to get machine-parseable output suitable for piping to jq or other tools:
pocketd query supplier list-suppliers --output json --network=main | jq '.supplier[] | .operator_address'Querying Historical State
Use the --height flag to query chain state at a past block height:
pocketd query application show-application pokt1app...xyz --height 5000 --network=mainUsing a Custom RPC Endpoint
Override the default network RPC with --node:
pocketd query shared params --node https://custom-rpc.example.com:443Counting Total Results
When paginating through large result sets, use --count-total on the first page to learn how many items exist:
pocketd query supplier list-suppliers --limit 10 --page 1 --count-total --network=main