> ## 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 activity

> Returns customer-facing wallet activity across the authenticated organization. Pass one or more `walletId` query parameters to filter to specific wallets.

Deposit activity may appear with `status: "processing"` before finality for workflow-idle wallets. Processing deposit activity means Ground has detected the inbound onchain transfer; it is not yet credited to wallet balances.


## OpenAPI

````yaml swagger/swagger-combined.yaml GET /v2/activity
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/activity:
    get:
      tags:
        - Portfolio Wallets
      summary: List activity
      description: >-
        Returns customer-facing wallet activity across the authenticated
        organization. Pass one or more `walletId` query parameters to filter to
        specific wallets.
      operationId: listActivityV2
      parameters:
        - name: walletId
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              format: uuid
          style: form
          explode: true
          description: Optional repeatable wallet ID filter.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Opaque cursor from a prior response.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
          description: >-
            Maximum number of activity items to return. Runtime clamps invalid,
            missing, and oversized values into the supported 1-100 range.
        - name: scope
          in: query
          required: false
          schema:
            type: string
            enum:
              - all
          description: >-
            Use `all` to include organization-wide activity. Omit for the
            default wallet-scoped view, optionally filtered by walletId.
        - name: type
          in: query
          required: false
          schema:
            type: string
            enum:
              - deposit
              - withdrawal
              - rebalance
          description: Filter activity by type.
        - name: status
          in: query
          required: false
          schema:
            type: string
            example: created,processing
          description: Comma-separated public activity statuses to include, or `all`.
        - name: startAt
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Inclusive ISO-8601 UTC lower bound for activity timestamps.
        - name: endAt
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Exclusive ISO-8601 UTC upper bound for activity timestamps.
      responses:
        '200':
          description: Activity feed
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: >-
                      Canonical list envelope. Same items as `activity` (kept as
                      a backwards-compatible alias).
                    items:
                      $ref: '#/components/schemas/ActivityItem'
                  activity:
                    type: array
                    description: Backwards-compatible alias of `data`.
                    items:
                      $ref: '#/components/schemas/ActivityItem'
                  nextCursor:
                    type: string
                    nullable: true
                  hasMore:
                    type: boolean
              example:
                data:
                  - id: a1b2c3d4-0000-4000-8000-000000000001
                    type: deposit
                    status: completed
                    amountUsd: '5000.000000'
                    timestamp: '2025-09-05T10:00:00Z'
                    deposit:
                      id: a1b2c3d4-0000-4000-8000-000000000001
                      amount: '5000.000000'
                      token: usdc
                      chain: ethereum
                      fromAddress: '0xfeed00000000000000000000000000000000beef'
                      txHash: >-
                        0xb4ec6ad9f2f2d75fb8df30c6e49b1f319138f0172d7bff7c402e7dcb7f017e8a
                      status: completed
                      createdAt: '2025-09-05T10:00:00Z'
                      completedAt: '2025-09-05T10:01:15Z'
                  - id: a1b2c3d4-0000-4000-8000-000000000002
                    type: withdrawal
                    status: processing
                    amountUsd: '65000.000000'
                    timestamp: '2025-09-05T11:00:00Z'
                    withdrawal:
                      id: a1b2c3d4-0000-4000-8000-000000000002
                      amountRequestedUsd: '65000.000000'
                      amountPaidUsd: null
                      feeUsd: '0.000000'
                      destinationChain: ethereum
                      destinationAddress: '0x76F8fc6667E239f83a547d4e16225d6a34f6FA22'
                      destinationToken: usdc
                      status: processing
                      legsCompleted: 0
                      legsTotal: 1
                      payoutLegs:
                        - status: pending_customer_approval
                          amountUsd: '65000.000000'
                          from:
                            kind: yield_source
                            id: syrup-usdc
                            label: Syrup USDC
                          to:
                            kind: external_payout
                            id: external_payout:ethereum:usdc
                            label: External payout (Ethereum)
                          startedAt: '2025-09-05T11:00:00Z'
                          completedAt: null
                          stepsCompleted: 1
                          stepsTotal: 2
                          steps:
                            - name: Redeeming from Syrup USDC
                              stepKind: yield_source_redeem
                              sequenceRole: yield_redeem
                              protocolType: syrup
                              stepOrdinal: 0
                              chain: ethereum
                              txKind: yield_source_redeem
                              state: completed
                              startedAt: '2025-09-05T11:00:00Z'
                              completedAt: '2025-09-05T11:01:00Z'
                              cancelledAt: null
                            - name: Sending payout
                              stepKind: external_payout_transfer
                              sequenceRole: external_payout_transfer
                              protocolType: external_payout
                              stepOrdinal: 1
                              chain: ethereum
                              txKind: external_payout_transfer
                              state: pending_customer_approval
                              startedAt: '2025-09-05T11:01:00Z'
                              completedAt: null
                              cancelledAt: null
                      failureReason: null
                      createdAt: '2025-09-05T11:00:00Z'
                      completedAt: null
                nextCursor: null
                hasMore: false
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: type must be "deposit", "withdrawal", or "rebalance"
                code: validation_error
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    ActivityItem:
      type: object
      description: >-
        One customer-facing activity feed item. Exactly one of `deposit`,
        `withdrawal`, or `rebalance` is present, matching `type`.
      required:
        - id
        - type
        - status
        - amountUsd
        - timestamp
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - deposit
            - withdrawal
            - rebalance
        status:
          type: string
          nullable: true
          description: Public status of the underlying deposit, withdrawal, or rebalance.
        amountUsd:
          type: string
          nullable: true
          description: USD amount for the activity item as a fixed-precision string.
        timestamp:
          type: string
          format: date-time
          nullable: true
        walletId:
          type: string
          format: uuid
          description: Present when the activity item is attributable to a single wallet.
        walletLabel:
          type: string
          description: Present when the wallet has a label.
        label:
          type: string
          description: Human-readable activity label, when available.
        deposit:
          $ref: '#/components/schemas/Deposit'
        withdrawal:
          $ref: '#/components/schemas/Withdrawal'
        rebalance:
          $ref: '#/components/schemas/WalletRebalanceWorkflowActivity'
    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
    Deposit:
      type: object
      properties:
        id:
          type: string
          format: uuid
        amount:
          type: string
          description: >-
            Deposit amount as a fixed six-decimal USD string (e.g.
            "100.500000").
          nullable: true
        token:
          type: string
          description: Deposited stablecoin.
          enum:
            - usdc
            - usdt
          nullable: true
        chain:
          type: string
          description: Chain where the deposit was detected.
          enum:
            - arbitrum
            - base
            - ethereum
            - ethereum_sepolia
            - polygon
            - solana
            - solana_devnet
        fromAddress:
          type: string
          nullable: true
        txHash:
          type: string
          nullable: true
          description: On-chain transaction hash.
        status:
          type: string
          nullable: true
          enum:
            - processing
            - completed
            - failed
          description: >-
            Deposit status. `processing` can mean the deposit was detected
            before finality for a workflow-idle wallet and is not yet credited
            to balances.
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            Populated after the deposit finalizes and posts; null while
            processing.
    Withdrawal:
      type: object
      properties:
        id:
          type: string
          format: uuid
        amountRequestedUsd:
          type: string
          nullable: true
          description: Requested withdrawal amount in USD as a formatted string.
        amountPaidUsd:
          type: string
          nullable: true
          description: >-
            Completed payout amount in USD as a formatted string. Null until at
            least one payout completes.
        feeUsd:
          type: string
          nullable: true
          description: Fee charged for the withdrawal as a formatted string.
        destinationChain:
          type: string
          description: Destination chain for the withdrawal.
          enum:
            - arbitrum
            - base
            - ethereum
            - ethereum_sepolia
            - polygon
            - solana
            - solana_devnet
        destinationAddress:
          type: string
        destinationToken:
          type: string
          enum:
            - usdc
            - usdt
          nullable: true
        status:
          type: string
          enum:
            - processing
            - completed
            - partially_completed
            - failed
            - cancelled
          description: >-
            Simplified withdrawal status. `partially_completed` means at least
            one payout leg delivered value and at least one leg failed or was
            cancelled.
        legsCompleted:
          type: integer
        legsTotal:
          type: integer
        payoutLegs:
          type: array
          items:
            $ref: '#/components/schemas/WalletWorkflowLeg'
          description: Source-to-destination payout workflow legs.
        failureReason:
          type: string
          nullable: true
          description: >-
            Human-readable reason for failure (only present when status is
            `failed`).
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
          nullable: true
    WalletRebalanceWorkflowActivity:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - created
            - processing
            - completed
            - failed
            - cancelled
        reason:
          type: string
          nullable: true
        amountUsd:
          type: string
          nullable: true
        failureReason:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
          nullable: true
        startedAt:
          type: string
          format: date-time
          nullable: true
        completedAt:
          type: string
          format: date-time
          nullable: true
        legsCompleted:
          type: integer
        legsTotal:
          type: integer
        rebalanceLegs:
          type: array
          items:
            $ref: '#/components/schemas/WalletWorkflowLeg'
    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.
    WalletWorkflowLeg:
      type: object
      properties:
        status:
          type: string
          enum:
            - created
            - processing
            - pending_customer_approval
            - completed
            - failed
            - cancelled
        from:
          $ref: '#/components/schemas/WalletAccount'
        to:
          $ref: '#/components/schemas/WalletAccount'
        amountUsd:
          type: string
          nullable: true
          description: >-
            USD amount for this workflow leg. Null when no USD value is
            available.
        startedAt:
          type: string
          format: date-time
          nullable: true
        completedAt:
          type: string
          format: date-time
          nullable: true
        stepsCompleted:
          type: integer
        stepsTotal:
          type: integer
        steps:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowStep'
        processingEstimate:
          $ref: '#/components/schemas/ProcessingEstimate'
    WalletAccount:
      oneOf:
        - type: object
          properties:
            kind:
              type: string
              enum:
                - yield_source
            id:
              type: string
            label:
              type: string
        - type: object
          properties:
            kind:
              type: string
              enum:
                - cash
            id:
              type: string
            label:
              type: string
        - type: object
          properties:
            kind:
              type: string
              enum:
                - external_payout
            id:
              type: string
            label:
              type: string
        - type: object
          properties:
            kind:
              type: string
              enum:
                - bridge
            id:
              type: string
            label:
              type: string
        - type: object
          properties:
            kind:
              type: string
              enum:
                - unknown
            id:
              type: string
            label:
              type: string
    WorkflowStep:
      type: object
      properties:
        name:
          type: string
        stepKind:
          type: string
          nullable: true
        sequenceRole:
          type: string
          nullable: true
        protocolType:
          type: string
          nullable: true
        stepOrdinal:
          type: integer
        chain:
          type: string
          nullable: true
        txKind:
          type: string
          nullable: true
        state:
          type: string
          enum:
            - created
            - processing
            - pending_customer_approval
            - completed
            - failed
            - cancelled
        startedAt:
          type: string
          format: date-time
          nullable: true
        completedAt:
          type: string
          format: date-time
          nullable: true
        cancelledAt:
          type: string
          format: date-time
          nullable: true
    ProcessingEstimate:
      oneOf:
        - type: object
          required:
            - basis
            - typicalCompletionDate
            - typicalWindowEndDate
          properties:
            basis:
              type: string
              enum:
                - banking_days
            typicalCompletionDate:
              type: string
              format: date
            typicalWindowEndDate:
              type: string
              format: date
        - type: object
          required:
            - basis
            - typicalMinDuration
            - typicalMaxDuration
          properties:
            basis:
              type: string
              enum:
                - elapsed_seconds
            typicalMinDuration:
              type: string
              description: ISO-8601 duration for the lower end of the usual window.
            typicalMaxDuration:
              type: string
              description: ISO-8601 duration for the upper end of the usual window.
  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

````