Skip to main content
POST
/
v2
/
wallets
/
{id}
/
withdraw
Initiate a withdrawal
curl --request POST \
  --url https://sandbox.groundtech.co/v2/wallets/{id}/withdraw \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "chain": "<string>",
  "token": "<string>",
  "withdrawalAmount": 1500.5,
  "destinationAddress": "<string>"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "walletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending_liquidity",
  "customerApprovalState": "<string>",
  "blockedBy": "<string>",
  "failureReason": "<string>",
  "withdrawalAmount": 123,
  "destinationToken": "<string>",
  "destinationChain": "<string>",
  "destinationAddress": "<string>",
  "payouts": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "withdrawalId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "walletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "legKey": "<string>",
      "status": "planning",
      "turnkeyActivityId": "<string>",
      "approvalRequestedAt": "2023-11-07T05:31:56Z",
      "approvalValidBefore": "2023-11-07T05:31:56Z",
      "amount": 123,
      "token": "<string>",
      "chain": "<string>",
      "destinationAddress": "<string>",
      "txHash": "<string>",
      "failureReason": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "sourceLegs": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "withdrawalId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "walletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "positionKey": "<string>",
      "sourceChain": "<string>",
      "requestedUsdcUnits": "<string>",
      "status": "<string>",
      "operationId": "<string>",
      "metadata": {},
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "completedAt": "2023-11-07T05:31:56Z"
}

Authorizations

​
Authorization
string
header
required

API keys are prefixed ground_sandbox_ (sandbox) or ground_prod_ (production). Pass the key as a Bearer token in the Authorization header.

Path Parameters

​
id
string<uuid>
required

Portfolio wallet ID

Body

application/json
​
requestId
string<uuid>
required

Client-generated idempotency key.

​
chain
string
required

Destination chain (e.g. arbitrum, ethereum, base, polygon, optimism, avalanche).

​
token
string
required

Token to withdraw (e.g. usdc).

​
withdrawalAmount
number
required

Amount to withdraw in USD. Maximum 6 decimal places for USDC/USDT.

Example:

1500.5

​
destinationAddress
string
required

On-chain address to receive funds.

Response

Withdrawal initiated (or existing withdrawal returned for duplicate requestId)

​
id
string<uuid>
​
requestId
string<uuid>
​
walletId
string<uuid>
​
status
enum<string>
Available options:
pending_liquidity,
processing,
pending_customer_approval,
pending_broadcast,
broadcasted,
completed,
partially_completed,
failed,
cancelled
​
customerApprovalState
string

Whether any payout currently requires customer approval.

​
blockedBy
string | null
​
failureReason
string | null
​
withdrawalAmount
number

Requested withdrawal amount in USD.

​
destinationToken
string
​
destinationChain
string
​
destinationAddress
string
​
payouts
object[]
​
sourceLegs
object[]
​
createdAt
string<date-time>
​
updatedAt
string<date-time>
​
completedAt
string<date-time> | null