Withdraw Funds

Portfolio wallet withdrawals are asynchronous. A withdrawal may involve unwinding yield positions, bridging across chains, and waiting for organization approval — all orchestrated automatically.

Creating a withdrawal reserves funds but does not guarantee the final payout. Morpho exits are normally synchronous, while Syrup USDC, the U.S. Treasury Bill Vault, and JTRSY may settle asynchronously. JTRSY USDC redemptions are instant through Basin when available; otherwise JTRSY typically takes 1-2 banking days and up to 3.

Investing through a fee wrapper accrues fees in wrapper shares. This is separate from the optional partner fee deducted during a withdrawal payout.

Withdrawal lifecycle

The typical flow is: preview -> initiate -> track -> complete.

Preview — call withdrawal-preview to see what’s available and get a sourcing plan.
Initiate — call withdrawals to create the withdrawal. The system reserves liquidity and begins sourcing.
Track — poll the withdrawal or subscribe to webhooks. The withdrawal moves through statuses as positions unwind, funds bridge, and payouts execute.
Complete — the withdrawal reaches completed when all funds have been delivered.

Preview a withdrawal

Before initiating, preview what balance is available for a given destination.

curl -X POST "$BASE_URL/v2/wallets/$WALLET_ID/withdrawal-preview" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationChain": "polygon",
    "amountUsd": 65000,
    "token": "usdc",
    "partnerFeeAmountUsd": 25,
    "partnerFeeRecipientAddress": "0x1111111111111111111111111111111111111111"
  }'

curl -X POST "$BASE_URL/v2/wallets/$WALLET_ID/withdrawal-preview" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "destinationChain": "solana", "token": "usdc", "amountUsd": 10 }'

curl -X POST "$BASE_URL/v2/wallets/$WALLET_ID/withdrawal-preview" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "destinationChain": "stellar_testnet", "token": "usdc", "amountUsd": 10 }'

curl -X POST "$BASE_URL/v2/wallets/$WALLET_ID/withdrawal-preview" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "destinationChain": "tron", "token": "usdt", "amountUsd": 10 }'

Field	Required	Description
`destinationChain`	Yes	Destination chain for the withdrawal
`amountUsd`	No	Gross wallet value to withdraw before fees (max 6 decimal places). If omitted, previews the maximum gross available balance.
`token`	Yes	Token to deliver: `usdc` or `usdt`. USDT withdrawals use Ethereum or TRON in production, and Ethereum Sepolia or Shasta in Sandbox. Funds must be available in the corresponding allocation group.
`sources`	No	Exact source positions when automatic rebalancing is disabled. Their gross amounts must sum to `amountUsd`. Omit this field for automatic source selection.
`partnerFeeAmountUsd`	No	Partner-calculated fee for an EVM or TRON withdrawal. Must be supplied with `partnerFeeRecipientAddress`.
`partnerFeeRecipientAddress`	No	Network-specific address that receives the partner fee. Must be supplied with `partnerFeeAmountUsd`.

With an explicit amountUsd, amountRequestedUsd echoes the requested amount:

{
  "amountRequestedUsd": "65000.000000",
  "feeUsd": "0.000000",
  "partnerFeeUsd": "25.000000",
  "amountToReceiveUsd": "64975.000000",
  "withdrawableUsd": "82500.000000",
  "totalUsdAfterWithdrawal": "35000.000000",
  "estimatedCompletionTime": "PT2H",
  "maxCompletionTime": "PT4H"
}

When amountUsd is omitted, the preview resolves the maximum available balance and returns that amount in amountRequestedUsd:

{
  "amountRequestedUsd": "82500.000000",
  "feeUsd": "0.000000",
  "partnerFeeUsd": "0.000000",
  "amountToReceiveUsd": "82500.000000",
  "withdrawableUsd": "82500.000000",
  "totalUsdAfterWithdrawal": "17500.000000",
  "estimatedCompletionTime": "PT2H",
  "maxCompletionTime": "PT4H"
}

