{"uid":"cap_L3wOg0NqGutG-OlBXMr0P","slug":"goldsky-feeds-api-chain-head-block-b4efd223","name":"Goldsky Feeds API – Chain Head Block","description":"Goldsky Feeds: onchain data over REST. Formerly Edge Data / Data APIs; existing URLs and keys keep working.\n\n- **Wallet feeds**: one wallet's token transfers or balances across chains, with USD values (`/feeds/wallets/transfers`, `/feeds/wallets/balances`).\n- **Tokens**: metadata and current USD price for up to 100 `chain:token_address` pairs per request (`/feeds/tokens`).\n- **Prediction markets** (Polymarket, on Polygon): Activity, Positions and Balances (`/polymarket/*`).\n- **Chain datasets**: Blocks and Chain head for each supported chain (`/blocks/{chain}`, `/blocks/{chain}/head`).\n\nBase URL: `https://edge.goldsky.com/data`. Every endpoint is a `GET` that returns JSON.\n\n## Authentication\n\nSend your Feeds API key in the `x-api-key` header, as the `?key=` query parameter, or as `Authorization: Bearer <key>`. Get it at [app.goldsky.com](https://app.goldsky.com) under **Feeds → API keys**. One key works for every endpoint; an invalid key gets `401`.\n\n## Billing\n\nRequests made with a key bill compute units (CUs) at $10 per million:\n\n- Wallet feeds and Tokens: 35 CUs per request.\n- Prediction markets and Chain datasets: 1 CU per row returned. Chain head is 1 CU per call.\n\nErrors are not billed, and a Prediction markets or Chain datasets request that returns no rows costs nothing. Rate limits are set per plan (`429` when exceeded); Goldsky support can raise them.\n\n## Pay per request with x402\n\nNo account or key needed. A request without a key gets `402` with an x402 v2 challenge in the `PAYMENT-REQUIRED` header (base64 JSON; the body carries the same challenge). Pay in USDC through Circle Gateway and retry. Each payment is a $0.005 prepaid top-up, tied to the paying wallet and shared with Edge RPC, that later requests spend down:\n\n- Wallet feeds and Tokens: $0.00035 (350 atomic USDC) per request.\n- Prediction markets and Chain datasets: $0.00001 (10 atomic USDC) per request, whatever the row count.\n\nThe payment flow is in [x402 nanopayments](https://docs.goldsky.com/edge-rpc/capabilities/x402).","url":"https://edge.goldsky.com/data/blocks/%7Bchain%7D/head?utm_source=zero.xyz","method":"GET","headers":{},"bodySchema":{"type":"object","properties":{"required":{"type":"string"},"properties":{"type":"string"}}},"responseSchema":{"type":"json","schema":{"type":"object","properties":{"chain":{"type":"string"},"number":{"type":"integer"},"timestamp":{"type":"integer"},"head_lag_seconds":{"type":"integer"}}}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.005","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.005/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.005","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.005","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_fe8vwpXxJF4wgdR0bvbfa","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.005","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns the current head block number, timestamp, and lag for a specified blockchain chain","exampleAgentPrompt":"What's the current head block number and timestamp for Ethereum right now, and how many seconds behind is Goldsky's feed?","exampleUseCases":[{"title":"Blockchain sync lag monitoring","prompt":"Check the chain head for Polygon and tell me how many seconds behind the Goldsky feed is — I want to know if it's falling behind real-time."},{"title":"Current block height for DeFi app","prompt":"What's the latest block number on Ethereum right now? I need it to validate a recent transaction confirmation window."},{"title":"Multi-chain dashboard head tracking","prompt":"Fetch the current head block and timestamp for Arbitrum so I can display it on my chain status dashboard."}],"resultDescription":"A JSON object containing the chain identifier string, the current head block number as an integer, the Unix timestamp of that block as an integer, and the head_lag_seconds integer indicating how many seconds behind real-time the indexed head currently is.","failureModes":["Unsupported or misspelled chain name returns 404 or empty/error response","Invalid or missing API key returns 401 Unauthorized","Temporary indexer lag may cause head_lag_seconds to be elevated without error","Rate limiting or insufficient prepaid balance may result in 402 Payment Required","Network timeout if the Goldsky edge node is temporarily unavailable"],"whenToPreferThis":"Use this endpoint when you need a fast, single-call lookup of the current chain head block number and timestamp for a specific blockchain, particularly when monitoring indexer freshness or confirming block heights. Prefer it over full block-range queries when only the latest state is needed, and over general RPC endpoints when you want REST/JSON access with USD-denominated micropayment billing.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-31T18:36:54.905Z","isFirstParty":false,"canonicalSlug":"goldsky-feeds-api-chain-head-block-b4efd223"}