> ## Documentation Index > Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Foundational # GoldRush Foundational API on Solana ## Critical Rules 1. Base URL: `https://api.covalenthq.com/v1/solana-mainnet/...` (kebab-case chain name). 2. Wallet address format: base58, **case-preserved** (unlike EVM 0x-hex which is lowercased). 3. Token mints: base58 mint pubkey - takes the `contract_address` / `tokenMint` slot. USDC = `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`, wrapped SOL = `So11111111111111111111111111111111111111112`. 4. Transaction id: base58 `signature` (\~88 chars), addressed via `/transaction_v2/{signature}/` - **not** `tx_hash` and **not** `/transaction_v2/{txHash}/`. 5. Slot is primary; `block_height` is secondary and can be null because \~5% of slots are skipped. 6. SPL Token + Token-2022 are aggregated by default in every balance/transfer/holder response. Opt out with `?include-token-2022=false`. 7. cNFTs surface alongside Metaplex NFTs with `compressed: true`. For cNFTs, `contract_address` is the Bubblegum Merkle tree (not a mint), and `token_id` is the Merkle leaf index. 8. ALT references in versioned transactions (`v0`) are pre-resolved at index time - clients always see the full `account_keys`. 9. `processed` commitment is not exposed via Foundational (too unstable for REST semantics). Default is `confirmed`; use `?commitment=finalized` for rollback-impossible reads. *** The GoldRush Foundational API on Solana is the same REST surface that serves 100+ EVM chains, adapted for Solana's account/program/slot model. Wallets are base58. Transactions are addressed by signature. Block identifiers are slots. SPL Token Program and Token-2022 are aggregated by default. ## Endpoint ``` GET https://api.covalenthq.com/v1/solana-mainnet/... Authorization: Bearer ``` `solana-mainnet` slots into the same `{chainName}` path parameter as `eth-mainnet`, `base-mainnet`, or `hyperevm-mainnet`. Response envelope (`data`, `error`, `error_message`, `error_code`, `pagination`) is unchanged. ## Solana-specific conventions Read these before wiring up any endpoint - they cover the differences from EVM that bite first. | Topic | Convention | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Wallet address** | Base58, 32-44 chars, **case-preserved** (unlike EVM 0x-hex which is lowercased). Example: `4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY`. | | **Token mint** | Base58 mint pubkey - takes the same path slot as `contract_address` on EVM. SOL is represented as `So11111111111111111111111111111111111111112` (wrapped SOL mint), USDC as `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`. | | **Block identifier** | `slot` (uint64) is primary; `block_height` (uint64) is secondary and may have gaps (\~5% of slots are skipped). Date-to-slot conversion uses `block_time` (unix seconds). | | **Transaction id** | `signature` (base58, \~88 chars) - separate path slot from EVM `tx_hash`. | | **Native unit** | Lamports (uint64, integer-string) - 1 SOL = 10⁹ lamports. | | **Commitment** | Default `confirmed` (\~1s). Optional `?commitment=finalized` (\~13s, rollback-impossible). `processed` is not exposed via Foundational. | | **SPL Token vs Token-2022** | Both programs are aggregated in every balance / transfer / holder response by default. Opt out with `?include-token-2022=false` for cheaper queries. | | **Compute units & priority fees** | Fees are `5000 lamports * num_signatures + compute_unit_price * compute_units_consumed`. Both components are surfaced on every transaction response. | | **ALT resolution** | Versioned transactions (`v0`) reference accounts via Address Lookup Tables. GoldRush pre-resolves the full account list at index time - no second lookup needed. | ## Surface by category ### Wallet | Endpoint | What it returns | | -------------------------------------------- | ------------------------------------------------------------------------------- | | **Get token balances for address** | SPL token balances (Token Program + Token-2022) plus native SOL with USD quote. | | **Get native token balance** | Native SOL only, in lamports. | | **Get historical token balances** | Balances as of any slot or block\_height. | | **Get historical portfolio value over time** | Per-day portfolio USD value over a range. | | **Get SPL token transfers for address** | Filterable transfer history for a mint. | | **Get token holders** | Holder snapshot for an SPL mint as of any slot. | Walkthrough: **Wallet**. ### Transactions | Endpoint | What it returns | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | **Get a transaction** | Single transaction by base58 signature with inner instructions, ALT-resolved accounts, CPI tree, and compute units consumed. | | **Get paginated transactions for address** | Cursor-paginated history for any wallet. | | **Get recent transactions for address** | The most recent N transactions. | | **Get transaction summary for address** | Total signed txs, earliest\_slot, latest\_slot, CU spent, fees paid. | Walkthrough: **Transactions**. ### NFT | Endpoint | What it returns | | ---------------------------------- | ------------------------------------------------------------------------------------ | | **Get NFTs for address** | Metaplex Token Metadata NFTs **and** Bubblegum cNFTs, disambiguated by `compressed`. | | **Check NFT collection ownership** | Boolean ownership for a Metaplex collection mint or Bubblegum Merkle tree. | | **Check NFT token ownership** | Boolean ownership for a specific mint (or cNFT leaf index). | Walkthrough: **NFTs**. ### Pricing | Endpoint | What it returns | | ------------------------------- | --------------------------------------------------------------------------------------------------- | | **Get historical token prices** | Per-day historical USD prices for SPL mints. | | **Get pool spot prices** | Live spot price from a Raydium AMM, Orca Whirlpool, or Meteora DLMM pool address. | | **Get gas prices** | Recommended priority fee in micro-lamports per CU at the 10/50/90 percentile over the last N slots. | Walkthrough: **Pricing**. ### Solana-native Endpoints with no EVM analog. Some are live; some are tracked on the **roadmap**. | Endpoint | What it returns | | --------------------- | ----------------------------------------------------------------------------------- | | Stake accounts | Per-wallet stake accounts (active, deactivating, withdrawn). | | Stake rewards | Per-epoch reward attribution by validator. | | Anchor IDL fetch | Decoded program metadata sourced from on-chain IDL accounts and a curated registry. | | Program log events | IDL-decoded events for a given program. | | Token-2022 extensions | Transfer fees, interest, confidential transfer state. | | Validators | Vote-account list with stake, commission, last vote, root slot. | | SPL delegations | SPL `Approve` delegation state and revocation tracking. | Walkthrough: **Solana-native**. ## Cross-chain endpoints Solana is included in every cross-chain endpoint, so a single call covers the user's full footprint without per-chain fan-out: * **Get cross-chain balances** - includes `solana-mainnet`. * **Get cross-chain transactions** - includes `solana-mainnet`. * **Get address activity** - returns `solana-mainnet` in the chain-presence map for any wallet active on Solana. ## Error codes Standard envelope plus two Solana-specific codes: | HTTP | `error_code` | Meaning | | ---- | ------------------------- | ----------------------------------------------------------------------------------------------------- | | 400 | `SOLANA_INVALID_BASE58` | Input failed base58 decode or wrong length. | | 404 | `SOLANA_SLOT_NOT_INDEXED` | Requested slot is below the indexer's backfill horizon. `error_metadata` includes `min_indexed_slot`. | Everything else (`401`, `404`, `429`, `500`) matches the **global error taxonomy**. *** This page walks through the wallet-centric Foundational endpoints on `solana-mainnet`. All examples use base58 wallets and SPL token mints; SOL is represented as the wrapped-SOL mint `So11111111111111111111111111111111111111112`. ## Balances (SPL + native SOL) Returns every SPL Token Program and Token-2022 holding, plus native SOL, with USD pricing where available. ```bash cURL theme={null} curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/address/4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY/balances_v2/" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` ```typescript TypeScript theme={null} import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient(process.env.GOLDRUSH_API_KEY); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "solana-mainnet", walletAddress: "4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY", }); for (const item of resp.data.items) { console.log(item.contract_ticker_symbol, item.balance, item.pretty_quote); } ``` ```python Python theme={null} import os, requests resp = requests.get( "https://api.covalenthq.com/v1/solana-mainnet/address/" "4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY/balances_v2/", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, ) print(resp.json()["data"]["items"][:3]) ``` Each item carries the SPL mint as `contract_address`, decimals from the Mint account, and `quote` in USD where pricing exists. The wrapped-SOL row (`So111…`) is the native balance; for raw lamports, use the dedicated endpoint below. > **Tip:** Token-2022 mints are aggregated by default. Append `?include-token-2022=false` to drop them - useful when you only want classic SPL. ## Native SOL only For SOL-only wallets, skip the full SPL scan: ```bash theme={null} curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/address/4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY/balances_native/" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` Response includes balance in lamports (string) and SOL (float) with USD quote. Reference: **`get-native-token-balance`**. ## Historical balances by slot Solana indexes by **slot** as primary and **block\_height** as secondary. Either works; slot is gap-free, block\_height has \~5% gaps. ```bash cURL (by slot) theme={null} curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/address/4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY/historical_balances/?slot=250000000" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` ```bash cURL (by date) theme={null} curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/address/4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY/historical_balances/?date=2025-06-01" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` Reference: **`get-historical-token-balances-for-address`**. ## SPL token transfers for a wallet Filterable transfer history for a single SPL mint. Returns `from_address` / `to_address` as base58 owners, `delta` as integer-string raw token units. ```bash theme={null} curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/address/4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY/transfers_v2/?contract-address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` `contract-address` is the SPL mint - in this example, USDC. Reference: **`get-erc20-token-transfers-for-address`**. > **Note:** **SPL transfers cover Token Program + Token-2022 by default.** A single response includes transfers from both programs; use `?include-token-2022=false` to limit to classic SPL. ## Token holders Holder snapshot for an SPL mint as of any slot. Useful for token concentration analytics, whale tracking, and airdrop targeting. ```bash theme={null} curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/tokens/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v/token_holders_v2/?slot=250000000" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` Holders are derived from full Token Program + Token-2022 account scans. Reference: **`get-token-holders-as-of-any-block-height-v2`**. ## Historical portfolio value Per-day total portfolio value in USD across all SPL holdings + native SOL. ```bash theme={null} curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/address/4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY/portfolio_v2/?days=30" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` Reference: **`get-historical-portfolio-value-over-time`**. ## Patterns ### Portfolio dashboard Combine **balances** for the current snapshot, **portfolio\_v2** for the time-series chart, and a single **`historical_balances`** call per "what did I hold on date X" lookup. ### Whale tracking Use **token\_holders\_v2** for the snapshot, then subscribe to **`walletTxs`** on `SOLANA_MAINNET` for the top-N holders to see their fills and transfers in real time. ### Tax / accounting Pull **transfers\_v2** per relevant mint, cross-reference with **historical token prices**, and use the **transaction summary** for first-seen / last-seen / total-fees attribution. ## Related * **Transactions on Solana** - signature lookup, paginated history, CPI tree, ALT resolution. * **NFTs on Solana** - Metaplex + cNFT walkthrough. * **Pricing on Solana** - historical and pool spot prices. * **Wallet activity recipe** - real-time push for the same wallets. *** This page walks through the transaction-centric Foundational endpoints on `solana-mainnet`. All examples use base58 signatures (\~88 chars) and base58 wallets. ## Get a transaction by signature Returns the full transaction with inner instructions, the CPI tree, ALT-resolved account list, compute units consumed, and priority fees. ```bash cURL theme={null} curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/transaction_v2/4kTLrnH5MJYWMq2KMM2Ne1AUjL3kk7g7B5fkA3NfECQjEsKDsWxFh5VTKdGABGmH7BFNfShUySN95vNbqx3Vrqy/" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` ```typescript TypeScript theme={null} import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient(process.env.GOLDRUSH_API_KEY); const resp = await client.TransactionService.getTransaction({ chainName: "solana-mainnet", txHash: "4kTLrnH5MJYWMq2KMM2Ne1AUjL3kk7g7B5fkA3NfECQjEsKDsWxFh5VTKdGABGmH7BFNfShUySN95vNbqx3Vrqy", }); const tx = resp.data.items[0]; console.log(`slot: ${tx.slot}, fee_lamports: ${tx.fees_paid}, cu: ${tx.compute_units_consumed}`); ``` The path slot is `signature` (separate from EVM `tx_hash`). The response includes: * `signature` - base58, \~88 chars. * `slot` - primary block index for Solana. * `block_height` - secondary, may be null if the slot was skipped. * `block_time` - unix seconds. * `signers` - array of base58 pubkeys. * `account_keys` - **ALT-resolved**, complete account list (no opaque table-index references). * `inner_instructions` - per-outer-instruction CPI list. * `compute_units_consumed` - uint64. * `priority_fee_micro_lamports_per_cu` - uint64. * `successful` - bool. > **Tip:** Set `?commitment=finalized` for rollback-impossible reads (\~13s lag). Default is `confirmed` (\~1s). `processed` is not exposed via Foundational - it's too unstable for REST semantics. Reference: **`get-a-transaction`**. ## Paginated transactions for a wallet Cursor-paginated history. Solana wallets can have 10-100x EVM tx volume (a single market-making bot signs millions of txs per month), so pagination is cursor-based rather than offset-based. ```bash cURL theme={null} curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/address/4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY/transactions_v3/page/0/" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` ```typescript TypeScript theme={null} const iter = client.TransactionService.getAllTransactionsForAddress({ chainName: "solana-mainnet", walletAddress: "4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY", }); for await (const page of iter) { for (const tx of page.items) { console.log(tx.signature, tx.slot, tx.successful); } } ``` The path's `pageNumber` slot accepts an opaque cursor string (treated as page 0 / 1 / 2... for backwards compat with EVM URLs). Cursors are unstable across redeploys - always read `pagination.next_cursor` from the response and pass it forward; don't construct cursors yourself. Reference: **`get-paginated-transactions-for-address-v3`**. ## Recent transactions for a wallet For "just give me the last N" without paging: ```bash theme={null} curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/address/4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY/transactions_v3/" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` Reference: **`get-recent-transactions-for-address-v3`**. ## Transaction summary for a wallet Aggregates: total signed txs, earliest\_slot, latest\_slot, CU spent, fees paid in lamports + USD. ```bash theme={null} curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/address/4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY/transactions_summary/" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` Reference: **`get-transaction-summary-for-address`**. ## Solana-specific fields to know | Field | Type | Notes | | ------------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------ | | `signature` | base58 string | Primary tx id - separate path slot from EVM `tx_hash`. | | `slot` | uint64 | Primary block index. Gap-free. | | `block_height` | uint64 \| null | Secondary. \~5% of slots are skipped, so this can be `null` even for valid txs. | | `block_time` | uint64 | Unix seconds. Use this for date-range queries. | | `compute_units_consumed` | uint64 | Solana's "gas spent" equivalent. | | `priority_fee_micro_lamports_per_cu` | uint64 | Per-CU priority fee for this tx. | | `fees_paid` | string (lamports) | `5000 * num_signatures + compute_unit_price * compute_units_consumed`. | | `inner_instructions` | array | Per-outer-instruction CPI list. Resolved at index time. | | `account_keys` | string\[] | **ALT-resolved**. Versioned-tx ALT references are pre-resolved so clients see no opaque indices. | ## Patterns ### Live wallet history Pair the **paginated history** with the **`walletTxs` subscription** on `SOLANA_MAINNET`. REST gives you the backfill; the subscription gives you the tip without polling. ### CPI tree analysis Use **`get-a-transaction`**'s `inner_instructions` to walk the CPI tree for any signature. Useful for understanding multi-program flows (Jupiter routing through Raydium and Orca in one tx, MEV sandwiches across programs, etc.). ### Fee analytics Combine **`transactions_summary`** for per-wallet aggregates with **`gas-prices`** for current priority-fee percentiles. Useful for "how much have I spent on priority fees" dashboards. ## Related * **Wallet endpoints** - balances and transfers that pair naturally with this history. * **Pricing on Solana** - to convert lamport fees into USD over a range. * **Solana-native endpoints** - stake, program logs, IDL. * **Wallet activity stream** - push delivery for the same data. *** This page walks through the NFT endpoints on `solana-mainnet`. Solana NFTs come in two flavors: * **Metaplex Token Metadata** - the classic Solana NFT model. Each NFT is a Token Program mint with supply 1 and an associated Metadata account. * **Bubblegum (compressed NFTs, cNFTs)** - stored as leaves in a Merkle tree, not as Token Program accounts. Standard token-account scans don't see them. GoldRush aggregates both into one response and disambiguates with the `compressed` flag. ## Get NFTs for an address Returns every Metaplex NFT plus every Bubblegum cNFT held by the wallet. ```bash cURL theme={null} curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/address/4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY/balances_nft/" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` ```typescript TypeScript theme={null} import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient(process.env.GOLDRUSH_API_KEY); const resp = await client.NftService.getNftsForAddress({ chainName: "solana-mainnet", walletAddress: "4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY", }); for (const nft of resp.data.items) { console.log(nft.contract_name, nft.compressed ? "cNFT" : "Metaplex", nft.token_id); } ``` Each item carries: * `contract_address` - for Metaplex, the collection mint pubkey; for cNFTs, the Bubblegum Merkle tree address. * `token_id` - for Metaplex, the NFT's mint pubkey; for cNFTs, the **Merkle leaf index** (uint64 as string). * `compressed` - `true` for cNFTs, `false` for Metaplex Token Metadata NFTs. * `external_data` - metadata JSON from the URI (name, image, attributes). > **Tip:** **cNFTs are the majority of new Solana NFT mints.** If your app filters on `contract_address` thinking it's a mint, you'll miss every cNFT - the `contract_address` is a Merkle tree, not a mint. Always branch on `compressed`. Reference: **`get-nfts-for-address`**. ## Check ownership of a collection For "is this wallet in the collection?" gating - faster than fetching the full NFT list. ```bash Metaplex collection theme={null} curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/address/4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY/collection/SMBH3wF6baUj6JWtzYvqcKuj2XCKWDqQxzspY12xPND/" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` ```bash Bubblegum tree theme={null} curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/address/4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY/collection/9KGYAjf9P5x1J9PibCv3rTNxYpbF9YpDz3PNcEsh2N6E/" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` The `collectionAddress` path slot accepts either: * A **Metaplex Collection mint** pubkey (for classic NFTs). * A **Bubblegum Merkle tree** address (for cNFT collections). Reference: **`check-ownership-in-nft-collection`**. ## Check ownership of a specific NFT For "does this wallet own this exact token?": ```bash theme={null} curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/address/4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY/collection/SMBH3wF6baUj6JWtzYvqcKuj2XCKWDqQxzspY12xPND/token/42/" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` `tokenId` semantics: * **Metaplex NFT** - the NFT's mint pubkey. * **cNFT** - the Merkle **leaf index** (uint64). The response includes the matched item with `compressed` set, so your app can dispatch on the discriminator. Reference: **`check-ownership-in-nft-collection-token`**. ## Patterns ### Token-gated UI Use **`check-ownership-in-nft-collection`** on each session - it's a single round-trip and doesn't require fetching the wallet's full NFT list. ### Collection floor / volume tracking Combine **`get-nfts-for-address`** with the **DEX firehose** to see when collection mints trade against SOL or USDC. ### Compressed-NFT airdrop verification For airdrops minted into a cNFT tree, **`check-ownership-in-nft-collection-token`** takes the tree address as `collectionAddress` and the leaf index as `tokenId` - no proof submission needed from the client. ## Related * **Wallet endpoints** - fungible balances for the same address. * **Solana-native endpoints** - Token-2022 extension metadata for assets that aren't NFTs. *** This page walks through the pricing-related Foundational endpoints on `solana-mainnet`. Solana has no dominant on-chain price oracle, so GoldRush derives prices from a resolution chain across the deepest DEX pools and the strongest off-chain feeds. ## How price resolution works For any SPL mint, GoldRush tries the following sources **in order** and returns the first usable price: 1. **USDC-quoted pool with deepest TVL** (Raydium AMM / Orca Whirlpool / Meteora DLMM or Dynamic). 2. **SOL-quoted pool with deepest TVL**, then convert via SOL/USD. 3. **Pyth Hermes** for tokens with a Pyth feed but no liquid pool. 4. **CoinGecko** as a final fallback for long-tail tokens. Every priced response includes a `quote_source` field that names which path was used. This is transparent on purpose: a token priced from a thin Meteora pool deserves more scepticism than one priced from a deep Raydium pool with \$10M+ TVL. ## Historical token prices Per-day USD prices over a range, for one or many mints. ```bash cURL theme={null} curl -X GET "https://api.covalenthq.com/v1/pricing/historical_by_addresses_v2/solana-mainnet/USD/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v,So11111111111111111111111111111111111111112/?from=2025-05-01&to=2025-05-30" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` ```typescript TypeScript theme={null} import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient(process.env.GOLDRUSH_API_KEY); const resp = await client.PricingService.getTokenPrices({ chainName: "solana-mainnet", quoteCurrency: "USD", contractAddress: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", from: "2025-05-01", to: "2025-05-30", }); for (const day of resp.data[0].prices) { console.log(day.date, day.price, day.quote_source); } ``` The `contractAddresses` path slot is a comma-separated list of base58 SPL mints. The response splits per mint, each carrying its own `quote_source` so you can colour-code or filter unreliable rows. Reference: **`get-historical-token-prices`**. ## Pool spot prices Live spot price from a specific DEX pool address. Useful when you want the price from one venue (the arbitrage source, the venue your bot trades on) rather than GoldRush's blended resolution. ```bash theme={null} curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/tokens/58oQChx4yWmvKdwLLZzBi4ChoCc2fqCUWBkwMihLYQo2/spot_prices/" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` `poolAddress` is the AMM / Whirlpool / DLMM / Dynamic pool address (not a token mint). The response includes: * `pool_address` - echoed back. * `protocol_name` - `raydium-amm`, `orca-whirlpool`, `meteora-dlmm`, `meteora-dynamic`, etc. * `base_token` / `quote_token` - mint, symbol, decimals. * `spot_price` - quote per 1 base. * `liquidity_usd` - approximate pool TVL. Reference: **`get-pool-spot-prices`**. ## Recommended priority fee Solana has no gwei. The fee model is `5000 lamports * num_signatures + compute_unit_price * compute_units_consumed`. The "gas price" endpoint returns the recommended **priority fee in micro-lamports per CU** at the 10 / 50 / 90 percentile over the last N slots. ```bash theme={null} curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/event/gas_prices/" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` Response includes: * `priority_fee_p10` - 10th percentile (cheap, slow inclusion). * `priority_fee_p50` - median. * `priority_fee_p90` - 90th percentile (more likely to be included in the next slot or two). * `base_fee_lamports_per_signature` - typically `5000` on mainnet. * `recent_slots_observed` - sample size N. For applications that need next-slot inclusion (MEV, liquidations), use `priority_fee_p90`. For background reconciliation, `priority_fee_p10` is fine. Reference: **`get-gas-prices`**. ## Patterns ### Chart a token Pass the SPL mint to **`historical_by_addresses_v2`** for the historical line; pair with a live **pool spot price** call every N seconds for the "now" tick. ### Real-time OHLCV For tick-level candles instead of day-level historical, the **OHLCV streams** are pinned to `SOLANA_MAINNET` and feed Raydium / Orca / Meteora pools in real time. ### Priority-fee aware transaction submission Before submitting a Solana transaction, call **`get-gas-prices`** and set the compute-unit-price on your tx to `p50` (baseline) or `p90` (urgent). Most failed Solana txs in retail apps are mispriced priority fees, not real reverts. ## Related * **Wallet endpoints** - balances priced through this same resolution chain. * **OHLCV markets recipe** - real-time candles for the same pools. * **DEX firehose** - new-pool discovery to feed your pricing index. *** This page covers Foundational endpoints that exist **only** on Solana. There is no EVM analog because the underlying primitive (stake account, Token-2022 extension, IDL account, Bubblegum leaf) doesn't exist on Ethereum. If you came from EVM expecting `get-token-approvals-for-address` semantics, the closest Solana cousin is [SPL delegations](#spl-delegations) - but it works very differently and gets its own response shape. ## Stake accounts SOL is overwhelmingly held in **stake accounts**, not as raw lamports. Any portfolio product that ignores stake accounts under-counts the wallet's real SOL exposure - often by 90%+. > **Note:** **Shipping in Q1 2027.** Tracked on the **roadmap**. Until then, use a Solana RPC `getProgramAccounts` against the Stake Program (`Stake11111111111111111111111111111111111111`) filtered on the wallet's stake-authority pubkey. ```bash theme={null} # Planned endpoint curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/address/4ZJhP.../stake_accounts/" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` Will return per-account: `stake_pubkey`, `validator_vote_pubkey`, `state` (`active` / `activating` / `deactivating` / `withdrawn`), `staked_lamports`, `activation_epoch`, `deactivation_epoch`, `withdrawer`, `staker`. ## Stake rewards Per-epoch reward attribution by validator. Critical for tax/accounting on staked SOL. > **Note:** **Shipping in Q1 2027.** See the **roadmap**. ```bash theme={null} # Planned endpoint curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/address/4ZJhP.../stake_rewards/?from-epoch=550&to-epoch=600" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` Will return per epoch: `epoch`, `slot`, `validator_vote_pubkey`, `validator_identity_pubkey`, `reward_lamports`, `post_balance_lamports`, `commission_bps`, `apy_estimate`. ## Anchor IDL fetch Most Solana programs ship with an Anchor IDL that describes instructions and events. GoldRush exposes a single endpoint that fetches the IDL from the program's on-chain IDL account, falling back to a curated registry when the on-chain copy is missing. > **Note:** **In design.** See the **roadmap**. ```bash theme={null} # Planned endpoint curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/program/6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P/idl/" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` Will return the full Anchor IDL JSON plus a `source` field (`on-chain` / `goldrush-registry`) and a fetched-at timestamp. ## Program log events Solana analog of `get-log-events-by-contract-address`. Returns IDL-decoded events emitted by a given program, indexed by slot. > **Note:** **In design.** See the **roadmap**. ```bash theme={null} # Planned endpoint curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/program/6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P/log_events/?from-slot=250000000&to-slot=250010000" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` For events from programs that don't expose an IDL yet, the response surfaces the raw base64 event blob plus the decoded discriminator so you can decode client-side. ## Token-2022 extensions Token-2022 is a superset of the classic SPL Token program. Mints can carry extensions that change transfer semantics: * **TransferFeeConfig** - protocol-level transfer tax (basis-point bps + cap). * **InterestBearingConfig** - mints accrue interest by changing `decimals` over time. * **ConfidentialTransfer** - zero-knowledge balance + transfer hiding. * **DefaultAccountState** - new token accounts start frozen. * **MintCloseAuthority** - mints can be closed by a designated authority. GoldRush exposes the parsed extension state in one call. > **Note:** **In design.** See the **roadmap**. ```bash theme={null} # Planned endpoint curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/tokens//extensions/" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` Will return an array of extension objects keyed by extension type, with parsed parameters per extension. ## Validators Vote-account list with per-validator stake, commission, last vote slot, and root slot. Pre-req for any staking UI. > **Note:** **In design.** See the **roadmap**. ```bash theme={null} # Planned endpoint curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/validators/" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` Will return per validator: `vote_pubkey`, `identity_pubkey`, `activated_stake_lamports`, `commission_bps`, `last_vote_slot`, `root_slot`, `epoch_credits`, `delinquent`. ## SPL delegations The Solana analog of EIP-20 `approve`. SPL `Approve` delegates a **specific amount** to a **specific delegate** - narrower than EIP-20 (which approves an allowance the spender can draw from over time). > **Note:** **In design.** See the **roadmap**. ```bash theme={null} # Planned endpoint curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/address/4ZJhP.../spl_delegations/" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" ``` Will return per delegation: `token_account`, `mint`, `delegate`, `delegated_amount`, `last_approve_slot`, plus a `revocable` flag (delegations are always revocable on Solana, unlike many EVM approval patterns). The response shape is **not** modeled on EVM approvals - the wallet-tab "revoke" flow looks more like "close stale delegations" than "shut off a long-running allowance." ## Why these endpoints matter The Solana primitives above aren't optional polish - they're the difference between a portfolio app that under-counts SOL by 90% (no stake accounts) and one that doesn't, or between an exchange that lets users self-custody Token-2022 assets (no surprise transfer fees) and one that doesn't. EVM-shaped wallets that ship without these endpoints feel "broken" to Solana-native users. ## Related * **Wallet endpoints** - fungible balances; pair with stake accounts for total SOL exposure. * **Transactions** - decoded inner instructions reveal stake-program CPIs. * **Roadmap** - per-endpoint shipping status.