Zerion wallet sets API
Operations on a wallet set — aggregated portfolio data across at most one EVM address and one Solana address queried together.
OpenAPI Specification
openapi: 3.0.3
info:
version: 1.0.0
title: REST chains wallet sets API
description: REST-like API provides access to rich Zerion ecosystem.
contact:
name: Zerion API
url: https://developers.zerion.io/
email: api@zerion.io
servers:
- description: Production API
url: https://api.zerion.io
security:
- APIKeyBasicAuth: []
tags:
- name: wallet sets
description: Operations on a wallet set — aggregated portfolio data across at most one EVM address and one Solana address queried together.
paths:
/v1/wallet-sets/charts/{chart_period}:
get:
operationId: getWalletSetChart
summary: Get wallet set balance chart
description: 'This endpoint returns a portfolio balance chart for a wallet set.
A wallet set is represented by an EVM address, a Solana address, or both. At least one address must be provided.
This is over a specified time period, based on the provided start and end timestamps.
Results can be filtered by blockchain and asset type, offering flexible and detailed visualizations of wallet set performance, similar to what you see in the Zerion interface.
**Complex positions.** By default the chart counts only simple positions: token and native-coin balances held directly in the wallet. Set `filter[positions]` to `only_complex` or `no_filter` to also include complex DeFi protocol positions. Uniswap V2 LP positions are supported today, and support for more protocols is rolling out over time. Positions from protocols that aren''t yet supported are omitted from the chart.
'
tags:
- wallet sets
parameters:
- $ref: '#/components/parameters/WalletSetAddresses'
- $ref: '#/components/parameters/ChartPeriod'
- $ref: '#/components/parameters/Currency'
- name: filter[chain_ids]
in: query
style: form
explode: false
description: Account only for balance on these chains (comma-separated list). Available chain ids can be found in chains endpoints.
schema:
type: array
example:
- aurora
maxItems: 25
items:
type: string
- name: filter[fungible_ids]
in: query
style: form
explode: false
description: Account only for balance of given fungible assets (comma-separated list). Mutually exclusive with `filter[exclude_fungible_ids]` — combining both returns `400`.
schema:
type: array
maxItems: 25
items:
type: string
maxLength: 44
- name: filter[exclude_fungible_ids]
in: query
style: form
explode: false
description: Exclude balance contributions from the given fungible assets (comma-separated list). Useful when the set you want to keep is large but the set you want to omit is small. Mutually exclusive with `filter[fungible_ids]` — combining both returns `400`.
schema:
type: array
maxItems: 25
items:
type: string
maxLength: 44
- name: filter[pool_addresses]
in: query
style: form
explode: false
description: Restrict the balance chart to specific liquidity-pool / vault positions, identified by their contract address (comma-separated list) — the Uniswap V2 LP-token or ERC-4626 vault (e.g. Morpho) address. Only the matching protocol positions are charted; simple token and native-coin balances are excluded. These are complex (protocol) positions, so passing `filter[positions]=only_simple` alongside this filter returns `400`. Mutually exclusive with `filter[exclude_pool_addresses]` — combining both returns `400`.
schema:
type: array
maxItems: 25
items:
type: string
maxLength: 44
- name: filter[exclude_pool_addresses]
in: query
style: form
explode: false
description: Exclude specific liquidity-pool / vault positions from the balance chart, identified by their contract address (comma-separated list) — the Uniswap V2 LP-token or ERC-4626 vault (e.g. Morpho) address. The matching positions are removed; the rest of the portfolio (including simple balances) is kept. These are complex (protocol) positions, so passing `filter[positions]=only_simple` alongside this filter — which would already drop every protocol position, making the exclusion a no-op — returns `400`. Mutually exclusive with `filter[pool_addresses]` — combining both returns `400`.
schema:
type: array
maxItems: 25
items:
type: string
maxLength: 44
- name: filter[positions]
in: query
style: form
explode: false
description: 'Which positions to include in the balance chart.
- `only_simple` (default) — simple positions only: wallet token and native-coin balances.
- `only_complex` — complex DeFi protocol positions only (e.g. liquidity-pool and vault positions).
- `no_filter` — include both simple and complex positions.
Uniswap V2 LP positions are supported today, and support for more protocols is rolling out over time.
'
schema:
type: string
default: only_simple
enum:
- only_simple
- only_complex
- no_filter
responses:
'200':
$ref: '#/components/responses/ChartsResponse-2'
'400':
$ref: '#/components/responses/MalformedParameters'
'401':
$ref: '#/components/responses/UnauthenticatedError'
'429':
$ref: '#/components/responses/TooManyRequests'
/v1/wallet-sets/pnl:
get:
operationId: getWalletSetPNL
summary: Get wallet set PnL
description: 'This endpoint returns the Profit and Loss (PnL) details of a wallet set.
A wallet set is represented by an EVM address, a Solana address, or both. At least one address must be provided.
This includes Unrealized PnL, Realized PnL, Net Invested amounts and filters for asset categories like Non Fungible Tokens (NFTs).
It uses the FIFO (First In, First Out) standard for calculations, providing accurate insights into wallet set performance.
Ideal for tracking and analyzing financial outcomes of wallet activity across multiple addresses.
The very first request for a wallet set might result in a 503 which should be retried later.
Wallet sets with over 1 million transactions are not supported.
'
tags:
- wallet sets
parameters:
- $ref: '#/components/parameters/WalletSetAddresses'
- $ref: '#/components/parameters/Currency'
- name: filter[chain_ids]
in: query
style: form
explode: false
description: Calculate PnL only for specified chains (comma-separated list).
schema:
type: array
example:
- ethereum
- polygon
maxItems: 25
items:
type: string
- name: filter[fungible_ids]
in: query
style: form
explode: false
description: 'Account only for PnL related to given fungible assets (comma-separated list). Maximum of 100 fungible IDs allowed.
When filtering by fungible_ids or fungible_implementations, assets without available prices are automatically excluded from calculations instead of causing an error. Excluded assets are returned in the response metadata for transparency.
'
schema:
type: array
maxItems: 100
items:
type: string
maxLength: 44
- name: filter[fungible_implementations]
in: query
style: form
explode: false
description: 'Account only for PnL related to given fungible asset implementations (comma-separated list of chain:address pairs). Maximum of 100 implementations allowed.
example: "base:0xae16c445d8a4082cecb49a9465e4dd5499df947d,ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
When filtering by fungible_ids or fungible_implementations, assets without available prices are automatically excluded from calculations instead of causing an error. Excluded assets are returned in the response metadata for transparency.
'
schema:
type: array
maxItems: 100
items:
type: string
- name: since
in: query
required: false
description: 'Only account sales since the given date.
A unix timestamp in milliseconds.
**Note:** PnL is pre-computed at standard marks (`now`, `1 day ago`, `1 week ago`, `1 month ago`, `1 year ago`, `beginning of the year`). Other values are supported only if fewer than 3,000 transactions sit between your timestamp and the nearest mark — otherwise the request errors out.'
schema:
type: string
example: '1688842525735'
minLength: 13
maxLength: 13
- name: till
in: query
required: false
description: 'Only account sales till the given date.
A unix timestamp in milliseconds.
**Note:** PnL is pre-computed at standard marks (`now`, `1 day ago`, `1 week ago`, `1 month ago`, `1 year ago`, `beginning of the year`). Other values are supported only if fewer than 3,000 transactions sit between your timestamp and the nearest mark — otherwise the request errors out.'
schema:
type: string
example: '1688842525735'
minLength: 13
maxLength: 13
responses:
'200':
$ref: '#/components/responses/PNLResponse-2'
'400':
$ref: '#/components/responses/MalformedParameters'
'401':
$ref: '#/components/responses/UnauthenticatedError'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/RetryAfter'
/v1/wallet-sets/portfolio:
get:
operationId: getWalletSetPortfolio
summary: Get wallet set portfolio
description: 'This endpoint returns a wallet set''s portfolio overview.
A wallet set is represented by an EVM address, a Solana address, or both. At least one address must be provided.
**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: 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.
'
tags:
- wallet sets
parameters:
- $ref: '#/components/parameters/WalletSetAddresses'
- name: filter[positions]
in: query
required: false
description: "This parameter allows to customize the aggregation of DeFi positions within a portfolio based on their types. The aggregation can include:\n\n - `only_simple`: Only includes wallet-type positions, which are basic, non-protocol related assets. This is the default selection if the parameter is not specified.\n - `only_complex`: Aggregates positions associated with DeFi protocols only (e.g., staked assets, liquidity pools), like Uniswap or Aave, excluding simple wallet positions.\n - `no_filter`: Provides an aggregated view of both protocol-related and simple wallet positions without any filtering.\n\nThe selection of filters affects the composition of the aggregated portfolio results, allowing for tailored analysis and reporting based on the types of positions of interest.\n\n> ⚠️ Note: Enterprise usage of this API may be subject to different pricing models depending on the selected filter type. For detailed pricing information, please contact `api@zerion.io`.\n"
schema:
type: string
default: only_simple
enum:
- only_simple
- only_complex
- no_filter
- $ref: '#/components/parameters/Currency'
responses:
'200':
$ref: '#/components/responses/PortfolioResponse-2'
'400':
$ref: '#/components/responses/MalformedParameters'
'401':
$ref: '#/components/responses/UnauthenticatedError'
'429':
$ref: '#/components/responses/TooManyRequests'
/v1/wallet-sets/positions/:
get:
operationId: listWalletSetPositions
summary: Get wallet set fungible positions
description: 'This endpoint returns a list of wallet set positions.
A wallet set is represented by an EVM address, a Solana address, or both. At least one address must be provided.
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.
'
tags:
- wallet sets
parameters:
- $ref: '#/components/parameters/WalletSetAddresses'
- name: filter[positions]
in: query
required: false
description: '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`.
'
schema:
type: string
default: only_simple
enum:
- only_simple
- only_complex
- no_filter
- $ref: '#/components/parameters/Currency'
- name: filter[position_types]
in: query
style: form
explode: false
description: '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
'
schema:
type: array
maxItems: 8
items:
$ref: '#/components/schemas/PositionType'
- name: filter[chain_ids]
in: query
style: form
explode: false
description: Keep only positions from these chains (comma-separated list). Available chain ids can be found in chains endpoints.
schema:
type: array
example:
- polygon
maxItems: 25
items:
type: string
- name: filter[fungible_ids]
in: query
style: form
explode: false
description: Keep only positions related to given fungible assets (comma-separated list).
schema:
type: array
maxItems: 25
items:
type: string
maxLength: 44
- name: filter[dapp_ids]
in: query
style: form
explode: false
description: Keep only positions related to these decentralized applications (dapps) (comma-separated list).
schema:
type: array
example:
- polygon
maxItems: 25
items:
type: string
maxLength: 32
minLength: 1
- name: filter[trash]
in: query
required: false
description: Filter positions based on the `is_trash` flag. If no flag is specified, then `only_non_trash` is applied.
schema:
type: string
default: only_non_trash
enum:
- only_trash
- only_non_trash
- no_filter
- name: sort
in: query
required: false
description: Choose how the result should be ordered
schema:
type: string
default: value
enum:
- -value
- value
- name: X-Env
in: header
description: Custom header that allows you to get data for testnets.
required: false
schema:
type: string
enum:
- testnet
responses:
'200':
$ref: '#/components/responses/PositionsListResponse-2'
'400':
$ref: '#/components/responses/MalformedParameters'
'401':
$ref: '#/components/responses/UnauthenticatedError'
'429':
$ref: '#/components/responses/TooManyRequests'
/v1/wallet-sets/transactions/:
get:
operationId: listWalletSetTransactions
summary: Get wallet set transactions
description: 'This endpoint returns a list of transactions associated with the wallet set.
A wallet set is represented by an EVM address, a Solana address, or both. At least one address must be provided.
This endpoint supports testnets. To get data for testnets use `X-Env` header.
**Temporary limitations for Solana addresses:**
- Doesn''t support NFT transactions
> NOTE: This endpoint supports a lot of filters, sorting, and pagination parameters. Make sure that your request URL length is safe 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.
'
tags:
- wallet sets
parameters:
- $ref: '#/components/parameters/WalletSetAddresses'
- $ref: '#/components/parameters/Currency'
- $ref: '#/components/parameters/Page'
- name: filter[search_query]
in: query
required: false
description: Query for a full-text search.
schema:
type: string
example: Trade
minLength: 2
maxLength: 64
- name: filter[operation_types]
in: query
required: false
description: Return only transactions with specified types (comma-separated list). See the operation type schema for the full list of values.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/Type'
- name: filter[asset_types]
in: query
required: false
description: Return only transactions that contain specified asset types (comma-separated list).
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/AssetType'
- name: filter[chain_ids]
in: query
required: false
description: Return only transactions from specified chains (comma-separated list). You can find available chain ids in chain endpoints.
style: form
explode: false
schema:
type: array
items:
type: string
example: polygon
- name: filter[fungible_ids]
in: query
required: false
description: Return only transactions with fungibles with specified ids (comma-separated list).
style: form
explode: false
schema:
type: array
items:
type: string
example: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
- name: filter[min_mined_at]
in: query
required: false
description: Return only transactions since specific date. Timestamp in milliseconds.
schema:
type: string
example: '1688842525735'
minLength: 13
maxLength: 13
- name: filter[max_mined_at]
in: query
required: false
description: Return only transactions until specific date. Timestamp in milliseconds.
schema:
type: string
example: '1694192535967'
minLength: 13
maxLength: 13
- name: filter[trash]
in: query
required: false
description: Filter transactions based on the `is_trash` flag. If no flag is specified, then `no_filter` is applied.
schema:
type: string
default: no_filter
enum:
- only_trash
- only_non_trash
- no_filter
- name: filter[fungible_implementations]
in: query
style: form
explode: false
required: false
description: 'Specify implementations of fungible tokens as a comma-separated list of `chain:address` pairs.
Example format: `ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48,polygon:0x123456789abcdef123456789abcdef123456789`
Each item consists of a blockchain `chain_id` and an `address`, separated by a colon (`:`). Multiple pairs can be provided using commas (`,`).
'
schema:
type: array
items:
type: string
example: ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
- name: X-Env
in: header
description: Custom header that allows you to get data for testnets.
required: false
schema:
type: string
enum:
- testnet
responses:
'200':
$ref: '#/components/responses/TransactionsListResponse-2'
'400':
$ref: '#/components/responses/MalformedParameters'
'401':
$ref: '#/components/responses/UnauthenticatedError'
'429':
$ref: '#/components/responses/TooManyRequests'
components:
responses:
TransactionsListResponse-2:
description: Response for requested list of transactions
content:
application/json:
schema:
$ref: '#/components/schemas/Response-11'
MalformedParameters:
description: Parameters are malformed
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
title:
type: string
description: Error short title
example: Parameter is malformed
detail:
type: string
description: Long description of the error
example: Some validation errors will be described here
TooManyRequests:
description: Too many requests error
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
title:
type: string
description: Error short title
example: Too many requests
detail:
type: string
description: Long description of the error
example: Your request had been throttled
RetryAfter:
description: Service is temporarily unavailable
headers:
Retry-After:
description: 'Indicates how long the client should wait before making a follow-up request.
'
schema:
type: integer
example: 10
description: Number of seconds to wait.
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
title:
type: string
description: Error short title
example: Service is temporarily unavailable
detail:
type: string
description: Long description of the error
example: Please, retry later (check the Retry-After header)
UnauthenticatedError:
description: Unathenticated request
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
title:
type: string
description: Error short title
example: Unauthorized Error
detail:
type: string
description: Long description of the error
example: The API key is invalid, please, make sure that you are using a valid key
PNLResponse-2:
description: Response for requested wallet set PnL
content:
application/json:
schema:
$ref: '#/components/schemas/Response-8'
PortfolioResponse-2:
description: Response for requested wallet set portfolio
content:
application/json:
schema:
$ref: '#/components/schemas/Response-9'
ChartsResponse-2:
description: Resource for the requested wallet set chart
content:
application/json:
schema:
$ref: '#/components/schemas/Response-7'
PositionsListResponse-2:
description: Response for requested list of positions
content:
application/json:
schema:
$ref: '#/components/schemas/Response-10'
schemas:
Relationship:
type: object
required:
- links
- data
properties:
links:
$ref: '#/components/schemas/RelationshipLinks'
data:
$ref: '#/components/schemas/ContainerShort'
ResponseLinks-9:
type: object
required:
- self
properties:
self:
type: string
format: url
example: https://api.zerion.io/v1/wallet-sets/portfolio?addresses=0x42b9df65b219b3dd36ff330a4dd8f327a6ada990%2C8BH9pjtgyZDC4iAQH5ZiYDZ1MDWC98xki2V8NzqqKW3K¤cy=eth&filter%5Bpositions%5D=no_filter
TradingVolumes:
type: object
properties:
volume_1d:
type: number
format: double
description: Trading volume over the last 24 hours in the selected currency.
example: 40096375.69294812
Relationship-2:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/ContainerShort-2'
Response-7:
type: object
required:
- links
- data
properties:
links:
$ref: '#/components/schemas/ResponseLinks-7'
data:
$ref: '#/components/schemas/Container-10'
Response-8:
type: object
required:
- links
- data
properties:
links:
$ref: '#/components/schemas/ResponseLinks-8'
data:
$ref: '#/components/schemas/Container-11'
meta:
type: object
description: 'Metadata about the PnL calculation (only present when assets were excluded from the calculation).
The structure matches the filter type used in the request:
- When filtering by `fungible_ids`, the meta contains an `excluded_fungible_ids` array
- When filtering by `fungible_implementations`, the meta contains an `excluded_fungible_implementations` array
- If both filters are used, both fields may appear in the meta
'
properties:
excluded_fungible_ids:
type: array
items:
type: string
description: Fungible asset IDs that were excluded due to missing prices (only present when the request used fungible_ids filter)
example:
- 4a702a34-5cfd-41af-96ad-bd1c45c3672e
excluded_fungible_implementations:
type: array
items:
type: string
description: 'Asset implementations that were excluded due to missing prices (only present when the request used fungible_implementations filter).
Format matches the user''s query format: "chain:address" for regular tokens, "chain:" for base assets.
'
example:
- ethereum:0x6b175474e89094c44da98b954eedeac495271d0f
- 'ethereum:'
Type:
type: string
description: 'Type of the transaction operation. This field indicates the primary action performed in the transaction.
Possible values and their meanings:
- `approve` - Grant permission to a smart contract to access and spend tokens on behalf of the wallet
- `bid` - Place a bid in a prediction market
- `burn` - Destroy tokens permanently, reducing the total token supply
- `claim` - Claim earned rewards, airdrops, or vested tokens from a protocol
- `delegate` - Delegate tokens or voting power to another address
- `deploy` - Deploy a new smart contract to the blockchain
- `deposit` - Deposit assets into a protocol (e.g., lending pool, liquidity pool, vault)
- `execute` - Execute a smart contract function or complex interaction that doesn''t fit other specific types
- `mint` - Create new tokens, increasing the total token supply
- `receive` - Receive tokens from another wallet address
- `revoke` - Revoke previously granted token spending permissions from a smart contract
- `revoke_delegation` - Revoke a previously delegated token or voting power
- `send` - S
# --- truncated at 32 KB (81 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zerion/refs/heads/main/openapi/zerion-wallet-sets-api-openapi.yml