> ## Documentation Index
> Fetch the complete documentation index at: https://docs.allium.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch DeFi Positions

> Retrieve DeFi positions for a wallet across multiple protocols and chains

## Position Types

The response contains a flat array of positions in `items`. Each position has a `position_type` discriminator:

* **`LP`** — Liquidity pool positions (Uniswap V2/V3/V4, PancakeSwap V3, Raydium CLMM, Meteora DLMM)
* **`lending`** — Lending/borrowing positions (Aave V3, Compound V3)
* **`staked`** — Staking positions (Lido, Hyperliquid, etc.)
* **`regular`** — Simple token holdings (Solana balances, Hyperliquid spot)
* **`perps`** — Perpetual futures positions (Hyperliquid)

## Supported Chains

| Chain                                                                                                                                                                                               | Chain ID      | Status |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------ |
| <img src="https://icons.llamao.fi/icons/chains/rsz_arbitrum.jpg" alt="Arbitrum" width="20" height="20" style={{display: "inline", verticalAlign: "middle", marginRight: "6px"}} />Arbitrum          | `arbitrum`    | ✅ Live |
| <img src="https://icons.llamao.fi/icons/chains/rsz_avalanche.jpg" alt="Avalanche" width="20" height="20" style={{display: "inline", verticalAlign: "middle", marginRight: "6px"}} />Avalanche       | `avalanche`   | ✅ Live |
| <img src="https://icons.llamao.fi/icons/chains/rsz_base.jpg" alt="Base" width="20" height="20" style={{display: "inline", verticalAlign: "middle", marginRight: "6px"}} />Base                      | `base`        | ✅ Live |
| <img src="https://icons.llamao.fi/icons/chains/rsz_blast.jpg" alt="Blast" width="20" height="20" style={{display: "inline", verticalAlign: "middle", marginRight: "6px"}} />Blast                   | `blast`       | ✅ Live |
| <img src="https://icons.llamao.fi/icons/chains/rsz_binance.jpg" alt="BSC" width="20" height="20" style={{display: "inline", verticalAlign: "middle", marginRight: "6px"}} />BSC                     | `bsc`         | ✅ Live |
| <img src="https://icons.llamao.fi/icons/chains/rsz_celo.jpg" alt="Celo" width="20" height="20" style={{display: "inline", verticalAlign: "middle", marginRight: "6px"}} />Celo                      | `celo`        | ✅ Live |
| <img src="https://icons.llamao.fi/icons/chains/rsz_ethereum.jpg" alt="Ethereum" width="20" height="20" style={{display: "inline", verticalAlign: "middle", marginRight: "6px"}} />Ethereum          | `ethereum`    | ✅ Live |
| <img src="https://icons.llamao.fi/icons/chains/rsz_hyperliquid.jpg" alt="Hyperliquid" width="20" height="20" style={{display: "inline", verticalAlign: "middle", marginRight: "6px"}} />Hyperliquid | `hyperliquid` | ✅ Live |
| <img src="https://icons.llamao.fi/icons/chains/rsz_megaeth.jpg" alt="MegaETH" width="20" height="20" style={{display: "inline", verticalAlign: "middle", marginRight: "6px"}} />MegaETH             | `megaeth`     | ✅ Live |
| <img src="https://icons.llamao.fi/icons/chains/rsz_monad.jpg" alt="Monad" width="20" height="20" style={{display: "inline", verticalAlign: "middle", marginRight: "6px"}} />Monad                   | `monad`       | ✅ Live |
| <img src="https://icons.llamao.fi/icons/chains/rsz_optimism.jpg" alt="Optimism" width="20" height="20" style={{display: "inline", verticalAlign: "middle", marginRight: "6px"}} />Optimism          | `optimism`    | ✅ Live |
| <img src="https://icons.llamao.fi/icons/chains/rsz_plasma.jpg" alt="Plasma" width="20" height="20" style={{display: "inline", verticalAlign: "middle", marginRight: "6px"}} />Plasma                | `plasma`      | ✅ Live |
| <img src="https://icons.llamao.fi/icons/chains/rsz_polygon.jpg" alt="Polygon" width="20" height="20" style={{display: "inline", verticalAlign: "middle", marginRight: "6px"}} />Polygon             | `polygon`     | ✅ Live |
| <img src="https://icons.llamao.fi/icons/chains/rsz_solana.jpg" alt="Solana" width="20" height="20" style={{display: "inline", verticalAlign: "middle", marginRight: "6px"}} />Solana                | `solana`      | ✅ Live |
| <img src="https://icons.llamao.fi/icons/chains/rsz_soneium.jpg" alt="Soneium" width="20" height="20" style={{display: "inline", verticalAlign: "middle", marginRight: "6px"}} />Soneium             | `soneium`     | ✅ Live |
| <img src="https://icons.llamao.fi/icons/chains/rsz_unichain.jpg" alt="Unichain" width="20" height="20" style={{display: "inline", verticalAlign: "middle", marginRight: "6px"}} />Unichain          | `unichain`    | ✅ Live |
| <img src="https://icons.llamao.fi/icons/chains/rsz_world chain.jpg" alt="World Chain" width="20" height="20" style={{display: "inline", verticalAlign: "middle", marginRight: "6px"}} />World Chain | `worldchain`  | ✅ Live |
| <img src="https://icons.llamao.fi/icons/chains/rsz_x layer.jpg" alt="X Layer" width="20" height="20" style={{display: "inline", verticalAlign: "middle", marginRight: "6px"}} />X Layer             | `x_layer`     | ✅ Live |
| <img src="https://icons.llamao.fi/icons/chains/rsz_zksync era.jpg" alt="zkSync" width="20" height="20" style={{display: "inline", verticalAlign: "middle", marginRight: "6px"}} />zkSync            | `zksync`      | ✅ Live |
| <img src="https://icons.llamao.fi/icons/chains/rsz_zora.jpg" alt="Zora" width="20" height="20" style={{display: "inline", verticalAlign: "middle", marginRight: "6px"}} />Zora                      | `zora`        | ✅ Live |

