GET /wallets/:address

🔹 Get Wallet Positions

🌐 Endpoint

GET https://client.deframe.io/v1/wallets/:address

📝 Overview

Retrieve all current positions and balances for a specific wallet address across different protocols and assets.

🔑 Authentication

This API requires authentication using an API key. Include your API key in the request headers:

x-api-key: YOUR_API_KEY

📋 Path Parameters

Parameter	Type	Description	Example
address	string	Ethereum wallet address	0x1234567890123456789012345678901234567890

📦 Response

Returns a JSON object containing:

• address: The queried wallet address

• stats: Object containing position information:

  • underlying: Array of collateral positions

    • asset: Token information

      • address: Contract address

      • decimals: Number of decimals

      • symbol: Token symbol

      • name: Token name

    • balance: Balance information

      • raw: Raw balance amount

      • humanized: Human-readable balance

      • decimals: Number of decimals

    • balanceUSD: USD value of balance

    • price: Current token price

    • liquidationThreshold: Threshold for liquidation

  • debt: Array of borrowed positions

    • asset: Token information

      • address: Contract address

      • decimals: Number of decimals

      • symbol: Token symbol

      • name: Token name

    • balance: Balance information

      • raw: Raw balance amount

      • humanized: Human-readable balance

      • decimals: Number of decimals

    • balanceUSD: USD value of debt

    • borrowRate: Current borrow interest rate

  • healthFactor: Current health factor of positions

  • ltv: Current loan-to-value ratio

  • liquidationPrice: Price at which position will be liquidated

  • maxBorrowValue: Maximum additional borrowing power in USD

Example Response:

{
  "address": "0x1234567890123456789012345678901234567890",
  "stats": {
    "underlying": [
      {
        "asset": {
          "address": "0x7ceb23fd6bc0add59e62ac25578270cff1b9f619",
          "decimals": "18",
          "symbol": "WETH",
          "name": "Wrapped Ether"
        },
        "balance": {
          "raw": 19887853736379464,
          "humanized": 0.019887853736379465,
          "decimals": "18"
        },
        "balanceUSD": "51.734075045906536",
        "price": 2601.29,
        "liquidationThreshold": 0.83
      }
    ],
    "debt": [
      {
        "asset": {
          "address": "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359",
          "decimals": "6",
          "symbol": "USDC",
          "name": "USD Coin"
        },
        "balance": {
          "raw": 27090825,
          "humanized": "27.090825",
          "decimals": "6"
        },
        "balanceUSD": "27.090825",
        "borrowRate": 0.073019171761316
      }
    ],
    "healthFactor": 1.585,
    "ltv": 0.8,
    "liquidationPrice": 1641.180019997122,
    "maxBorrowValue": -5.620099685948787
  }
}

❌ Error Responses

Status Code	Description
400	Bad Request - Invalid address format
401	Unauthorized - Invalid or missing API key
404	Address not found or has no positions
429	Too many requests - Rate limit exceeded
500	Internal server error

Example Error Response:

{
  "error": {
    "code": "INVALID_ADDRESS",
    "message": "Invalid Ethereum address format"
  }
}

📝 Notes

• The response includes both collateral (underlying) and debt positions

• All monetary values are provided in both raw and humanized formats

• USD values are calculated using current market prices

• Health factor below 1 indicates risk of liquidation

• Negative maxBorrowValue indicates no additional borrowing power