Field	Description
`amountRequestedUsd`	Gross wallet value previewed (equals the requested amount, or the resolved gross maximum when `amountUsd` was omitted)
`feeUsd`	Estimated execution fee deducted from the gross amount, including yield source protocol exit fees
`partnerFeeUsd`	Partner fee deducted from the gross amount
`amountToReceiveUsd`	Estimated net amount to be sent to the destination after execution and partner fees
`withdrawableUsd`	Maximum gross wallet value that can safely start a withdrawal for this destination right now
`totalUsdAfterWithdrawal`	Estimated wallet total after the gross requested amount is removed
`estimatedCompletionTime`	Estimated end-to-end completion time as an ISO 8601 duration
`maxCompletionTime`	Worst-case (SLA upper bound) end-to-end completion time as an ISO 8601 duration

withdrawableUsd on the wallet object and in preview are related but different:

Wallet withdrawableUsd is the wallet-level conservative gross amount that can be withdrawn now before plan-specific fees.
Preview withdrawableUsd is the destination-specific gross amount that can safely start right now.
Preview withdrawableUsd can be lower than the wallet object’s withdrawableUsd.

Ground keeps wallet-level ownership, wallet-level readiness, and destination-specific readiness separate on purpose. Value can remain customer-owned while still being unavailable to start a fresh withdrawal to a specific destination, for example when a prior unwind, bridge, or payout boundary is still settling and the destination representation has not yet been observed.

Initiate a withdrawal

curl -X POST "$BASE_URL/v2/wallets/$WALLET_ID/withdrawals" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "df8b7be6-e110-4f6d-9b2d-7c44a5b1f0b0",
    "destinationChain": "ethereum",
    "amountUsd": 65000,
    "token": "usdc",
    "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "partnerFeeAmountUsd": 25,
    "partnerFeeRecipientAddress": "0x1111111111111111111111111111111111111111"
  }'

Field	Required	Description
`requestId`	Yes	UUID v4 idempotency key
`destinationChain`	Yes	Destination chain
`amountUsd`	Yes	Gross wallet value to withdraw before execution fees (max 6 decimal places)
`token`	Yes	Token to deliver: `usdc` or `usdt`.
`destinationAddress`	Yes	Recipient address on the destination chain. Stellar destinations use a G-address.
`sources`	No	Exact source positions when automatic rebalancing is disabled. Their gross amounts must sum to `amountUsd`.
`partnerFeeAmountUsd`	No	Partner-calculated fee for an EVM or TRON withdrawal. Must be positive, smaller than `amountUsd`, have at most 6 decimal places, and be supplied with `partnerFeeRecipientAddress`.
`partnerFeeRecipientAddress`	No	Network-specific address that receives the partner fee. Must be supplied with `partnerFeeAmountUsd` and differ from the customer destination.

To withdraw exact amounts from selected positions, disable automatic rebalancing and send the same sources array to preview and create:

{
  "amountUsd": 1000,
  "sources": [
    { "id": "morpho-august-usdc-v2", "amountUsd": 600 },
    { "id": "syrup-usdc", "amountUsd": 400 }
  ]
}

Use position IDs returned by GET /v2/wallets/{id}. Ground does not fall back to another position when a selected source cannot cover its requested amount. Wallets with automatic rebalancing do not support explicit sources in V1. When withdraw succeeds, Ground has accepted the gross debit and reserved liquidity against the wallet. The destination receives the gross amountUsd minus execution fees and any partner fee. Ground snapshots the partner fee and recipient for that withdrawal and sends the customer payout and partner fee atomically. The payout legs remain the source of truth for what was actually delivered, especially for asynchronous exits. Sandbox notes:

Sandbox USDC destinations include ethereum_sepolia and solana_devnet, plus stellar_testnet.
Sandbox USDT withdrawals require token: "usdt" with destinationChain: "ethereum_sepolia" or "tron_shasta", matching the funded allocation group.
destinationAddress must match the selected chain format: EVM hex for EVM chains, base58 for Solana, a G-address for Stellar, and checksummed TRON base58 for TRON.

Solana Devnet withdrawal

curl -X POST "$BASE_URL/v2/wallets/$WALLET_ID/withdrawals" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "e1f2a3b4-0000-4000-8000-000000000001",
    "destinationChain": "solana_devnet",
    "amountUsd": 5,
    "token": "usdc",
    "destinationAddress": "DmaePN7kL6WjSecMaH4urdS8zN8FwNPTxbdTqFwAw6Fd"
  }'

List withdrawals

curl -X GET "$BASE_URL/v2/wallets/$WALLET_ID/withdrawals?limit=25" \
  -H "Authorization: Bearer $API_TOKEN"

Query parameters:

Param	Description
`limit`	Max items (default 50, max 200)
`cursor`	Opaque cursor from `nextCursor`
`sort`	Sort field (default `createdAt`)
`order`	`desc` (default) or `asc`
`createdAtGte`	ISO-8601 timestamp filter
`status`	Repeatable status filter (e.g. `status=processing&status=completed`)

Fetch a withdrawal

curl -X GET "$BASE_URL/v2/wallets/$WALLET_ID/withdrawals/$WITHDRAWAL_ID" \
  -H "Authorization: Bearer $API_TOKEN"

{
  "id": "0ad2fd60-f906-46fd-a395-f50b21dccd18",
  "amountRequestedUsd": "5.000000",
  "amountPaidUsd": "5.000000",
  "amountPaidToPartnerUsd": "0.000000",
  "feeUsd": "0.000000",
  "destinationChain": "ethereum_sepolia",
  "destinationAddress": "0x76F8fc6667E239f83a547d4e16225d6a34f6FA22",
  "destinationToken": "usdc",
  "status": "completed",
  "legsCompleted": 2,
  "legsTotal": 2,
  "payoutLegs": [
    {
      "status": "completed",
      "amountUsd": "2.999999",
      "from": { "kind": "yield_source", "id": "morpho-steakhouse-usdc", "label": "Morpho Steakhouse USDC Prime" },
      "to": { "kind": "external_payout", "id": "external_payout:ethereum_sepolia:usdc", "label": "External payout (Ethereum Sepolia)" },
      "startedAt": "2026-07-09T21:37:22.227Z",
      "completedAt": "2026-07-09T21:40:43.578Z",
      "stepsCompleted": 2,
      "stepsTotal": 2,
      "steps": [
        {
          "name": "Redeeming from Morpho Steakhouse USDC Prime",
          "stepKind": "yield_source_redeem",
          "sequenceRole": "yield_redeem",
          "protocolType": "morpho",
          "stepOrdinal": 0,
          "chain": "ethereum_sepolia",
          "txKind": "yield_source_redeem",
          "state": "completed",
          "startedAt": "2026-07-09T21:38:29.885Z",
          "completedAt": "2026-07-09T21:38:29.885Z",
          "cancelledAt": null
        },
        {
          "name": "Sending payout",
          "stepKind": "external_payout_transfer",
          "sequenceRole": "external_payout_transfer",
          "protocolType": "external_payout",
          "stepOrdinal": 1,
          "chain": "ethereum_sepolia",
          "txKind": "external_payout_transfer",
          "state": "completed",
          "startedAt": "2026-07-09T21:38:31.697Z",
          "completedAt": "2026-07-09T21:40:43.578Z",
          "cancelledAt": null
        }
      ]
    },
    {
      "status": "completed",
      "amountUsd": "2.000001",
      "from": { "kind": "yield_source", "id": "syrup-usdc", "label": "Syrup USDC" },
      "to": { "kind": "external_payout", "id": "external_payout:ethereum_sepolia:usdc", "label": "External payout (Ethereum Sepolia)" },
      "startedAt": "2026-07-09T21:37:22.227Z",
      "completedAt": "2026-07-09T21:45:10.274Z",
      "stepsCompleted": 2,
      "stepsTotal": 2,
      "steps": [
        {
          "name": "Redeeming from Syrup USDC",
          "stepKind": "syrup_request_redeem",
          "sequenceRole": "yield_redeem",
          "protocolType": "syrup",
          "stepOrdinal": 0,
          "chain": "ethereum_sepolia",
          "txKind": "yield_source_redeem",
          "state": "completed",
          "startedAt": "2026-07-09T21:39:05.596Z",
          "completedAt": "2026-07-09T21:39:05.596Z",
          "cancelledAt": null
        },
        {
          "name": "Sending payout",
          "stepKind": "external_payout_transfer",
          "sequenceRole": "external_payout_transfer",
          "protocolType": "external_payout",
          "stepOrdinal": 1,
          "chain": "ethereum_sepolia",
          "txKind": "external_payout_transfer",
          "state": "completed",
          "startedAt": "2026-07-09T21:44:25.926Z",
          "completedAt": "2026-07-09T21:45:10.274Z",
          "cancelledAt": null
        }
      ]
    }
  ],
  "failureReason": null,
  "createdAt": "2026-07-09T21:37:22.227Z",
  "completedAt": "2026-07-09T21:44:37.964Z"
}

Top-level fields:

Field	Description
`amountRequestedUsd`	The gross wallet value requested for withdrawal.
`amountPaidUsd`	Sum of completed payout legs; `null` until at least one leg completes.
`amountPaidToPartnerUsd`	Confirmed amount paid to the partner; `null` until at least one partner payout completes.
`feeUsd`	Total execution and protocol fees across legs.
`destinationChain` / `destinationAddress`	Where funds are delivered.
`destinationToken`	Stablecoin delivered by the withdrawal: `usdc` or `usdt`. Older records without token metadata can return `null`.
`status`	Withdrawal status (see Withdrawal statuses).
`legsCompleted` / `legsTotal`	Progress across payout legs.
`payoutLegs[]`	The individual payout legs of the withdrawal (see below).
`failureReason`	Populated when `status` is `failed` or `partially_completed`.

The payoutLegs array contains the individual legs of the withdrawal. Each leg moves funds from one representation (from) to another (to) through one or more onchain steps:

Field	Description
`status`	Leg status (see complete list below)
`amountUsd`	Amount routed through this leg, as a fixed-precision USD string
`from` / `to`	`{ kind, id, label }` source and destination of the leg (e.g. `yield_source` → `external_payout`)
`startedAt` / `completedAt`	Leg timing
`stepsCompleted` / `stepsTotal`	Progress across the leg’s onchain steps
`steps[]`	Per-step detail: `{ name, stepKind, sequenceRole, protocolType, stepOrdinal, chain, txKind, state, startedAt, completedAt, cancelledAt }`.

Use portfolio_wallet.withdrawal.payout.status_changed for per-leg progress, including the redeem and payout-transfer steps. When a step enters pending_customer_approval, fetch the pending Turnkey activity and verify it before approving — see Transaction Approvals.

Payout statuses

Withdrawal payoutLegs[].status and payoutLegs[].steps[].state use the workflow status set:

Status	Terminal	Meaning
`created`	No	Payout leg or step has been planned but has not started.
`processing`	No	Payout is actively being processed.
`pending_customer_approval`	No	Awaiting the organization’s configured signer. Use Ground Portal or your approval integration to approve or reject the activity.
`completed`	Yes	Payout delivered successfully.
`failed`	Yes	Payout failed; see `failureReason`
`cancelled`	Yes	Payout was cancelled (e.g. parent withdrawal cancelled)

Withdrawal statuses

Withdrawals move through five public statuses:

Status	Meaning
`processing`	Accepted and in progress: unwinding positions, bridging, or delivering funds
`partially_completed`	Terminal: some payout legs completed while others did not
`completed`	Terminal: funds delivered to destination address
`failed`	Terminal: withdrawal failed
`cancelled`	Terminal: withdrawal was cancelled

If realized redemption proceeds are not enough to pay the committed partner fee while leaving a positive customer payout, the withdrawal fails before payout with failureReason: "insufficient_proceeds_after_partner_fee". No customer payout or partner fee is sent, and the realized proceeds remain available in the portfolio wallet. Submit a new withdrawal with a lower or zero partner fee.

