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.

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.

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.

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.

{
  "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.