queryLedgerState/stakePools

Query stake pool information and registration details

Query information about registered stake pools including their parameters, pledge, margin, and metadata.

Request

All Stake Pools

{
  "jsonrpc": "2.0",
  "method": "queryLedgerState/stakePools"
}

Specific Pools

{
  "jsonrpc": "2.0",
  "method": "queryLedgerState/stakePools",
  "params": {
    "stakePools": [
      { "id": "pool1..." }
    ]
  }
}

Parameters

Parameter	Type	Required	Description
`stakePools`	`object[]`	No	Array of pool IDs to query (all pools if omitted)
`stakePools[].id`	`string`	Yes	Pool ID (Bech32 format starting with `pool1`)

Response

{
  "jsonrpc": "2.0",
  "method": "queryLedgerState/stakePools",
  "result": {
    "pool1pu5jlj4q9w9jlxeu370a3c9myx47md5j5m2str0naunn2q3lkdy": {
      "id": "pool1pu5jlj4q9w9jlxeu370a3c9myx47md5j5m2str0naunn2q3lkdy",
      "vrfVerificationKeyHash": "abc123...",
      "pledge": { "ada": { "lovelace": 500000000000 } },
      "cost": { "ada": { "lovelace": 340000000 } },
      "margin": "1/100",
      "rewardAccount": "stake1u8...",
      "owners": ["stake1u8..."],
      "relays": [
        {
          "type": "hostname",
          "hostname": "relay1.example.com",
          "port": 6001
        }
      ],
      "metadata": {
        "url": "https://example.com/pool.json",
        "hash": "def456..."
      }
    }
  }
}

Response Fields

Field	Type	Description
`id`	`string`	Pool ID in Bech32 format
`vrfVerificationKeyHash`	`string`	VRF key hash for block production
`pledge`	`object`	Pool pledge in lovelace
`cost`	`object`	Fixed cost per epoch (min 340 ADA)
`margin`	`string`	Pool margin as fraction (e.g., "1/100" = 1%)
`rewardAccount`	`string`	Stake address for rewards
`owners`	`string[]`	Pool owner stake addresses
`relays`	`object[]`	Pool relay information
`metadata.url`	`string`	URL to pool metadata JSON
`metadata.hash`	`string`	Hash of metadata for verification

Code Examples

async function getStakePool(poolId) {
const response = await fetch('https://api.nacho.builders/v1/ogmios', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'apikey': process.env.NACHO_API_KEY
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'queryLedgerState/stakePools',
    params: {
      stakePools: [{ id: poolId }]
    }
  })
});

const { result } = await response.json();
return result[poolId];
}

// Get pool info and calculate effective margin
const pool = await getStakePool('pool1...');
const [num, den] = pool.margin.split('/').map(Number);
const marginPercent = (num / den) * 100;
console.log('Pool margin:', marginPercent, '%');
console.log('Fixed cost:', pool.cost.ada.lovelace / 1_000_000, 'ADA');

Pool Metadata

Pool metadata is stored off-chain at the URL specified in registration. To fetch and verify:

async function fetchPoolMetadata(pool) {
  if (!pool.metadata) return null;

  const response = await fetch(pool.metadata.url);
  const metadata = await response.json();

  // Verify hash matches
  const encoder = new TextEncoder();
  const data = encoder.encode(JSON.stringify(metadata));
  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
  const hash = Array.from(new Uint8Array(hashBuffer))
    .map(b => b.toString(16).padStart(2, '0'))
    .join('');

  if (hash !== pool.metadata.hash) {
    throw new Error('Metadata hash mismatch');
  }

  return metadata;
}

Metadata includes pool name, description, ticker symbol, and homepage URL. The maximum metadata size is 512 bytes.

Use Cases

Pool selection - Compare pools by margin, pledge, and cost
Delegation tools - Build stake pool explorers
Pool monitoring - Track your pool's registration parameters
Governance - Identify pool operators for voting

Full Ogmios API Reference

Was this page helpful?