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:
- Submission - Submit and monitor transactions
- Use Cases - Complete real-world examples