Positions

Query aggregated DeFi positions across organizations, wallets and chains.

Get Positions

get

Retrieve aggregated DeFi protocol positions. Positions represent interactions with DeFi protocols with net value, collateral, debt, and other metrics.

Supports filtering by wallet, chain, time range, market, and protocol.

Authorizations

ApiKeyAuth

x-api-KeystringRequired

API key for authentication

Query parameters

chain_idintegerOptional

Blockchain network ID (e.g., 1 for Ethereum mainnet, 137 for Polygon)

Example: 1

chainstringOptional

Blockchain network name (alternative to chain_id)

Example: ethereum

walletstringOptional

Wallet address to filter by

Example: 0x1234567890123456789012345678901234567890Pattern: ^0x[a-fA-F0-9]{40}$

from_datestring · date-timeOptional

Start date for time range filter (ISO 8601 format)

Example: 2024-01-01T00:00:00Z

to_datestring · date-timeOptional

End date for time range filter (ISO 8601 format)

Example: 2024-12-31T23:59:59Z

from_blockstringOptional

Start block number for filtering

Example: 18000000

to_blockstringOptional

End block number for filtering

Example: 18500000

via_proxystringOptional

Proxy contract address if interaction was through a proxy

Example: 0x0000000000000000000000000000000000000000Pattern: ^0x[a-fA-F0-9]{40}$

snapshot_modestring · enumOptional

Filter by snapshot capture mode:

• all: All snapshot types
• daily_only: Daily scheduled snapshots
• interaction_only: Event-driven snapshots on wallet interactions
• harmonized_only: Regularly scheduled harmonized snapshots

Default: allExample: allPossible values:

next_cursorstring · date-timeOptional

Pagination cursor from previous response

Example: 2024-06-15T12:00:00Z

limitinteger · min: 1 · max: 500Optional

Maximum number of results to return (capped at 500)

Default: 500Example: 100

position_idstringOptional

Unique identifier for a specific position

Example: eth_0x123...abc_0x456...def_aave_v3_0x000...000_2024-01-01T00:00:00Z

market_addressstringOptional

Protocol market/pool contract address

Example: 0x7d2768dE32b0b80b7a3454c06BdAc94A69DDc7A9Pattern: ^0x[a-fA-F0-9]{40}$

protocol_namestringOptional

Name of the DeFi protocol

Example: compound

validatestring · enumOptional

Enable data quality validation (returns only WARNINGS)

Example: truePossible values:

Responses

200

Successful response

application/json

400

Bad Request - Invalid parameters

application/json

404

Not Found - No data found matching the criteria

application/json

500

Internal Server Error

application/json

get

/positions

HTTPcURLJavaScriptPython

