Withdraw Funds

Preview, initiate, and track portfolio wallet withdrawals.

Portfolio wallet withdrawals are asynchronous. A withdrawal may involve unwinding yield positions, bridging across chains, and waiting for customer 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.

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.

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

Field	Required	Description
destinationChain	Yes	Destination chain for the withdrawal
amountUsd	No	Amount to preview as a number (max 6 decimal places). If omitted, previews the maximum available balance.
token	Yes	Token to deliver: usdc or usdt. USDT is Ethereum-only in production and Ethereum Sepolia-only in sandbox.

With an explicit amountUsd, amountRequestedUsd echoes the requested amount:

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

When amountUsd is omitted, the preview reflects the maximum available balance and amountRequestedUsd is null:

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

Field	Description
amountRequestedUsd	The withdrawal amount previewed (equals the requested amount, or null when amountUsd was omitted and the max available is previewed)
feeUsd	Fee for the withdrawal (currently always "0.000000")
withdrawableUsd	Conservative amount that can safely start a new withdrawal for this destination right now
totalUsdAfterWithdrawal	Estimated wallet total after the previewed withdrawal amount is paid out
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 amount that can be withdrawn now.
• Preview withdrawableUsd is the destination-specific 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"
  }'

Field	Required	Description
requestId	Yes	UUID v4 idempotency key
destinationChain	Yes	Destination chain
amountUsd	Yes	Amount as a number (max 6 decimal places)
token	Yes	Token to deliver: usdc or usdt.
destinationAddress	Yes	Recipient address on the destination chain

When withdraw succeeds, Ground has accepted the request and reserved liquidity against the wallet. The requested amountUsd remains the target amount for the withdrawal, but the payout legs are the source of truth for what was actually delivered. Integrators should set end-user expectations based on the underlying yield source, especially for asynchronous exits.

Sandbox notes:

• In sandbox, use explicit testnet keys such as destinationChain: "ethereum_sepolia".
• Sandbox USDT withdrawals require token: "usdt" with destinationChain: "ethereum_sepolia".
• destinationAddress must match the selected chain format: EVM hex for EVM chains, base58 for solana.

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",
  "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 requested withdrawal amount (the target).
amountPaidUsd	Sum of completed payout legs; null until at least one leg completes.
feeUsd	Total fee across legs (currently always "0.000000").
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.

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 customer signature. Use Ground Portal or your enabled approval integration to review and 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

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

---

Bridge domains reference

A bridge domain is a hard boundary for where liquidity can come from. The withdrawal engine never crosses bridge domain boundaries.

USDC unified (CCTP)

USDC on CCTP-supported chains forms a single usdc:unified domain:

• Arbitrum, Base, Ethereum, Polygon, Solana

A withdrawal to any of these chains can source USDC from any other chain in the domain (via CCTP bridging).

USDT Ethereum

In V1, USDT withdrawals are supported only to Ethereum in production and Ethereum Sepolia in sandbox.

How cash fits in

Within a bridge domain, cash is always the first source of liquidity. Only if cash is insufficient will the system unwind yield positions in the same domain.

Bridge domain IDs are always lowercase and intended to be stable, but use the withdrawal preview as the canonical source of truth for what’s available.