Preview a withdrawal request

POST/v1/earn/external-wallet/queued-withdrawal-previews

Check the mechanism against the position's withdrawal options first, and resolve every blockingIssues entry before the customer confirms. The preview is read-only and safe to retry. It does not check the wallet's balance, so keep shares within the position's withdrawableShares.

Requires an API key with the earn.read action.

HeadersCopy Anchor Link

• x-project-id · string · min length 1 · example prj_example

  Required for dashboard sessions. API keys use their assigned project.

Request bodyCopy Anchor Link

application/json · required

Preview a solver-queue or operator-redemption request against live provider limits. Read-only: nothing is built or persisted.

Any of:

• object

  • positionId · string · required · min length 1 · max length 128 · example earn_position_2f8b6b04-7147-487e-b760-b1caa4fbcb8b

    The position's ID, from the positions list or the deposit submit response.

  • shares · string · required · max length 128 · pattern ^(?=.*[1-9])\d+(\.\d+)?$ · example 10

    Shares to place in the withdrawal request, in share units.

  • mechanism · string · always solverQueue

    Selects the solver queue, which is also the default when omitted. Operator redemptions must set mechanism explicitly.

  • discountBps · integer · required · min 0 · max 10000 · example 25

    Discount offered to a solver, in basis points. It must stay inside the live queueAsset minimum and maximum.

  • deadlineSeconds · integer · required · greater than 0 · max 7776000 · example 86400

    Solver window after maturity, in seconds. It must stay inside the live queueAsset minimum and maximum.

• object

  • positionId · string · required · min length 1 · max length 128 · example earn_position_2f8b6b04-7147-487e-b760-b1caa4fbcb8b

    The position's ID, from the positions list or the deposit submit response.

  • shares · string · required · max length 128 · pattern ^(?=.*[1-9])\d+(\.\d+)?$ · example 10

    Shares to place in the withdrawal request, in share units.

  • mechanism · string · required · always operatorRedemption

    Selects an operator redemption, which takes no solver discount or deadline.

• object

  • positionId · string · required · min length 1 · max length 128 · example earn_position_2f8b6b04-7147-487e-b760-b1caa4fbcb8b

    The position's ID, from the positions list or the deposit submit response.

  • intermediateAmount · string · required · max length 128 · pattern ^(?=.*[1-9])\d+(\.\d+)?$ · example 2000

    Intermediate token the owner already holds outside any request (such as a cancelled request's wYLDS) to redeem at par, in that token's units. Send instead of shares, never with it.

  • mechanism · string · required · always operatorRedemption

    Selects an operator redemption, which takes no solver discount or deadline.

ResponsesCopy Anchor Link

• 200 Expected request terms

  • data · object · required

    Any of:

    • object

      • positionId · string · required · min length 1 · max length 128 · example earn_position_2f8b6b04-7147-487e-b760-b1caa4fbcb8b

        The position's ID, from the positions list or the deposit submit response.

      • assetMint · string · required · min length 32 · max length 44 · pattern ^[1-9A-HJ-NP-Za-km-z]{32,44}$ · example 2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo

        Base58 Solana mint address.

      • shares · string · required · max length 128 · pattern ^(?=.*[1-9])\d+(\.\d+)?$ · example 25

        Positive decimal string with at least one non-zero digit; never a float.

      • shareDecimals · integer · required · min 0 · max 38

      • assets · string · required · max length 128 · pattern ^(?=.*[1-9])\d+(\.\d+)?$ · example 9.975

        Expected payout after the discount, in assetMint units.

      • assetDecimals · integer · required · min 0 · max 38

      • discountBps · integer · required · min 0 · max 10000

      • maturityTimestamp · string · required · pattern ^\d+$ · example 1789722000

        Unix time, in seconds, when a solver may start fulfilling the request.

      • deadlineTimestamp · string · required · pattern ^\d+$ · example 1789808400

        Unix time, in seconds, of the request's deadline. A solver may fulfill it until this time; cancellation is allowed only after it.

      • blockingIssues · object[] · required

        • code · string · required · example SHARE_LOCKED

        • message · string · required

    • object

      • positionId · string · required · min length 1 · max length 128 · example earn_position_2f8b6b04-7147-487e-b760-b1caa4fbcb8b

        The position's ID, from the positions list or the deposit submit response.

      • mechanism · string · required · always operatorRedemption

      • shares · string · required · max length 128 · pattern ^\d+(\.\d+)?$ · example 10

        Position shares the request burns, in share units; "0" when it redeems intermediate the owner already holds.

      • shareDecimals · integer · required · min 0 · max 38

      • intermediateMint · string · required · min length 32 · max length 44 · pattern ^[1-9A-HJ-NP-Za-km-z]{32,44}$ · example 2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo

        Token the request creates or delegates for later operator settlement.

      • intermediateAmount · string · required · max length 128 · pattern ^(?=.*[1-9])\d+(\.\d+)?$ · example 25

        Expected intermediate-token amount, in that token's units.

      • assetMint · string · required · min length 32 · max length 44 · pattern ^[1-9A-HJ-NP-Za-km-z]{32,44}$ · example 2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo

        Base58 Solana mint address.

      • assets · string · required · max length 128 · pattern ^(?=.*[1-9])\d+(\.\d+)?$ · example 10

        Expected par payout when the operator completes the redemption.

      • assetDecimals · integer · required · min 0 · max 38

      • blockingIssues · object[] · required

        • code · string · required · example SHARE_LOCKED

        • message · string · required

  • meta · object · required

    Response metadata.

    • requestId · string · required · min length 1 · example req_example

      Request identifier for tracing.

    • timestamp · string · required · format date-time · example 2025-01-01T00:00:00.000Z

      ISO 8601 timestamp.

• 400 Bad Request

  • error · object · required

    Standard error payload.

    • code · string · required

      Machine-readable error code.

    • message · string · required

      Human-readable error message.

    • details · object

      Optional error details for debugging.

      • * · any

  • meta · object

    • requestId · string · min length 1 · example req_example

      Request identifier for tracing.

• 401 Unauthorized

  Same fields as 400.

• 403 Forbidden. Requires the earn.read action: an API key must hold it (a module's manage or execute also covers its read), and a signed-in member's organization role must include it. Without it the error is INSUFFICIENT_PERMISSIONS and error.details.action names the action. Any other 403 names its own reason.

  Same fields as 400.

• 404 Not Found

  Same fields as 400.

• 429 Too Many Requests

  Same fields as 400.

• 500 Internal Server Error

  Same fields as 400.

• 501 The provider does not support this operation.

  • error · object · required

    Standard error payload.

    • code · string · required

    • message · string · required

      Human-readable error message.

    • details · object

      Optional error details for debugging.

      • * · any

  • meta · object

    • requestId · string · min length 1 · example req_example

      Request identifier for tracing.

• 503 Service Unavailable

  Same fields as 400.