Skip to main content
POST
Batch lookup
Resolves many addresses in one request. Costs 1 credit per wallet submitted. This is the endpoint to build on. Fifty single lookups and one fifty-wallet batch cost the same credits, but the batch is one request instead of fifty and returns in a fraction of the time.

Body

string[]
required
Addresses to resolve. Up to 50 on Pro, 200 on Unlimited. The whole body is capped at 1 MB.

Request

Response

array
One entry per unique address, in submission order. Entries are the same object as single lookup, or null where nothing was found.
object
Positions map to the deduplicated list, not to the array you sent. Submit [A, B, A] and you get two entries back, not three. Deduplicate before you send, then index by the wallet field rather than by position.

Differences from single lookup

Batch returns a deliberately lighter record. Three things present on /v1/wallet/{address} are absent here:
  • No quality object.
  • No verified flag inside twitter or farcaster.
  • No stale or last_updated in meta, and no staleness headers.
If you are filtering on confidence, resolve in bulk with batch and then re-fetch the shortlist through single lookup. It is usually a small number of addresses and it is the only way to see the quality metadata.

Cost

Credits are charged on the addresses you submit, before deduplication. Submitting [A, B, A] costs 3 credits and returns 2 records. Deduplicate first. A batch that exceeds your plan limit is rejected whole with BATCH_SIZE_EXCEEDED. Nothing is charged and nothing is partially processed, so split oversized batches client-side and send the pieces.

Errors

INVALID_REQUEST, INVALID_ADDRESS, BATCH_SIZE_EXCEEDED, plus the standard errors. A single malformed address rejects the entire batch. The error message names the first few offenders.