GET /api/positions HTTP/1.1
x-api-Key: YOUR_API_KEY
Accept: */*

{
  "positions": [
    {
      "id": "eth_0x123...abc_0x456...def_aave_v3_0x000...000_2024-01-01T00:00:00Z",
      "chain_id": 1,
      "chain": "ethereum",
      "block_number": "18500000",
      "block_timestamp": "2024-01-15T10:30:00Z",
      "market_address": "0x7d2768dE32b0b80b7a3454c06BdAc94A69DDc7A9",
      "wallet_address": "0x1234567890123456789012345678901234567890",
      "via_proxy": "0x0000000000000000000000000000000000000000",
      "protocol_name": "aave",
      "protocol_version": "v3",
      "start_timestamp": "2024-01-01T00:00:00Z",
      "end_timestamp": null,
      "value_net_usd": 5000,
      "value_collateral_usd": 10000,
      "value_debt_usd": 5000,
      "health_factor": 2.5,
      "snapshot_mode": "harmonized",
      "interaction_types": [
        "deposit",
        "borrow"
      ],
      "interaction_tx_hashs": [
        "0xabc123...",
        "0xdef456..."
      ],
      "value_roi_pct": 15.7,
      "value_apr_pct": 12.3,
      "capital_basis_usd": 10000,
      "realized_pnl_usd": 1500,
      "unrealized_pnl_usd": 500,
      "realized_balance_pnl_usd": 1200,
      "unrealized_balance_pnl_usd": 300,
      "price_effect_pnl_usd": 500,
      "cumulative_capital_added_usd": 15000,
      "cumulative_capital_removed_usd": 5000,
      "cumulative_inflow_usd": 15000,
      "cumulative_outflow_usd": 5000,
      "dtd_realized_pnl_usd": 150,
      "dtd_unrealized_pnl_usd": 75,
      "dtd_inflow_usd": 1000,
      "dtd_outflow_usd": 500,
      "mtd_realized_pnl_usd": 800,
      "mtd_unrealized_pnl_usd": 300,
      "mtd_inflow_usd": 5000,
      "mtd_outflow_usd": 2000,
      "ytd_realized_pnl_usd": 1500,
      "ytd_unrealized_pnl_usd": 500,
      "ytd_inflow_usd": 15000,
      "ytd_outflow_usd": 5000,
      "assets": [
        {
          "id": "eth_0x123...abc_0x456...def_aave_v3_0x789...ghi_0x000...000_2024-01-01T00:00:00Z",
          "chain_id": 1,
          "chain": "ethereum",
          "block_number": "18500000",
          "block_timestamp": "2024-01-15T10:30:00Z",
          "asset_address": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
          "wallet_address": "0x1234567890123456789012345678901234567890",
          "via_proxy": "0x0000000000000000000000000000000000000000",
          "type": "collateral",
          "protocol_name": "aave",
          "protocol_version": "v3",
          "asset_name": "Dai Stablecoin",
          "asset_symbol": "DAI",
          "asset_decimals": 18,
          "asset_balance_wei": "1000000000000000000000",
          "asset_value_usd": 1000.5,
          "receipt_token_address": "0x028171bCA77440897B824Ca71D1c56caC55b68A3",
          "receipt_token_name": "Aave Dai",
          "receipt_token_symbol": "aDAI",
          "receipt_token_decimals": 18,
          "receipt_token_balance_wei": "1000000000000000000000",
          "receipt_token_value_usd": 1000.5,
          "pool_address": "0x7d2768dE32b0b80b7a3454c06BdAc94A69DDc7A9",
          "market_address": "0x7d2768dE32b0b80b7a3454c06BdAc94A69DDc7A9",
          "price_usd": 1,
          "oracle_price_usd": 1,
          "snapshot_mode": "harmonized",
          "interaction_type": "deposit",
          "interaction_tx_hash": "0xabc123...",
          "interaction_delta_asset_balance_wei": "500000000000000000000",
          "interaction_delta_asset_value_usd": 500.25,
          "value_roi_pct": 12.5,
          "value_apr_pct": 8.2,
          "balance_roi_pct": 10.3,
          "balance_apr_pct": 7.5,
          "capital_basis_usd": 10000,
          "capital_basis_wei": "10000000000000000000000",
          "realized_pnl_wei": "1000000000000000000000",
          "realized_pnl_usd": 1000,
          "unrealized_pnl_wei": "250000000000000000000",
          "unrealized_pnl_usd": 250,
          "realized_balance_pnl_usd": 800,
          "unrealized_balance_pnl_usd": 200,
          "price_effect_pnl_usd": 250,
          "cumulative_capital_added_usd": 15000,
          "cumulative_capital_removed_usd": 5000,
          "cumulative_capital_added_wei": "15000000000000000000000",
          "cumulative_capital_removed_wei": "5000000000000000000000",
          "asset_unwrapping": [
            "[Circular Reference]"
          ]
        }
      ]
    }
  ],
  "page_info": {
    "has_more": true,
    "next_cursor": "2024-06-15T12:00:00Z"
  }
}