# Withdrawals

Send an available settlement balance or a direct wallet asset to an address on the selected network. A registered StarSwap email can be used in place of its main wallet address.

## Create a withdrawal

`amountRaw` uses the selected token's native decimals. Read the settlement token's address and decimals from `GET /v1/chains` to withdraw available StarSwap balance. Use a wallet token contract to send a direct onchain position. Do not send a decimal number or assume six decimals on every chain.

~~~bash POST /v1/withdrawals
curl https://starswap.cc/api/v1/withdrawals \
  -X POST \
  -H "Authorization: Bearer $STARSWAP_API_KEY" \
  -H "Idempotency-Key: withdrawal-$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "walletId":"wlt_example",
    "chain":"base",
    "token":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amountRaw":"1000000",
    "recipient":"developer@example.com"
  }'
~~~

An email recipient must already have a StarSwap account. StarSwap resolves it to the account's main wallet before the request reaches the custody ledger.

For a native EVM asset, send `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` as `token`.

On Solana, send `solana:native` for SOL or the exact case-sensitive mint address for an SPL or Token-2022 asset. The recipient is a wallet owner address. StarSwap creates its associated token account when needed and pays the required rent from the relayer account.

For SOL Max, use the position's `withdrawableRaw` from the portfolio response. It leaves a dynamic rent-exempt reserve based on the source account's actual data length. The relayer pays direct-withdrawal transaction fees and destination token-account rent. Do not subtract those costs again from custody SOL. A transfer that would leave a nonzero balance below the current rent-exempt minimum is rejected before signing.

~~~bash POST /v1/withdrawals
curl https://starswap.cc/api/v1/withdrawals \
  -X POST \
  -H "Authorization: Bearer $STARSWAP_API_KEY" \
  -H "Idempotency-Key: withdrawal-$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "walletId":"wlt_example",
    "chain":"solana",
    "token":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "amountRaw":"1000000",
    "recipient":"HAgk14JpMQLgt6rVgv7cBQFJWFto5Dqxi472uT3DKpqk"
  }'
~~~

## Read withdrawal state

The create call returns a durable withdrawal in `queued` state. Poll it through `submitted` and any `awaiting_ticket_refund` state until it reaches `confirmed` or `failed`. Preserve the original request and idempotency key if the create response is lost.

~~~bash GET /v1/withdrawals/:withdrawalId
curl https://starswap.cc/api/v1/withdrawals/wdr_example \
  -H "Authorization: Bearer $STARSWAP_API_KEY"
~~~

Use `GET /v1/withdrawals?walletId=wlt_example` to list withdrawals for one wallet. A finalized withdrawal includes a generic `transaction` reference. Its `finality.kind` is `block` for EVM or `slot` for Solana.

~~~json
{
  "transaction": {
    "id": "z3XN8ZK368b5Fps5CjyZJBNdF81zEUCJzwyDn3BnwqGHBZqjaVvWa5yQCjEAq3LAjQEhhCATZZGeVLtovtncrbr",
    "finality": {
      "kind": "slot",
      "value": "356123456",
      "hash": "4NwnA4HWZurKyXWNowJwYmb9CwX4gBKzwQKov1ExMf8M"
    }
  }
}
~~~

## Settlement withdrawals

The minimum settlement withdrawal is `10000` micros, or `0.01` settlement tokens. StarSwap reserves the amount before submitting the vault claim. If submission fails, the response enters `awaiting_ticket_refund` while the reservation is returned.