Authentication

Making An Authenticated API Request 🪄

Dev Environment Key

To get started, log into the docs if you haven't already done so!

Any API keys associated with your account should automatically be populated above. If you don't have any API key yet, the key for your development environment will be generated automatically. The dev key begins withzk_dev_ prefix.

📘

My key is disabled

By default, all new dev keys are disabled. To activate it, please fill the form. We will activate your key after moderation within 2 business days.

Note: We have a system which disables suspicious dev keys. If your dev key is mistakenly deactivated, please navigate to the #devs-lounge in our Discord and tag the admin @zebastieneth to get your key activated again.

Production Environment Key

If you need a key for a production environment, please contact us at [email protected] with your dev key details and any special requirements. The paid production keys begin withzk_prod_ prefix.

🚧

Browser requests and CORS

If you use API from a browser it's highly probably that the browser uses CORS. Currently API supports requests only from "local" domains: localhost, 127.0.0.1 and *.local with any port. We recommend to use your own backend to hide the key in production, because anyone has access to your frontend and can extract the key and able to burn all your request limits which can lead to extra issues and costs.

If you understand risks and decide to use the API directly anyway, please contact us to enable your origin hosts.

Send your first authenticated request

• Once you've selected an API key, you'll see it automatically populate in the authentication field in the top-right corner (under How to Authenticate).
• Under that is a little API playground where you can send an authenticated request. Click that big blue "Try It!" button and see what happens!
• You can copy the code snippet, which is fully runnable. Try pasting that into a terminal of your choice and you should see the exact same results. 🚀

You can see example responses by clicking on the corresponding status code or selecting the dropdown "EXAMPLES" menu.

🚧

Ensure your requests are made over HTTPS

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Making requests manually

To make requests manually you need to pass Basic Auth credentials. You can do it using one of the approaches below.

Use Authorization header

Let's say your API key is zk_prod_d3f4a91b56c74a2c9edc8e3a71e8f921. Add : to the key at the end and get base64 string using any tool:

echo -n 'zk_prod_d3f4a91b56c74a2c9edc8e3a71e8f921:' | base64

import base64
base64.b64encode(b'zk_prod_d3f4a91b56c74a2c9edc8e3a71e8f921:').decode()

The encoded string is emtfcHJvZF9kM2Y0YTkxYjU2Yzc0YTJjOWVkYzhlM2E3MWU4ZjkyMTo=. Now you can make a request using curl or any other tool using Authorization header:

curl -H "Authorization: Basic emtfcHJvZF9kM2Y0YTkxYjU2Yzc0YTJjOWVkYzhlM2E3MWU4ZjkyMTo=" --globoff 'https://api.zerion.io/v1/wallets/0x42b9df65b219b3dd36ff330a4dd8f327a6ada990/positions/?filter[chain_ids]=ethereum'

Use curl --user flag

If you use curl, you can use this approach. Add : to the key at the end and use this string as --user flag

curl --user zk_prod_d3f4a91b56c74a2c9edc8e3a71e8f921: --globoff 'https://api.zerion.io/v1/wallets/0x42b9df65b219b3dd36ff330a4dd8f327a6ada990/positions/?filter[chain_ids]=ethereum'

Rate Limits

Every Zerion API key has its own rate limits. For development keys, the limit is currently set at 120 requests per minute and 5k requests per day.

The dev key limits are meant to remain appropriate for local development.

If you reach the limit, the Zerion API will return a 429 status code with an error for every request beyond the limit before it will be reset.

Rotating API Keys

If you need to remove a key or generate extra keys, please contact us at [email protected] with the complete details or our shared Slack/Telegram channel (if created).