Updates to Zapper’s Public APIs
Giving Zapper’s APIs the TLC that they deserve.
Hello! I’m Sam Tolomei. I joined Zapper in January 2022 as the product manager for developer tools and platforms.
If you’ve been using Zapper’s public APIs over the past few months, you may have noticed some changes. This article explains these changes and offers a head’s up on a few more things you can expect to see implemented soon. The net result of our updates is we expect our APIs to be much more maintainable for the Zapper devs and stable for you, our builders.
Recent changes to our APIs
In March 2022, as result of several consecutive botnet attacks, we began heavily throttling query volume on our public API key. We began asking builders to request an API key via our customer success team. This was long overdue, as our public API key and endpoints were an obvious target for botting.
If you haven’t already done so, we highly recommend you request a private API key, as the public key will continue to be heavily throttled. The rate limits on private keys are 30 RPM on the v1/balances and v2/balances endpoints, and 1000 RPM globally.
Additionally, at the end of March 2022, we removed the gas price endpoint v1/gas-price. All users should use v1/gas-prices now and going forward.
New structure for our public APIs
We have a few other big improvements coming to our APIs over the next month that we want to make folks aware of.
The main driver of these changes is our efforts to build a public GitHub repo that contains all code relating to Zapper’s app integrations for fetching balances. Devs outside of Zapper will be able to view, fork and build off of this repo. Any developer or community member can use the repo to submit an app integration; waiting for Zapper to prioritize an integration will no longer be a blocker! If you are curious, take a look at the GitHub repo. We’ll release even more details on this soon.
By implementing this new backend, there are some downstream changes to our public APIs, such as changes to the data that is passed through our API endpoints and the data’s shape.
Specifically, we are making the following updates to our APIs:
Replacing v1/balances, v1/apps, and v1/apps/{appId} endpoints with v2s that have different data shapes
When we originally built our backend we made a basic assumption that all positions could be defined as a farm, a pool, a vault or a lending position. Forcing that classification ended up being too rigid, as the DeFi ecosystem was too dynamic for it to scale. To that end, we’ve now adopted a much more scalable approach, where positions are defined as either tokenized positions (like pools) or contract positions (like farms).
Additionally, all new integrations we’ve written since late March were written for the new backend, not the old one. You may have noticed this–it is why all the assets you see on zapper.fi do not show up in v1/balances, as v1/balances points to our old repo.
We need to replace the endpoints that point to our old backend with new ones, which have an updated set of data and a new data shape. We are marking v1/balances, v1/apps, and v1/apps/{appId} as deprecated today, and they will be sunset’d in 1 month, on May 25th, 2022. These 3 endpoints will be replaced by v2/balances, v2/apps, and v2/apps/{appsId}, respectively. These new endpoints contain all of the apps Zapper has written to date; there will be no more missing integrations and thus confusion as to why an integration is missing.
Over the next month, if your application or queries rely on these endpoints, please work to move them over to the new endpoints.
Note that both v1/balances and v2/balances both are SEE endpoints. Please refer to this doc for more information on how to handle SSE data.
Deprecating APIs that are not maintained by Zapper
In the past, we have been building experimental APIs to consume on the Zapper front-end. We realize we need to be more intentional and explicit with the community about which of these endpoints are maintained and trusted, and which should not be used.
To that end, we want to clean up our available API endpoints, and as a result we will be deprecating the following APIs:
Current endpoint name that is being deprecated — What is the alternative endpoint to use?
v1/apps (mentioned above) — Replaced with v2/apps
v1/apps/{appId} (mentioned above) — Replaced with v2/apps/{appId}
v1/apps/balances/supported — Replaced with v2/balances
v1/balances (mentioned above) — Replaced with v2/balances
v1/farms/{farmStatsType} — Farm investment and flow to be refactored
v1/farms/{farmStatsType}/approval-state — Farm investment and flow to be refactored
v1/farms/{farmStatsType}/approval-transaction — Farm investment and flow to be refactored
v1/farms/{farmStatsType}/claim — Farm investment and flow to be refactored
v1/farms/{farmStatsType}/exit — Farm investment and flow to be refactored
v1/farms/{farmStatsType}/stake — Farm investment and flow to be refactored
v1/positions/contract-positions — Replaced with v2/apps/{appId}/positions
v1/positions/tokens — Replaced with v2/apps/{appId}/tokens
v1/protocols/{appId}/balances —Replace with v2/apps/{appId}/balances
v1/protocols/{appId}/farms — Replace with v2/apps/{appId}/positions
v1/protocols/{appId}/token-market-data — Replace with v2/apps/{appId}/tokens
v1/protocols/balances/supported — Replace with v2/balances
v1/staked-balance/{stakedBalanceType} — Very old endpoint that is no longer maintained (and hasn’t been for some time); use v2/apps/{appId}/balances
Updating naming of remaining APIs to be v2/
As we started our API endpoint cleanup, we realized we have terrible API name hygiene, to the point that we were even confusing ourselves (ie: what is v1/prices vs v2/prices vs v2/prices-v3?)
Because of this, for endpoints that are not being touched, we still want to harmonize the endpoint names. This will allow us to start with a clean slate so that devs such as yourself aren’t left wondering. Thus, we will be updating all the remaining APIs to all have v2/ as their path.
Current endpoint name — New endpoint name
v1/apps/{appId}/contracts — v2/apps/{appId}/contracts
v1/apps/{appId}/positions — v2/apps/{appId}/positions
v1/apps/{appId}/tokens — v2/apps/{appId}/tokens
v1/exchange/price — v2/exchange/price
v1/exchange/quote — v2/exchange/quote
v1/exchange/supported — v2/exchange/supported
v1/gas-prices — v2/gas-prices
v1/prices/{tokenAddress} — v2/prices/{tokenAddress}
v1/transactions — v2/transactions
v1/zap-in/{type}/{appId}/approval-state — v2/zap-in/{type}/{appId}/approval-state
v1/zap-in/{type}/{appId}/approval-transaction — v2/zap-in/{type}/{appId}/approval-transaction
v1/zap-in/{type}/{appId}/transaction — v2/zap-in/{type}/{appId}/transaction
v1/zap-in/{type}/supported — v2/zap-in/{type}/supported
v1/zap-out/{type}/{appId}/approval-state — v2/zap-out/{type}/{appId}/approval-state
v1/zap-out/{type}/{appId}/approval-transaction — v2/zap-out/{type}/{appId}/approval-transaction
v1/zap-out/{type}/{appId}/transaction — v2/zap-out/{type}/{appId}/transaction
v1/zap-out/{type}/supported — v2/zap-out/{type}/supported
v2/apps/{appId}/balances — v2/apps/{appId}/balances [unchanged, as its already in v2 path]
v2/prices — v2/prices [unchanged, as its already in v2/ path]
PSA: Any API not documented in our docs is not supported for public use and may change at any time
This one is pretty straightforward, but has not been clear in the past. Previously, if folks found an undocumented API while poking around in our frontend, they were free to use it and we’d answer questions about it. This is not sustainable for us, as we do a lot of experimenting.
Going forward, any API endpoint that is not in our public docs, you should use at your own risk. Zapper will not support questions on these endpoints via our customer success team or in our #build-on-zapper Discord channel. Undocumented APIs may change at any time and should not be relied upon for production environments.
That being said, if you find the data in the undocumented API interesting, we are interested in hearing that feedback! We may consider supporting some of those APIs in the future.
Here is a list of APIs that some of you may be using, that we want to explicitly call out as being unsupported by the Zapper team. Note that we have no plans to sunset these APIs at this time, as we do use them on our frontend.
Endpoints that are explicitly unsupported
v1/fiat-rates
v1/approval-state
v1/approval-transaction
v1/token-transfer/transaction
v1/gas-prices/trend
v1/network/nonce-changes
v1/balances/flush-for-address
Update to handling of private API keys and the future of the public API key
We want to update the way we handle private API keys and how they are passed to us for authentication. As of today, we will be rolling out the ability for the API key to be passed via the header instead of embedded in the URL. With this move, we will then be deprecating the ability to pass the API key in the URL, and so it will sunset on May 25th.
In the same vein, we are planning to deprecate the public API key entirely, and ask the community to leverage private keys for querying data. We do not have a date set for the sunsetting of the public key, and will give folks plenty of time to migrate. However, again, we highly recommend you request a private API.
Why only one month’s notice prior to sunsetting?
We recognize the relatively short notice period is not ideal for builders, but maintaining multiple databases for a longer period of time would put unacceptable strain on our small engineering team. We will strive to provide a longer grace period preceding any future API updates and we hope you continue to enjoy Zapper’s powerful and free APIs to enhance your apps!
I know that was a ton of information on the changes to our APIs. If you have any questions or feedback, please do reach out to myself and the team on Zapper’s #build-on-zapper Discord channel.
