> ## 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 webhook events

> Returns a cursor-paginated delivery event feed across all active webhooks for the organization.



## OpenAPI

````yaml swagger/swagger-combined.yaml GET /v2/webhooks/events
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/webhooks/events:
    get:
      tags:
        - Webhooks
      summary: List webhook events
      description: >-
        Returns a cursor-paginated delivery event feed across all active
        webhooks for the organization.
      operationId: listWebhookEvents
      parameters:
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Opaque cursor from the previous page.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 25
            minimum: 1
            maximum: 100
          description: Maximum number of events to return.
      responses:
        '200':
          description: Webhook event feed
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: >-
                      Canonical list envelope. Same items as `events` (kept as a
                      backwards-compatible alias).
                    items:
                      type: object
                  events:
                    type: array
                    description: Backwards-compatible alias of `data`.
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        registrationId:
                          type: string
                          format: uuid
                          description: >-
                            ID of the webhook registration this event belongs
                            to.
                        registration_id:
                          type: string
                          format: uuid
                          description: >-
                            Backwards-compatible snake_case alias of
                            `registrationId`.
                        eventType:
                          type: string
                          description: Event type that was delivered.
                        event_type:
                          type: string
                          description: >-
                            Backwards-compatible snake_case alias of
                            `eventType`.
                        payload:
                          description: >-
                            Delivered webhook body for this event; shape depends
                            on `event_type`.
                          oneOf:
                            - $ref: >-
                                #/components/schemas/WebhookWalletStatusChangedPayload
                            - $ref: >-
                                #/components/schemas/WebhookDepositStatusChangedPayload
                            - $ref: >-
                                #/components/schemas/WebhookWithdrawalStatusChangedPayload
                            - $ref: >-
                                #/components/schemas/WebhookWithdrawalPayoutStatusChangedPayload
                            - $ref: >-
                                #/components/schemas/WebhookStrategyStatusChangedPayload
                            - $ref: >-
                                #/components/schemas/WebhookRebalanceStatusChangedPayload
                            - $ref: >-
                                #/components/schemas/WebhookRiskAlertTriggeredPayload
                            - $ref: >-
                                #/components/schemas/WebhookRiskAlertResolvedPayload
                            - $ref: >-
                                #/components/schemas/WebhookRiskActionStatusChangedPayload
                            - $ref: >-
                                #/components/schemas/WebhookRiskUnwindCompletedPayload
                        status:
                          type: string
                          enum:
                            - pending
                            - completed
                            - failed
                        attempt_count:
                          type: integer
                        delivered_at:
                          type: string
                          format: date-time
                          nullable: true
                        last_error:
                          type: string
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                        updated_at:
                          type: string
                          format: date-time
                        registration:
                          type: object
                          nullable: true
                          properties:
                            id:
                              type: string
                              format: uuid
                            callbackUrl:
                              type: string
                              format: uri
                        latestEmission:
                          type: object
                          nullable: true
                          properties:
                            id:
                              type: string
                              format: uuid
                            event_id:
                              type: string
                              format: uuid
                            attempt_number:
                              type: integer
                            requested_at:
                              type: string
                              format: date-time
                            completed_at:
                              type: string
                              format: date-time
                              nullable: true
                            response_status:
                              type: integer
                              nullable: true
                            response_ms:
                              type: integer
                              nullable: true
                            error_message:
                              type: string
                              nullable: true
                  nextCursor:
                    type: string
                    nullable: true
                  hasMore:
                    type: boolean
              example:
                data:
                  - id: 73a8e0c9-c20d-4b10-b9a4-0f0ff6b5cb9c
                    registrationId: 6b6a0502-9d38-4f94-83fe-06706adbdc51
                    registration_id: 6b6a0502-9d38-4f94-83fe-06706adbdc51
                    eventType: portfolio_wallet.withdrawal.status_changed
                    event_type: portfolio_wallet.withdrawal.status_changed
                    payload:
                      event: portfolio_wallet.withdrawal.status_changed
                      observedAt: '2026-05-01T17:35:39.000Z'
                      withdrawal:
                        id: a1f9e803-12a1-4f7c-8bb1-30277d1f6574
                        amountRequestedUsd: '65000.000000'
                        amountPaidUsd: '65000.000000'
                        feeUsd: '0.000000'
                        destinationChain: ethereum
                        destinationAddress: '0x76F8fc6667E239f83a547d4e16225d6a34f6FA22'
                        destinationToken: usdc
                        status: completed
                        legsCompleted: 1
                        legsTotal: 1
                        payoutLegs: []
                        failureReason: null
                        createdAt: '2026-05-01T17:30:00.000Z'
                        completedAt: '2026-05-01T17:35:39.000Z'
                    status: completed
                    attempt_count: 1
                    delivered_at: '2026-05-01T17:35:41.000Z'
                    last_error: null
                    created_at: '2026-05-01T17:35:39.000Z'
                    updated_at: '2026-05-01T17:35:41.000Z'
                    registration:
                      id: 6b6a0502-9d38-4f94-83fe-06706adbdc51
                      callbackUrl: https://ops.acme-treasury.com/webhooks/ground
                    latestEmission:
                      id: c177e6a4-2ee3-4ce0-b795-f092cb0e572d
                      attempt_number: 1
                      requested_at: '2026-05-01T17:35:39.000Z'
                      completed_at: '2026-05-01T17:35:41.000Z'
                      response_status: 200
                      response_ms: 184
                      error_message: null
                nextCursor: null
                hasMore: false
        '400':
          description: Invalid cursor or limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_cursor:
                  value:
                    error: cursor is invalid
                    code: invalid_cursor
                invalid_limit:
                  value:
                    error: limit must be a positive integer no greater than 100
                    code: validation_error
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    WebhookWalletStatusChangedPayload:
      type: object
      description: Delivered for `portfolio_wallet.status_changed`.
      required:
        - event
        - organizationId
        - walletId
        - previousStatus
        - status
        - occurredAt
      properties:
        event:
          type: string
          enum:
            - portfolio_wallet.status_changed
        organizationId:
          type: string
          format: uuid
        walletId:
          type: string
          format: uuid
        previousStatus:
          type: string
          nullable: true
          description: >-
            Previous wallet status when known; null when not tracked for this
            transition.
        status:
          type: string
          enum:
            - creating
            - idle
            - withdrawal_active
            - rebalance_active
            - withdrawal_and_rebalance_active
            - failed
        occurredAt:
          type: string
          format: date-time
    WebhookDepositStatusChangedPayload:
      type: object
      description: Delivered for `portfolio_wallet.deposit.status_changed`.
      required:
        - event
        - observedAt
        - deposit
      properties:
        event:
          type: string
          enum:
            - portfolio_wallet.deposit.status_changed
        observedAt:
          type: string
          format: date-time
        deposit:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Deposit'
    WebhookWithdrawalStatusChangedPayload:
      type: object
      description: Delivered for `portfolio_wallet.withdrawal.status_changed`.
      required:
        - event
        - observedAt
        - withdrawal
      properties:
        event:
          type: string
          enum:
            - portfolio_wallet.withdrawal.status_changed
        observedAt:
          type: string
          format: date-time
        withdrawal:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Withdrawal'
    WebhookWithdrawalPayoutStatusChangedPayload:
      type: object
      description: Delivered for `portfolio_wallet.withdrawal.payout.status_changed`.
      required:
        - event
        - observedAt
        - payout
      properties:
        event:
          type: string
          enum:
            - portfolio_wallet.withdrawal.payout.status_changed
        observedAt:
          type: string
          format: date-time
        payout:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/PayoutLeg'
    WebhookStrategyStatusChangedPayload:
      type: object
      description: Delivered for `portfolio_wallet.strategy.status_changed`.
      required:
        - event
        - observedAt
        - strategy
      properties:
        event:
          type: string
          enum:
            - portfolio_wallet.strategy.status_changed
        observedAt:
          type: string
          format: date-time
        strategy:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/StrategySnapshot'
    WebhookRebalanceStatusChangedPayload:
      type: object
      description: Delivered for `portfolio_wallet.rebalance.status_changed`.
      required:
        - event
        - observedAt
        - rebalance
      properties:
        event:
          type: string
          enum:
            - portfolio_wallet.rebalance.status_changed
        observedAt:
          type: string
          format: date-time
        rebalance:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/WalletRebalanceWorkflowActivity'
    WebhookRiskAlertTriggeredPayload:
      type: object
      description: Delivered for `portfolio_wallet.risk.alert.triggered`.
      required:
        - event
        - organizationId
        - portfolioWalletId
        - riskAlertId
        - riskRuleId
        - yieldSourceId
        - metric
        - ruleKind
        - comparator
        - thresholdValue
        - observedValue
        - baselineValue
        - observedChangeBps
        - windowSeconds
        - status
        - metricsObservationId
        - explanation
      properties:
        event:
          type: string
          enum:
            - portfolio_wallet.risk.alert.triggered
        organizationId:
          type: string
          format: uuid
        portfolioWalletId:
          type: string
          format: uuid
        riskAlertId:
          type: string
          format: uuid
        riskRuleId:
          type: string
          format: uuid
        yieldSourceId:
          type: string
          nullable: true
          description: >-
            Public yield source id the rule targets; null for wallet-level
            metrics.
        metric:
          type: string
          description: Metric the rule evaluates (e.g. `apy_bps`, `tvl_usd`).
        ruleKind:
          type: string
          description: Rule kind (e.g. `threshold`, `relative_change`).
        comparator:
          type: string
          description: Comparison operator (e.g. `lt`, `gt`).
        thresholdValue:
          type: number
          nullable: true
        observedValue:
          type: number
          nullable: true
        baselineValue:
          type: number
          nullable: true
        observedChangeBps:
          type: number
          nullable: true
        windowSeconds:
          type: number
          nullable: true
        status:
          type: string
          description: Alert status at emission time (`triggered`).
        metricsObservationId:
          type: string
          format: uuid
          nullable: true
        triggeredAt:
          type: string
          format: date-time
          description: Present when the trigger timestamp is known.
        explanation:
          type: object
          additionalProperties: true
          description: Free-form human-readable context for the alert.
    WebhookRiskAlertResolvedPayload:
      type: object
      description: Delivered for `portfolio_wallet.risk.alert.resolved`.
      required:
        - event
        - organizationId
        - portfolioWalletId
        - riskAlertId
        - riskRuleId
        - yieldSourceId
        - metric
        - ruleKind
        - comparator
        - thresholdValue
        - observedValue
        - baselineValue
        - observedChangeBps
        - windowSeconds
        - status
        - metricsObservationId
        - explanation
      properties:
        event:
          type: string
          enum:
            - portfolio_wallet.risk.alert.resolved
        organizationId:
          type: string
          format: uuid
        portfolioWalletId:
          type: string
          format: uuid
        riskAlertId:
          type: string
          format: uuid
        riskRuleId:
          type: string
          format: uuid
        yieldSourceId:
          type: string
          nullable: true
          description: >-
            Public yield source id the rule targets; null for wallet-level
            metrics.
        metric:
          type: string
          description: Metric the rule evaluates (e.g. `apy_bps`, `tvl_usd`).
        ruleKind:
          type: string
          description: Rule kind (e.g. `threshold`, `relative_change`).
        comparator:
          type: string
          description: Comparison operator (e.g. `lt`, `gt`).
        thresholdValue:
          type: number
          nullable: true
        observedValue:
          type: number
          nullable: true
        baselineValue:
          type: number
          nullable: true
        observedChangeBps:
          type: number
          nullable: true
        windowSeconds:
          type: number
          nullable: true
        status:
          type: string
          description: Alert status at emission time (`resolved`).
        metricsObservationId:
          type: string
          format: uuid
          nullable: true
        triggeredAt:
          type: string
          format: date-time
          description: Present when the trigger timestamp is known.
        resolvedAt:
          type: string
          format: date-time
          description: Present when the resolution timestamp is known.
        resolutionSource:
          type: string
          description: >-
            What resolved the alert (e.g. `metric_recovered`, `manual`). Present
            when known.
        resolutionNote:
          type: string
          description: Optional human-entered note. Present when set.
        explanation:
          type: object
          additionalProperties: true
          description: Free-form human-readable context for the alert.
    WebhookRiskActionStatusChangedPayload:
      type: object
      description: Delivered for `portfolio_wallet.risk.action.status_changed`.
      required:
        - event
        - organizationId
        - portfolioWalletId
        - riskActionId
        - riskAlertId
        - riskRuleId
        - yieldSourceId
        - outcome
        - approvalMode
        - previousStatus
        - status
        - attemptCount
        - executionVersion
        - rebalanceId
        - changedAt
        - executionError
        - explanation
      properties:
        event:
          type: string
          enum:
            - portfolio_wallet.risk.action.status_changed
        organizationId:
          type: string
          format: uuid
        portfolioWalletId:
          type: string
          format: uuid
        riskActionId:
          type: string
          format: uuid
        riskAlertId:
          type: string
          format: uuid
        riskRuleId:
          type: string
          format: uuid
        yieldSourceId:
          type: string
          nullable: true
          description: >-
            Public yield source id the action targets; null for wallet-level
            actions.
        outcome:
          type: string
          description: >-
            Configured action outcome (e.g. `exit_position`,
            `prevent_allocation`).
        approvalMode:
          type: string
          description: How execution is approved (e.g. `automatic`, `manual`).
        previousStatus:
          type: string
          nullable: true
        status:
          type: string
        attemptCount:
          type: number
          nullable: true
        executionVersion:
          nullable: true
          oneOf:
            - type: number
            - type: string
          description: Monotonic execution version used for idempotent status transitions.
        rebalanceId:
          type: string
          format: uuid
          nullable: true
          description: Rebalance workflow executing this action, when one exists.
        changedAt:
          type: string
          format: date-time
        executionError:
          type: object
          nullable: true
          additionalProperties: true
          description: Structured execution error when the action failed; null otherwise.
        explanation:
          type: object
          additionalProperties: true
          description: Free-form human-readable context for the action.
    WebhookRiskUnwindCompletedPayload:
      type: object
      description: >-
        Delivered for `portfolio_wallet.risk.unwind.completed` when a
        risk-triggered unwind finishes moving value to cash.
      required:
        - event
        - organizationId
        - portfolioWalletId
        - riskActionId
        - riskAlertId
        - riskRuleId
        - rebalanceId
        - yieldSourceId
        - yieldSourceName
        - completedRebalanceLegId
        - completedSourceAccountId
        - cashDestinationAccountId
        - cashDestinationChain
        - cashDestinationToken
        - completedAmountNativeUnits
        - completedAt
        - occurredAt
        - explanation
      properties:
        event:
          type: string
          enum:
            - portfolio_wallet.risk.unwind.completed
        organizationId:
          type: string
          format: uuid
        portfolioWalletId:
          type: string
          format: uuid
        riskActionId:
          type: string
          format: uuid
        riskAlertId:
          type: string
          format: uuid
        riskRuleId:
          type: string
          format: uuid
        rebalanceId:
          type: string
          format: uuid
        yieldSourceId:
          type: string
          nullable: true
          description: Public yield source id that was unwound.
        yieldSourceName:
          type: string
          nullable: true
        completedRebalanceLegId:
          type: string
          nullable: true
        completedSourceAccountId:
          type: string
          nullable: true
        cashDestinationAccountId:
          type: string
          nullable: true
        cashDestinationChain:
          type: string
          nullable: true
        cashDestinationToken:
          type: string
          nullable: true
        completedAmountNativeUnits:
          nullable: true
          oneOf:
            - type: string
            - type: number
          description: Amount moved to cash in the source account's native base units.
        completedAt:
          type: string
          format: date-time
          nullable: true
        eventId:
          type: string
          format: uuid
          description: >-
            Risk event id backing this notification. Present when the event row
            was recorded.
        occurredAt:
          type: string
          format: date-time
        explanation:
          type: object
          additionalProperties: true
          description: Free-form human-readable context for the unwind.
    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
    PayoutLeg:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          description: Payout leg status.
          enum:
            - planning
            - processing
            - pending_customer_approval
            - pending_broadcast
            - broadcasted
            - completed
            - failed
            - cancelled
            - skipped
        turnkeyActivityId:
          type: string
          nullable: true
          description: >-
            Turnkey signing activity ID. Only populated when the payout required
            customer approval; null if Ground auto-approved.
        approvalRequestedAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            When customer approval was requested. Null if customer approval was
            not required.
        approvalValidBefore:
          type: string
          format: date-time
          nullable: true
          description: >-
            ISO-8601 deadline for the approval. Null if customer approval was
            not required.
        amountUsd:
          type: string
          nullable: true
          description: >-
            Payout amount as a fixed-precision USD string (for example,
            "50.000000").
        feeUsd:
          type: string
          nullable: true
          description: >-
            Customer-impacting protocol fee and protocol slippage attributed to
            this payout leg.
        txHash:
          type: string
          nullable: true
          description: On-chain transaction hash (populated after broadcast).
        failureReason:
          type: string
          nullable: true
        steps:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowStep'
          description: Workflow execution steps for this payout.
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
          nullable: true
    StrategySnapshot:
      type: object
      description: >-
        Applied strategy update, as delivered on
        `portfolio_wallet.strategy.status_changed` webhooks.
      required:
        - walletId
        - requestId
        - status
        - allocations
        - createdAt
      properties:
        walletId:
          type: string
          format: uuid
        requestId:
          type: string
          format: uuid
          description: The `requestId` of the strategy update request that was applied.
        status:
          type: string
          enum:
            - completed
        allocations:
          type: array
          items:
            $ref: '#/components/schemas/StrategySnapshotAllocation'
          description: >-
            Flat list of allocations applied by this update. Resolve
            yield-source token compatibility through the catalog's
            `depositToken`; USDT cash entries include `token: usdt`.
        createdAt:
          type: string
          format: date-time
    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'
    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
    StrategySnapshotAllocation:
      type: object
      required:
        - yieldSourceId
        - pct
      properties:
        yieldSourceId:
          $ref: '#/components/schemas/PortfolioWalletYieldSourceId'
        pct:
          type: number
          multipleOf: 0.1
          minimum: 0
          maximum: 100
        token:
          $ref: '#/components/schemas/PortfolioWalletStrategyToken'
        chain:
          type: string
          description: Chain for an applied cash allocation when explicitly configured.
    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
    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.
    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.
    PortfolioWalletStrategyToken:
      type: string
      enum:
        - usdc
        - usdt
      description: >-
        Stablecoin lane used to validate, fund, rebalance, and withdraw an
        allocation independently from other token lanes.
  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

````