> ## Documentation Index
> Fetch the complete documentation index at: https://docs.services.payward.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deallocate from a Bonded Earn strategy

> Submits a request to deallocate funds of the specified account from the bonded earn strategy identified in the path.

Partial deallocation is allowed. To exit a strategy completely, send the full `earning` amount. The funds then pass through the exit queue (if any) and the unbonding period. For an instant strategy they return right away.

The request is processed asynchronously. A successful response only confirms that the request was accepted and returns its `request_id`; poll the request status endpoint with that identifier to learn whether the deallocation succeeded or failed.

Reuse the same `Idempotency-Key` only when retrying the same request. Keys are scoped to the account. Retrying with the same key, strategy, and `amount` returns the original `request_id` without deallocating again. Reusing the key with a different strategy or `amount`, or for an allocation instead of a deallocation, returns a conflict error.

Rejected requests return a machine-readable `error.code`; branch on it rather than on the message text. Known codes are `strategy_not_found`, `insufficient_balance`, `amount_too_high`, `idempotency_key_reused`, and `allocation_in_progress`. Only funds that are earning can be deallocated. `insufficient_balance` means the amount is more than those funds. Funds that are still bonding, unbonding, or in the exit queue do not count. An account that is not eligible for the strategy returns `forbidden`. A 403 with the code `gateway` is an authorization failure from the API gateway instead, so branch on `error.code` to tell the two apart.

A request that is accepted can still fail later. The request status endpoint then reports it in `error.reason`, for example `insufficient_balance` or `not_eligible`. A request that failed after it was accepted keeps its `Idempotency-Key`, so retry with a new key. New codes may be added, so treat an unknown code as a generic `bad_request`, `not_found`, or `request_conflict` error.



## OpenAPI

````yaml https://d2588n1sy4m36o.cloudfront.net/uat/merged/openapi.json post /v1/accounts/{account_id}/earn/bonded/strategies/{strategy_id}/deallocate
openapi: 3.1.0
info:
  title: PWS Public API
  version: '1'
  description: >-
    Integrate with Payward Services to onboard users, manage accounts and funds,
    trade assets, and receive event notifications.
  contact:
    name: Payward Services
servers:
  - url: https://api.sandbox.services.payward.com
security: []
tags:
  - name: Assets
    description: List the assets PWS is willing to swap.
    x-displayName: Assets
  - name: Conversions
    description: >-
      Rule-driven and on-demand fiat ↔ crypto value movement, including
      conversion rules and deposits.
    x-displayName: Conversions
  - name: Auto Earn
    description: >-
      Manage Auto Earn preferences and retrieve allocation and reward
      information.
    x-displayName: Auto Earn
  - name: Bonded Earn
    description: >-
      Allocate funds to and deallocate funds from bonded earn strategies, review
      allocations, and track request status.
    x-displayName: Bonded Earn
  - name: Funding
    description: >-
      Discover deposit and withdrawal options, manage deposit addresses, and
      move funds between accounts.
    x-displayName: Funding
  - name: Derivative transfers
    description: >-
      Move funds between an account's spot balance and the same owner's futures
      balance.
    x-displayName: Derivative transfers
  - name: Portfolio
    description: 'Inspect a customer''s portfolio: balances, valuations, and transactions.'
    x-displayName: Portfolio
  - name: Ramp
    description: >-
      Support Ramp flows with discovery, quotes, limits, and hosted checkout
      experiences.
    x-displayName: Ramp
  - name: Reports
    description: Settlement and reconciliation reports for the partner.
    x-displayName: Reports
  - name: Swaps
    description: Account-funded quotes that lock a price until they expire or are executed.
    x-displayName: Swaps
  - name: Onchain quotes
    description: Wallet-funded quotes that return the data needed to settle onchain.
    x-displayName: Onchain quotes
  - name: Price trigger swaps
    description: Swaps that wait for a target price before submitting a trade.
    x-displayName: Price trigger swaps
  - name: Travel Rule verifications
    description: Travel Rule address ownership verification flows.
    x-displayName: Travel Rule verifications
  - name: Users
    description: >-
      User onboarding and status flows that the partner manages.


      - **Create User** provisions an account-owned user from an external
      reference and optional email.

      - **Get User** retrieves the user's profile, verification status, and
      required actions.


      Use the returned user `id` for calls that require the user's identifier.
    x-displayName: Users
  - name: Verifications
    description: Identity verification (KYC) submission and status for end users.
    x-displayName: Verifications
  - name: Webhooks
    description: >-
      Register HTTPS destinations to receive event deliveries, rotate signing
      secrets, and inspect, update, or delete existing subscriptions. Each
      subscription is owned by the authenticated partner; deliveries are signed
      with HMAC-SHA256 and retried on transient failures.
    x-displayName: Webhooks
