Zapper API update

New & improved endpoints for NFTs & balances!

TL;DR we’re releasing new API endpoints relating to fetching balances and NFTs that are significantly better & cheaper than the existing endpoints, and marking our existing endpoint v2/balances for deprecation, to be sunset in May 2023.

Hello all,

Based on the feedback from API users, we’re excited to announce 3 sets of new API endpoints, adding to our growing list of endpoints made available through Zapper’s suite of APIs.

The endpoints deliver 3 improvements / new features:

1. Better way to pull wallet balances: no more streaming endpoint! No more SSE response! No more timeouts! Better reliability!
2. Cheaper and faster NFT endpoint!
3. Remaining API points endpoint: query for your points remaining; no need to go checkout the Zapper API dashboard

Along with the above endpoints being released, we are also now marking v2/balances for deprecation, which will be turned down on May 15th, 2023.

New balance-fetching endpoints for apps and ERC20 tokens

We have heard everyone’s feedback that our existing endpoint, v2/balances, is difficult to work with. It’s a streaming endpoint with a long-lived connection to Zapper’s backend, and can be brittle and finicky, particularly for wallets with many positions. And the response provided is annoying to work with, as it’s in SSE format instead of regular JSON.

To that end, we have built a set of new endpoints to replace its functionality, and then some. Zapper’s frontend, www.zapper.xyz, has been using these endpoints since mid-December, and have seen a significant performance improvement and reduction in errors, and we expect the same for our API customers.

The endpoints are the following:

1. GET /v2/balances/apps (link to docs)
2. GET /v2/balances/tokens (link)
3. POST /v2/balances/apps (link)
4. POST /v2/balances/tokens (link)
5. GET /v2/balances/job-status (link)

Differences between these endpoints and v2/balances:

• Significant performance and reliability improvements!
• Results are not streamed back, but are a GET query
• Results are not in the SSE format, but in traditional JSON (yay!)
• App balances and base token balances are now split into two calls (/apps and /tokens), instead of combined into one
• Values returned are much more “cleaned up”; no more empty arrays of claimables [], lending [], nft [], etc.
• No longer can set bundled = true; all results are returned per address (but you can still pass in up to 15 addresses in query params)

As part of these endpoints being released, we are also marking v2/balances for deprecation today. We will be turning down functionality of v2/balances on May 15th, 2023, so ~3.5 months from now. We strongly recommend you migrate to these new endpoints, as they’re cheaper, more reliable, and more performant.

How to use the new endpoints:

When calling GET /v2/balances/apps or /v2/balances/tokens, you will be calling on Zapper’s cached value for that wallet, if it exists. A cache is generated anytime that wallet has been queried on Zapper’s frontend or through our APIs. The cached value contains the timestamp when it was calculated in the field UpdatedAt, which can be used to determine if the cache is too stale for your use

If you call the GET /v2/balances/apps or /v2/balances/tokens endpoints and are returned a value, then you are good to go!

However, if you find there is no cache value, or it is too stale to be useful for you, you can request Zapper to re-compute the wallet’s balances using the POST routes.

When you call the POST /v2/balances/apps and /v2/balances/tokens routes, you input an array of wallets, and the response will provide a jobId value, a unique ID relating to Zapper’s job re-calculating that wallet’s balances.

You can then pass that jobId into the endpoint GET /v2/balances/job-status?jobId=:jobId to monitor the status of the job. (Alternatively, you could just wait for 10 seconds, as thats generally the maximum length of job times.

Once the job is completed, call the GET /v2/balances/* endpoints again for that wallet, and you will find the re-calculated values you requested via the POST routes, with updatedAt values.

If you are trying to completely replace the exact functionality of v2/balances, check out this code snippet here.

New endpoints are also cheaper!

These endpoints will have the following pricing:

1. GET v2/balances/tokens AND GET v2/balances/apps cost 0.25 points per wallet fetched
2. POST for v2/balances/apps cost 4 points (as this triggers recalculation of all app balances for a wallet)
3. POST for v2/balances/tokens cost 1 point (triggers recalculation of all base token balances for a wallet)
4. GET v2/balances/job-status cost 0 points. It is free for you to poll for the status of a job

This is compared to the existing price of 7 points per wallet query on v2/balances.

Here is a full summary of all points costs (full details here):

Pricing details for all endpoints

So, if you wanted to do the equivalent of a v2/balances query, with always fresh data and never bothering with cache, the cost would be 5.5 total points (4 points for POST /apps query, 1 point for POST / tokens query, 0.25 points for GET /apps and 0.25 points for GET /tokens = 5.5 points), a 21% query cost reduction from 7 points per wallet in v2/balances.

If you want to roll the dice and check for valid caches, the cost to get balances of a wallet could be as low as 0.5 points (if caches found on /tokens and /apps and they are not too stale), or maximum of 6 points, where you check the caches on /apps and /tokens for 0.5 points + 5.5 total points to re-calculate them and re-pull them, which is still ~14% cheaper than the 7 points for a v2/balances query today.

New NFT endpoint, returning unordered NFT list 100 items per page

We have found that users of our API often want to extract ALL NFTs in a wallet, a query that can be quite costly and time consuming for certain wallets via our existing endpoint, v2/nft/balances/tokens (link).

Most wallets queried on Zapper’s APIs contain less than 25 NFTs, but there are some that greatly exceed that; for example, Pranksy.eth’s wallet contains >50,000 NFTs!

To help API users ingest large volumes of NFTs in a given wallet, we put together a more performant endpoint built for this use-case, found at v2/nft/users/tokens (link).

This endpoint returns 100 NFTs per page instead of the 25 NFTs maximum returned in v2/nft/balances/tokens. Additionally, the NFTs are no longer sorted by descending estimated USD value, which significantly improves performance when querying it.

Calls on this new endpoint will also cost the same as the other endpoint, leading to a cost reduction in pulling all NFTs in a wallet of up to 75%!

Note that you do still want to get only a preview of the most valuable NFTs a wallet holds, you can continue to use v2/nft/balances/tokens for that use-case, as that endpoint will remain unchanged.

Link to docs for v2/nft/users/tokens

Points remaining endpoint, v1/api-clients/points

Finally, a good number of users have highlighted the difficulty of how many points they have remaining on their API key. We do provide all users access to a pretty substantial reporting dashboard (link), but we know it can be annoying to hop in there to monitor your points balance.

To that end, we’ve created a new endpoint, v1/api-clients/points (link to docs), that returns the remaining points balance your API key has, as well as the total number of points consumed yesterday, and a timestamp as to when we last calculated your remaining points balance (as the points remaining value is refreshed every hour).

Link to docs for v1/api-clients-points

What’s next for Zapper’s APIs

This is our latest major update to the APIs for a bit, but we do plan to update tooling in the coming weeks for managing your API usage. A big improvement will be the release of an API partner portal, a one-stop-shop that will allow you to monitor your API use, buy new points instantaneously, disable API keys, get new API keys, and other useful functionality. More to come on that, but we’re excited to get the partner portal released later in Q1!

For more details on our API and to get an API key, check out https://build.zapper.xyz/

Please do reach out if you have any questions or suggestions on Zapper’s APIs, as we are always interested in feedback.

Thanks!

Sam