# Workflows & Decision Trees

## Quick Decision Tree

**Select the right endpoint based on what the user wants to do:**

### Balance & Portfolio Queries
- Check wallet balance → `getTokenBalancesForWalletAddress` (primary, 1 per call)
- Get historical balance at block → `getHistoricalTokenBalancesForWalletAddress` (specialized, 1 per call)
- Get portfolio value over time → `getHistoricalPortfolioForWalletAddress` (primary, 2 per item)
- Get native token only → `getNativeTokenBalance` (primary, 0.5 per call)

### Transaction Queries
- Get recent transactions → `getRecentTransactionsForAddress` (primary, 0.1 per item)
- Get paginated history → `getTransactionsForAddressV3` (primary, 0.1 per item)
- Get single transaction details → `getTransaction` (primary, 0.1 per call)
- Get ERC20 transfers → `getErc20TransfersForWalletAddress` (primary, 0.05 per item)
- Get transaction summary → `getTransactionSummary` (primary, 1 per call)

### Security & Approvals
- Check token approvals → `getApprovals` (primary, 2 per call)
- Check NFT approvals → `getNftApprovals` (primary, 1 per call)

### NFT & Token Queries
- Get NFT holdings → `getNftsForAddress` (primary, 1 per call)
- Get token holders → `getTokenHoldersV2ForTokenAddress` (specialized, 0.02 per item)

### Multi-chain Queries
- Check which chains address is active on → `getAddressActivity` (primary, 0.5 per call)
- Get balances across chains → `getMultiChainBalances` (specialized, 2.5 per call)
- Get transactions across chains → `getMultiChainMultiAddressTransactions` (specialized, 0.25 per item)

### Token & Price Queries
- Get token price history → `getTokenPrices` (primary, 1 per call)
- Get DEX pool prices → `getPoolSpotPrices` (specialized, Foundational only)

### Block & Event Queries
- Get block details → `getBlock` (specialized, 1 per call)
- Get block heights by date → `getBlockHeights` (specialized, 1 per call)
- Get contract event logs → `getLogEventsByAddress` (specialized, 0.01 per item)
- Get logs by topic hash → `getLogEventsByTopicHash` (specialized, 0.01 per item)

---

## Common Multi-Endpoint Workflows

### Portfolio Valuation & Analysis
```
1. getTokenBalancesForWalletAddress → Get current token holdings with spot prices
2. getHistoricalPortfolioForWalletAddress → Get historical portfolio value over time
3. getTransactionsForAddressV3 → Get full transaction history for cost basis
```
**Use case:** Portfolio trackers, tax calculators, wealth management dashboards

### Transaction Deep Dive
```
1. getRecentTransactionsForAddress → Get latest transactions
2. getTransaction(txHash) → Get detailed decoded data for specific transaction
3. getLogEventsByAddress → Get contract event logs for context
```
**Use case:** Transaction explorers, audit trails, forensic analysis

### Security Audit
```
1. getApprovals → Check ERC20 token approvals
2. getNftApprovals → Check NFT approvals
3. getRecentTransactionsForAddress → Review recent approval transactions
```
**Use case:** Security dashboards, wallet protection tools

### Multi-Chain Portfolio
```
1. getAddressActivity → Discover which chains the address is active on
2. getMultiChainBalances → Get balances across all active chains
3. getMultiChainMultiAddressTransactions → Get transaction history across chains
```
**Use case:** Cross-chain wallets, multi-chain portfolio trackers

### NFT Collection Analysis
```
1. getNftsForAddress → Get NFT holdings for an address
2. checkOwnershipInNft → Verify NFT ownership for token gating
3. getRecentTransactionsForAddress → Get recent NFT transaction history
```
**Use case:** NFT galleries, token-gated access, collection tracking

---

## Common Errors & Troubleshooting

This section covers common errors for frequently used endpoints.

### Get token balances for address

**1. 400 Bad Request - Invalid address**
- Solution: Ensure address starts with 0x and is 40 hex characters
- Example: Valid: `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045`

**2. 404 Not Found - Chain not found**
- Solution: Use exact chain name (case-sensitive): `eth-mainnet` not "ethereum"
- Example: Correct: `eth-mainnet` | Wrong: `ethereum`

**3. Response contains spam tokens**
- Solution: Filter by `is_spam: false` or use minimum quote threshold
- Example: Filter: `items.filter(t => !t.is_spam && parseFloat(t.quote) > 0.01)`

### Get paginated transactions for address (v3)

**1. 400 Bad Request - Invalid pagination**
- Solution: Page numbers are 0-indexed. First page is 0, not 1.
- Example: First: `page-number=0` | Second: `page-number=1`

**2. Incomplete transaction history**
- Solution: Check `pagination.has_more` field. Continue until `has_more: false`.
- Example: Loop: `while (response.data.pagination.has_more)`

### Get a transaction

**1. 404 Not Found - Transaction not found**
- Solution: Verify tx hash format (0x + 64 hex chars) and wait for confirmation
- Example: Valid: `0x1234...` (66 chars total)

**2. Tracing costs extra credits**
- Solution: Each trace flag adds 0.05 credits. Only on Foundational chains.
- Example: Base: 0.1 | With traces: 0.25 credits

### Wallet Activity Stream

**1. WebSocket connection failed**
- Solution: Verify URL (wss://gr-staging-v2.streaming.covalenthq.com/graphql) and auth header
- Example: Header: `Authorization: Bearer YOUR_API_KEY`

**2. Subscription not receiving data**
- Solution: Use enum format: `ETH_MAINNET` not `eth-mainnet`. Check chain supports Streaming.
- Example: GraphQL: `ETH_MAINNET` | REST: `eth-mainnet`

### General Tips
- Always check `response.error` field before accessing `response.data`
- Chain names are case-sensitive: use exact values from Chain Capabilities Matrix
- Token balances are strings: use BigInt or decimal libraries for math
- Pagination is 0-indexed: first page is 0, not 1
- Check Chain Capabilities Matrix for feature availability