Evolution SDK
Providers

Querying

Query blockchain data with provider methods

Querying

Providers expose methods to query UTxOs, protocol parameters, delegation information, and datums. All methods work identically across provider types.

Protocol Parameters

Retrieve current network parameters for fee calculation and transaction constraints:

import {  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

const  = await .();

// Fee calculation parameters
.("Min fee A:", .);
.("Min fee B:", .);

// Transaction limits
.("Max tx size:", .);

// Deposits
.("Key deposit:", .);
.("Pool deposit:", .);

// Script execution costs
.("Price memory:", .);
.("Price steps:", .);

UTxO Queries

Query unspent transaction outputs by address, credential, unit, or reference.

By Address

import { ,  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

// Get all UTxOs at address
const  = await .(
  ..("addr1qxy8sclc58rsck0pzsc0v4skmqjwuqsqpwfcvrdldl5sjvvhyltp7fk0fmtmrlnykgmhnzcns2msa2cmpvllzgqd2azqhpv8e4")
);

// Calculate total ADA
const  = .(
  (, ) =>  + (.. ?? 0n),
  0n
);
.("Total ADA:", () / 1_000_000);

// List native assets
.(() => {
  .(.).(([, ]) => {
    if ( !== "lovelace") {
      .(`Asset: ${}, Amount: ${}`);
    }
  });
});

By Credential

Query UTxOs by payment credential instead of full address:

import { createClient, Credential } from "@evolution-sdk/evolution";

const client = createClient({
  network: "mainnet",
  provider: {
    type: "blockfrost",
    baseUrl: "https://cardano-mainnet.blockfrost.io/api/v0",
    projectId: process.env.BLOCKFROST_PROJECT_ID!
  }
});

// Create credential from key hash
const credential = Credential.keyHash("payment-key-hash-here");

// Query by credential
const utxos = await client.getUtxos(credential);

By Unit

Query UTxOs containing specific native asset:

import { ,  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

// Find UTxOs with specific token at address
const  = "abc123def456abc123def456abc123def456abc123def456abc123de7890";
const  = "MyToken";
const  =  + ;

const  = await .(
  ..("addr1qxy8sclc58rsck0pzsc0v4skmqjwuqsqpwfcvrdldl5sjvvhyltp7fk0fmtmrlnykgmhnzcns2msa2cmpvllzgqd2azqhpv8e4"),
  
);

.("UTxOs with token:", .);

By Reference

Query specific UTxOs by transaction output reference:

import {  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

// Query specific UTxOs
const  = await .([
  { : "abc123...", : 0 },
  { : "def456...", : 1 }
]);

.("Found UTxOs:", .);

By Unit (Single)

Find a single UTxO by unique unit identifier:

import { ,  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

// Query NFT (unique token with quantity 1)
const  = "policyId" + "tokenName";
const  = await .();

.("NFT found at:", ..(.));
.("Current owner UTxO:", ..(.));

Delegation Queries

Query staking delegation and reward information:

import {  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

const  = await .("stake1uxy...");

.("Delegated to pool:", .);
.("Is delegated:", . !== );
.("Rewards:", .);

Datum Resolution

Retrieve datum content by hash:

import {  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

// Get datum from hash
const  = "abc123...";
const  = await .();

.("Datum CBOR:", );

Query Patterns

Portfolio Balance

Calculate total balance across multiple addresses:

import { ,  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

async function (: string[]) {
  const  = await .(
    .(async () => {
      const  = ..();
      const  = await .();
      const  = .(
        (, ) =>  + ..,
        0n
      );
      
      return {
        : ,
        ,
        : () / 1_000_000
      };
    })
  );
  
  const  = .(
    (, ) =>  + .,
    0n
  );
  
  return {
    : ,
    : {
      : ,
      : () / 1_000_000
    }
  };
}

Token Holdings

Find all holders of a specific token:

import { ,  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

async function (
  : string[],
  : string
) {
  const  = [];
  
  for (const  of ) {
    const  = ..();
    const  = await .(, );
    
    if (. > 0) {
      // Count UTxOs containing this token
      .({
        : ,
        : (.),
        : .
      });
    }
  }
  
  return ;
}

Delegation Status

Check if addresses are delegated to specific pool:

import {  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

async function (
  : string[],
  : string
) {
  const  = await .(
    .(async () => {
      const  = await .();
      
      return {
        ,
        : . === ,
        : .,
        : . !== ,
        : .
      };
    })
  );
  
  return ;
}

NFT Ownership

Track NFT ownership across collection:

import { ,  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

async function (: string[]) {
  const  = await .(
    .(async () => {
      try {
        const  = await .();
        return {
          ,
          : ..(.),
          : ..(.),
          : .
        };
      } catch (: any) {
        return {
          ,
          : null,
          : "Not found or burned"
        };
      }
    })
  );
  
  return ;
}

Error Handling

Handle query errors gracefully:

import { ,  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

async function (: string) {
  try {
    const  = ..();
    const  = await .();
    return { : true as ,  };
  } catch (: any) {
    .("Failed to query UTxOs:", );
    return { : false as , : .message };
  }
}

async function (: string) {
  try {
    const  = await .();
    return { : true as ,  };
  } catch (: any) {
    // May fail if address not registered
    return { : false as , : .message };
  }
}

Performance Considerations

Optimize queries for better performance:

import { ,  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

// Batch queries in parallel
async function (: string[]) {
  // Good: parallel queries
  const  = await .(
    .( => 
      .(..())
    )
  );
  
  return ;
}

// Cache protocol parameters
type  = <<typeof .>>;
let :  | null = null;
let  = 0;
const  = 300000; // 5 minutes

async function () {
  const  = .();
  
  if (! ||  -  > ) {
     = await .();
     = ;
  }
  
  return ;
}

Next Steps

Learn about transaction submission: