Build a withdrawal transaction

POST/v1/earn/external-wallet/withdrawal-transactions

Withdrawals keep working after a provider stops taking deposits. Send minAmountOut when the strategy's withdrawalSlippage is not null, and omit it when null. A provider-order route may not support a preview: it places an order that pays out later, not an instant redemption.

Requires an API key with the earn.execute 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

Build one unsigned withdrawal transaction for a position. SDP reads the strategy and mints from the position.

• 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.

• redemptionMode · string · one of standard, instant

  The redemption route to build: standard queues a provider-managed order for a later payout, instant is the provider's faster route but still waits for cross-chain delivery — chain confirmation alone is not payout, so treat the exit as complete only at the movement's verified delivered outcome. Defaults to standard; a provider without the requested route refuses the build.

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

  Shares to redeem, decimal string in share units.

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

  Withdrawal slippage floor: the minimum deposit-token amount to accept, as a decimal string. Derive it from the withdrawal preview's assetsOut minus your tolerance. Required when the strategy's withdrawalSlippage is not null; refused with 400 when it is null, because the transaction cannot enforce it.

• feePayer · string · min length 32 · max length 44 · pattern ^[1-9A-HJ-NP-Za-km-z]{32,44}$ · example 3nMFwZXwY1s1M5s8vYAHqd4wGs4iSxXE4LRoUMMYqEgF

  Pay for this transaction from a wallet your backend controls instead of the customer's. The named address becomes the fee payer: it pays the network fee, funds any share-account rent, and must sign alongside the customer. Co-sign on your backend before you submit. The build returns 400, naming the fee payer, when it cannot pay. Sending the customer's own address keeps the default: the customer pays and signs alone.

ResponsesCopy Anchor Link

• 200 Unsigned withdrawal transaction

  • data · object · required

    • transaction · object · required

      The common fields of one built withdrawal transaction.

      • transactionId · string · required · example earn_external_wallet_transaction_e7a88258-1d19-48f3-8d0e-81fefa4bf3b3

      • transaction · string · required

        Base64 wire bytes of the unsigned transaction. Add every required signature without changing the message, then submit through SDP. The blockhash bounds when the network can first accept it; retain the original signed bytes for recovery.

      • lastValidBlockHeight · string · required · example 361186610

        Last block height at which the network can first accept this transaction. This is a block height, not a slot or timestamp.

      • sponsored · boolean · required · example false

        Always false: SDP does not pay an external wallet's fees. The customer's wallet pays, or the feePayer you name.

      • ownerAddress · string · required · example 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM

        The customer's wallet address.

      • feePayer · string · example 3nMFwZXwY1s1M5s8vYAHqd4wGs4iSxXE4LRoUMMYqEgF

        The feePayer your build request named. When present, the transaction needs the fee payer's signature as well as the customer's: co-sign on your backend before you submit, or the submit refuses it. When omitted, the customer signs alone and pays the fee.

      • provider · string · required · example kamino

      • providerReference · string · required · example 7uib8xGAwkaPz4ZGCA6t8sSEid5Yp9ty13PHUweTypx

        The strategy's onchain address at the provider. It identifies the instrument; never send funds to it.

      • tokenMint · string · required · example 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU

      • shareMint · string · required · example hXm2xSRF5PLKGMrTvAWqKhR76MuJX5dAabeSChkjqu2

      • 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.

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

        The floor encoded in the transaction, or null when the request carried none.

      • positionId · string · required · example earn_position_2f8b6b04-7147-487e-b760-b1caa4fbcb8b

  • 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.execute 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.