balances.json

{
  "openapi": "3.0.3",
  "info": {
    "title": "Sim API - Balances Endpoint",
    "description": "This API provides realtime token balances for addresses across different EVM chains.",
    "license": {
      "name": ""
    },
    "version": "0.1.0"
  },
  "servers": [
    {
      "url": "https://api.sim.dune.com"
    }
  ],
  "paths": {
    "/v1/evm/balances/{address}": {
      "get": {
        "tags": [
          "balances"
        ],
        "summary": "Get EVM token balances for a given address",
        "description": "This endpoint returns EVM token balances for an address for any token that the address has interacted with",
        "operationId": "getEvmBalances",
        "parameters": [
          {
            "name": "X-Sim-Api-Key",
            "in": "header",
            "description": "Used for authenticating requests. Provide an API key with a purpose of `Sim API`. See [Authentication](/#authentication).",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "address",
            "in": "path",
            "description": "Wallet address to get balances for",
            "required": true,
            "schema": {
              "type": "string",
              "default": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
            }
          },
          {
            "name": "chain_ids",
            "in": "query",
            "required": false,
            "description": "Filter by chain(s). Accepts numeric chain IDs and/or tags. Provide a single value (e.g. `?chain_ids=1` or `?chain_ids=mainnet`) or a comma-separated list (e.g. `?chain_ids=1,8543,testnet`). Chain names are not accepted. If this query parameter is omitted, results include balances from chains with the `default` tag. See the [Supported Chains Tags](/evm/supported-chains#tags) section.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "filters",
            "in": "query",
            "description": "Specify `erc20` or `native` to get only ERC20 tokens or native assets, respectively",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["erc20", "native"]
            }
          },
          {
            "name": "metadata",
            "in": "query",
            "description": "A comma separated list of additional metadata fields to include for each token. Supported values: `logo`, `url`, `pools`",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "exclude_spam_tokens",
            "in": "query",
            "description": "When true, excludes tokens with less than 100 USD liquidity from the response. This differs from the `low_liquidity` field in the response.",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "historical_prices",
            "in": "query",
            "description": "Historical price selection. Provide a single integer or a comma-separated list of up to 3 integers representing hours in the past (e.g. `168` for 1 week ago or `720,168,24` for 1 month, 1 week, and 1 day ago). When set, each balance includes a historical_prices array with one entry per offset.",
            "required": false,
            "schema": {
              "type": "string"
            },
            "examples": {
              "single_offset": {
                "summary": "Single offset (1 week ago)",
                "value": "168"
              },
              "three_offsets": {
                "summary": "Three offsets (1 month, 1 week, 1 day ago)",
                "value": "720,168,24"
              }
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "The offset to paginate through result sets. This is a cursor being passed from the previous response, only use what the backend returns here.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of balances to return. Default is 1000 when not provided. Values above 1000 are reduced to 1000.",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 1,
              "maximum": 1000,
              "default": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BalancesResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                  "wallet_address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
                  "balances": [
                    {
                      "chain": "ethereum",
                      "chain_id": 1,
                      "address": "0x0e36c45d16585d1801e37cfaa577a9ad39f9343a",
                      "amount": "45787557175393926414790300082",
                      "symbol": "Kendu",
                      "name": "Kendu of Bank",
                      "decimals": 18,
                      "price_usd": 1.233346836175539e+21,
                      "value_usd": 5.647193877847869e+31,
                      "pool_size": 1233.34683617554,
                      "low_liquidity": true
                    },
                    {
                      "chain": "ethereum",
                      "chain_id": 1,
                      "address": "0x113404d2003c4acf4231a3a62374bb503bff03d7",
                      "amount": "432599243131405501735524",
                      "symbol": "ALT",
                      "name": "AltLayer",
                      "decimals": 18,
                      "price_usd": 9.38838601200003e+18,
                      "value_usd": 4.061408683016688e+24,
                      "pool_size": 9.38838601200001,
                      "low_liquidity": true
                    }
                  ],
                        "next_offset": "opaque-pagination-token",
                        "request_time": "2025-08-13T10:31:08Z",
                        "response_time": "2025-08-13T10:31:08Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request. The request could not be understood by the server due to malformed data"
          },
          "404": {
            "description": "Not Found"
          },
          "500": {
            "description": "Internal Server Error. A generic error occurred on the server."
          }
        }
      }
    },
    "/v1/evm/balances/{address}/token/{token_address}": {
      "get": {
        "tags": ["balances"],
        "summary": "Get a single token balance for a given address",
        "description": "Returns the balance for a specific token (or native asset) for a wallet on a single specified chain. This sub-endpoint reuses the Balances response format.",
        "operationId": "getEvmSingleTokenBalance",
        "parameters": [
          {
            "name": "X-Sim-Api-Key",
            "in": "header",
            "description": "Used for authenticating requests. Provide an API key with a purpose of `Sim API`. See [Authentication](/#authentication).",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "address",
            "in": "path",
            "description": "Wallet address to get the token balance for",
            "required": true,
            "schema": { "type": "string", "default": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }
          },
          {
            "name": "token_address",
            "in": "path",
            "description": "Token contract address or `native` for the chain's native asset",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "chain_ids",
            "in": "query",
            "required": true,
            "description": "Filter by chain(s). Accepts numeric chain IDs and/or tags. Provide a single value (e.g. `?chain_ids=1`) or a comma-separated list (e.g. `?chain_ids=1,8543,testnet`). Chain names are not accepted. If omitted, results include balances from chains with the \"default\" tag for the address. See the [Supported Chains Tags](/evm/supported-chains#tags) section.",
            "schema": { "type": "string" }
          },
          {
            "name": "metadata",
            "in": "query",
            "description": "A comma separated list of additional metadata fields to include for each token. Supported values: `logo`, `url`, `pools`",
            "required": false,
            "schema": { "type": "string" }
          },
          {
            "name": "historical_prices",
            "in": "query",
            "description": "Historical price selection. Provide a single integer or a comma-separated list of up to 3 integers representing hours in the past (e.g. `168` for 1 week ago or `720,168,24` for 1 month, 1 week, and 1 day ago). When set, each balance includes a historical_prices array with one entry per offset.",
            "required": false,
            "schema": { "type": "string" },
            "examples": {
              "single_offset": { "summary": "Single offset (1 week ago)", "value": "168" },
              "three_offsets": { "summary": "Three offsets (1 month, 1 week, 1 day ago)", "value": "720,168,24" }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SingleBalanceResponse" },
                "examples": {
                  "success": {
                    "value": {
                      "request_time": "2025-10-07T13:18:14.789152386+00:00",
                      "response_time": "2025-10-07T13:18:14.850098525+00:00",
                      "wallet_address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
                      "balances": [
                        {
                          "chain": "ethereum",
                          "chain_id": 1,
                          "address": "0x146523e8db6337291243a63a5555f446fa6c279f",
                          "amount": "7156868995423049840501842481",
                          "symbol": "AiMeme",
                          "name": "Ai Meme",
                          "decimals": 18,
                          "price_usd": 129086.448055109,
                          "value_usd": 923854797814899,
                          "pool_size": 9.09741149400001,
                          "low_liquidity": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": { "description": "Bad Request. The request could not be understood by the server due to malformed data" },
          "404": { "description": "Not Found" },
          "500": { "description": "Internal Server Error. A generic error occurred on the server." }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "HistoricalPricePoint": {
        "type": "object",
        "required": [
          "offset_hours",
          "price_usd"
        ],
        "properties": {
          "offset_hours": {
            "type": "integer",
            "format": "int32",
            "minimum": 1
          },
          "price_usd": {
            "type": "number",
            "format": "double"
          }
        }
      },
      "PoolMetadata": {
        "type": "object",
        "required": [
          "pool_type",
          "address",
          "token0",
          "token1"
        ],
        "properties": {
          "pool_type": {
            "type": "string",
            "description": "The type of liquidity pool used for pricing (e.g., aerodrome_stable, uniswap_v2, uniswap_v3)"
          },
          "address": {
            "type": "string",
            "description": "The contract address of the liquidity pool"
          },
          "token0": {
            "type": "string",
            "description": "The contract address of the first token in the pool pair"
          },
          "token1": {
            "type": "string",
            "description": "The contract address of the second token in the pool pair"
          }
        }
      },
      "BalanceData": {
        "type": "object",
        "required": [
          "chain",
          "address",
          "amount"
        ],
        "properties": {
          "address": {
            "type": "string"
          },
          "amount": {
            "type": "string"
          },
          "chain": {
            "type": "string"
          },
          "chain_id": {
            "type": "integer",
            "format": "int64"
          },
          "decimals": {
            "type": "integer",
            "format": "int64"
          },
          "low_liquidity": {
            "type": "boolean"
          },
          "name": {
            "type": "string"
          },
          "pool_size": {
            "type": "number",
            "format": "double"
          },
          "price_usd": {
            "type": "number",
            "format": "double"
          },
          "historical_prices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HistoricalPricePoint"
            },
            "description": "Historical price points for the requested offsets. Only present when the historical_prices query parameter is provided."
          },
          "symbol": {
            "type": "string"
          },
          "token_metadata": {
            "type": "object",
            "properties": {
              "logo": {
                "type": "string"
              },
              "url": {
                "type": "string"
              }
            }
          },
          "pool": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PoolMetadata"
              }
            ],
            "description": "Liquidity pool information used for token pricing. Only present when metadata=pools is specified."
          },
          "value_usd": {
            "type": "number",
            "format": "double"
          }
        }
      },
      "BalanceErrorInformation": {
        "type": "object",
        "required": [
          "chain_id",
          "address"
        ],
        "properties": {
          "address": {
            "type": "string"
          },
          "chain_id": {
            "type": "integer",
            "format": "int64"
          },
          "description": {
            "type": "string"
          }
        }
      },
      "BalanceErrors": {
        "type": "object",
        "properties": {
          "error_message": {
            "type": "string"
          },
          "token_errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BalanceErrorInformation"
            }
          }
        }
      },
      "Warning": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Warning code identifier",
            "example": "UNSUPPORTED_CHAIN_IDS"
          },
          "message": {
            "type": "string",
            "description": "Human-readable warning message",
            "example": "Some requested chain_ids are not supported. Balances are returned only for supported chains."
          },
          "chain_ids": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "int64"
            },
            "description": "List of chain IDs that triggered this warning"
          },
          "docs_url": {
            "type": "string",
            "description": "URL to relevant documentation",
            "example": "https://docs.sim.dune.com/evm/supported-chains"
          }
        }
      },
      "BalancesResponse": {
        "type": "object",
        "required": [
          "wallet_address",
          "balances"
        ],
        "properties": {
          "balances": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BalanceData"
            }
          },
          "errors": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BalanceErrors"
              }
            ]
          },
          "warnings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Warning"
            },
            "description": "Array of warnings about the request. For example, warnings about unsupported chain IDs."
          },
          "next_offset": {
            "type": "string",
            "description": "Use this value as the `offset` in your next request to continue pagination. Not included when there are no more balances."
          },
          "request_time": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of when the request was received."
          },
          "response_time": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of when the response was generated."
          },
          "wallet_address": {
            "type": "string",
            "example": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
          }
        }
      },
      "SingleBalanceResponse": {
        "type": "object",
        "required": [
          "wallet_address",
          "balances"
        ],
        "properties": {
          "balances": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/BalanceData" }
          },
          "warnings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Warning"
            },
            "description": "Array of warnings about the request. For example, warnings about unsupported chain IDs."
          },
          "request_time": { "type": "string", "format": "date-time" },
          "response_time": { "type": "string", "format": "date-time" },
          "wallet_address": { "type": "string", "example": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045" }
        }
      }
    }
  },
  "tags": [
    {
      "name": "balances",
      "description": "Balances API"
    }
  ]
}