Batch lookup
Lookups
Batch lookup
POST /v1/batch
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
Differences from single lookup
Batch returns a deliberately lighter record. Three things present on/v1/wallet/{address} are absent here:
- No
qualityobject. - No
verifiedflag insidetwitterorfarcaster. - No
staleorlast_updatedinmeta, and no staleness headers.
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.