> ## Documentation Index > Fetch the complete documentation index at: https://docs.groundtech.co/llms.txt > Use this file to discover all available pages before exploring further. # List portfolio wallets > Returns a cursor-paginated list of wallets for the authenticated organization. ## OpenAPI ````yaml swagger/swagger-combined.yaml GET /v2/wallets openapi: 3.0.0 info: title: Ground API description: Core API for portfolio wallets, deposits, withdrawals, and webhooks. version: 2.0.0 servers: - url: https://sandbox.groundtech.co - url: https://production.groundtech.co security: - bearerAuth: [] tags: - name: System description: System health and utility endpoints. - name: Sandbox Faucets description: Sandbox-only test token faucets. - name: Portfolio Wallets description: >- Portfolio wallets with strategy allocation, deposits, withdrawals, and yield positions. - name: Webhook Endpoints description: Webhook endpoint management for portfolio wallet notifications. paths: /v2/wallets: get: tags: - Portfolio Wallets summary: List Wallets description: >- Returns a cursor-paginated list of wallets for the authenticated organization. operationId: listWalletsV2 parameters: - name: cursor in: query required: false schema: type: string description: >- Opaque cursor from a prior response; pass it unchanged to fetch the next page (must be reused with the same filters and sort). - name: limit in: query required: false schema: type: integer default: 25 minimum: 1 maximum: 100 description: >- Maximum number of wallets to return in this response (smaller values reduce payload size and latency). - name: sort in: query required: false schema: type: string default: createdAt enum: - createdAt description: Field to sort by (currently only `createdAt` is supported). - name: order in: query required: false schema: type: string default: desc enum: - asc - desc description: >- Sort direction for results; use `desc` for newest-first or `asc` for oldest-first. - name: createdAtGte in: query required: false schema: type: string format: date-time description: >- Filter results to wallets created at or after this ISO-8601 timestamp. - name: id in: query required: false schema: type: string format: uuid description: Filter to a specific wallet ID. - name: requestId in: query required: false schema: type: string format: uuid description: Filter to the wallet created with this idempotency request ID. - name: label in: query required: false schema: type: string description: Filter to wallets whose label exactly matches this value. - name: search in: query required: false schema: type: string description: Case-insensitive label search. - name: status in: query required: false schema: type: string enum: - creating - active - disabled - failed description: >- Filter by wallet lifecycle status stored on the wallet record. This is not the projected public response status, which can include active workflow states such as `withdrawal_active` or `rebalance_active`. responses: '200': description: Cursor-paginated list of wallets content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Wallet' nextCursor: type: string nullable: true description: >- Opaque cursor to fetch the next page, or null when there are no more results. example: data: - id: b1c2d3e4-0000-4000-8000-000000000001 label: Corporate Treasury createdAt: '2025-09-01T00:00:00Z' status: withdrawal_active failureReason: null depositAddresses: arbitrum: '0xAbC1230000000000000000000000000000000001' base: '0xAbC1230000000000000000000000000000000001' ethereum: '0xAbC1230000000000000000000000000000000001' polygon: '0xAbC1230000000000000000000000000000000001' solana: 7vFgKxM3bP4oEFbqkPmA5E2rYJ8HqKz8abc1 balance: totalUsd: '100.000000' withdrawableUsd: '95.000000' reservedUsd: '5.000000' earnedUsd: '5.000000' positions: - id: syrup-usdc kind: yield_source label: Syrup USDC valueUsd: '38.000000' pct: 40 - id: morpho-gauntlet-usdc kind: yield_source label: Morpho Gauntlet USDC Prime valueUsd: '28.500000' pct: 30 - id: morpho-steakhouse-usdc kind: yield_source label: Morpho Steakhouse USDC Prime valueUsd: '28.500000' pct: 30 - id: cash:ethereum:usdc kind: cash label: Cash (Ethereum) valueUsd: '5.000000' nextCursor: null '400': description: Invalid query parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_cursor: summary: Cursor decode/compatibility error value: error: >- cursor is not compatible with the requested createdAtGte filter code: invalid_cursor '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' components: schemas: Wallet: type: object properties: id: type: string format: uuid label: type: string nullable: true createdAt: type: string format: date-time status: type: string description: Compact wallet lifecycle and active-workflow status. enum: - creating - idle - withdrawal_active - rebalance_active - withdrawal_and_rebalance_active - failed failureReason: type: string nullable: true depositAddresses: type: object description: Deposit addresses keyed by chain name. additionalProperties: type: string example: arbitrum: '0xAbC1230000000000000000000000000000000001' base: '0xAbC1230000000000000000000000000000000001' ethereum: '0xAbC1230000000000000000000000000000000001' polygon: '0xAbC1230000000000000000000000000000000001' solana: 7vFgKxM3bP4oEFbqkPmA5E2rYJ8HqKz8abc1 balance: type: object properties: totalUsd: type: string description: >- Gross economically owned wallet value across cash, positions, and in-transit customer-owned value. withdrawableUsd: type: string description: >- Conservative amount that can be initiated for withdrawal now, excluding active withdrawal encumbrances and unavailable transit. reservedUsd: type: string description: Customer-owned value reserved by active wallet workflows. earnedUsd: type: string description: >- Customer-facing lifetime realized gross yield earned to date, before explicit protocol fees and protocol slippage. positions: type: array items: type: object properties: id: type: string description: >- Public account/position id. Yield positions use yield source ids; cash positions use stable synthetic ids. kind: type: string enum: - yield_source - cash - bridge - external_payout - unknown label: type: string description: Human-readable display name. valueUsd: type: string description: Current USD value of this position. pct: type: number description: >- Target allocation percentage. Present on yield positions and configured cash allocations; omitted on unconfigured synthetic positions. yieldSourceId: type: string description: >- Stable public yield source id. Present for yield-source positions. token: $ref: '#/components/schemas/PortfolioWalletStrategyToken' chain: type: string description: >- Chain for a cash position. Omitted from yield-source positions; use the matching yield-source catalog row for its chain. strategyAllocations: $ref: '#/components/schemas/PublicStrategyAllocationGroups' ErrorResponse: type: object required: - error - code properties: error: type: string description: >- Human-readable error message. May change without notice; do not parse programmatically. code: type: string description: >- Machine-readable error code. Stable across API versions — safe to switch on in client code. enum: - validation_error - unknown_parameters - unsupported_chain - unsupported_token - invalid_destination_address - precision_overflow - invalid_cursor - unauthenticated - forbidden - wallet_not_found - wallet_limit_reached - withdrawal_not_found - deposit_not_found - yield_source_not_found - wallet_projection_unavailable - insufficient_funds - duplicate_request_id - request_id_conflict - invalid_position_weight - invalid_withdrawal_plan - payout_not_found - webhook_not_found - webhook_duplicate_url - withdrawal_not_cancellable - withdrawal_already_cancelled - withdrawal_payout_in_progress - withdrawal_policy_required - workflow_conflict - payout_already_terminal - payout_in_progress - payout_not_retryable - address_book_entry_not_found - address_book_duplicate_entry - address_book_whitelist_violation - rate_limited - rate_limit_exceeded - internal_error - wallet_creation_failed - service_temporarily_unavailable PortfolioWalletStrategyToken: type: string enum: - usdc - usdt description: >- Stablecoin lane used to validate, fund, rebalance, and withdraw an allocation independently from other token lanes. PublicStrategyAllocationGroups: type: object properties: usdc: type: array items: $ref: '#/components/schemas/PublicStrategyAllocation' usdt: type: array items: $ref: '#/components/schemas/PublicStrategyAllocation' description: >- Desired strategy targets grouped by stablecoin. Each returned group uses basis-point weights that sum to 10000. AuthErrorResponse: type: object required: - error properties: error: type: string description: Authentication or authorization error message. message: type: string nullable: true description: Additional auth middleware detail, when present. code: type: string nullable: true enum: - unauthenticated - forbidden description: >- Some auth and scope failures include a stable code; middleware errors may omit it. PublicStrategyAllocation: type: object required: - yieldSourceId - targetWeightBps properties: yieldSourceId: $ref: '#/components/schemas/PortfolioWalletYieldSourceId' targetWeightBps: type: integer minimum: 0 maximum: 10000 description: Target weight within this token lane, in basis points. token: $ref: '#/components/schemas/PortfolioWalletStrategyToken' chain: type: string description: Chain for a chain-scoped cash target. PortfolioWalletYieldSourceId: type: string description: >- Stable yield source ID from `GET /v2/wallets/yield-sources`, or the special `cash` id for cash held in the allocation's token lane. The live yield source catalog is environment-specific; fetch it before creating or updating a yield allocation. responses: Unauthorized: description: >- The request is missing a valid bearer token, or the token is invalid or expired. content: application/json: schema: $ref: '#/components/schemas/AuthErrorResponse' example: error: Unauthenticated request message: Missing or invalid bearer token TooManyRequests: description: >- Rate limit exceeded. Limits are enforced by API key/customer identity and by endpoint class. Retry with backoff; rate-limit headers are not currently emitted. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Rate limit exceeded code: rate_limited InternalServerError: description: >- An unexpected error occurred while processing the request. The request can be safely retried with the same `requestId`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Internal server error code: internal_error securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````