| name | query-blockchain |
| description | Use when you need to read any data from the Flow blockchain — account state, blocks, events, transaction results, collections, or custom contract state via Cadence scripts. |
Querying the Flow Blockchain with flow-cli
Overview
Use this skill any time you need on-chain data. Choose the right command from the decision table, then run it.
When the entity commands don't expose what you need, use flow scripts execute — Cadence scripts can query any on-chain state and are the primary tool for anything not covered by the commands below. See Cadence Scripts.
Network
Default: mainnet. Infer from conversation context:
| Context | Flag |
|---|
| Default / production | --network mainnet |
| Testnet discussion | --network testnet |
| Local development / emulator | --network emulator |
Access node endpoints (built-in):
- Mainnet:
access.mainnet.nodes.onflow.org:9000
- Testnet:
access.devnet.nodes.onflow.org:9000
- Emulator:
127.0.0.1:3569
Override with --host <endpoint> to point at a custom access node.
Decision Table
| What you need | Command |
|---|
| Account balance, keys, deployed contracts | flow accounts get |
| Account staking info | flow accounts staking-info |
| Block info | flow blocks get |
| Events emitted in a block range | flow events get |
| Regular transaction status / result | flow transactions get |
| System transaction for a block | flow transactions get-system |
| Scheduled transaction details | flow schedule get / flow schedule list |
| Collection contents | flow collections get |
| Network status (online/offline) | flow status |
| Protocol state snapshot | flow snapshot save |
| Anything not covered above | flow scripts execute |
Commands
Accounts
flow accounts get <address|name> [--include contracts] [--network mainnet]
--include contracts adds deployed contract source code to the output- Flow addresses must include the
0x prefix (e.g. 0xf8d6e0586b0a20c7)
<name> resolves via flow.json — only use names when a flow.json is present
flow accounts get 0xe467b9dd11fa00df --network mainnet
flow accounts get 0xe467b9dd11fa00df --include contracts --network mainnet
flow accounts staking-info 0xe467b9dd11fa00df --network mainnet
Blocks
flow blocks get <block_id|latest|block_height> [--include transactions] [--events <event_name>] [--network mainnet]
flow blocks get latest --network mainnet
flow blocks get 12884163 --include transactions --network mainnet
flow blocks get latest --events A.1654653399040a61.FlowToken.TokensDeposited --network mainnet
Events
flow events get <event_name> [<event_name2> ...] [--last 10] [--start N --end M] [--network mainnet]
- Default: last 10 blocks. Use
--last N to widen.
--start/--end for explicit block height range.- Multiple event types are fetched in parallel.
- Event name format:
A.<address>.<ContractName>.<EventName>
flow events get A.1654653399040a61.FlowToken.TokensDeposited --last 20 --network mainnet
flow events get A.1654653399040a61.FlowToken.TokensDeposited --start 11559500 --end 11559600 --network mainnet
flow events get A.1654653399040a61.FlowToken.TokensDeposited A.1654653399040a61.FlowToken.TokensWithdrawn --network mainnet
Transactions
flow transactions get <tx_id> [--include signatures,code,payload,fee-events] [--exclude events] [--network mainnet]
flow transactions get-system <block_id|latest|block_height> [tx_id] [--network mainnet]
flow schedule get <numeric-id> [--network mainnet]
flow schedule list <address|account-name> [--network mainnet]
Collections
flow collections get <collection_id> [--network mainnet]
Network Status
flow status --network mainnet
Output Format
All commands support --output json for machine-readable output.
flow accounts get 0xe467b9dd11fa00df --output json --network mainnet
flow events get A.1654653399040a61.FlowToken.TokensDeposited --output json --network mainnet
Use --filter <property> to extract specific fields from results.
Cadence Scripts
flow scripts execute is the most powerful read tool. Use it when:
- You need data from a contract that has no dedicated CLI command
- You need to call a
view function or read a field from a contract
- You need to combine data from multiple contracts in one query
- You need a historical snapshot at a specific block height
flow scripts execute <script.cdc> [args...] [--args-json '[{"type":"...","value":"..."}]'] [--block-height N] [--block-id <id>] [--network mainnet]
- Simple types (Address, UInt64, String, Bool) can be passed as positional args
- Use
--args-json for complex types (UFix64, optionals, structs, arrays)
--block-height / --block-id execute against historical state- Write a temporary
.cdc file, execute it, then clean up
Writing and Running Scripts
Write script to a temp file, execute, clean up:
cat > /tmp/query.cdc << 'EOF'
import FungibleToken from 0xf233dcee88fe0abe
import FlowToken from 0x1654653399040a61
access(all) fun main(address: Address): UFix64 {
let account = getAccount(address)
let vaultRef = account.capabilities
.borrow<&{FungibleToken.Balance}>(/public/flowTokenBalance)
?? panic("Could not borrow FungibleToken Balance capability for account \(address) at path /public/flowTokenBalance. Make sure the account has a FlowToken Vault set up properly.")
return vaultRef.balance
}
EOF
flow scripts execute /tmp/query.cdc 0xe467b9dd11fa00df --network mainnet
rm /tmp/query.cdc
Passing Arguments
flow scripts execute /tmp/query.cdc 0xe467b9dd11fa00df --network mainnet
flow scripts execute /tmp/query.cdc --args-json '[{"type":"UFix64","value":"100.0"},{"type":"Address","value":"0xe467b9dd11fa00df"}]' --network mainnet
flow scripts execute /tmp/query.cdc 0xe467b9dd11fa00df --block-height 12884163 --network mainnet
Contract Addresses
| Contract | Mainnet | Testnet | Emulator |
|---|
| FungibleToken | 0xf233dcee88fe0abe | 0x9a0766d93b6608b7 | 0xee82856bf20e2aa6 |
| FungibleTokenMetadataViews | 0xf233dcee88fe0abe | 0x9a0766d93b6608b7 | 0xf8d6e0586b0a20c7 |
| FungibleTokenSwitchboard | 0xf233dcee88fe0abe | 0x9a0766d93b6608b7 | 0xf8d6e0586b0a20c7 |
| Burner | 0xf233dcee88fe0abe | 0x9a0766d93b6608b7 | 0xf8d6e0586b0a20c7 |
| FlowToken | 0x1654653399040a61 | 0x7e60df042a9c0868 | 0x0ae53cb6e3f42a79 |
| NonFungibleToken | 0x1d7e57aa55817448 | 0x631e88ae7f1d7c20 | 0xf8d6e0586b0a20c7 |
| MetadataViews | 0x1d7e57aa55817448 | 0x631e88ae7f1d7c20 | 0xf8d6e0586b0a20c7 |
| ViewResolver | 0x1d7e57aa55817448 | 0x631e88ae7f1d7c20 | 0xf8d6e0586b0a20c7 |
| FlowFees | 0xf919ee77447b7497 | 0x912d5440f7e3769e | 0xe5a8b7f23e8b548f |
| FlowServiceAccount | 0xe467b9dd11fa00df | 0x8c5303eaa26202d6 | 0xf8d6e0586b0a20c7 |
| FlowStorageFees | 0xe467b9dd11fa00df | 0x8c5303eaa26202d6 | 0xf8d6e0586b0a20c7 |
| NodeVersionBeacon | 0xe467b9dd11fa00df | 0x8c5303eaa26202d6 |
¹ The EVM bridge account hosts many contracts beyond FlowEVMBridge itself (FlowEVMBridgeConfig, FlowEVMBridgeUtils, FlowEVMBridgeNFTEscrow, FlowEVMBridgeTokenEscrow, CrossVMNFT, CrossVMToken, and more). Run flow accounts get 0x1e4aa0b87d10b141 --network mainnet for the current deployed contract list, or check the flow-evm-bridge repo for available scripts.
Cadence Script Recipes & Data Structures
See cadence-scripts.md for 20+ ready-to-use Cadence scripts organized by category:
- Token queries — FLOW balance, total supply, generic FT balance, FT metadata
- Account & storage — storage capacity, available balance, account creation fee, fee parameters
- Epoch — counter, phase, metadata, timing config
- Staking — node info, staked node IDs, total staked, by role, requirements, rewards, delegator info, staking collections
- Protocol — node version beacon, random beacon source
- NFT — collection IDs, NFT metadata (Display)
- Key data structures — NodeInfo, DelegatorInfo, EpochMetadata, EpochPhase, Node Roles
Common Event Types
| Event | Description |
|---|
A.f233dcee88fe0abe.FungibleToken.Deposited | Any fungible token deposited |
A.f233dcee88fe0abe.FungibleToken.Withdrawn | Any fungible token withdrawn |
A.f233dcee88fe0abe.FungibleToken.Burned | Any fungible token burned |
A.1d7e57aa55817448.NonFungibleToken.Deposited | Any NFT deposited to a collection |
A.1d7e57aa55817448.NonFungibleToken.Withdrawn | Any NFT withdrawn from a collection |
A.8624b52f9ddcd04a.FlowEpoch.NewEpoch | New epoch started |
A.8624b52f9ddcd04a.FlowEpoch.EpochSetup | Epoch setup phase began |
A.8624b52f9ddcd04a.FlowEpoch.EpochCommit | Epoch commit phase began |
A.8624b52f9ddcd04a.FlowIDTableStaking.NewNodeCreated | New staking node registered |
A.8624b52f9ddcd04a.FlowIDTableStaking.TokensCommitted | Tokens committed to stake |
A.8624b52f9ddcd04a.FlowIDTableStaking.RewardsPaid | Staking rewards distributed |
A.8624b52f9ddcd04a.FlowIDTableStaking.NewDelegatorCreated | New delegator registered |
A.f919ee77447b7497.FlowFees.FeesDeducted | Transaction fees paid |
A.f919ee77447b7497.FlowFees.TokensDeposited | Fees deposited to fee vault |
Available Script Libraries
For more complex queries, clone these repos to /tmp and use their scripts directly:
| Repo | Scripts Path | Use For |
|---|
| flow-core-contracts | transactions/*/scripts/ | Staking, epoch, fees, locked tokens, version beacon, random beacon |
| flow-ft | transactions/scripts/, transactions/metadata/scripts/ | FT balances, supply, metadata, switchboard |
| flow-nft | transactions/scripts/ | NFT collections, metadata views, cross-VM views |
| flow-evm-bridge | cadence/scripts/ | Bridge state, onboarding checks, escrow, EVM balances, cross-VM associations |
| nft-storefront | scripts/ | Marketplace listings, ghost listings, commission receivers, storefront IDs |
| hybrid-custody | scripts/hybrid-custody/, scripts/delegator/, scripts/factory/ | Child/parent account relationships, cross-account NFT/FT access, capability delegation |
git clone --depth 1 https://github.com/onflow/flow-core-contracts.git /tmp/flow-core-contracts
flow scripts execute /tmp/flow-core-contracts/transactions/idTableStaking/scripts/get_node_info.cdc "abc123...def456" --network mainnet
Note: Some repo scripts use import "ContractName" syntax (no address). These require a flow.json with address mappings. For ad-hoc queries, replace with explicit addresses:
// Repo style (requires flow.json aliases):
import "FlowToken"
// Direct style (works without flow.json):
import FlowToken from 0x1654653399040a61
