Account positions across chains

Comma-separated list of positive chain IDs (single value allowed). Duplicate IDs are removed in first-occurrence order; at most 20 distinct IDs and 512 input characters are accepted.

Account-position page offset, capped at 1000 to bound position discovery and enrichment work.

Requested page size. Values above the endpoint cap are clamped; the default shared cap is 100.

When true, re-read every position on the page, at most 50, and wait briefly for the new rows. A position whose refresh completed is served from its new row, and a position whose refresh did not complete in time is read live. Any other position is served from its stored row; it is read live only when it has no row, or when discovery still finds it but its row shows no exposure. A page can hold fewer than limit rows when a position has no exposure left; meta.hasMore still marks continuation. forceFresh is allowed once a minute per address. Each re-read position takes one unit of the caller's refresh budget: by default 60 a minute per API key, or per client IP without a key, and 120 a minute for all callers together. Over the per-address limit, or when the budget cannot cover the whole page, the request runs as maxAge=300 and freshness.fallbackReason is force-fresh-downgraded. When the refresh budget cannot be checked, nothing is re-read and freshness has rateLimited: true and fallbackReason: rate-limit-unavailable. All these answers are HTTP 200. A request the admission gate refuses, including when its store is down, gets 429 or 503 as before.

Re-read only the page positions whose stored row is older than this many seconds, or that have no row, and wait as forceFresh does. Values under the minimum (300 by default) count as the minimum; freshness.maxAge gives the value used. A request where no row is older takes no budget and queues nothing. Each re-read position takes one unit of the caller's refresh budget; a position whose refresh job is already queued costs nothing. At most 50 positions are re-read per request. When the budget or that cap covers only part, the oldest rows are re-read and the rest stay stored (fallbackReason: refresh-budget-partial); when the budget covers none, every row stays stored (fallbackReason: refresh-budget). Both answer HTTP 200 with rateLimited: true.

Serve rows that include the state of this block, for example the block of a transaction the caller just sent. Needs exactly one chainId; otherwise 400. The request first waits until the indexer has processed the block, so a position the block created is found even before it has a stored row. Then it re-reads every page position whose row was read before the block, or has no row, and waits until the new rows reach it; a re-read position whose row has not reached the block in time is read live. A position whose refresh job is already queued costs no budget; any other re-read takes one unit, as for maxAge. The whole wait, for the indexer and the rows, is about 12 seconds, and a request that has to wait for the indexer takes one more unit. When the indexer does not reach the block in time, or reaches it with under a second left, the stored rows are served with timedOut: true and fallbackReason: indexer-behind. A block well past the chain head, or too far ahead of the indexer to reach in time, is answered that way at once, without a wait or a charge.