## Important Notes

* USD value fields (`total_value_usd`, `token0_amount_usd`, `staked_amount_usd`, etc.) may return `null` when price data is temporarily unavailable
* Positions are sorted by type priority (lending > LP > staked > regular), then by USD value descending
* Each entry in the request array is an address/chain pair — to query the same address on multiple chains, include separate entries for each chain
* Use the returned `cursor` query parameter to paginate through large result sets


## OpenAPI

````yaml /_openapi/wallet-api.json POST /api/v1/developer/wallet/positions
openapi: 3.1.0
info:
  title: Allium API
  version: 0.1.0
servers:
  - url: https://api.allium.so
security: []
paths:
  /api/v1/developer/wallet/positions:
    post:
      tags:
        - WALLET
        - DEVELOPER
      summary: Wallet DeFi Positions
      description: Get DeFi positions (LP and lending) for up to 5 wallet addresses.
      operationId: get_wallet_positions_api_v1_developer_wallet_positions_post
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            exclusiveMinimum: 0
            description: Max number of positions returned. Default is 25.
            default: 25
            title: Limit
          description: Max number of positions returned. Default is 25.
        - name: cursor
          in: query
          required: false
          schema:
            description: Cursor to request the next page of results.
            title: Cursor
            type: string
          description: Cursor to request the next page of results.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/PayloadAddress'
              minItems: 1
              maxItems: 5
              description: List of chain+addresses to get positions for.
              title: Payload
            example:
              - chain: solana
                address: 125Z6k4ZAxsgdG7JxrKZpwbcS1rxqpAeqM9GSCKd66Wp
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletPositionsEnvelope'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyBearer: []
components:
  schemas:
    PayloadAddress:
      properties:
        chain:
          type: string
          title: Chain
          description: Lowercase chain name
        address:
          type: string
          title: Address
          description: Wallet address
      type: object
      required:
        - chain
        - address
      title: PayloadAddress
      examples:
        - address: '0xab16781a13fe343a275f4bb5c883a64ceda52917'
          chain: ethereum
        - address: 125Z6k4ZAxsgdG7JxrKZpwbcS1rxqpAeqM9GSCKd66Wp
          chain: solana
    WalletPositionsEnvelope:
      properties:
        items:
          items:
            anyOf:
              - $ref: '#/components/schemas/LPPosition'
              - $ref: '#/components/schemas/LendingPosition'
              - $ref: '#/components/schemas/VaultPosition'
              - $ref: '#/components/schemas/StakedPosition'
              - $ref: '#/components/schemas/PerpPosition'
              - $ref: '#/components/schemas/RegularPosition'
          type: array
          title: Items
          description: List of DeFi positions across all requested wallets
        cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Cursor
          description: Pagination cursor for the next page of results
        total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total
          description: Total number of positions across all pages
      type: object
      required:
        - items
      title: WalletPositionsEnvelope
      description: Response envelope for wallet positions with pagination support.
      examples:
        - cursor: eyJwYWdlIjogMn0=
          items:
            - address: '0xab16781a13fe343a275f4bb5c883a64ceda52917'
              chain: ethereum
              fee_tier: '500'
              in_range: true
              pool_address: '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640'
              position_id: uniswap_v3-ethereum-637818
              position_type: LP
              protocol: uniswap_v3
              token0:
                address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
                chain: ethereum
                decimals: 6
                info:
                  name: USD Coin
                  symbol: USDC
                object: token
                type: evm_erc20
              token0_amount: '2100.543210'
              token0_amount_usd: '2100.54'
              token1:
                address: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2'
                chain: ethereum
                decimals: 18
                info:
                  name: Wrapped Ether
                  symbol: WETH
                object: token
                type: evm_erc20
              token1_amount: '1.234567890123456789'
              token1_amount_usd: '2421.33'
              total_value_usd: '4521.87'
            - address: '0xab16781a13fe343a275f4bb5c883a64ceda52917'
              borrows:
                - amount: '3500.000000'
                  amount_usd: '3500.00'
                  token:
                    address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
                    chain: ethereum
                    decimals: 6
                    info:
                      name: USD Coin
                      symbol: USDC
                    object: token
                    type: evm_erc20
              chain: ethereum
              collateral: []
              health_factor: '1.85'
              pool_address: '0x87870bca3f3fd6335c3f4ce8392d69350b4fa4e2'
              position_id: aave_v3-ethereum-0xab16781a13fe343a275f4bb5c883a64ceda52917
              position_type: lending
              protocol: aave_v3
              supplies:
                - amount: '5.234567890123456789'
                  amount_usd: '10250.32'
                  token:
                    address: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2'
                    chain: ethereum
                    decimals: 18
                    info:
                      name: Wrapped Ether
                      symbol: WETH
                    object: token
                    type: evm_erc20
              total_value_usd: '15230.45'
          total: 5
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    LPPosition:
      properties:
        chain:
          type: string
          title: Chain
          description: Lowercase chain name
        address:
          type: string
          title: Address
          description: Wallet address that holds this position
        position_id:
          type: string
          title: Position Id
          description: Unique identifier for the position
        protocol:
          type: string
          title: Protocol
          description: Protocol name (e.g. uniswap-v3, aave-v3)
        total_value_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Total Value Usd
          description: Total USD value of the position
        position_type:
          type: string
          const: LP
          title: Position Type
          default: LP
        pool_address:
          type: string
          title: Pool Address
          description: Pool contract address
        fee_tier:
          anyOf:
            - type: string
            - type: 'null'
          title: Fee Tier
          description: Pool fee tier (e.g. 0.3%)
        in_range:
          anyOf:
            - type: boolean
            - type: 'null'
          title: In Range
          description: Whether the position is within the active price range
        token0:
          $ref: '#/components/schemas/Token'
          description: First token in the pool pair
        token1:
          $ref: '#/components/schemas/Token'
          description: Second token in the pool pair
        token0_amount:
          type: string
          title: Token0 Amount
          description: Amount of token0 in the position (human-readable decimal string)
        token1_amount:
          type: string
          title: Token1 Amount
          description: Amount of token1 in the position (human-readable decimal string)
        token0_amount_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Token0 Amount Usd
          description: USD value of token0 amount
        token1_amount_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Token1 Amount Usd
          description: USD value of token1 amount
        unclaimed_fees_token0:
          anyOf:
            - type: string
            - type: 'null'
          title: Unclaimed Fees Token0
          description: Unclaimed fee amount in token0
        unclaimed_fees_token1:
          anyOf:
            - type: string
            - type: 'null'
          title: Unclaimed Fees Token1
          description: Unclaimed fee amount in token1
        unclaimed_fees_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Unclaimed Fees Usd
          description: Total unclaimed fees in USD
      type: object
      required:
        - chain
        - address
        - position_id
        - protocol
        - pool_address
        - token0
        - token1
        - token0_amount
        - token1_amount
      title: LPPosition
      description: >-
        Liquidity provider position (e.g., Uniswap V3, Raydium CLMM, Meteora
        DLMM).

        Concentrated or standard AMM positions.
      examples:
        - address: '0xab16781a13fe343a275f4bb5c883a64ceda52917'
          chain: ethereum
          fee_tier: '500'
          in_range: true
          pool_address: '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640'
          position_id: uniswap_v3-ethereum-637818
          position_type: LP
          protocol: uniswap_v3
          token0:
            address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
            chain: ethereum
            decimals: 6
            info:
              name: USD Coin
              symbol: USDC
            object: token
            type: evm_erc20
          token0_amount: '2100.543210'
          token0_amount_usd: '2100.54'
          token1:
            address: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2'
            chain: ethereum
            decimals: 18
            info:
              name: Wrapped Ether
              symbol: WETH
            object: token
            type: evm_erc20
          token1_amount: '1.234567890123456789'
          token1_amount_usd: '2421.33'
          total_value_usd: '4521.87'
          unclaimed_fees_token0: '3.210000'
          unclaimed_fees_token1: '0.001234567890123456'
          unclaimed_fees_usd: '5.63'
    LendingPosition:
      properties:
        chain:
          type: string
          title: Chain
          description: Lowercase chain name
        address:
          type: string
          title: Address
          description: Wallet address that holds this position
        position_id:
          type: string
          title: Position Id
          description: Unique identifier for the position
        protocol:
          type: string
          title: Protocol
          description: Protocol name (e.g. uniswap-v3, aave-v3)
        total_value_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Total Value Usd
          description: Total USD value of the position
        position_type:
          type: string
          const: lending
          title: Position Type
          default: lending
        pool_address:
          type: string
          title: Pool Address
          description: Lending pool contract address
        supplies:
          items:
            $ref: '#/components/schemas/LendingAsset'
          type: array
          title: Supplies
          description: Assets supplied to the pool
        borrows:
          items:
            $ref: '#/components/schemas/LendingAsset'
          type: array
          title: Borrows
          description: Assets borrowed from the pool
        collateral:
          items:
            $ref: '#/components/schemas/LendingAsset'
          type: array
          title: Collateral
          description: Assets posted as collateral
        health_factor:
          anyOf:
            - type: string
            - type: 'null'
          title: Health Factor
          description: Position health factor (below 1.0 is liquidatable)
      type: object
      required:
        - chain
        - address
        - position_id
        - protocol
        - pool_address
        - supplies
        - borrows
        - collateral
      title: LendingPosition
      description: Lending/borrowing position (e.g., Aave, Compound, Kamino).
      examples:
        - address: '0xab16781a13fe343a275f4bb5c883a64ceda52917'
          borrows:
            - amount: '3500.000000'
              amount_usd: '3500.00'
              token:
                address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
                chain: ethereum
                decimals: 6
                info:
                  name: USD Coin
                  symbol: USDC
                object: token
                type: evm_erc20
          chain: ethereum
          collateral: []
          health_factor: '1.85'
          pool_address: '0x87870bca3f3fd6335c3f4ce8392d69350b4fa4e2'
          position_id: aave_v3-ethereum-0xab16781a13fe343a275f4bb5c883a64ceda52917
          position_type: lending
          protocol: aave_v3
          supplies:
            - amount: '5.234567890123456789'
              amount_usd: '10250.32'
              token:
                address: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2'
                chain: ethereum
                decimals: 18
                info:
                  name: Wrapped Ether
                  symbol: WETH
                object: token
                type: evm_erc20
          total_value_usd: '15230.45'
    VaultPosition:
      properties:
        chain:
          type: string
          title: Chain
          description: Lowercase chain name
        address:
          type: string
          title: Address
          description: Wallet address that holds this position
        position_id:
          type: string
          title: Position Id
          description: Unique identifier for the position
        protocol:
          type: string
          title: Protocol
          description: Protocol name (e.g. uniswap-v3, aave-v3)
        total_value_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Total Value Usd
          description: Total USD value of the position
        position_type:
          type: string
          const: vault
          title: Position Type
          default: vault
        pool_address:
          type: string
          title: Pool Address
          description: Vault/pool account address
        share_token:
          $ref: '#/components/schemas/Token'
          description: Share token (cToken, JLP, etc.)
        share_balance:
          type: string
          title: Share Balance
          description: User's share token balance (human-readable decimal string)
        total_shares:
          type: string
          title: Total Shares
          description: Total share tokens outstanding (human-readable decimal string)
        underlying_assets:
          items:
            $ref: '#/components/schemas/LendingAsset'
          type: array
          title: Underlying Assets
          description: Vault's underlying assets with user's pro-rata share
      type: object
      required:
        - chain
        - address
        - position_id
        - protocol
        - pool_address
        - share_token
        - share_balance
        - total_shares
        - underlying_assets
      title: VaultPosition
      description: >-
        Vault/pool share position (e.g., Kamino strategy vaults, Jupiter LP).

        Users hold share tokens representing proportional claims on
        vault-managed assets.
      examples:
        - address: 3SNEjesH9gNacn2haLcF5W8zYq2Gy98GA3xTeQDpvtEa
          chain: solana
          pool_address: 5BUwFW4nRbftYTDMbgxykoFWqWHPzahFSNAaaaJtVKsq
          position_id: jupiter-lp_5BUwFW4n
          position_type: vault
          protocol: jupiter-lp
          share_balance: '953.316'
          share_token:
            address: 27G8MtK7VtTcCHkpASjSDdkWWYfoqT6ggEuKidVJidD4
            chain: solana
            decimals: 6
            info:
              name: JLP
              symbol: JLP
            object: token
            type: sol_spl
          total_shares: '1500000000.0'
          total_value_usd: '1250.00'
          underlying_assets:
            - amount: '500.123'
              amount_usd: '500.12'
              token:
                address: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
                chain: solana
                decimals: 6
                info:
                  name: USD Coin
                  symbol: USDC
                object: token
                type: sol_spl
            - amount: '3.456'
              amount_usd: '750.00'
              token:
                address: So11111111111111111111111111111111111111112
                chain: solana
                decimals: 9
                info:
                  name: Wrapped SOL
                  symbol: SOL
                object: token
                type: sol_spl
    StakedPosition:
      properties:
        chain:
          type: string
          title: Chain
          description: Lowercase chain name
        address:
          type: string
          title: Address
          description: Wallet address that holds this position
        position_id:
          type: string
          title: Position Id
          description: Unique identifier for the position
        protocol:
          type: string
          title: Protocol
          description: Protocol name (e.g. uniswap-v3, aave-v3)
        total_value_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Total Value Usd
          description: Total USD value of the position
        position_type:
          type: string
          const: staked
          title: Position Type
          default: staked
        pool_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Pool Address
          description: Staking pool contract address
        staked_token:
          $ref: '#/components/schemas/Token'
          description: Token that is staked
        staked_amount:
          type: string
          title: Staked Amount
          description: Amount staked (human-readable decimal string)
        staked_amount_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Staked Amount Usd
          description: USD value of staked amount
        rewards_token:
          anyOf:
            - $ref: '#/components/schemas/Token'
            - type: 'null'
          description: Token in which rewards are paid out
        unclaimed_rewards:
          anyOf:
            - type: string
            - type: 'null'
          title: Unclaimed Rewards
          description: Unclaimed reward amount
        unclaimed_rewards_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Unclaimed Rewards Usd
          description: USD value of unclaimed rewards
        rewards_additive:
          type: boolean
          title: Rewards Additive
          description: >-
            Whether unclaimed_rewards_usd is additive to total_value_usd. False
            for LSTs where the staked token price already captures underlying
            value.
          default: true
        apy:
          anyOf:
            - type: string
            - type: 'null'
          title: Apy
          description: Annual percentage yield
      type: object
      required:
        - chain
        - address
        - position_id
        - protocol
        - staked_token
        - staked_amount
      title: StakedPosition
      description: |-
        Staked/held DeFi position (e.g., staking pools, liquid staking, vaults).
        Simpler than LP - single token staked with optional rewards.
      examples:
        - address: '0xab16781a13fe343a275f4bb5c883a64ceda52917'
          apy: '3.2'
          chain: ethereum
          pool_address: '0xae7ab96520de3a18e5e111b5eaab095312d7fe84'
          position_id: lido-ethereum-0xab16781a13fe343a275f4bb5c883a64ceda52917
          position_type: staked
          protocol: lido
          staked_amount: '5.012345678901234567'
          staked_amount_usd: '9812.50'
          staked_token:
            address: '0xae7ab96520de3a18e5e111b5eaab095312d7fe84'
            chain: ethereum
            decimals: 18
            info:
              name: Lido Staked Ether
              symbol: stETH
            object: token
            type: evm_erc20
          total_value_usd: '9812.50'
    PerpPosition:
      properties:
        chain:
          type: string
          title: Chain
          description: Lowercase chain name
        address:
          type: string
          title: Address
          description: Wallet address that holds this position
        position_id:
          type: string
          title: Position Id
          description: Unique identifier for the position
        protocol:
          type: string
          title: Protocol
          description: Protocol name (e.g. uniswap-v3, aave-v3)
        total_value_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Total Value Usd
          description: Total USD value of the position
        position_type:
          type: string
          const: perp
          title: Position Type
          default: perp
        coin:
          type: string
          title: Coin
          description: Traded asset symbol (e.g. BTC, ETH)
        size:
          type: string
          title: Size
          description: Position size in units of the base asset
        entry_price:
          type: string
          title: Entry Price
          description: Average entry price in USD
        mark_price:
          anyOf:
            - type: string
            - type: 'null'
          title: Mark Price
          description: Current mark price in USD
        unrealized_pnl:
          type: string
          title: Unrealized Pnl
          description: Unrealized profit/loss in USD
        leverage_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Leverage Type
          description: Leverage type (e.g. cross, isolated)
        leverage_value:
          anyOf:
            - type: string
            - type: 'null'
          title: Leverage Value
          description: Leverage multiplier (e.g. 10x)
        liquidation_price:
          anyOf:
            - type: string
            - type: 'null'
          title: Liquidation Price
          description: Price at which the position will be liquidated
        margin_used:
          anyOf:
            - type: string
            - type: 'null'
          title: Margin Used
          description: Margin used by this position in USD
        return_on_equity:
          anyOf:
            - type: string
            - type: 'null'
          title: Return On Equity
          description: Return on equity as a decimal (e.g. 0.05 = 5%)
      type: object
      required:
        - chain
        - address
        - position_id
        - protocol
        - coin
        - size
        - entry_price
        - unrealized_pnl
      title: PerpPosition
      description: Perpetual futures position (e.g., Hyperliquid, dYdX).
      examples:
        - address: '0xab16781a13fe343a275f4bb5c883a64ceda52917'
          chain: hyperliquid
          coin: ETH
          entry_price: '1950.00'
          leverage_type: cross
          leverage_value: '5'
          liquidation_price: '1620.00'
          margin_used: '975.00'
          mark_price: '2030.00'
          position_id: hyperliquid-perp-ETH
          position_type: perp
          protocol: hyperliquid
          return_on_equity: '0.2051'
          size: '2.5'
          total_value_usd: '5200.00'
          unrealized_pnl: '200.00'
    RegularPosition:
      properties:
        position_type:
          type: string
          const: regular
          title: Position Type
          default: regular
        chain:
          type: string
          title: Chain
          description: Lowercase chain name
        address:
          type: string
          title: Address
          description: Wallet address
        token:
          $ref: '#/components/schemas/Token'
          description: Token details
        amount:
          type: string
          title: Amount
          description: Token balance (human-readable decimal string)
        amount_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Amount Usd
          description: USD value of the balance
        block_timestamp:
          anyOf:
            - type: string
            - type: 'null'
          title: Block Timestamp
        block_number:
          anyOf:
            - type: integer
            - type: 'null'
          title: Block Number
      type: object
      required:
        - chain
        - address
        - token
        - amount
      title: RegularPosition
      description: |-
        Regular token holding - what tokens a wallet holds and in what amounts.
        Used for chains like Solana where we just want to show current balances.
      examples:
        - address: 125Z6k4ZAxsgdG7JxrKZpwbcS1rxqpAeqM9GSCKd66Wp
          amount: '0.00298584'
          amount_usd: '0.25811587191266855'
          chain: solana
          position_type: regular
          token:
            address: So11111111111111111111111111111111111111112
            chain: solana
            decimals: 9
            info:
              name: Solana
              symbol: SOL
            object: token
            price: 86.4466521691278
            type: native
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    Token:
      properties:
        object:
          type: string
          const: token
          title: Object
          default: token
        chain:
          type: string
          title: Chain
          description: Lowercase chain name
        address:
          type: string
          title: Address
          description: Token contract address
        type:
          anyOf:
            - type: string
              enum:
                - native
                - non_native
                - evm_erc20
                - evm_erc721
                - evm_erc1155
                - sol_spl
                - sui_token
                - near_nep141
                - near_nep245
                - stellar_classic
                - stellar_sac
                - stellar_wasm
            - type: 'null'
          title: Type
          description: >-
            Token standard type: evm_erc20/evm_erc721/evm_erc1155 (EVMs),
            sol_spl (Solana), sui_token (Sui), near_nep141/near_nep245 (Near),
            stellar_classic/stellar_sac/stellar_wasm (Stellar), or native (All)
        price:
          anyOf:
            - type: number
            - type: 'null'
          title: Price
          description: Current price (USD)
        decimals:
          anyOf:
            - type: integer
            - type: 'null'
          title: Decimals
          description: Token decimal places
        info:
          anyOf:
            - $ref: >-
                #/components/schemas/api_server__app__core__models__token__TokenInfo
            - type: 'null'
          description: Token name and symbol
        attributes:
          anyOf:
            - $ref: '#/components/schemas/TokenAttributes'
            - type: 'null'
          description: Token market attributes
      type: object
      required:
        - chain
        - address
      title: Token
    LendingAsset:
      properties:
        token:
          $ref: '#/components/schemas/Token'
          description: Token details
        amount:
          type: string
          title: Amount
          description: Token amount (human-readable decimal string)
        amount_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Amount Usd
          description: USD value of the amount
      type: object
      required:
        - token
        - amount
      title: LendingAsset
      description: An asset in a lending position (supply, borrow, or collateral).
    api_server__app__core__models__token__TokenInfo:
      properties:
        name:
          type: string
          title: Name
          description: Token name
        symbol:
          type: string
          title: Symbol
          description: Token symbol
      type: object
      required:
        - name
        - symbol
      title: TokenInfo
    TokenAttributes:
      properties:
        total_liquidity_usd:
          anyOf:
            - $ref: '#/components/schemas/LiquidityResults'
            - type: 'null'
          description: >-
            Liquidity data: {'amount': number} when available, or {'details':
            'LIQUIDITY_TOO_HIGH'} when limit exceeded
        price_diff_1d:
          anyOf:
            - type: number
            - type: 'null'
          title: Price Diff 1D
          description: Price change (USD) over last 24h
        price_diff_pct_1d:
          anyOf:
            - type: number
            - type: 'null'
          title: Price Diff Pct 1D
          description: Price change (%) over last 24h
        price_diff_1h:
          anyOf:
            - type: number
            - type: 'null'
          title: Price Diff 1H
          description: Price change (USD) over last 1h
        price_diff_pct_1h:
          anyOf:
            - type: number
            - type: 'null'
          title: Price Diff Pct 1H
          description: Price change (%) over last 1h
        total_supply:
          anyOf:
            - type: number
            - type: 'null'
          title: Total Supply
          description: Total token supply
        fully_diluted_valuation_usd:
          anyOf:
            - type: number
            - type: 'null'
          title: Fully Diluted Valuation Usd
          description: Fully diluted valuation (USD)
        volume_1h:
          anyOf:
            - type: number
            - type: 'null'
          title: Volume 1H
          description: Trading volume over last 1h
        volume_1d:
          anyOf:
            - type: number
            - type: 'null'
          title: Volume 1D
          description: Trading volume over last 24h
        volume_usd_1h:
          anyOf:
            - type: number
            - type: 'null'
          title: Volume Usd 1H
          description: Trading volume (USD) over last 1h
        volume_usd_1d:
          anyOf:
            - type: number
            - type: 'null'
          title: Volume Usd 1D
          description: Trading volume (USD) over last 24h
        volume_24h:
          anyOf:
            - type: number
            - type: 'null'
          title: Volume 24H
          description: Trading volume over last 24h
        volume_usd_24h:
          anyOf:
            - type: number
            - type: 'null'
          title: Volume Usd 24H
          description: Trading volume (USD) over last 24h
        trade_count_1h:
          anyOf:
            - type: integer
            - type: 'null'
          title: Trade Count 1H
          description: Trade count over last 1h
        trade_count_1d:
          anyOf:
            - type: integer
            - type: 'null'
          title: Trade Count 1D
          description: Trade count over last 24h
        all_time_high:
          anyOf:
            - type: number
            - type: 'null'
          title: All Time High
          description: All-time high price (USD)
        all_time_low:
          anyOf:
            - type: number
            - type: 'null'
          title: All Time Low
          description: All-time low price (USD)
        image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Url
          description: Token logo URL
        token_creation_time:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Token Creation Time
          description: Token creation timestamp (UTC)
        holders_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Holders Count
          description: Number of token holders
        stellar_fields:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Stellar Fields
          description: Stellar-specific metadata
      type: object
      title: TokenAttributes
    LiquidityResults:
      properties:
        amount:
          anyOf:
            - type: number
            - type: 'null'
          title: Amount
          description: Liquidity amount (USD)
        details:
          anyOf:
            - type: string
            - type: 'null'
          title: Details
          description: Status when amount unavailable (e.g. LIQUIDITY_TOO_HIGH)
      type: object
      title: LiquidityResults
  securitySchemes:
    APIKeyBearer:
      type: apiKey
      in: header
      name: X-API-KEY

````