queryLedgerState/utxo

Query unspent transaction outputs by address or reference

Query the UTxO set for specific addresses or transaction output references.

Request

By Address

{
  "jsonrpc": "2.0",
  "method": "queryLedgerState/utxo",
  "params": {
    "addresses": [
      "addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3jcu5d8ps7zex2k2xt3uqxgjqnnj83ws8lhrn648jjxtwq2ytjqp"
    ]
  }
}

By Output Reference

{
  "jsonrpc": "2.0",
  "method": "queryLedgerState/utxo",
  "params": {
    "outputReferences": [
      {
        "transaction": { "id": "3e40d...abcdef" },
        "index": 0
      }
    ]
  }
}

With Asset Filter (NACHO Extension)

Filter UTxOs by native asset policy ID and optional asset name. This dramatically reduces response size for contract addresses like DEX pools.

{
  "jsonrpc": "2.0",
  "method": "queryLedgerState/utxo",
  "params": {
    "addresses": ["addr1z84q0denmyep98..."],
    "assets": [
      { "policyId": "29d222ce763455e3d7a09a665ce554f00ac89d2e99a1a83d267170c6" }
    ]
  }
}

Parameters

Parameter	Type	Required	Description
`addresses`	`string[]`	No*	Bech32 addresses to query
`outputReferences`	`object[]`	No*	Specific UTxO references
`assets`	`object[]`	No	Asset filters (NACHO extension)
`assets[].policyId`	`string`	Yes**	56-character hex policy ID
`assets[].assetName`	`string`	No	Hex-encoded asset name

*At least one of addresses or outputReferences must be provided.

**Required when using assets filter.

Asset Filter Semantics

Filter Type	Matches
`policyId` only	UTxOs containing ANY asset with that policy
`policyId` + `assetName`	UTxOs containing that EXACT asset
Multiple filters	OR logic (match any filter)
`addresses` + `assets`	AND logic (filter by address, then by assets)

For DEX pools, use the LP token policy to find pool UTxOs, or use a specific token's policy to find that token's pool.

Response

{
  "jsonrpc": "2.0",
  "method": "queryLedgerState/utxo",
  "result": [
    {
      "transaction": {
        "id": "3e40d0530281df85e08fb0c5ac7a44c8cd94cabae4b6d32f0c29ab05dcfc79e6"
      },
      "index": 0,
      "address": "addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3jcu5d8ps7zex2k2xt3uqxgjqnnj83ws8lhrn648jjxtwq2ytjqp",
      "value": {
        "ada": {
          "lovelace": 5000000
        },
        "ab4f3d7e...": {
          "546f6b656e": 100
        }
      },
      "datum": "d8799f...",
      "datumHash": "abc123...",
      "script": {
        "language": "plutus:v2",
        "cbor": "..."
      }
    }
  ]
}

Response Fields

Field	Type	Description
`transaction.id`	`string`	Transaction hash that created this UTxO
`index`	`number`	Output index within the transaction
`address`	`string`	Address holding this UTxO
`value.ada.lovelace`	`number`	ADA amount in lovelace
`value.[policyId]`	`object`	Native tokens by policy ID
`datum`	`string`	Inline datum (CBOR hex)
`datumHash`	`string`	Datum hash (if not inline)
`script`	`object`	Reference script

Code Examples

async function getAddressUtxos(address) {
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/utxo',
    params: { addresses: [address] }
  })
});

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

// Calculate total ADA balance
const utxos = await getAddressUtxos('addr1...');
const totalLovelace = utxos.reduce((sum, u) => sum + u.value.ada.lovelace, 0);
console.log('Balance:', totalLovelace / 1_000_000, 'ADA');

Filtering by Asset

Query only UTxOs containing specific assets. This is ideal for DEX pool queries where you need just one pool out of thousands.

// Query Minswap for only the MIN token pool
const MINSWAP_ADDRESS = 'addr1z84q0denmyep98ph3tmzwsmw0j7zau9ljmsqx6a4rvaau66j2c79gy9l76sdg0xwhd7r0c0kna0tycz4y5s6mlenh8pq777e2a';
const MIN_POLICY = '29d222ce763455e3d7a09a665ce554f00ac89d2e99a1a83d267170c6';

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/utxo',
  params: {
    addresses: [MINSWAP_ADDRESS],
    assets: [{ policyId: MIN_POLICY }]  // Server-side filter!
  }
})
});

const { result } = await response.json();
console.log(`Found ${result.length} MIN pool UTxOs`);  // 1-2 instead of 3000+

Without filtering, querying Minswap returns ~3MB of data (3000+ pools). With the assets filter, you get ~5KB (just the pool you need).

Cache Metadata for Chainsync

When querying prewarmed addresses (like Minswap), the response includes cache metadata:

{
  "result": [...utxos...],
  "_cache": {
    "slot": 142857000,
    "height": 11234567,
    "hash": "d4b8f7e2a1c9...",
    "age": 45
  }
}

Field	Description
`slot`	Slot number when cache was populated
`height`	Block height when cache was populated
`hash`	Block hash (use for `findIntersection`)
`age`	Seconds since cache was populated

Use _cache.hash with findIntersection to start chainsync at the exact block, ensuring zero gaps between your initial query and real-time updates.

Working with Native Tokens

function getTokens(utxo) {
  const tokens = [];

  for (const [policyId, assets] of Object.entries(utxo.value)) {
    if (policyId === 'ada') continue;

    for (const [assetName, quantity] of Object.entries(assets)) {
      tokens.push({
        policyId,
        assetName,
        assetNameUtf8: Buffer.from(assetName, 'hex').toString('utf8'),
        quantity
      });
    }
  }

  return tokens;
}

Tips

Query multiple addresses in a single request to reduce API calls. The response includes UTxOs from all addresses.

UTxOs with datum or datumHash are typically locked by Plutus scripts. You'll need to provide the correct redeemer and satisfy the script logic to spend them.

Full Ogmios API Reference

Was this page helpful?