> For the complete documentation index, see [llms.txt](https://docs.syncrone.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.syncrone.fi/api-reference/syncrone-api/holdings.md).

# Holdings

Query token holdings across organizations, wallets and chains.

## Get Holdings

> Retrieve token holdings data across organizations, wallets and chains.\
> Holdings represent direct token balances held by wallets, excluding DeFi protocol positions.\
> \
> Supports filtering by wallet, chain, time range, and asset address.<br>

```json
{"openapi":"3.0.3","info":{"title":"Syncrone API","version":"1.0.0"},"tags":[{"name":"Holdings","description":"Query token holdings across organizations, wallets and chains."}],"servers":[{"url":"https://api.syncrone.fi/api","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-Key","description":"API key for authentication"}},"parameters":{"ChainId":{"name":"chain_id","in":"query","description":"Blockchain network ID (e.g., 1 for Ethereum mainnet, 137 for Polygon)","required":false,"schema":{"type":"integer"}},"Chain":{"name":"chain","in":"query","description":"Blockchain network name (alternative to chain_id)","required":false,"schema":{"type":"string"}},"Wallet":{"name":"wallet","in":"query","description":"Wallet address to filter by","required":false,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},"FromDate":{"name":"from_date","in":"query","description":"Start date for time range filter (ISO 8601 format)","required":false,"schema":{"type":"string","format":"date-time"}},"ToDate":{"name":"to_date","in":"query","description":"End date for time range filter (ISO 8601 format)","required":false,"schema":{"type":"string","format":"date-time"}},"FromBlock":{"name":"from_block","in":"query","description":"Start block number for filtering","required":false,"schema":{"type":"string"}},"ToBlock":{"name":"to_block","in":"query","description":"End block number for filtering","required":false,"schema":{"type":"string"}},"ViaProxy":{"name":"via_proxy","in":"query","description":"Proxy contract address if interaction was through a proxy","required":false,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},"SnapshotMode":{"name":"snapshot_mode","in":"query","description":"Filter by snapshot capture mode:\n- `all`: All snapshot types\n- `daily_only`: Daily scheduled snapshots\n- `interaction_only`: Event-driven snapshots on wallet interactions\n- `harmonized_only`: Regularly scheduled harmonized snapshots\n","required":false,"schema":{"type":"string","enum":["all","daily_only","interaction_only","harmonized_only"],"default":"all"}},"NextCursor":{"name":"next_cursor","in":"query","description":"Pagination cursor from previous response","required":false,"schema":{"type":"string","format":"date-time"}},"Limit":{"name":"limit","in":"query","description":"Maximum number of results to return (capped at 500)","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":500}}},"schemas":{"HoldingsResponse":{"type":"object","required":["holdings","page_info"],"properties":{"holdings":{"type":"array","items":{"$ref":"#/components/schemas/Holding"}},"page_info":{"$ref":"#/components/schemas/PageInfo"}}},"Holding":{"type":"object","required":["id","chain_id","chain","block_number","block_timestamp","asset_address","wallet_address","via_proxy","snapshot_mode"],"properties":{"id":{"type":"string","description":"Unique identifier for the holding"},"chain_id":{"type":"integer","description":"Blockchain network ID"},"chain":{"type":"string","description":"Blockchain network name"},"block_number":{"type":"string","description":"Block number at snapshot time"},"block_timestamp":{"type":"string","format":"date-time","description":"Block timestamp (ISO 8601)"},"asset_address":{"type":"string","description":"Token contract address"},"wallet_address":{"type":"string","description":"Owner wallet address"},"via_proxy":{"type":"string","description":"Proxy contract address (0x00 if none)"},"asset_decimals":{"type":"integer","nullable":true,"description":"Token decimals"},"asset_symbol":{"type":"string","nullable":true,"description":"Token symbol"},"asset_name":{"type":"string","nullable":true,"description":"Token name"},"asset_balance_wei":{"type":"string","nullable":true,"description":"Balance in smallest unit"},"asset_value_usd":{"type":"number","format":"double","nullable":true,"description":"USD value of balance"},"price_usd":{"type":"number","format":"double","nullable":true,"description":"Token price in USD"},"oracle_price_usd":{"type":"number","format":"double","nullable":true,"description":"Oracle-based price in USD"},"snapshot_mode":{"type":"string","enum":["interaction","daily","hourly","harmonized"],"description":"How the snapshot was captured"},"interaction_type":{"type":"string","nullable":true,"description":"Type of interaction if snapshot_mode is 'interaction'"},"interaction_tx_hash":{"type":"string","nullable":true,"description":"Transaction hash if snapshot_mode is 'interaction'"},"interaction_delta_asset_balance_wei":{"type":"string","nullable":true,"description":"Balance change from interaction"},"interaction_delta_asset_value_usd":{"type":"number","format":"double","nullable":true,"description":"USD value change from interaction"},"value_roi_pct":{"type":"number","format":"double","nullable":true,"description":"Return on investment (percentage)"},"value_apr_pct":{"type":"number","format":"double","nullable":true,"description":"Annual percentage rate"},"balance_roi_pct":{"type":"number","format":"double","nullable":true,"description":"Balance-based ROI (percentage)"},"balance_apr_pct":{"type":"number","format":"double","nullable":true,"description":"Balance-based APR"},"capital_basis_usd":{"type":"number","format":"double","nullable":true,"description":"Initial capital invested (USD)"},"capital_basis_wei":{"type":"string","nullable":true,"description":"Initial capital invested (wei)"},"realized_pnl_wei":{"type":"string","nullable":true,"description":"Realized profit/loss"},"realized_pnl_usd":{"type":"number","format":"double","nullable":true,"description":"Realized profit/loss in USD"},"unrealized_pnl_wei":{"type":"string","nullable":true,"description":"Unrealized profit/loss"},"unrealized_pnl_usd":{"type":"number","format":"double","nullable":true,"description":"Unrealized profit/loss in USD"},"cumulative_capital_added_usd":{"type":"number","format":"double","nullable":true,"description":"Total capital added over time (USD)"},"cumulative_capital_removed_usd":{"type":"number","format":"double","nullable":true,"description":"Total capital removed over time (USD)"},"cumulative_capital_added_wei":{"type":"string","nullable":true,"description":"Total capital added over time"},"cumulative_capital_removed_wei":{"type":"string","nullable":true,"description":"Total capital removed over time"}}},"PageInfo":{"type":"object","required":["has_more"],"properties":{"has_more":{"type":"boolean","description":"Whether more results are available"},"next_cursor":{"type":"string","nullable":true,"description":"Cursor for fetching next page (ISO 8601 timestamp)"}}},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"integer","description":"HTTP status code"}}}},"responses":{"BadRequest":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Not Found - No data found matching the criteria","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/holdings":{"get":{"tags":["Holdings"],"summary":"Get Holdings","description":"Retrieve token holdings data across organizations, wallets and chains.\nHoldings represent direct token balances held by wallets, excluding DeFi protocol positions.\n\nSupports filtering by wallet, chain, time range, and asset address.\n","operationId":"getHoldings","parameters":[{"$ref":"#/components/parameters/ChainId"},{"$ref":"#/components/parameters/Chain"},{"$ref":"#/components/parameters/Wallet"},{"$ref":"#/components/parameters/FromDate"},{"$ref":"#/components/parameters/ToDate"},{"$ref":"#/components/parameters/FromBlock"},{"$ref":"#/components/parameters/ToBlock"},{"$ref":"#/components/parameters/ViaProxy"},{"$ref":"#/components/parameters/SnapshotMode"},{"$ref":"#/components/parameters/NextCursor"},{"$ref":"#/components/parameters/Limit"},{"name":"holding_id","in":"query","description":"Unique identifier for a specific holding","required":false,"schema":{"type":"string"}},{"name":"asset_address","in":"query","description":"Token contract address","required":false,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"validate","in":"query","description":"Enable data quality validation (returns only WARNINGS)","required":false,"schema":{"type":"string","enum":["true","1"]}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HoldingsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```