{"uid":"cap_SLKCutkgJfGxfBLtdpcY8","slug":"defillama-block-by-timestamp-384ebe71","name":"DefiLlama Block by Timestamp","description":"Block by timestamp from DefiLlama — the closest block number to a unix timestamp on a given chain.","url":"https://defillama.use.x402atlas.com/block","method":"GET","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method"],"properties":{"type":{"type":"string","const":"http"},"method":{"enum":["GET"],"type":"string"},"queryParams":{"type":"object","required":["chain","timestamp"],"properties":{"chain":{"type":"string","pattern":"^[^/?#]+$","maxLength":100,"minLength":1,"description":"Chain name (e.g. ethereum, arbitrum, polygon); no slashes or query characters"},"timestamp":{"type":"string","pattern":"^[0-9]+$","maxLength":20,"minLength":1,"description":"Unix timestamp (seconds, digits only) to find the closest block for"}}}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object","required":["queried_at","data"],"properties":{"data":{"type":"object","properties":{"height":{"type":"integer","description":"Block height closest to the requested timestamp"},"timestamp":{"type":"integer","description":"Unix timestamp (seconds) of that block"}}},"queried_at":{"type":"string","format":"date-time","description":"When this bridge fetched the upstream data"}}}}}}},"responseSchema":{"type":"json","example":{"data":{"height":14688775,"timestamp":1650000000},"queried_at":"2026-07-01T12:00:00Z"}},"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_SkRd822Db8-gF4nxaLGt3","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 closest block number to a given unix timestamp on a specified blockchain chain.","exampleAgentPrompt":"What was the closest Ethereum block number to unix timestamp 1700000000? Use DefiLlama's block-by-timestamp lookup.","exampleUseCases":[{"title":"Historical token balance snapshot","prompt":"I need to analyze a wallet's token holdings at the exact moment a major DeFi protocol launched on Arbitrum on March 15, 2023. Can you find the closest block number to that date so I can query the on-chain state at that point in time?"},{"title":"Sync multichain DeFi data pipeline","prompt":"I'm building a report comparing Ethereum, Polygon, and Arbitrum protocol states at the start of 2024. Can you look up the closest block numbers on all three chains to January 1, 2024 at midnight UTC so I can anchor my queries correctly?"},{"title":"Audit on-chain event timing","prompt":"There was a suspicious large transaction on Polygon that our logs show happened around unix timestamp 1690000000. Can you find the closest block number to that timestamp on Polygon so I can pull the event logs and investigate what happened?"}],"resultDescription":"Returns the block number on the specified chain that is closest to the provided unix timestamp, along with metadata such as the actual timestamp of that block.","failureModes":["Invalid chain name returns an error or empty result","Timestamp out of range for indexed chain history returns an error","Missing required query parameters (chain or timestamp) returns a 400-level error","Network or payment failure returns a non-200 response"],"whenToPreferThis":"Use this endpoint when you need to anchor on-chain historical queries to a specific point in time — e.g., fetching a token balance, protocol state, or event log at a known date/time. It is ideal when working with multichain DeFi data pipelines where you need to synchronize block heights with real-world timestamps across Ethereum, Arbitrum, Polygon, and other DefiLlama-tracked chains.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T18:47:27.368Z","isFirstParty":false}