Interactive DEMO
Note: You can explore our Interactive Demo using the Demo Project ID:
8ry9f6t9dct1se2hlagxnd9n2a
Demo Guide
This guide will help you quickly get started with the Histori API by walking you through the process of obtaining your API key, understanding how to authenticate requests, and making a sample request.
Step 1: Sign Up and Log In
To access the Histori API, you first need to create an account.
- Visit the Histori API Portal.
- Sign up with your email address and create a password. Alternatively, you can sign up with GitHub, Google or Metamask.
- Once registered, Log in to your account.
Step 2: Get Your Project ID
Once logged in, you will be able to get your API key.
- Navigate to the Project ID section of your dashboard.
- Click Show
- Your Project ID key will appear. Be sure to copy this key and keep it secure. Do not share your Project ID as it is tied to your account and usage limits.
Step 3: Understand API Authentication
You must include your Project ID either in the headers of every request you make to the Histori API or pass it as a query parameter. It is recommended (and more secure) to pass it in the headers to make it harder for a malicious entity to steal. The projectID is passed using the x-api-key header. Without this, your requests will be unauthorized.
Here’s an example of how your request headers should look:
x-api-key: <YOUR_UNIQUE_PROJECT_ID>
Step 4: Make a Sample Request
Now that you have your Project ID API key, let's try making a sample request to the Histori API. For this guide, we’ll retrieve the balance of an Ethereum address. Make sure to replace the example values with actual ones.
API Endpoint:
https://api.histori.xyz/v1/eth-mainnet/balance/single/token_address={:your_token}&holder={:your_ens_or_address}&block_height={:optional_block_height}
Sample Request Using cURL:
curl -X GET https://api.histori.xyz/v1/eth-mainnet/balance/single?token_address=0xF2ec4a773ef90c58d98ea734c0eBDB538519b988&holder=vitalik.eth' \
-H 'x-api-key: 8ry9f6t9dct1se2hlagxnd9n2a'
or you could pass it as a query parameter:
curl -X GET https://api.histori.xyz/v1/eth-mainnet/balance/single?token_address=0xF2ec4a773ef90c58d98ea734c0eBDB538519b988&holder=vitalik.eth&projectId=8ry9f6t9dct1se2hlagxnd9n2a'
Sample Response:
{
"network_name": "eth-mainnet",
"chain_id": 1,
"holder": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
"token_address": "0xF2ec4a773ef90c58d98ea734c0eBDB538519b988",
"token_name": "Doge 2.0",
"token_symbol": "DOGE2.0",
"token_type": "erc20",
"checked_at_block": 20984814,
"checked_at_date": "2024-10-17T10:53:35.000Z",
"balance": "18842536318442137573493"
}
Step 5: Check Rate Limits and Quotas
Each API key has a rate limit based on your subscription plan (Free, Starter, Growth, Business, or Enterprise). You can check your usage in the Dashboard under the Usage section.
If you reach your rate limit, consider upgrading your plan or wait until the next reset period (monthly).
Step 6: Error Handling
If your API key is invalid or you've exceeded your rate limit, the API will return an appropriate error message. Here’s an example of a typical error response:
Example Error Response:
{
"message": "Historical Allowance does not exist for this owner and spender",
"error": "Not Found",
"statusCode": 404
}