Fetch DeFi Positions

Alpha Release - This endpoint is in alpha. Schema and response format may change. To request access, contact us or reach out to your account manager.

Get detailed position information for a specific wallet address, including LP positions, regular token positions, lending positions, and staking positions across supported protocols.

Request

Body Parameters

addresses

string[]

required

Addresses to get positions for. Supports both EVM addresses (0x…) and Solana addresses.Min: 1, Max: 5Example: ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"]

chains

string[]

Filter positions by specific chains.Max: 5Example: ["ethereum", "arbitrum", "solana"]Supported chains:

EVM: ethereum, arbitrum, optimism, base, polygon, avalanche, bsc
Non-EVM: solana

cursor

string

Cursor for pagination. Use the cursor value from the previous response to fetch the next page.

limit

integer

default:"50"

Limit the number of items in the response. Max: 100.

Response

Response Fields

items

array

Array of position objects. The fields present depend on the position_type.

Show Common Fields (all position types)

position_type

string

Type of position: LP, regular, lending, or staked

chain

string

Chain where the position exists

address

string

The wallet address holding the position

Show Token Object (used across position types)

chain

string

Chain of the token

address

string

Token contract address

price

number

Current token price in USD

decimals

integer

Token decimals

symbol

string

Token symbol

cursor

string

Cursor for fetching the next page of results. null if there are no more results.

Position Types

LP Positions

LP positions include liquidity pool data from protocols like Uniswap.

position_id

string

Unique identifier for the LP position (e.g., NFT token ID for Uniswap V3)

protocol

string

Protocol name (e.g., uniswap_v3)

total_value_usd

string

Total USD value of the position

pool_address

string

Address of the liquidity pool

fee_tier

string

Pool fee tier

in_range

boolean

Whether the position is currently in range (for concentrated liquidity)

token0

object

First token in the pair (Token Object)

token1

object

Second token in the pair (Token Object)

token0_amount

string

Amount of token0 in the position

token1_amount

string

Amount of token1 in the position

token0_amount_usd

string

USD value of token0 amount

token1_amount_usd

string

USD value of token1 amount

unclaimed_fees_token0

string

Unclaimed fees in token0

unclaimed_fees_token1

string

Unclaimed fees in token1

unclaimed_fees_usd

string

Total unclaimed fees in USD

Regular Positions

Regular token positions represent simple token holdings.

token

object

The token held (Token Object)

amount

string

Amount of the token held

amount_usd

string

USD value of the token amount

Lending Positions

Lending positions track supplies, borrows, and collateral on lending protocols.

position_id

string

Unique identifier for the lending position

protocol

string

Protocol name (e.g., aave_v3)

total_value_usd

string

Total USD value of the position

pool_address

string

Address of the lending pool/market

supplies

array

Supplied assets

Show Supply Object

token

object

The supplied token (Token Object)

amount

string

Supplied amount

amount_usd

string

USD value of supplied amount

borrows

array

Borrowed assets

Show Borrow Object

token

object

The borrowed token (Token Object)

amount

string

Borrowed amount

amount_usd

string

USD value of borrowed amount

collateral

array

Collateral assets

Show Collateral Object

token

object

The collateral token (Token Object)

amount

string

Collateral amount

amount_usd

string

USD value of collateral amount

health_factor

string

Health factor of the lending position

Staked Positions

Staking positions track staked assets and unclaimed rewards.

position_id

string

Unique identifier for the staking position

protocol

string

Protocol name (e.g., lido)

total_value_usd

string

Total USD value of the staked position

pool_address

string

Address of the staking contract

staked_token

object

The staked token (Token Object)

staked_amount

string

Amount of staked tokens

staked_amount_usd

string

USD value of staked amount

rewards_token

object

The rewards token (Token Object)

unclaimed_rewards

string

Amount of unclaimed rewards

unclaimed_rewards_usd

string

USD value of unclaimed rewards

apy

string

Current annual percentage yield

Examples

curl -X POST "https://api.allium.so/v1/positions" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"],
    "chains": ["ethereum", "arbitrum"],
    "limit": 50
  }'

Response Example

