Three windows, the headers that report them, and how to back off correctly.
Limits apply in three windows at once: per minute, per day, and per month. Exceeding any one of them returns 429, even if the other two have room.See plans for your request limits; which preset serves you follows the largest unexpired pack the account holds. Rate limits are counted in their own units, not in match credits: a 50-wallet batch consumes 50 of your per-minute allowance while billing only the wallets that resolved, and a free estimate weighs identically to the batch it previews. A job submission weighs one unit however long its list, and its status poll weighs nothing. Credits shows both meters side by side.
Headers
Every response carries the current state:
Header
Meaning
X-RateLimit-Limit
Rate-limit units allowed in the current window.
X-RateLimit-Remaining
Units left in it.
X-RateLimit-Reset
When the window resets, as a Unix timestamp in seconds.
X-Matches-Available
Match credits available before this call’s matches were debited.
X-RateLimit-Reset is seconds since the epoch, not seconds from now. Convert it rather than treating it as a duration.X-Matches-Available is the balance the request was admitted with, not the balance it left behind: what a call costs is not known until it resolves, so subtract the matches the response reports to know what remains. It rides on success responses, on 402 (where it reads 0) and on 429; it is absent on 401, where no account was identified, and for the legacy unmetered accounts, which have no balance to report.
Handling 429
{ "error": "Rate limit exceeded. Try again in 42 seconds", "code": "RATE_LIMIT_EXCEEDED"}
The response also carries the rate limit headers, so read X-RateLimit-Reset to know exactly when to retry.
Retry with exponential backoff and jitter. Retrying immediately on a shared
minute boundary is how a fleet of workers turns one 429 into a synchronized
stampede that keeps every one of them limited.
A worked example of the whole loop:
async function lookup(wallets, key) { for (let attempt = 0; attempt < 5; attempt++) { const res = await fetch('https://walletlink.social/api/v1/batch', { method: 'POST', headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ wallets }), }); if (res.status !== 429) return res.json(); // Header is epoch seconds, not a duration. const resetAt = Number(res.headers.get('X-RateLimit-Reset')) * 1000; const wait = Math.max(resetAt - Date.now(), 1000) + Math.random() * 1000; await new Promise((r) => setTimeout(r, wait)); } throw new Error('rate limited after 5 attempts');}
Staying under the limit
Batch aggressively. One 50-wallet batch and 50 single lookups consume the same 50 rate-limit units and bill the same matches, but the batch is one round trip instead of fifty, and it is far faster.Deduplicate before submitting. Duplicates are not billed, because billing is on matches after deduplication, but they do consume your per-minute rate limit, so sending them costs you throughput rather than credits.Cache your own results. The underlying records change on the order of days, not seconds. Re-resolving a wallet that already matched spends a match credit for information you already hold. Re-resolving one that missed costs nothing, but it still spends rate limit.Check /v1/usage rather than guessing. It reports all three windows and your match balance, and costs nothing.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"walletlink.social","description":"Resolve wallet addresses to the X and Farcaster accounts their owners published, and back again. Every match is labeled with the evidence behind it, attested or correlated, and every X handle carries a state saying whether it still reaches a person. Sold as one-time credit packs, metered only on matches, with a USDC rail that needs no account. Product overview at https://walletlink.social/llms.txt and full docs at https://docs.walletlink.social/llms-full.txt.","colors":{"primary":"#4131B0","light":"#8585FF","dark":"#36239A"},"api":{"openapi":"openapi.yaml"},"background":{"color":{"light":"#F6F6FA","dark":"#0A0A0C"}},"navbar":{"links":[{"href":"mailto:help@walletlink.social","label":"Support"}],"primary":{"type":"button","label":"Open app","href":"https://walletlink.social"}},"footer":{"socials":{"x":"https://x.com/walletlinkETH"}},"contextual":{"options":["download-spec"],"display":"header"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"walletlink","hasAudioNarration":false,"actualSubdomain":"walletlink","customDomains":["docs.walletlink.social"],"gitSource":{"type":"github","owner":"starl3xx","repo":"wallet-to-social","deployBranch":"main","contentDirectory":"docs-site","isPrivate":false,"mountPath":"","label":""},"entitlements":{},"buildId":"6ae16601270944e7c88ad02f","clientVersion":"0.0.4177","searchFilterCounts":[{"language":"default","tag":"API reference","count":11},{"language":"default","tag":"Documentation","count":8},{"language":"default","tag":"Lookups","count":3},{"language":"default","tag":"Overview","count":3},{"language":"default","tag":"Concepts","count":3},{"language":"default","tag":"For agents","count":2},{"language":"default","tag":"Reverse lookups","count":2},{"language":"default","tag":"Account","count":2},{"language":"default","tag":"Get started","count":2},{"language":"default","tag":"Jobs","count":1}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/rate-limits","slug":"/api-reference/rate-limits","pageMetadata":{"title":"Rate limits","description":"Three windows, the headers that report them, and how to back off correctly.","href":"/api-reference/rate-limits"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Three windows, the headers that report them, and how to back off correctly.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,..._provideComponents(),...props.components},{CodeBlock,Heading,Table,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`Limits apply in three windows at once: per minute, per day, and per month. Exceeding any one of them returns `,_jsx(_components.code,{children:`429`}),`, even if the other two have room.`]}),`\n`,_jsxs(_components.p,{children:[`See `,_jsx(_components.a,{href:`/api-reference/introduction#plans`,children:`plans`}),` for your request limits; which preset serves you follows the largest unexpired pack the account holds. Rate limits are counted in their own units, not in match credits: a 50-wallet batch consumes 50 of your per-minute allowance while billing only the wallets that resolved, and a free `,_jsx(_components.a,{href:`/api-reference/estimate`,children:`estimate`}),` weighs identically to the batch it previews. A `,_jsx(_components.a,{href:`/api-reference/jobs`,children:`job`}),` submission weighs one unit however long its list, and its status poll weighs nothing. `,_jsx(_components.a,{href:`/api-reference/introduction#credits`,children:`Credits`}),` shows both meters side by side.`]}),`\n`,_jsx(Heading,{level:`2`,id:`headers`,children:`Headers`}),`\n`,_jsx(_components.p,{children:`Every response carries the current state:`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Header`}),_jsx(_components.th,{children:`Meaning`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`X-RateLimit-Limit`})}),_jsx(_components.td,{children:`Rate-limit units allowed in the current window.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`X-RateLimit-Remaining`})}),_jsx(_components.td,{children:`Units left in it.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`X-RateLimit-Reset`})}),_jsxs(_components.td,{children:[`When the window resets, as a `,_jsx(_components.strong,{children:`Unix timestamp in seconds`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`X-Matches-Available`})}),_jsxs(_components.td,{children:[`Match credits available `,_jsx(_components.strong,{children:`before`}),` this call’s matches were debited.`]})]})]})]}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`X-RateLimit-Reset`}),` is seconds since the epoch, not seconds from now. Convert it rather than treating it as a duration.`]}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`X-Matches-Available`}),` is the balance the request was admitted with, not the balance it left behind: what a call costs is not known until it resolves, so subtract the matches the response reports to know what remains. It rides on success responses, on `,_jsx(_components.code,{children:`402`}),` (where it reads `,_jsx(_components.code,{children:`0`}),`) and on `,_jsx(_components.code,{children:`429`}),`; it is absent on `,_jsx(_components.code,{children:`401`}),`, where no account was identified, and for the legacy unmetered accounts, which have no balance to report.`]}),`\n`,_jsx(Heading,{level:`2`,id:`handling-429`,children:`Handling 429`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`4`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`4`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"error\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Rate limit exceeded. Try again in 42 seconds\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"code\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"RATE_LIMIT_EXCEEDED\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`The response also carries the rate limit headers, so read `,_jsx(_components.code,{children:`X-RateLimit-Reset`}),` to know exactly when to retry.`]}),`\n`,_jsx(Warning,{children:_jsx(_components.p,{children:`Retry with exponential backoff and jitter. Retrying immediately on a shared\nminute boundary is how a fleet of workers turns one 429 into a synchronized\nstampede that keeps every one of them limited.`})}),`\n`,_jsx(_components.p,{children:`A worked example of the whole loop:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`20`,language:`javascript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`javascript`,children:_jsxs(_components.code,{language:`javascript`,numberOfLines:`20`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`async`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` function`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` lookup`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:`wallets`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:`key`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`) {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` for`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` (`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`let`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` attempt`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 0`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`; `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`attempt`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` \u003c`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 5`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`; `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`attempt`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`++`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`) {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` const`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:` res`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` await`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` fetch`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'https://walletlink.social/api/v1/batch'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` method:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'POST'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` headers:`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` Authorization:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:\" `Bearer \"}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#569CD6`},children:\"${\"}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`key`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#569CD6`},children:`}`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:\"`\"}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'Content-Type'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'application/json'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` },`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` body:`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:` JSON`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`stringify`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`({ `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`wallets`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }),`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` });`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` if`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` (`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`res`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`status`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` !==`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 429`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`) `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`return`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` res`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`json`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`();`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` // Header is epoch seconds, not a duration.`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` const`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:` resetAt`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` Number`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`res`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`headers`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`get`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'X-RateLimit-Reset'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)) `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`*`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 1000`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`;`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` const`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:` wait`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` Math`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`max`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`resetAt`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` -`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` Date`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`now`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(), `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`1000`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`) `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`+`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` Math`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`random`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`() `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`*`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 1000`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`;`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` await`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` new`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4EC9B0`},children:` Promise`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`((`}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:`r`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`) `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`=>`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` setTimeout`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`r`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`wait`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`));`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` throw`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` new`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` Error`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'rate limited after 5 attempts'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`);`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`staying-under-the-limit`,children:`Staying under the limit`}),`\n`,_jsx(_components.p,{children:`Batch aggressively. One 50-wallet batch and 50 single lookups consume the same 50 rate-limit units and bill the same matches, but the batch is one round trip instead of fifty, and it is far faster.`}),`\n`,_jsx(_components.p,{children:`Deduplicate before submitting. Duplicates are not billed, because billing is on matches after deduplication, but they do consume your per-minute rate limit, so sending them costs you throughput rather than credits.`}),`\n`,_jsx(_components.p,{children:`Cache your own results. The underlying records change on the order of days, not seconds. Re-resolving a wallet that already matched spends a match credit for information you already hold. Re-resolving one that missed costs nothing, but it still spends rate limit.`}),`\n`,_jsxs(_components.p,{children:[`Check `,_jsx(_components.a,{href:`/api-reference/usage`,children:_jsx(_components.code,{children:`/v1/usage`})}),` rather than guessing. It reports all three windows and your match balance, and costs nothing.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Rate limits","description":"Three windows, the headers that report them, and how to back off correctly.","href":"/api-reference/rate-limits"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Headers","slug":"headers","depth":2,"children":[]},{"title":"Handling 429","slug":"handling-429","depth":2,"children":[]},{"title":"Staying under the limit","slug":"staying-under-the-limit","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"walletlink","siteName":"walletlink.social","title":"Rate limits - walletlink.social","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-09-02T04:57:40.007Z","originalFileLocation":"api-reference/rate-limits.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Three windows, the headers that report them, and how to back off correctly.\">\u003cmeta data-mint-head name=\"application-name\" content=\"walletlink.social\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/walletlink/_generated/favicon/apple-touch-icon.png?v=3\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/walletlink/_generated/favicon/favicon-32x32.png?v=3\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/walletlink/_generated/favicon/favicon-16x16.png?v=3\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/walletlink/_generated/favicon/favicon.ico?v=3\">\u003cmeta data-mint-head property=\"og:title\" content=\"Rate limits - walletlink.social\">\u003cmeta data-mint-head property=\"og:description\" content=\"Three windows, the headers that report them, and how to back off correctly.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"walletlink.social\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.walletlink.social/api-reference/rate-limits\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://walletlink.mintlify.site/_mintlify/api/og/v2?division=Overview\u0026amp;title=Rate+limits\u0026amp;description=Three+windows%2C+the+headers+that+report+them%2C+and+how+to+back+off+correctly.\u0026amp;theme=a33f390d9f66a2cfd68d4de4\u0026amp;signature=b77f277d347eb797d7032b7f1508917fe686c2334dc5f55a79f47fa9c8a14697\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Rate limits - walletlink.social\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Three windows, the headers that report them, and how to back off correctly.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://walletlink.mintlify.site/_mintlify/api/og/v2?division=Overview\u0026amp;title=Rate+limits\u0026amp;description=Three+windows%2C+the+headers+that+report+them%2C+and+how+to+back+off+correctly.\u0026amp;theme=a33f390d9f66a2cfd68d4de4\u0026amp;signature=b77f277d347eb797d7032b7f1508917fe686c2334dc5f55a79f47fa9c8a14697\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"https://mintlify.s3.us-west-1.amazonaws.com/walletlink/_generated/favicon/browserconfig.xml?v=3\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"walletlink.social\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#4131B0\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.walletlink.social/api-reference/rate-limits\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/rate-limits.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.walletlink.social/#organization\",\"name\":\"walletlink.social\",\"url\":\"https://docs.walletlink.social\"},{\"@type\":\"WebSite\",\"@id\":\"https://docs.walletlink.social#website\",\"name\":\"walletlink.social\",\"url\":\"https://docs.walletlink.social\",\"publisher\":{\"@id\":\"https://docs.walletlink.social/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.walletlink.social/api-reference/rate-limits#webpage\",\"url\":\"https://docs.walletlink.social/api-reference/rate-limits\",\"name\":\"Rate limits\",\"description\":\"Three windows, the headers that report them, and how to back off correctly.\",\"dateModified\":\"2026-09-02T04:57:40.007Z\",\"isPartOf\":{\"@id\":\"https://docs.walletlink.social#website\"},\"breadcrumb\":{\"@id\":\"https://docs.walletlink.social/api-reference/rate-limits#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.walletlink.social/api-reference/rate-limits#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Overview\",\"item\":\"https://docs.walletlink.social/api-reference/introduction\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Rate limits\",\"item\":\"https://docs.walletlink.social/api-reference/rate-limits\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.walletlink.social/api-reference/rate-limits#article\",\"headline\":\"Rate limits\",\"name\":\"Rate limits\",\"description\":\"Three windows, the headers that report them, and how to back off correctly.\",\"url\":\"https://docs.walletlink.social/api-reference/rate-limits\",\"mainEntityOfPage\":{\"@id\":\"https://docs.walletlink.social/api-reference/rate-limits#webpage\"},\"dateModified\":\"2026-09-02T04:57:40.007Z\",\"publisher\":{\"@id\":\"https://docs.walletlink.social/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.walletlink.social#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"walletlink.social\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"walletlink.social\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/rate-limits.md","siteName":"walletlink.social","nav":{"global":null,"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":""}]},{"tab":"API reference","groups":[{"group":"Overview","pages":[{"title":"Introduction","description":"Base URL, authentication, plans, and the conventions every endpoint follows.","href":"/api-reference/introduction"},{"title":"Rate limits","href":"/api-reference/rate-limits"},{"title":"Errors","description":"Error shape and every code the API returns.","href":"/api-reference/errors"}]},{"group":"Lookups","pages":[{"title":"Look up a wallet","api":"GET https://walletlink.social/api/v1/wallet/{address}","href":"/api-reference/wallet"},{"title":"Batch lookup","api":"POST https://walletlink.social/api/v1/batch","href":"/api-reference/batch"},{"title":"Estimate","api":"POST https://walletlink.social/api/v1/estimate","href":"/api-reference/estimate"}]},{"group":"Jobs","pages":[{"title":"Async jobs","api":"POST https://walletlink.social/api/v1/jobs","href":"/api-reference/jobs"}]},{"group":"Reverse lookups","pages":[{"title":"Reverse X lookup","api":"GET https://walletlink.social/api/v1/reverse/twitter/{handle}","href":"/api-reference/reverse-twitter"},{"title":"Reverse Farcaster lookup","api":"GET https://walletlink.social/api/v1/reverse/farcaster/{username}","href":"/api-reference/reverse-farcaster"}]},{"group":"Account","pages":[{"title":"Index stats","api":"GET https://walletlink.social/api/v1/stats","href":"/api-reference/stats"},{"title":"Usage","api":"GET https://walletlink.social/api/v1/usage","href":"/api-reference/usage"}]}]}]},"basePath":"","title":"Rate limits - walletlink.social","deploymentId":"dpl_HhUetB7eHHDAmK9T1Teip38TgFx9","buildId":"dpl_HhUetB7eHHDAmK9T1Teip38TgFx9","dynamics":[],"chunks":[]}