## Use with LLMs
### Complete Documentation for LLMs
For LLM applications such as custom agents, RAG systems, or any scenario requiring our complete documentation, we provide an optimized text file at [`https://docs.sim.dune.com/llms-full.txt`](https://docs.sim.dune.com/llms-full.txt).
### Per-Page Access
Each page on this documentation site offers several ways to access its content in LLM-friendly formats:
* **Copy Page:** Copies the fully rendered content of the current page.
* **View Markdown:** Provides a URL with the raw Markdown source. This is ideal for direct input into LLMs.
* **Open with ChatGPT:** Instantly loads the page's content into a new session with ChatGPT. Ask questions, summarize, or generate code based on the page's content.
You can retrieve the Markdown version of any documentation page by appending `.md` to its URL. For example, `/evm/activity` becomes [`https://docs.sim.dune.com/evm/activity.md`](https://docs.sim.dune.com/evm/activity.md).
You can also type `⌘C` or `Ctrl+C` to copy any page's Markdown content.
Try it now.
## Cursor Integration
To integrate our documentation directly into Cursor:
1. Go to Cursor Settings -> Features -> Docs -> Add new doc.
2. Enter "docs.sim.dune.com" in the URL field.
3. Provide a name (e.g., "@simdocs").
4. Hit confirm. The documentation will sync automatically.
5. Reference Sim APIs documentation by typing `@simdocs` (or your chosen name) in your Cursor chat window.
## OpenAPI Specifications
For a more compact format, we provide OpenAPI specifications for each of our endpoints. These files detail available parameters, request bodies, and response schemas. This format is particularly useful for LLMs and AI code generation tools to understand our API structure.
You can find our OpenAPI specifications in the following directories:
* EVM API specifications: [`/evm/openapi/`](https://github.com/duneanalytics/sim-docs/tree/main/evm/openapi)
* SVM API specifications: [`/svm/openapi/`](https://github.com/duneanalytics/sim-docs/tree/main/svm/openapi)
# Error Handling
Source: https://docs.sim.dune.com/error-handling
How to handle errors when using Sim APIs
This guide explains how to handle errors when using Sim APIs, including common error codes, troubleshooting steps, and code examples for proper error handling.
## Error Response Format
When an error occurs, Sim APIs return a standard error response format:
```json
{
"error": {
"message": "Description of what went wrong",
"code": "ERROR_CODE"
}
}
```
## Common Error Codes
| HTTP Status | Error Code | Description | Troubleshooting |
| ----------- | ----------------------- | -------------------------- | -------------------------------------------------------------------------------------------- |
| 401 | UNAUTHORIZED | Invalid or missing API key | Check that you're including the correct API key in the `X-Sim-Api-Key` header |
| 400 | BAD\_REQUEST | Malformed request | Verify the address format and other parameters in your request |
| 404 | NOT\_FOUND | Resource not found | Verify the endpoint URL and resource identifiers |
| 429 | RATE\_LIMIT\_EXCEEDED | Too many requests | Implement backoff strategies and consider upgrading your plan if you consistently hit limits |
| 500 | INTERNAL\_SERVER\_ERROR | Server-side error | Retry the request after a short delay; if persistent, contact support |
## Handling Errors in Code
Here are examples of how to properly handle errors in different programming languages:
### JavaScript
```javascript
fetch('https://api.sim.dune.com/v1/evm/balances/0xd8da6bf26964af9d7eed9e03e53415d37aa96045', {
method: 'GET',
headers: {'X-Sim-Api-Key': 'YOUR_API_KEY'}
})
.then(response => {
if (!response.ok) {
return response.json().then(err => {
throw new Error(`API error: ${err.error?.message || response.statusText}`);
});
}
return response.json();
})
.then(data => {
console.log('Success:', data);
// Process your data here
})
.catch(err => {
console.error('Error fetching balances:', err);
// Handle error appropriately in your application
// e.g., show user-friendly message, retry, or fallback behavior
});
```
### Python
```python
import requests
import time
def get_balances(address, api_key, max_retries=3):
url = f"https://api.sim.dune.com/v1/evm/balances/{address}"
headers = {"X-Sim-Api-Key": api_key}
for attempt in range(max_retries):
try:
response = requests.get(url, headers=headers)
response.raise_for_status() # Raises an exception for 4XX/5XX responses
return response.json()
except requests.exceptions.HTTPError as err:
status_code = err.response.status_code
error_data = {}
try:
error_data = err.response.json()
except:
pass
error_message = error_data.get('error', {}).get('message', 'Unknown error')
print(f"HTTP Error {status_code}: {error_message}")
# Handle specific error codes
if status_code == 429: # Rate limit exceeded
wait_time = min(2 ** attempt, 60) # Exponential backoff
print(f"Rate limit exceeded. Retrying in {wait_time} seconds...")
time.sleep(wait_time)
continue
elif status_code == 500: # Server error
if attempt < max_retries - 1:
wait_time = 2 ** attempt
print(f"Server error. Retrying in {wait_time} seconds...")
time.sleep(wait_time)
continue
# For other errors or if we've exhausted retries
return {"error": error_message, "status_code": status_code}
except requests.exceptions.RequestException as err:
print(f"Request error: {err}")
return {"error": "Network or connection error", "details": str(err)}
return {"error": "Max retries exceeded"}
# Usage
result = get_balances("0xd8da6bf26964af9d7eed9e03e53415d37aa96045", "YOUR_API_KEY")
if "error" in result:
print(f"Failed to get balances: {result['error']}")
else:
print(f"Found {len(result['balances'])} token balances")
```
## Best Practices for Error Handling
1. **Always check for errors**: Don't assume API calls will succeed.
2. **Implement retry logic with backoff**: For transient errors (like rate limits or server errors), implement exponential backoff:
```javascript
async function fetchWithRetry(url, options, maxRetries = 3) {
let retries = 0;
while (retries < maxRetries) {
try {
const response = await fetch(url, options);
if (response.ok) return response.json();
const error = await response.json();
// Don't retry for client errors (except rate limiting)
if (response.status < 500 && response.status !== 429) {
throw new Error(error.error?.message || response.statusText);
}
// For rate limiting or server errors, retry with backoff
retries++;
const delay = Math.min(1000 * 2 ** retries, 10000);
await new Promise(resolve => setTimeout(resolve, delay));
} catch (err) {
if (retries === maxRetries - 1) throw err;
retries++;
}
}
}
```
3. **Provide meaningful error messages**: Transform API error responses into user-friendly messages.
4. **Log errors for debugging**: Maintain detailed logs of API errors for troubleshooting.
5. **Implement fallbacks**: When possible, have fallback behavior when API calls fail.
## Debugging Tips
If you're experiencing persistent errors:
1. **Verify your API key**: Ensure it's valid and has the necessary permissions.
2. **Check request format**: Validate that your request parameters match the API specifications.
3. **Inspect full error responses**: The error message often contains specific details about what went wrong.
4. **Monitor your usage**: Check if you're approaching or exceeding rate limits.
5. **Test with cURL**: Isolate issues by testing the API directly with cURL:
```bash
curl -v -X GET "https://api.sim.dune.com/v1/evm/balances/0xd8da6bf26964af9d7eed9e03e53415d37aa96045" \
-H "X-Sim-Api-Key: YOUR_API_KEY"
```
## Need More Help?
If you're still experiencing issues after following these guidelines, please reach out through our [support channels](/support).
# Activity
Source: https://docs.sim.dune.com/evm/activity
evm/openapi/activity.json get /v1/evm/activity/{uri}
View chronologically ordered transactions including native transfers, ERC20 movements, NFT transfers, and decoded contract interactions.
export const SupportedChains = ({endpoint}) => {
const [data, setData] = useState(null);
useEffect(() => {
fetch("https://api.sim.dune.com/v1/evm/supported-chains", {
method: "GET",
headers: {
"X-Sim-Api-Key": "sim_qfIvSWu7c8WBXzfCQ0SeLBGJts204uyT"
}
}).then(response => response.json()).then(setData);
}, []);
if (data === null) {
return null;
}
const chains = endpoint !== undefined ? data.chains.filter(chain => chain[endpoint]?.supported) : data.chains;
console.log("data", data);
return 
Now that you have a wallet capable of showing realtime token balances and total portfolio value, let's enhance it by adding an *Activity* tab.
A key feature for any wallet is the ability to view past transaction activity.
This includes native currency transfers, ERC20 token movements, NFT transfers, and decoded interactions with smart contracts.
The [Activity API](/evm/activity) provides a comprehensive, realtime feed of this onchain activity, letting you implement this functionality with a single API request across 60+ EVM chains.
In this guide, you'll learn how to build **Simchat**, an AI chat agent that can provide realtime blockchain insights through natural conversation.
Users can ask questions about wallet balances, transaction history, NFT collections, and token information across 60+ EVM chains and Solana, and the agent will fetch and explain the data in a friendly way.
By combining OpenAI's LLMs with the realtime blockchain data provided by Sim APIs, you'll create a chat agent that makes onchain data accessible to everyone, regardless of their technical expertise.
This is the first guide in our series on building a realtime, multichain wallet using Sim APIs.
In this one, we will lay the foundation for our wallet.
You will set up a Node project with Express.js, fetch and display token balances from 60+ EVM chains using the Balances API, and calculate the wallet's total portfolio value in USD.
<% if (tokens && tokens.length > 0) { %>
<% tokens.forEach(token => { %>
<% if (token.token_metadata && token.token_metadata.logo) { %>
<% } else { %>
<% } %>
<% }); %>
<% } else if (walletAddress) { %>
<% if (token.token_metadata && token.token_metadata.url) { %>
<%= token.name || token.symbol %>
<% } else { %><%= token.name || token.symbol %>
<% } %><%= token.valueUSDFormatted || (token.value_usd != null ? token.value_usd : 'N/A') %>
<%= token.amountFormatted || token.amount %> <%= token.symbol %>
No tokens found for this wallet.
<% } else { %>Enter a wallet address above to see token balances.
<% } %>Activity feature will be added in the next guide.
Collectibles feature will be added in a future guide.
## Format Balances
The Balances API returns token amounts in their smallest denomination. This will be in wei for ETH-like tokens.
To display these amounts in a user-friendly way, like `1.23` ETH instead of `1230000000000000000` wei, we need to adjust the amount using the token's `decimals` property, which is also returned from the Balances API.
We can add a new property, `balanceFormatted`, to each token object.
Modify your `getWalletBalances` function in `server.js` as follows. The main change is mapping over `data.balances` to add the `balanceFormatted` property:
```javascript server.js (getWalletBalances with formatting) {24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38}
async function getWalletBalances(walletAddress) {
if (!walletAddress) return [];
const queryParams = `metadata=url,logo&exclude_spam_tokens`;
const url = `https://api.sim.dune.com/v1/evm/balances/${walletAddress}?${queryParams}`;
try {
const response = await fetch(url, {
headers: {
'X-Sim-Api-Key': SIM_API_KEY,
'Content-Type': 'application/json'
}
});
if (!response.ok) {
const errorBody = await response.text();
console.error(`API request failed with status ${response.status}: ${response.statusText}`, errorBody);
throw new Error(`API request failed: ${response.statusText}`);
}
const data = await response.json();
// Return formatted values and amounts
return (data.balances || []).map(token => {
// 1. Calculate human-readable token amount
const numericAmount = parseFloat(token.amount) / Math.pow(10, parseInt(token.decimals));
// 2. Get numeric USD value
const numericValueUSD = parseFloat(token.value_usd);
// 3. Format using numbro
const valueUSDFormatted = numbro(numericValueUSD).format('$0,0.00');
const amountFormatted = numbro(numericAmount).format('0,0.[00]A');
return {
...token,
valueUSDFormatted,
amountFormatted
};
}).filter(token => token.symbol !== 'RTFKT'); // Removing Spam Tokens. Add more if you like.
} catch (error) {
console.error("Error fetching wallet balances:", error.message);
return [];
}
}
```
Now, each token object returned by `getWalletBalances` will include a `balanceFormatted` string, which our EJS template (`views/wallet.ejs`) already uses: `<%= token.balanceFormatted || token.amount %>`.
Restart the server and refresh the browser. You will now see formatted balances.
## Calculate Total Portfolio Value
The wallet's total value at the top of the UI still says `$0.00`.
Let's calculate the total USD value of the wallet and properly show it.
The Balances API provides a `value_usd` field with each token.
This field represents the total U.S. dollar value of the wallet's entire holding for that specific token.
Let's modify the `app.get('/')` route handler to iterate through the fetched tokens and sum their individual `value_usd` to calculate the `totalWalletUSDValue`.
```javascript server.js (app.get('/') with total value calculation) {16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 37}
app.get('/', async (req, res) => {
const {
walletAddress = '',
tab = 'tokens'
} = req.query;
let tokens = [];
let totalWalletUSDValue = 0; // Will be updated
let errorMessage = null;
if (walletAddress) {
try {
tokens = await getWalletBalances(walletAddress);
// Calculate the total USD value from the fetched tokens
if (tokens && tokens.length > 0) {
tokens.forEach(token => {
let individualValue = parseFloat(token.value_usd);
if (!isNaN(individualValue)) {
totalWalletUSDValue += individualValue;
}
});
}
totalWalletUSDValue = numbro(totalWalletUSDValue).format('$0,0.00');
} catch (error) {
console.error("Error in route handler:", error);
errorMessage = "Failed to fetch wallet data. Please try again.";
// tokens will remain empty, totalWalletUSDValue will be 0
}
}
res.render('wallet', {
walletAddress: walletAddress,
currentTab: tab,
totalWalletUSDValue: totalWalletUSDValue, // Pass the calculated total
tokens: tokens,
activities: [], // Placeholder for Guide 2
collectibles: [], // Placeholder for Guide 3
errorMessage: errorMessage
});
});
```
We use the `reduce` method to iterate over the `tokens` array.
For each `token`, we access its `value_usd` property, parse it as a float, and add it to the running `sum`.
The calculated `totalWalletUSDValue` is then formatted to two decimal places and passed to the template.
The `views/wallet.ejs` template already has `
## Conclusion
You have successfully set up the basic structure of your multichain wallet and integrated Sim APIs `Balances API` endpoint to display realtime token balances and total portfolio value.
In the next guide, [Add Account Activity](/evm/add-account-activity), we will enhance this wallet by adding a transaction history feature in the UI using the [Activity API](/evm/activity).
# Collectibles
Source: https://docs.sim.dune.com/evm/collectibles
evm/openapi/collectibles.json get /v1/evm/collectibles/{address}
Retrieve EVM compatiable NFTs (ERC721 and ERC1155) that include token identifiers, token standard, chain information, balance, and basic token attributes.
export const SupportedChains = ({endpoint}) => {
const [data, setData] = useState(null);
useEffect(() => {
fetch("https://api.sim.dune.com/v1/evm/supported-chains", {
method: "GET",
headers: {
"X-Sim-Api-Key": "sim_qfIvSWu7c8WBXzfCQ0SeLBGJts204uyT"
}
}).then(response => response.json()).then(setData);
}, []);
if (data === null) {
return null;
}
const chains = endpoint !== undefined ? data.chains.filter(chain => chain[endpoint]?.supported) : data.chains;
console.log("data", data);
return 
Chain support varies by API endpoint.
Use the dropdown sections below to check which chains are available for each API:
Sim APIs power wallets and onchain apps with fast, reliable access to real-time blockchain activity and ownership data.
Access data from 60+ chains with a single request.
This guide will help you make your first API call to retrieve multichain token balances for an address.
## Authentication
Sim APIs use API keys to authenticate requests.
You can create and manage your API keys in your [Sim Dashboard](https://sim.dune.com/).
To authenticate, include your API key in the `X-Sim-Api-Key` header for every request.
```bash
curl --request GET \
--header "X-Sim-Api-Key: YOUR_API_KEY"
```
All API requests must be made over HTTPS.
Calls made over plain HTTP will fail.
API requests without authentication will also fail.