{"uid":"cap_AsfR8OjK-TlL0fCuhrKuO","slug":"financial-data-x402-block-by-timestamp-cc8e32d3","name":"Financial Data x402 – Block by Timestamp","description":"Pay-per-call stock, macro, on-chain, and crypto data over the x402 protocol. USDC on Base or Solana, no API keys, no subscriptions.","url":"https://x402financialdata.com/block-by-timestamp","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","HEAD","DELETE"],"type":"string"},"queryParams":{"type":"object","required":["timestamp"],"properties":{"chain":{"enum":["eth"],"type":"string","description":"Which chain to query. Only 'eth' is supported right now."},"closest":{"enum":["before","after"],"type":"string","description":"Return the closest block before or after the timestamp, default 'before'."},"timestamp":{"type":"integer","description":"Unix timestamp (seconds)."}}}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object"}}}}},"responseSchema":{"type":"json","example":{"chain":"eth","closest":"before","timestamp":1780000000,"block_number":25196227}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.01","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.01/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm__1RrR89ghwWis8K3axiIH","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns the Ethereum block number closest to a given Unix timestamp, paid per-call via USDC over the x402 protocol.","exampleAgentPrompt":"What Ethereum block number was mined just before Unix timestamp 1780000000? I need the closest block before that time on ETH.","exampleUseCases":[{"title":"Historical on-chain event anchoring","prompt":"I need to find the Ethereum block number that was mined just before Unix timestamp 1700000000 so I can anchor a historical token price query to the right block."},{"title":"Smart contract state at specific moment","prompt":"What was the closest Ethereum block after Unix timestamp 1672531200? I want to query a smart contract's state at exactly that point in time."},{"title":"DeFi protocol audit at known date","prompt":"Give me the Ethereum block number closest to Unix timestamp 1609459200 — I need the block just before that time for a DeFi protocol audit."}],"resultDescription":"Returns a JSON object with the chain name ('eth'), the closest direction used ('before' or 'after'), the requested Unix timestamp, and the resolved Ethereum block number as an integer (e.g. {\"chain\":\"eth\",\"closest\":\"before\",\"timestamp\":1780000000,\"block_number\":25196227}).","failureModes":["Missing required 'timestamp' query parameter returns an error","Unsupported chain value (only 'eth' is supported) returns a validation error","Future timestamp with no mined blocks yet may return an error or unexpected result","Payment failure or insufficient USDC balance causes x402 payment rejection","Invalid 'closest' enum value (not 'before' or 'after') returns a validation error"],"whenToPreferThis":"Choose this endpoint when you need to map a specific Unix timestamp to an Ethereum block number without signing up for an API key or subscription — ideal for agents that need pay-as-you-go on-chain historical lookups, smart contract state queries anchored to a moment in time, or DeFi data pipelines that bill per-call via USDC over x402.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T18:45:38.784Z","isFirstParty":false}