Collections by Wallet(s)

get https://api.simplehash.com/api/v0/nfts/collections_by_wallets_v2?chains={chains}&wallet_addresses={wallet_addresses}

This endpoint is commonly used to pass specific chains and wallet addresses to get back a summary of the NFT collection ownership of these addresses, and the number of tokens owned.

To supply multiple values, provide them comma separated in the query params, e.g., chains=optimism,ethereum&wallet_addresses=0xa12,0xb34. ENS addresses can also be provided for the wallet_addresses.

Note that last_acquired_date here represents, for each collection, for the wallet address(es) passed in the query, the timestamp at which an NFT from the collection was most recently added to one of those wallets.

Similarly, total_copies_owned indicates the sum of the quantities of the NFTs from the collection that are owned by the wallet address(es) passed to the endpoint.

This endpoint also returns info on the distinct owner count and distinct NFT count for the listed collections.

To understand more about the difference between Collections and Contracts, please refer to our FAQ

This is an updated version of the Collections by Wallet(s) endpoint. Visit the old version here.

Query Params

chains

string

required

Defaults to ethereum

Chain(s) to query - may be comma delimited (e.g., ethereum,arbitrum)

wallet_addresses

string

required

Defaults to 0xC01A0311708476E586fc194eB433979FF904E6Dd

Owner wallet address(es), comma-separated for multiple values (e.g., 0xa12,0xb34). Limit of 20 addresses.

spam_score__lte

int32

Filter to collections with spam score less than or equal to this value (valid range: 0-100, inclusive)

spam_score__lt

int32

Filter to collections with spam score less than this value (valid range: 1-101, inclusive)

spam_score__gte

int32

Filter to collections with spam score greater than or equal to this value (valid range: 0-100, inclusive)

spam_score__gt

int32

Filter to collections with spam score greater than this value (valid range: -1-99, inclusive)

include_null_spam_scores

string

When filtering by spam score (such as spam_score__gt=90), you can optionally pass in include_null_spam_scores=1 to also return collections that have a null spam score

nft_ids

string

Defaults to 1

Optional parameter to include a field called nft_ids providing the nft_ids from that collection held by the wallet(s)

include_top_contract_details

string

Include the associated contract details for the addresses listed in top_contracts

include_escrowed_nfts

string

Defaults to 0

Optional parameter to include NFTs that are associated with this wallet, but held by an escrow account. Currently supports: Solana NFTs listed on Magic Eden and Tensor (except for AMMs).

cursor

string

Used to retrieve the next page of results

order_by

string

Defaults to transfer_time__desc

The default is transfer_time__desc. For convenience, we have provided transfer_time__desc and transfer_time__asc as abstractions over acquired date, to provide more intuitive ordering when there are multiple copies acquired at different times or the same NFT is received and sent multiple times.

limit

int32

Defaults to 50

Limit. Defaults to 50, capped at 50.

Responses

Language


xxxxxxxxxx
1
curl --request GET \
2
     --url 'https://api.simplehash.com/api/v0/nfts/collections_by_wallets_v2?chains=ethereum&wallet_addresses=0xC01A0311708476E586fc194eB433979FF904E6Dd&nft_ids=1&include_escrowed_nfts=0&order_by=transfer_time__desc&limit=50' \
3
     --header 'X-API-KEY: sh_sk1_Z4jhWXXBE09em' \
4
     --header 'accept: application/json'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200200

400400

401401

403403