---
title: "List withdrawable positions"
method: GET
path: "/positions/{address}"
tags: ["Utilities"]
---

# List withdrawable positions

`GET /positions/{address}`

## Request

- Base URL: `https://v1.orchestrator.rhinestone.dev/deposit-processor`
- URL: `https://v1.orchestrator.rhinestone.dev/deposit-processor/positions/{address}`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/rhinestonewtf/apis/deposit-service-api/docs/positions/:address/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns DeFi positions and the amounts currently available to withdraw.

## Path parameters

- `address` string, required: EVM address holding the DeFi positions

## Headers

- `x-api-key` string: API key for authentication
- `x-api-version` string: API version identifier (e.g. "2026-04.amazon"). Optional today, will become required in a future release.

## Response `200`

Normalised DeFi positions

- PositionsResponse
  - `positions` object[], required
    - `venue` 'aave', required
    - `kind` 'lending', required
    - `market` object, required: Positions are keyed by market, not chain — Ethereum alone hosts four Aave v3 markets with distinct pools and risk params.
      - `address` string, required
      - `name` string, required
    - `chain` string, required: CAIP-2 chain id
    - `asset` object, required
      - `address` string, required
      - `symbol` string, required
      - `decimals` number, required
    - `amount` string, required: Supplied balance in base units, accrued interest included
    - `usdValue` number, required
    - `apy` number, required
    - `isCollateral` boolean, required
    - `maxWithdrawable` string, required: Largest amount withdrawable right now, in base units. Capped so the withdraw cannot be rejected on-chain.
    - `withdrawableUsd` number, required: USD value of `maxWithdrawable` — what would actually reach the deposit address, as opposed to `usdValue`, which prices the whole holding. Display this next to an amount you offer: it is also the figure this project's deposit floor is judged against, and re-deriving it from `usdValue` needs the amount ratio taken in integer space to survive an 18-decimal balance.
    - `isFullExit` boolean, required: True when the entire supplied balance can leave in one transaction
    - `constraints` string[], required
  - `totalUsd` number, required
  - `minDepositUsd` number, required: The USD floor the withdrawn proceeds must clear for this project, resolved from the platform minimum and the project's own `minDepositUsd`. Proceeds below it are rejected on ingest after the withdrawal has already happened.
  - `failures` object[]: Present only when a venue could not be reached, so an empty `positions` list can be told apart from a failed lookup.
    - `venue` string, required
    - `reason` string, required

## Other responses

- `400`: Invalid request, unauthorized, or the project is not configured for deposits
- `401`: Authentication required or the presented credential is invalid.
- `403`: API key lacks the required deposits scope
- `503`: The account could not be read, so migratable positions cannot be determined. Retry.

## Changes

- **2026-11-06** `aa1767d704fa`: 4 info
  - the endpoint scheme security `internalProjectBearer` was added to the API
  - the endpoint scheme security `tenantApiKey` was added to the API
  - the `header` request parameter `x-api-key` became optional
  - added the non-success response with the status `401`
- **2026-09-17** `676300ac19ff`: 3 info
  - added the optional property `code` to the response with the `400` status
  - added the optional property `code` to the response with the `403` status
  - added the optional property `code` to the response with the `503` status
- **2026-09-11** `b49146029e5a`: 1 warning, 1 info
  - added the new `outside_session_scope` enum value to the `positions/items/constraints/items/` response property for the response status `200`
  - added the non-success response with the status `503`
- **2026-07-29** `7f6aae39bb48`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/rhinestonewtf/apis/deposit-service-api/changes/positions/:address/get.md)

---

[API](https://skmtc.dev/rhinestonewtf/apis/deposit-service-api.md) - [All operations](https://skmtc.dev/rhinestonewtf/apis/deposit-service-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rhinestonewtf/apis/deposit-service-api/revisions/aa1767d704fa?raw)