Timing expectations

Withdrawal time depends on which yield positions need to unwind and whether cross-chain bridging is required.

Position	Typical timing	Developer note	Customer-facing copy
Cash (USDC)	Instant	No unwind needed.	This withdrawal is expected to complete right away.
Cash (USDT)	Instant	No unwind needed. Ethereum or TRON, matching the funded allocation group.	This withdrawal is expected to complete right away.
`morpho-gauntlet-usdc`	Instant (`PT0H`)	Synchronous ERC-4626 redeem on Ethereum. There is no normal queue-based delay.	This withdrawal is expected to complete quickly and is not normally queued.
`morpho-steakhouse-usdc`	Instant (`PT0H`)	Synchronous ERC-4626 redeem on Ethereum. There is no normal queue-based delay.	This withdrawal is expected to complete quickly and is not normally queued.
`syrup-usdc`	Up to 24h (`PT24H`)	Queue-based withdrawal. Low-liquidity periods can take longer. The payout can be processed in parts, and the final amount is based on Maple’s withdrawal value when the queue processes the request.	This withdrawal is queued rather than instant. Most withdrawals are processed within 24 hours, but it can take longer in low-liquidity periods. The payout can be processed in parts, and the final amount can be lower if Maple’s withdrawal value falls before processing.

Cross-chain delivery (CCTP) adds time on top of the unwind. Withdrawal previews currently estimate this CCTP leg at about 20 minutes (PT20M); live settlement can vary with chain and Circle attestation conditions. For precise per-position estimates to a specific destination, use the withdrawal preview endpoint.

Withdrawal webhooks

Subscribe to portfolio_wallet.withdrawal.status_changed for real-time withdrawal tracking. See Webhooks for registration and payload details.

Fund and destination compatibility

Withdrawals source cash and eligible yield positions compatible with the requested stablecoin and destination network. When sources is omitted, cash is used first and positions are unwound when additional liquidity is needed. For manual wallets with explicit sources, the withdrawal uses only the selected positions.

Token and destination	Eligible funds	Network movement
USDC on Arbitrum, Base, Ethereum, Polygon, Solana, or Stellar (Beta)	USDC cash and positions in `usdc`	Supported routes may use CCTP
USDT on Ethereum	Ethereum USDT cash and positions in `usdt`	Stays on Ethereum
USDT on TRON	TRON USDT cash and positions in `usdt:tron`	Stays on TRON

Use token: "usdc" or "usdt" and the exact destinationChain key for your environment. Sandbox uses ethereum_sepolia, solana_devnet, stellar_testnet, and tron_shasta according to Supported Chains. Destination addresses must follow the selected network’s format. The destination Stellar account must be active and able to receive Circle USDC. Use the preview response to determine the amount available for your destination and its estimated completion time. Source redemption can depend on market liquidity, provider settlement, and transaction confirmation. Payouts follow the same approval workflow across supported networks; track the withdrawal until completed.

Getting Started

Wallet Lifecycle

Fees

Approvals

Monitoring & Webhooks

Security

Resources

API Reference

Withdraw Funds

Withdrawal lifecycle

Preview a withdrawal

Initiate a withdrawal

Solana Devnet withdrawal

List withdrawals

Fetch a withdrawal

Payout statuses

Withdrawal statuses

Timing expectations

Withdrawal webhooks

Fund and destination compatibility

​Withdrawal lifecycle

​Preview a withdrawal

​Initiate a withdrawal

​Solana Devnet withdrawal

​List withdrawals

​Fetch a withdrawal

​Payout statuses

​Withdrawal statuses

​Timing expectations

​Withdrawal webhooks

​Fund and destination compatibility

Withdrawal lifecycle

Preview a withdrawal

Initiate a withdrawal

Solana Devnet withdrawal

List withdrawals

Fetch a withdrawal

Payout statuses

Withdrawal statuses

Timing expectations

Withdrawal webhooks

Fund and destination compatibility