Withdraw Funds

Preview, initiate, and track portfolio wallet withdrawals.

Withdraw stablecoins to a recipient by previewing the amount, submitting the request, and tracking delivery. Ground redeems investments and moves funds between networks when needed. Some withdrawals also require your approval.

​

Prerequisites

Use a funded wallet, your server-side API key, and a recipient on a supported network. Set BASE_URL, API_TOKEN, and WALLET_ID for the requests below. If your organization requires signing, prepare an authorized signer.

​

Withdrawal lifecycle

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

1. Preview — call withdrawal-preview to see what’s available and get a sourcing plan.
2. Initiate — call withdrawals to create the withdrawal. The system reserves liquidity and begins sourcing.
3. Track — poll the withdrawal or subscribe to webhooks. The withdrawal moves through statuses as positions unwind, funds bridge, and payouts execute.
4. 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.

EVM USDC

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

Set the destination network and token you want to receive. Include amountUsd for a specific gross amount, or omit it to preview the maximum available amount.

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, usdt, or ousd (on Tempo). USDT withdrawals use Ethereum or TRON in production, and Ethereum Sepolia or Shasta in Sandbox. Funds must be available in the corresponding allocation group.
memo	No	Stellar recipient memo with type (id or text) and a string value.
sources	No	Exact source positions when automatic rebalancing is disabled. Their gross amounts must sum to amountUsd. Omit this field for automatic source selection.
sources[].stockPriceToleranceBps	No	For an explicit Ondo stock source, maximum executable sell quote difference from its reference price, 0–500 bps. Defaults to 100 bps (1%). Use the same limit in preview and create.
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",
  "processingEstimate": {
    "basis": "elapsed_seconds",
    "typicalMinDuration": "PT2H",
    "typicalMaxDuration": "PT2H"
  }
}

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",
  "processingEstimate": {
    "basis": "elapsed_seconds",
    "typicalMinDuration": "PT2H",
    "typicalMaxDuration": "PT2H"
  }
}

Use amountToReceiveUsd for the estimated payout after fees and processingEstimate for expected timing. A missing estimate is unavailable, not immediate settlement. Preview withdrawableUsd can be lower than the wallet balance because it applies to your selected destination.

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, including owned holdings that cannot fund this destination
processingEstimate	Typical processing window. elapsed_seconds estimates use typicalMinDuration and typicalMaxDuration; banking_days estimates use completion/window dates. null means no reliable estimate is available.

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.

Funds awaiting redemption, bridging, or payout can remain part of the wallet’s total value while being unavailable for a new withdrawal to this destination.

​

Check the destination

​

Tempo beta limit

USDC.e withdrawals to Tempo allow at most 100 USDC.e per request, before fees. Both preview and create return HTTP 400 tempo_beta_transfer_limit_exceeded above the limit, without reserving funds. Identical request-ID replays of committed withdrawals still work.

If amountUsd is omitted, preview checks the full withdrawable amount and rejects it when it exceeds the limit. Supply an explicit amount to preview a smaller withdrawal. Deposits and total wallet balances are not capped.

​

Stellar memos

For stellar or stellar_testnet, use the memo type and value provided by the receiving exchange or recipient. Include the same memo in both preview and create requests:

{
  "destinationChain": "stellar",
  "token": "usdc",
  "amountUsd": 10,
  "memo": { "type": "id", "value": "123456" }
}

Use type: "id" for an unsigned 64-bit number sent as a string, or type: "text" for 1–28 UTF-8 bytes. Text is preserved exactly. For example: {"type":"text","value":"customer-123"}. Do not infer the memo type from the value; a text memo can contain only digits. Omit memo when the recipient does not require one; other networks reject it.

The memo is attached to each final Stellar payout. It appears in the preview, withdrawal responses, withdrawal activity and webhooks, and customer approval details. Retrying the same request preserves it; changing it requires a new requestId.

​

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"
  }'

Use the same destination, amount, memo, selected sources, and fees you previewed. Add the recipient address and a new UUID v4 requestId. Save the ID and exact payload before sending; retry an uncertain response with them unchanged.

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, usdt, or ousd (on Tempo).
destinationAddress	Yes	Recipient address on the destination chain. Stellar destinations use a G-address.
memo	No	Stellar recipient memo with type (id or text) and a string value.
sources	No	Exact source positions when automatic rebalancing is disabled. Their gross amounts must sum to amountUsd.
sources[].stockPriceToleranceBps	No	For an explicit Ondo stock source, maximum executable sell quote difference from its reference price, 0–500 bps. Defaults to 100 bps (1%).
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:

{
  "requestId": "c6b0be95-7f37-4334-9476-89fcc3538761",
  "destinationChain": "ethereum",
  "token": "usdc",
  "destinationAddress": "0x1111111111111111111111111111111111111111",
  "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	Token delivered by the withdrawal: usdc, usdt, or ousd. 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.

​

Tempo withdrawals

Use destinationChain: "tempo" and token: "usdc" to receive USDC.e on Tempo mainnet. Preview first, then submit a withdrawal with the same destination and a new requestId. USDC.e withdrawals to Tempo are not available in sandbox. Partner fees are not supported for Tempo withdrawals.

{
  "requestId": "da7cc377-8e31-45ea-9078-857abcc13c03",
  "destinationChain": "tempo",
  "destinationAddress": "0x76f8fc6667e239f83a547d4e16225d6a34f6fa22",
  "token": "usdc",
  "amountUsd": 10
}

Track the withdrawal until completed; acceptance does not confirm delivery.

​

Timing expectations

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 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, Stellar, or Tempo	USDC cash and positions in usdc	Supported cross-network delivery
OUSD on Tempo	OUSD cash, Tempo Earn, or Sentora	Native OUSD payout after any required redemption
USDC on Stellar from OUSD	OUSD cash, Tempo Earn, or Sentora	Tempo Routes conversion followed by Stellar payout
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 the token you want to receive 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.

Sandbox supports native OUSD on tempo_moderato for enabled organizations; conversion to Stellar USDC requires mainnet.

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.