{
  "items": [
    {
      "position_type": "LP",
      "chain": "ethereum",
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "position_id": "604387",
      "protocol": "uniswap_v3",
      "total_value_usd": "15234.56",
      "pool_address": "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
      "fee_tier": "500",
      "in_range": true,
      "token0": {
        "chain": "ethereum",
        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "price": 1.0,
        "decimals": 6,
        "symbol": "USDC"
      },
      "token1": {
        "chain": "ethereum",
        "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "price": 3245.12,
        "decimals": 18,
        "symbol": "WETH"
      },
      "token0_amount": "5000.123456",
      "token1_amount": "1.543210987654321",
      "token0_amount_usd": "5000.12",
      "token1_amount_usd": "10234.44",
      "unclaimed_fees_token0": "12.345678",
      "unclaimed_fees_token1": "0.001234567890123",
      "unclaimed_fees_usd": "16.35"
    },
    {
      "position_type": "regular",
      "chain": "solana",
      "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "token": {
        "chain": "solana",
        "address": "So11111111111111111111111111111111111111112",
        "price": 142.35,
        "decimals": 9,
        "symbol": "SOL"
      },
      "amount": "25.123456789",
      "amount_usd": "3575.82"
    },
    {
      "position_type": "lending",
      "chain": "ethereum",
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "position_id": "aave_v3_0x1234",
      "protocol": "aave_v3",
      "total_value_usd": "42500.00",
      "pool_address": "0x87870bca3f3fd6335c3f4ce8392d69350b4fa4e2",
      "supplies": [
        {
          "token": {
            "chain": "ethereum",
            "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "price": 3245.12,
            "decimals": 18,
            "symbol": "WETH"
          },
          "amount": "10.5",
          "amount_usd": "34073.76"
        }
      ],
      "borrows": [
        {
          "token": {
            "chain": "ethereum",
            "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
            "price": 1.0,
            "decimals": 6,
            "symbol": "USDC"
          },
          "amount": "8500.00",
          "amount_usd": "8500.00"
        }
      ],
      "collateral": [
        {
          "token": {
            "chain": "ethereum",
            "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "price": 3245.12,
            "decimals": 18,
            "symbol": "WETH"
          },
          "amount": "10.5",
          "amount_usd": "34073.76"
        }
      ],
      "health_factor": "2.45"
    },
    {
      "position_type": "staked",
      "chain": "ethereum",
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "position_id": "lido_steth_0x1234",
      "protocol": "lido",
      "total_value_usd": "16225.60",
      "pool_address": "0xae7ab96520de3a18e5e111b5eaab095312d7fe84",
      "staked_token": {
        "chain": "ethereum",
        "address": "0xae7ab96520de3a18e5e111b5eaab095312d7fe84",
        "price": 3245.12,
        "decimals": 18,
        "symbol": "stETH"
      },
      "staked_amount": "5.0",
      "staked_amount_usd": "16225.60",
      "rewards_token": {
        "chain": "ethereum",
        "address": "0xae7ab96520de3a18e5e111b5eaab095312d7fe84",
        "price": 3245.12,
        "decimals": 18,
        "symbol": "stETH"
      },
      "unclaimed_rewards": "0.0123",
      "unclaimed_rewards_usd": "39.91",
      "apy": "3.2"
    }
  ],
  "cursor": "eyJvZmZzZXQiOiAyNX0="
}

Error Responses

error

object

Show Error Object

code

string

Error code

message

string

Human-readable error message

Common Errors

Status Code	Error Code	Description
400	`invalid_address`	Invalid wallet address format
400	`invalid_chain`	Unsupported chain specified
401	`unauthorized`	Missing or invalid API key
429	`rate_limit_exceeded`	Too many requests
500	`internal_error`	Internal server error

Best Practices

Batch Addresses: Query up to 5 addresses in a single request to reduce API calls
Use Chain Filters: Filter by specific chains to reduce response size
Cursor Pagination: Use the returned cursor to iterate through large result sets
Caching: Consider caching position data on your end if you don’t need realtime updates

Uniswap V3/V4 historical data backfill is in progress. Current positions are available in realtime.

Realtime API

Stream Transformation API

Explorer API

Deep Dives

Request

Body Parameters

Response

Response Fields

Position Types

LP Positions

Regular Positions

Lending Positions

Staked Positions

Examples

Response Example

Error Responses

Common Errors

Best Practices

Realtime API

Stream Transformation API

Explorer API

Deep Dives

​Request

​Body Parameters

​Response

​Response Fields

​Position Types

​LP Positions

​Regular Positions

​Lending Positions

​Staked Positions

​Examples

​Response Example

​Error Responses

​Common Errors

​Best Practices

Request

Body Parameters

Response

Response Fields

Position Types

LP Positions

Regular Positions

Lending Positions

Staked Positions

Examples

Response Example

Error Responses

Common Errors

Best Practices