v1

latestOpenAPI 3.0.32026-07-2639188178.2 KB

wallets

Get wallet fungible positions

This endpoint returns a list of wallet positions.

This endpoint supports testnets. To get data for testnets use X-Env header.

Understanding Liquidity Pool Positions:

Liquidity pools (Uniswap, Curve, Balancer, etc.) return multiple positions - one for each token in the pool. Positions belonging to the same pool share the same group_id value in attributes.

For example, a Uniswap V2 USDC/WETH pool returns two positions:

Position 1: WETH token, group_id="820ee2f1ca8ccb716f6beb5e450908a028be890ec44aba87c739b416ef41e197", fungible_info.symbol="WETH"
Position 2: USDC token, group_id="820ee2f1ca8ccb716f6beb5e450908a028be890ec44aba87c739b416ef41e197", fungible_info.symbol="USDC"

To display all tokens in a liquidity pool together, group positions by their group_id attribute.

Temporary limitations for Solana addresses:

Doesn't support protocol positions

NOTE: Don't forget to stop retries after some reasonable period of time. If the 200 status is not returned within 2 minutes it most probably means that some unexpected error occurred and the client should stop the polling.

NOTE: This endpoint is not paginated and returns all matching positions in a single response. It supports a lot of filters and sorting parameters, so make sure that a request URL length is in a safe range for your platform. Usually, 2000 characters are the safe limit in virtually any combination of client and server software.

NOTE: Consider all IDs as abstract strings, without making any assumptions about their format or relying on such assumptions. There is a non-zero probability that IDs may change in the future, and this should not result in any breaking changes.

get/v1/wallets/{address}/positions/

Path parameters

string required

Ethereum-compatible address (EVM).

string required

Solana address

Example:0x42b9df65b219b3dd36ff330a4dd8f327a6ada990

The web3 wallet address. Must be a valid EVM or Solana address. Returns 400 if the address is not tracked by Zerion.

Query parameters

filter[positions]'only_simple' | 'only_complex' | 'no_filter'

This parameter allows users to filter DeFi positions based on their types. There are three options:

only_simple: Retrieves exclusively wallet-type positions. These are basic, non-protocol related positions. This option is applied if parameter is not specified.
only_complex: Fetches only positions associated with all DeFi protocols (including staked assets, liquidity pools, etc), like Uniswap or Aave. This option excludes simple wallet positions.
no_filter: Applies no filtering, thus returning both protocol-related and simple wallet positions.

⚠️ Note: Different pricing models are applied for enterprise usage of this API, depending on the filter type selected. For detailed pricing information, please reach out to us at api@zerion.io.

currency'eth' | 'btc' | 'usd' | 'eur' | 'krw' | 'rub' | 'gbp' | 'aud' | 'cad' | 'inr' | 'jpy' | 'nzd' | 'try' | 'zar' | 'cny' | 'chf'

Denominated currency value of returned prices

filter[position_types]PositionType[]

Keep only positions with these types (comma-separated list).

Possible values:

deposit - Assets deposited into a DeFi protocol (e.g., supplied to lending pools, deposited in vaults, or provided as liquidity)
loan - Borrowed assets representing a debt position that needs to be repaid
locked - Assets locked for a specific period or purpose (e.g., vote-escrowed tokens, time-locked tokens)
staked - Assets staked in a protocol to earn rewards, participate in consensus, or for governance purposes
reward - Earned rewards that are claimable or have been distributed but not yet withdrawn
wallet - Regular assets held directly in the wallet, not actively deposited in any protocol
investment - Investment positions such as tokenized funds, indices, or structured products

filter[chain_ids]string[]

Keep only positions from these chains (comma-separated list). Available chain ids can be found in chains endpoints.

[
  "polygon"
]

filter[fungible_ids]string[]

Keep only positions related to given fungible assets (comma-separated list).

filter[dapp_ids]string[]

Keep only positions related to these decentralized applications (dapps) (comma-separated list).

[
  "polygon"
]

filter[trash]'only_trash' | 'only_non_trash' | 'no_filter'

Filter positions based on the is_trash flag. If no flag is specified, then only_non_trash is applied.

sort'-value' | 'value'

Choose how the result should be ordered

Headers

X-Env'testnet'

Custom header that allows you to get data for testnets.

Response

Response for requested list of positions

Example response