paths:
  /v1/accounts/{account_id}/earn/bonded/strategies/{strategy_id}/deallocate:
    post:
      tags:
        - Bonded Earn
      summary: Deallocate from a Bonded Earn strategy
      description: >-
        Submits a request to deallocate funds of the specified account from the
        bonded earn strategy identified in the path.


        Partial deallocation is allowed. To exit a strategy completely, send the
        full `earning` amount. The funds then pass through the exit queue (if
        any) and the unbonding period. For an instant strategy they return right
        away.


        The request is processed asynchronously. A successful response only
        confirms that the request was accepted and returns its `request_id`;
        poll the request status endpoint with that identifier to learn whether
        the deallocation succeeded or failed.


        Reuse the same `Idempotency-Key` only when retrying the same request.
        Keys are scoped to the account. Retrying with the same key, strategy,
        and `amount` returns the original `request_id` without deallocating
        again. Reusing the key with a different strategy or `amount`, or for an
        allocation instead of a deallocation, returns a conflict error.


        Rejected requests return a machine-readable `error.code`; branch on it
        rather than on the message text. Known codes are `strategy_not_found`,
        `insufficient_balance`, `amount_too_high`, `idempotency_key_reused`, and
        `allocation_in_progress`. Only funds that are earning can be
        deallocated. `insufficient_balance` means the amount is more than those
        funds. Funds that are still bonding, unbonding, or in the exit queue do
        not count. An account that is not eligible for the strategy returns
        `forbidden`. A 403 with the code `gateway` is an authorization failure
        from the API gateway instead, so branch on `error.code` to tell the two
        apart.


        A request that is accepted can still fail later. The request status
        endpoint then reports it in `error.reason`, for example
        `insufficient_balance` or `not_eligible`. A request that failed after it
        was accepted keeps its `Idempotency-Key`, so retry with a new key. New
        codes may be added, so treat an unknown code as a generic `bad_request`,
        `not_found`, or `request_conflict` error.
      operationId: deallocateBondedEarn
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/BondedEarn_BondedStrategyId'
        - $ref: '#/components/parameters/RequiredIdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: Request to deallocate funds from a bonded earn strategy.
              type: object
              additionalProperties: false
              required:
                - amount
              properties:
                amount:
                  $ref: '#/components/schemas/BondedEarn_BondedAmount'
            examples:
              deallocate:
                summary: Deallocate 2 units of the strategy's asset
                value:
                  amount: '2.0'
      responses:
        '202':
          description: The deallocation request was accepted and is pending.
          headers:
            X-Trace-Id:
              $ref: '#/components/headers/TraceId'
            Strict-Transport-Security:
              $ref: '#/components/headers/StrictTransportSecurity'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BondedEarn_BondedRequestAccepted'
                required:
                  - data
              examples:
                accepted:
                  summary: Deallocation request accepted
                  value:
                    data:
                      request_id: EBARXUKF-PWQSJN-JNZQDS
        '400':
          $ref: '#/components/responses/BondedEarnDeallocateBadRequestResponse'
        '401':
          $ref: '#/components/responses/EarnUnauthenticatedResponse'
        '403':
          $ref: '#/components/responses/BondedEarnWriteForbiddenResponse'
        '404':
          $ref: '#/components/responses/BondedEarnWriteNotFoundResponse'
        '409':
          $ref: '#/components/responses/BondedEarnConflictResponse'
        '429':
          $ref: '#/components/responses/EarnResourceExhaustedResponse'
        '500':
          $ref: '#/components/responses/EarnInternalResponse'
        '503':
          $ref: '#/components/responses/EarnUnavailableResponse'
        '504':
          $ref: '#/components/responses/EarnDeadlineExceededResponse'
      security:
        - ApiKey: []
          ApiSign: []
          ApiNonce: []
