ZEzerion
wallets

Get wallet fungible positions

Changed on

Returns the fungible positions of a wallet: tokens and native coins held directly, plus DeFi protocol positions when filter[positions] is set to only_complex or no_filter.

Liquidity pool positions. A liquidity pool (Uniswap, Curve, Balancer and similar) returns one position per token in the pool, not one position for the pool. Positions from the same pool share an attributes.group_id, so group on that value to render a pool as a single row. A Uniswap V2 USDC/WETH pool, for example, returns a WETH position and a USDC position carrying the same group_id.

Not paginated. All matching positions come back in a single response; there is no links.next and page[size] is ignored. Filters and sorting are applied server-side, so keep the request URL within a safe length (2000 characters is safe across virtually every client and server).

Solana limitation. Protocol positions are not supported for Solana addresses yet.

See also: Testnets (X-Env: testnet) · Filtering and the 2000-character URL limit · Resource IDs

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

Request

  • Base URL
    https://api.zerion.io
  • URL
    https://api.zerion.io/v1/wallets/{address}/positions/
  • Auth
    HTTP basic

Path parameters

string required

Ethereum-compatible address (EVM).

OR
string required

Solana address

Example:0x42b9df65b219b3dd36ff330a4dd8f327a6ada990

The web3 wallet address. Must be a valid EVM or Solana address. The PnL endpoint additionally requires an address Zerion tracks, and returns 400 otherwise; see that endpoint's description for what that excludes.

Query parameters

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

Which positions to return. Defaults to only_simple.

  • only_simple - tokens and native coins held directly in the wallet. DeFi protocol positions are left out.
  • only_complex - DeFi protocol positions only, such as staked assets and liquidity pools (for example Uniswap or Aave).
  • no_filter - both simple and protocol positions. A share token that a returned protocol position carries as receipt can be left out as its own wallet row. So no_filter can return fewer rows than only_simple and only_complex combined, and some share tokens still appear twice. See Deduplicating share tokens.

Note: only_complex and no_filter count as advanced requests. Advanced requests have their own, smaller quota within your plan, and once it's used up these requests return 429 even if your overall quota has room. Check your plan's advanced quota in the Dashboard, or contact api@zerion.io for a different plan.

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). Only chains reporting supports_positions in the flags of GET /v1/chains/ are accepted here. Naming a chain that fails that gate returns 400 rather than an empty result, with detail reading chain <id> does not support positions (for example chain bob does not support positions). A chain of the wrong network family for the address is rejected the same way, with does not support this wallet address type. When the filter is omitted, chains that fail the gate are left out of data silently, with no error and no meta signal.

[
  "polygon"
]
filter[fungible_ids]string[]

Keep only positions for these fungible IDs (comma-separated list).

filter[dapp_ids]string[]

Keep only positions from these dapps (comma-separated list of dapp IDs).

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

Filter positions by the is_trash spam flag. Defaults to only_non_trash, which leaves spam positions out.

sort'-value' | 'value'

Sort by position value. Defaults to value, which puts the highest value first. Use -value for lowest first.

Headers

X-Env'testnet'

Set to testnet to return testnet data instead of mainnet.

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
              }
            }
          },
          "nft_info": {
            "chain_id": "ethereum",
            "contract_address": "0xc36442b4a4522e871399cd717abdd847ab11fe88",
            "token_id": "1303743"
          },
          "quantity": {
            "int": "12345678",
            "decimals": 5,
            "float": 123.45678,
            "numeric": "123.45678"
          }
        }
      },
      "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"
          }
        }
      }
    }
  ]
}

Changes

  • 719a229a555dRevision changes
    • breaking

      the response property ////// became nullable for the status

    • breaking

      the response property /////// became nullable for the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ////// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status