{
  "links": {
    "self": "https://api.zerion.io/v1/wallets/0x42b9df65b219b3dd36ff330a4dd8f327a6ada990/positions/"
  },
  "data": [
    {
      "id": "0x111c47865ade3b172a928df8f990bc7f2a3b9aaa-polygon-asset-none-",
      "attributes": {
        "parent": "0x111c47865ade3b172a928df8f990bc7f2a3b9aaa-polygon-asset-none-",
        "protocol_module": "lending",
        "pool_address": "0x109830a1aaad605bbf02a9dfa7b0b92ec2fb7daa",
        "name": "Asset",
        "group_id": "0a771a0064dad468045899032c7fb01a971f973f7dff0a5cdc3ce199f45e94d7",
        "quantity": {
          "int": "12345678",
          "decimals": 5,
          "float": 123.45678,
          "numeric": "123.45678"
        },
        "value": 5.384656557642683,
        "price": 0.043615722,
        "changes": {
          "absolute_1d": 0.272309794,
          "percent_1d": 5.326512552079021
        },
        "fungible_info": {
          "id": "0230395c-2b01-46d8-b2d6-ce8121d51f9e",
          "name": "Bankless BED Index",
          "symbol": "BED",
          "description": "The BED index is meant to track crypto’s top 3 investab.",
          "icon": {
            "url": "https://token-icons.s3.amazonaws.com/0x0391d2021f89dc339f60fff84546ea23e337750f.png"
          },
          "flags": {
            "verified": true
          },
          "implementations": [
            {
              "chain_id": "ethereum",
              "address": "0x2af1df3ab0ab157e1e2ad8f88a7d04fbea0c7dc6",
              "decimals": 18
            }
          ],
          "market_data": {
            "total_supply": 29905.762448515918,
            "circulating_supply": 29905.762448515918,
            "fully_diluted_valuation": 3196313.736038149,
            "market_cap": 3196313.736038149,
            "price": 106.87952669793131,
            "changes": {
              "percent_1d": -0.7379066649086338,
              "percent_30d": -2.499465618806962,
              "percent_90d": 11.316340269371775
            },
            "trading_volumes": {
              "volume_1d": 40096375.69294812
            }
          }
        },
        "flags": {
          "displayable": true
        },
        "updated_at": "2023-11-10T23:00:00Z",
        "application_metadata": {
          "name": "AAVE",
          "icon": {
            "url": "https://token-icons.s3.amazonaws.com/0x0391d2021f89dc339f60fff84546ea23e337750f.png"
          },
          "url": "https://app.aave.com/"
        },
        "receipt": {
          "fungible_info": {
            "id": "0230395c-2b01-46d8-b2d6-ce8121d51f9e",
            "name": "Bankless BED Index",
            "symbol": "BED",
            "description": "The BED index is meant to track crypto’s top 3 investab.",
            "icon": {
              "url": "https://token-icons.s3.amazonaws.com/0x0391d2021f89dc339f60fff84546ea23e337750f.png"
            },
            "flags": {
              "verified": true
            },
            "implementations": [
              {
                "chain_id": "ethereum",
                "address": "0x2af1df3ab0ab157e1e2ad8f88a7d04fbea0c7dc6",
                "decimals": 18
              }
            ],
            "market_data": {
              "total_supply": 29905.762448515918,
              "circulating_supply": 29905.762448515918,
              "fully_diluted_valuation": 3196313.736038149,
              "market_cap": 3196313.736038149,
              "price": 106.87952669793131,
              "changes": {
                "percent_1d": -0.7379066649086338,
                "percent_30d": -2.499465618806962,
                "percent_90d": 11.316340269371775
              },
              "trading_volumes": {
                "volume_1d": 40096375.69294812
              }
            }
          }
        }
      },
      "relationships": {
        "chain": {
          "links": {
            "related": "https://api.zerion.io/v1/chains/polygon"
          },
          "data": {
            "type": "chains",
            "id": "polygon"
          }
        },
        "fungible": {
          "links": {
            "related": "https://api.zerion.io/v1/fungibles/0x111c47865ade3b172a928df8f990bc7f2a3b9aaa"
          },
          "data": {
            "type": "fungibles",
            "id": "0x111c47865ade3b172a928df8f990bc7f2a3b9aaa"
          }
        },
        "dapp": {
          "data": {
            "type": "dapps",
            "id": "aave-v3"
          }
        }
      }
    }
  ]
}