components:
  parameters:
    AccountId:
      name: account_id
      in: path
      required: true
      example: WVSD33HRMGSZUBM7
      schema:
        $ref: '#/components/schemas/AccountId'
    BondedEarn_BondedStrategyId:
      name: strategy_id
      in: path
      description: >-
        Identifier of the bonded earn strategy to allocate to or deallocate
        from.
      required: true
      example: ESQEFMZ-JPPIY-3KXFJ2
      schema:
        $ref: '#/components/schemas/BondedEarn_BondedStrategyId'
    RequiredIdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        $ref: '#/components/schemas/IdempotencyKey'
      example: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    BondedEarn_BondedAmount:
      description: Amount in the strategy's asset, as a decimal string.
      type: string
      minLength: 1
      maxLength: 64
      example: '2.0'
    BondedEarn_BondedRequestAccepted:
      description: Confirmation that an allocate or deallocate request was accepted.
      type: object
      additionalProperties: false
      required:
        - request_id
      properties:
        request_id:
          description: >-
            Identifier of the submitted request. Use it to look up the request
            status.
          type: string
          minLength: 1
          maxLength: 64
    AccountId:
      description: Globally unique public identifier for an account.
      type: string
      minLength: 14
      maxLength: 42
    BondedEarn_BondedStrategyId:
      description: Identifier of the bonded earn strategy.
      type: string
      minLength: 20
      maxLength: 20
      pattern: ^ES[A-Z2-7]{5}-[A-Z2-7]{5}-[A-Z2-7]{6}$
      example: ESQEFMZ-JPPIY-3KXFJ2
    IdempotencyKey:
      description: >-
        Client-generated canonical UUIDv4 that uniquely identifies a request for
        safe retries.
      type: string
      format: uuid
      pattern: >-
        ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
      example: 550e8400-e29b-41d4-a716-446655440000
    BadRequestError:
      title: Bad Request
      description: Request validation failed or the request could not be processed.
      oneOf:
        - title: Bad Request
          allOf:
            - $ref: '#/components/schemas/PwsValidationErrorEnvelope'
            - type: object
              required:
                - error
              properties:
                error:
                  allOf:
                    - $ref: '#/components/schemas/PwsValidationError'
                    - type: object
                      required:
                        - status
                        - code
                      properties:
                        status:
                          type: integer
                          format: int32
                          const: 400
                        code:
                          type: string
                          enum:
                            - bad_request
        - title: Gateway
          description: >-
            Gateway-level validation failure returned before the request reaches
            the service.
          allOf:
            - $ref: '#/components/schemas/PwsValidationErrorEnvelope'
            - type: object
              required:
                - error
              properties:
                error:
                  allOf:
                    - $ref: '#/components/schemas/PwsValidationError'
                    - type: object
                      required:
                        - status
                        - code
                      properties:
                        type:
                          type: string
                          const: service_error
                        status:
                          type: integer
                          format: int32
                          const: 400
                        code:
                          type: string
                          const: gateway
    BondedEarn_InsufficientBalanceError:
      description: >-
        The account's earning balance in the strategy does not cover the
        requested deallocation `amount`.
      allOf:
        - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
        - type: object
          required:
            - error
          properties:
            error:
              allOf:
                - $ref: '#/components/schemas/PwsGeneralError'
                - type: object
                  required:
                    - status
                    - code
                  properties:
                    status:
                      type: integer
                      format: int32
                      const: 400
                    code:
                      type: string
                      enum:
                        - insufficient_balance
    BondedEarn_AmountTooHighError:
      description: The requested `amount` is larger than the system can represent.
      allOf:
        - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
        - type: object
          required:
            - error
          properties:
            error:
              allOf:
                - $ref: '#/components/schemas/PwsGeneralError'
                - type: object
                  required:
                    - status
                    - code
                  properties:
                    status:
                      type: integer
                      format: int32
                      const: 400
                    code:
                      type: string
                      enum:
                        - amount_too_high
    UnauthenticatedError:
      title: Unauthenticated
      description: Authentication credentials are missing, invalid, or not accepted.
      oneOf:
        - title: Unauthenticated
          allOf:
            - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
            - type: object
              required:
                - error
              properties:
                error:
                  allOf:
                    - $ref: '#/components/schemas/PwsGeneralError'
                    - type: object
                      required:
                        - status
                        - code
                      properties:
                        status:
                          type: integer
                          format: int32
                          const: 401
                        code:
                          type: string
                          enum:
                            - unauthenticated
        - title: Gateway
          description: Authentication failure returned by the API gateway.
          allOf:
            - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
            - type: object
              required:
                - error
              properties:
                error:
                  allOf:
                    - $ref: '#/components/schemas/PwsGeneralError'
                    - type: object
                      required:
                        - status
                        - code
                      properties:
                        type:
                          type: string
                          const: service_error
                        status:
                          type: integer
                          format: int32
                          const: 401
                        code:
                          type: string
                          const: gateway
    ForbiddenError:
      title: Forbidden
      description: The caller is not allowed to perform this operation.
      oneOf:
        - title: Forbidden
          allOf:
            - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
            - type: object
              required:
                - error
              properties:
                error:
                  allOf:
                    - $ref: '#/components/schemas/PwsGeneralError'
                    - type: object
                      required:
                        - status
                        - code
                      properties:
                        status:
                          type: integer
                          format: int32
                          const: 403
                        code:
                          type: string
                          enum:
                            - forbidden
        - title: Gateway
          description: Authorization failure returned by the API gateway.
          allOf:
            - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
            - type: object
              required:
                - error
              properties:
                error:
                  allOf:
                    - $ref: '#/components/schemas/PwsGeneralError'
                    - type: object
                      required:
                        - status
                        - code
                      properties:
                        type:
                          type: string
                          const: service_error
                        status:
                          type: integer
                          format: int32
                          const: 403
                        code:
                          type: string
                          const: gateway
    NotFoundError:
      description: The requested resource was not found.
      allOf:
        - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
        - type: object
          required:
            - error
          properties:
            error:
              allOf:
                - $ref: '#/components/schemas/PwsGeneralError'
                - type: object
                  required:
                    - status
                    - code
                  properties:
                    status:
                      type: integer
                      format: int32
                      const: 404
                    code:
                      type: string
                      enum:
                        - not_found
    BondedEarn_StrategyNotFoundError:
      description: The strategy identified in the path does not exist.
      allOf:
        - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
        - type: object
          required:
            - error
          properties:
            error:
              allOf:
                - $ref: '#/components/schemas/PwsGeneralError'
                - type: object
                  required:
                    - status
                    - code
                  properties:
                    status:
                      type: integer
                      format: int32
                      const: 404
                    code:
                      type: string
                      enum:
                        - strategy_not_found
    BondedEarn_RequestConflictError:
      description: >-
        The request conflicts with a request that was already recorded or is
        still running, for example because the idempotency key was already used
        for a different strategy or amount.
      allOf:
        - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
        - type: object
          required:
            - error
          properties:
            error:
              allOf:
                - $ref: '#/components/schemas/PwsGeneralError'
                - type: object
                  required:
                    - status
                    - code
                  properties:
                    status:
                      type: integer
                      format: int32
                      const: 409
                    code:
                      type: string
                      enum:
                        - request_conflict
    BondedEarn_IdempotencyKeyReusedError:
      description: >-
        The `Idempotency-Key` was already used for a request with a different
        strategy, `amount`, or direction.
      allOf:
        - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
        - type: object
          required:
            - error
          properties:
            error:
              allOf:
                - $ref: '#/components/schemas/PwsGeneralError'
                - type: object
                  required:
                    - status
                    - code
                  properties:
                    status:
                      type: integer
                      format: int32
                      const: 409
                    code:
                      type: string
                      enum:
                        - idempotency_key_reused
    BondedEarn_AllocationInProgressError:
      description: >-
        Another allocation change is already in progress, so this request cannot
        be accepted yet.
      allOf:
        - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
        - type: object
          required:
            - error
          properties:
            error:
              allOf:
                - $ref: '#/components/schemas/PwsGeneralError'
                - type: object
                  required:
                    - status
                    - code
                  properties:
                    status:
                      type: integer
                      format: int32
                      const: 409
                    code:
                      type: string
                      enum:
                        - allocation_in_progress
    ResourceExhaustedError:
      description: The request was rate limited or a resource quota was exhausted.
      allOf:
        - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
        - type: object
          required:
            - error
          properties:
            error:
              allOf:
                - $ref: '#/components/schemas/PwsGeneralError'
                - type: object
                  required:
                    - status
                    - code
                  properties:
                    status:
                      type: integer
                      format: int32
                      const: 429
                    code:
                      type: string
                      enum:
                        - resource_exhausted
    InternalError:
      description: An unexpected server-side error occurred.
      allOf:
        - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
        - type: object
          required:
            - error
          properties:
            error:
              allOf:
                - $ref: '#/components/schemas/PwsGeneralError'
                - type: object
                  required:
                    - status
                    - code
                  properties:
                    status:
                      type: integer
                      format: int32
                      const: 500
                    code:
                      type: string
                      enum:
                        - internal
    UnavailableError:
      description: The service is temporarily unavailable.
      allOf:
        - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
        - type: object
          required:
            - error
          properties:
            error:
              allOf:
                - $ref: '#/components/schemas/PwsGeneralError'
                - type: object
                  required:
                    - status
                    - code
                  properties:
                    status:
                      type: integer
                      format: int32
                      const: 503
                    code:
                      type: string
                      enum:
                        - unavailable
    DeadlineExceededError:
      description: The request deadline was exceeded before a response could be produced.
      allOf:
        - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
        - type: object
          required:
            - error
          properties:
            error:
              allOf:
                - $ref: '#/components/schemas/PwsGeneralError'
                - type: object
                  required:
                    - status
                    - code
                  properties:
                    status:
                      type: integer
                      format: int32
                      const: 504
                    code:
                      type: string
                      enum:
                        - deadline_exceeded
    PwsValidationErrorEnvelope:
      description: Error envelope for request validation failures.
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/PwsValidationError'
          description: Validation error details.
    PwsValidationError:
      description: Standard PWS API error object for request validation failures.
      type: object
      required:
        - type
        - status
        - instance
        - code
      properties:
        type:
          description: Machine-readable error class.
          type: string
        status:
          description: HTTP status code returned for this error.
          type: integer
          format: int32
        instance:
          description: Request identifier for this specific error occurrence.
          type: string
        code:
          description: Stable machine-readable error code.
          type: string
        doc_url:
          description: Optional link to documentation for this error.
          type: string
          format: uri
        causes:
          description: Validation failures that contributed to the error.
          type: array
          items:
            $ref: '#/components/schemas/PwsErrorCause'
    PwsGeneralErrorEnvelope:
      description: Error envelope for operational or domain failures.
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/PwsGeneralError'
          description: General error details.
    PwsGeneralError:
      description: Standard PWS API error object for non-validation failures.
      allOf:
        - $ref: '#/components/schemas/PwsErrorBase'
        - type: object
          properties:
            causes:
              description: Additional error details, when present.
              type: array
              items:
                type: object
                additionalProperties: true
    PwsErrorCause:
      description: A single request validation failure.
      type: object
      required:
        - field
        - message
      properties:
        field:
          description: Dot-notation path to the offending request field.
          type: string
        message:
          description: Human-readable explanation of the failed validation rule.
          type: string
    PwsErrorBase:
      description: Common fields present on every PWS API error object.
      type: object
      required:
        - type
        - status
        - instance
        - code
      properties:
        type:
          description: Machine-readable error class.
          type: string
        status:
          description: HTTP status code returned for this error.
          type: integer
          format: int32
        instance:
          description: Request identifier for this specific error occurrence.
          type: string
        code:
          description: Stable machine-readable error code.
          type: string
        doc_url:
          description: Optional link to documentation for this error.
          type: string
          format: uri
  headers:
    TraceId:
      description: Trace identifier for the request. Include it when contacting support.
      schema:
        type: string
        example: 4bf92f3577b34da6a3ce929d0e0e4736
    StrictTransportSecurity:
      description: Enforces HTTPS for the duration specified by `max-age`.
      schema:
        type: string
        example: max-age=31536000; includeSubDomains; preload
    CacheControl:
      description: Prevents caching of sensitive financial data. Always `no-store`.
      schema:
        type: string
        enum:
          - no-store
        example: no-store
  responses:
    BondedEarnDeallocateBadRequestResponse:
      description: The request was rejected. Branch on `error.code`.
      headers:
        X-Trace-Id:
          $ref: '#/components/headers/TraceId'
        Strict-Transport-Security:
          $ref: '#/components/headers/StrictTransportSecurity'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/BadRequestError'
                title: Bad request
              - $ref: '#/components/schemas/BondedEarn_InsufficientBalanceError'
                title: Insufficient balance
              - $ref: '#/components/schemas/BondedEarn_AmountTooHighError'
                title: Amount too high
          examples:
            invalid-request:
              $ref: '#/components/examples/earn-bad-request'
            insufficient-balance:
              $ref: '#/components/examples/bonded-earn-insufficient-balance'
            amount-too-high:
              $ref: '#/components/examples/bonded-earn-amount-too-high'
    EarnUnauthenticatedResponse:
      description: Authentication failed
      headers:
        X-Trace-Id:
          $ref: '#/components/headers/TraceId'
        Strict-Transport-Security:
          $ref: '#/components/headers/StrictTransportSecurity'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthenticatedError'
          examples:
            authentication-failed:
              $ref: '#/components/examples/earn-unauthenticated'
    BondedEarnWriteForbiddenResponse:
      description: >-
        The account is not eligible for the strategy (`forbidden`), or the API
        gateway rejected the request (`gateway`). Branch on `error.code`.
      headers:
        X-Trace-Id:
          $ref: '#/components/headers/TraceId'
        Strict-Transport-Security:
          $ref: '#/components/headers/StrictTransportSecurity'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenError'
          examples:
            not-eligible:
              $ref: '#/components/examples/earn-forbidden'
    BondedEarnWriteNotFoundResponse:
      description: The strategy does not exist. Branch on `error.code`.
      headers:
        X-Trace-Id:
          $ref: '#/components/headers/TraceId'
        Strict-Transport-Security:
          $ref: '#/components/headers/StrictTransportSecurity'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/NotFoundError'
                title: Not found
              - $ref: '#/components/schemas/BondedEarn_StrategyNotFoundError'
                title: Strategy not found
          examples:
            strategy-not-found:
              $ref: '#/components/examples/bonded-earn-strategy-not-found'
    BondedEarnConflictResponse:
      description: >-
        The request conflicts with a request that was already recorded or is
        still running. Branch on `error.code`.
      headers:
        X-Trace-Id:
          $ref: '#/components/headers/TraceId'
        Strict-Transport-Security:
          $ref: '#/components/headers/StrictTransportSecurity'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/BondedEarn_RequestConflictError'
                title: Request conflict
              - $ref: '#/components/schemas/BondedEarn_IdempotencyKeyReusedError'
                title: Idempotency key reused
              - $ref: '#/components/schemas/BondedEarn_AllocationInProgressError'
                title: Allocation in progress
          examples:
            idempotency-key-reused:
              $ref: '#/components/examples/bonded-earn-idempotency-key-reused'
            allocation-in-progress:
              $ref: '#/components/examples/bonded-earn-allocation-in-progress'
            request-conflict:
              $ref: '#/components/examples/bonded-earn-request-conflict'
    EarnResourceExhaustedResponse:
      description: Rate limit exceeded
      headers:
        X-Trace-Id:
          $ref: '#/components/headers/TraceId'
        Strict-Transport-Security:
          $ref: '#/components/headers/StrictTransportSecurity'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceExhaustedError'
          examples:
            rate-limit-exceeded:
              $ref: '#/components/examples/earn-resource-exhausted'
    EarnInternalResponse:
      description: Internal server error
      headers:
        X-Trace-Id:
          $ref: '#/components/headers/TraceId'
        Strict-Transport-Security:
          $ref: '#/components/headers/StrictTransportSecurity'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalError'
          examples:
            internal-error:
              $ref: '#/components/examples/earn-internal'
    EarnUnavailableResponse:
      description: Service unavailable
      headers:
        X-Trace-Id:
          $ref: '#/components/headers/TraceId'
        Strict-Transport-Security:
          $ref: '#/components/headers/StrictTransportSecurity'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnavailableError'
          examples:
            service-unavailable:
              $ref: '#/components/examples/earn-service-unavailable'
    EarnDeadlineExceededResponse:
      description: Deadline exceeded
      headers:
        X-Trace-Id:
          $ref: '#/components/headers/TraceId'
        Strict-Transport-Security:
          $ref: '#/components/headers/StrictTransportSecurity'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DeadlineExceededError'
          examples:
            request-deadline-exceeded:
              $ref: '#/components/examples/earn-deadline-exceeded'
  examples:
    earn-bad-request:
      summary: Invalid request
      value:
        error:
          type: earn_error
          instance: req_01H00000000000000000000000
          status: 400
          code: bad_request
          causes:
            - field: account_id
              message: must be a valid account identifier
    bonded-earn-insufficient-balance:
      summary: Balance does not cover the amount
      value:
        error:
          type: earn_error
          instance: req_01H00000000000000000000000
          status: 400
          code: insufficient_balance
          causes:
            - field: amount
              message: Not enough funds to deallocate
    bonded-earn-amount-too-high:
      summary: Amount too large to represent
      value:
        error:
          type: earn_error
          instance: req_01H00000000000000000000000
          status: 400
          code: amount_too_high
          causes:
            - field: amount
              message: The amount is outside the range that can be processed
    earn-unauthenticated:
      summary: Authentication failed
      value:
        error:
          type: earn_error
          instance: req_01H00000000000000000000000
          status: 401
          code: unauthenticated
    earn-forbidden:
      summary: Caller is not allowed
      value:
        error:
          type: earn_error
          instance: req_01H00000000000000000000000
          status: 403
          code: forbidden
    bonded-earn-strategy-not-found:
      summary: Strategy not found
      value:
        error:
          type: earn_error
          instance: req_01H00000000000000000000000
          status: 404
          code: strategy_not_found
    bonded-earn-idempotency-key-reused:
      summary: Idempotency key reused for a different request
      value:
        error:
          type: earn_error
          instance: req_01H00000000000000000000000
          status: 409
          code: idempotency_key_reused
          causes:
            - field: idempotency_key
              message: Idempotency key already used for a different request
    bonded-earn-allocation-in-progress:
      summary: Another request is running on the strategy
      value:
        error:
          type: earn_error
          instance: req_01H00000000000000000000000
          status: 409
          code: allocation_in_progress
          causes:
            - field: request
              message: Another allocation is already running on this strategy
    bonded-earn-request-conflict:
      summary: Request conflicts with an existing request
      value:
        error:
          type: earn_error
          instance: req_01H00000000000000000000000
          status: 409
          code: request_conflict
    earn-resource-exhausted:
      summary: Rate limit exceeded
      value:
        error:
          type: earn_error
          instance: req_01H00000000000000000000000
          status: 429
          code: resource_exhausted
    earn-internal:
      summary: Internal error
      value:
        error:
          type: earn_error
          instance: req_01H00000000000000000000000
          status: 500
          code: internal
    earn-service-unavailable:
      summary: Service unavailable
      value:
        error:
          type: earn_error
          instance: req_01H00000000000000000000000
          status: 503
          code: unavailable
    earn-deadline-exceeded:
      summary: Request deadline exceeded
      value:
        error:
          type: earn_error
          instance: req_01H00000000000000000000000
          status: 504
          code: deadline_exceeded
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: API-Key
      description: Your public API key. Identifies the partner making the request.
    ApiSign:
      type: apiKey
      in: header
      name: API-Sign
      description: HMAC signature over the request, computed with your private key.
    ApiNonce:
      type: apiKey
      in: header
      name: API-Nonce
      description: Monotonically increasing nonce included in the request signature.

````